stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
2eafe98d44818e57a33ebe36d05d50f5f5737a7d
git.stella-ops.org/docs/implplan/IMPLEMENTATION_INDEX.md
master 8bbfe4d2d2 feat(rate-limiting): Implement core rate limiting functionality with configuration, decision-making, metrics, middleware, and service registration 
- Add RateLimitConfig for configuration management with YAML binding support.
- Introduce RateLimitDecision to encapsulate the result of rate limit checks.
- Implement RateLimitMetrics for OpenTelemetry metrics tracking.
- Create RateLimitMiddleware for enforcing rate limits on incoming requests.
- Develop RateLimitService to orchestrate instance and environment rate limit checks.
- Add RateLimitServiceCollectionExtensions for dependency injection registration.
2025-12-17 18:02:37 +02:00

283 lines
9.1 KiB
Markdown
Raw Blame History

# Implementation Index — Score Proofs & Reachability
**Last Updated**: 2025-12-17
**Status**: READY FOR EXECUTION
**Total Sprints**: 10 (20 weeks)
---
## Quick Start for Agents
**If you are an agent starting work on this initiative, read in this order**:
1. **Master Plan** (15 min): `SPRINT_3500_0001_0001_deeper_moat_master.md`
- Understand the full scope, analysis, and decisions
2. **Your Sprint File** (30 min): `SPRINT_3500_000X_000Y_<topic>.md`
- Read the specific sprint you're assigned to
- Review tasks, acceptance criteria, and blockers
3. **AGENTS Guide** (20 min): `src/Scanner/AGENTS_SCORE_PROOFS.md`
- Step-by-step implementation instructions
- Code examples, testing guidance, debugging tips
4. **Technical Specs** (as needed):
- Database: `docs/db/schemas/scanner_schema_specification.md`
- API: `docs/api/scanner-score-proofs-api.md`
- Reference: Product advisories (see below)
---
## All Documentation Created
### Planning Documents (Master + Sprints)
| File | Purpose | Lines | Status |
|------|---------|-------|--------|
| `SPRINT_3500_0001_0001_deeper_moat_master.md` | Master plan with full analysis, risk assessment, epic breakdown | ~800 | ✅ COMPLETE |
| `SPRINT_3500_0002_0001_score_proofs_foundations.md` | Epic A Sprint 1 - Foundations with COMPLETE code | ~1,100 | ✅ COMPLETE |
| `SPRINT_3500_SUMMARY.md` | Quick reference for all 10 sprints | ~400 | ✅ COMPLETE |
**Total Planning**: ~2,300 lines
---
### Technical Specifications
| File | Purpose | Lines | Status |
|------|---------|-------|--------|
| `docs/db/schemas/scanner_schema_specification.md` | Complete DB schema: tables, indexes, partitions, enums | ~650 | ✅ COMPLETE |
| `docs/api/scanner-score-proofs-api.md` | API spec: 10 endpoints with request/response schemas, errors | ~750 | ✅ COMPLETE |
| `src/Scanner/AGENTS_SCORE_PROOFS.md` | Agent implementation guide with code examples | ~650 | ✅ COMPLETE |
**Total Specs**: ~2,050 lines
---
### Code & Implementation
**Provided in sprint files** (copy-paste ready):
| Component | Language | Lines | Location |
|-----------|----------|-------|----------|
| Canonical JSON library | C# | ~80 | SPRINT_3500_0002_0001, Task T1 |
| DSSE envelope implementation | C# | ~150 | SPRINT_3500_0002_0001, Task T3 |
| ProofLedger with node hashing | C# | ~100 | SPRINT_3500_0002_0001, Task T4 |
| Scan Manifest model | C# | ~50 | SPRINT_3500_0002_0001, Task T2 |
| Proof Bundle Writer | C# | ~100 | SPRINT_3500_0002_0001, Task T6 |
| Database migration (scanner schema) | SQL | ~100 | SPRINT_3500_0002_0001, Task T5 |
| EF Core entities | C# | ~80 | SPRINT_3500_0002_0001, Task T5 |
| Reachability BFS algorithm | C# | ~120 | AGENTS_SCORE_PROOFS.md, Task 3.2 |
| .NET call-graph extractor | C# | ~200 | AGENTS_SCORE_PROOFS.md, Task 3.1 |
| Unit tests | C# | ~400 | Across all tasks |
| Integration tests | C# | ~100 | SPRINT_3500_0002_0001, Integration Tests |
**Total Implementation-Ready Code**: ~1,480 lines
---
## Sprint Execution Order
```mermaid
graph LR
A[Prerequisites] --> B[3500.0002.0001<br/>Foundations]
B --> C[3500.0002.0002<br/>Unknowns]
C --> D[3500.0002.0003<br/>Replay API]
D --> E[3500.0003.0001<br/>.NET Reachability]
E --> F[3500.0003.0002<br/>Java Reachability]
F --> G[3500.0003.0003<br/>Attestations]
G --> H[3500.0004.0001<br/>CLI]
G --> I[3500.0004.0002<br/>UI]
H --> J[3500.0004.0003<br/>Tests]
I --> J
J --> K[3500.0004.0004<br/>Docs]
```
---
## Prerequisites Checklist
**Must complete BEFORE Sprint 3500.0002.0001 starts**:
- [ ] Schema governance: `scanner` and `policy` schemas approved in `docs/db/SPECIFICATION.md`
- [ ] Index design review: DBA sign-off on 15-index plan
- [ ] Air-gap bundle spec: Extend `docs/24_OFFLINE_KIT.md` with reachability format
- [ ] Product approval: UX wireframes for proof visualization (3-5 mockups)
- [ ] Claims update: Add DET-004, REACH-003, PROOF-001, UNKNOWNS-001 to `docs/market/claims-citation-index.md`
**Must complete BEFORE Sprint 3500.0003.0001 starts**:
- [ ] Java worker spec: Engineering writes Java equivalent of .NET call-graph extraction
- [ ] Soot/WALA evaluation: POC for Java static analysis
- [ ] Ground-truth corpus: 10 .NET + 10 Java test cases
- [ ] Rekor budget policy: Documented in `docs/operations/rekor-policy.md`
---
## File Map
### Sprint Files (Detailed)
```
docs/implplan/
├── SPRINT_3500_0001_0001_deeper_moat_master.md ⭐ START HERE
├── SPRINT_3500_0002_0001_score_proofs_foundations.md ⭐ DETAILED (Epic A)
├── SPRINT_3500_SUMMARY.md ⭐ QUICK REFERENCE
└── IMPLEMENTATION_INDEX.md (this file)
```
### Technical Specs
```
docs/
├── db/schemas/
│ └── scanner_schema_specification.md ⭐ DATABASE
├── api/
│ └── scanner-score-proofs-api.md ⭐ API CONTRACTS
└── product-advisories/
└── archived/17-Dec-2025/
└── 16-Dec-2025 - Building a Deeper Moat Beyond Reachability.md (processed)
```
### Implementation Guides
```
src/Scanner/
└── AGENTS_SCORE_PROOFS.md ⭐ FOR AGENTS
```
---
## Key Decisions Reference
| ID | Decision | Implication for Agents |
|----|----------|------------------------|
| DM-001 | Split into Epic A (Score Proofs) and Epic B (Reachability) | Can work on score proofs without blocking on reachability |
| DM-002 | Simplify Unknowns to 2-factor model | No centrality graphs; just uncertainty + exploit pressure |
| DM-003 | .NET + Java only in v1 | Focus on .NET and Java; defer Python/Go/Rust |
| DM-004 | Graph-level DSSE only in v1 | No edge bundles; simpler attestation flow |
| DM-005 | `scanner` and `policy` schemas | Clear schema ownership; no cross-schema writes |
---
## Success Criteria (Sprint Completion)
**Technical gates** (ALL must pass):
- [ ] Unit tests ≥85% coverage
- [ ] Integration tests pass
- [ ] Deterministic replay: bit-identical on golden corpus
- [ ] Performance: TTFRP <30s (p95)
- [ ] Database: migrations run without errors
- [ ] API: returns RFC 7807 errors
- [ ] Security: no hard-coded secrets
**Business gates**:
- [ ] Code review approved (2+ reviewers)
- [ ] Documentation updated
- [ ] Deployment checklist complete
---
## Risks & Mitigations (Top 5)
| Risk | Mitigation | Owner |
|------|------------|-------|
| Java worker POC fails | Allocate 1 sprint buffer; evaluate alternatives (Spoon, JavaParser) | Scanner Team |
| Unknowns ranking needs tuning | Ship simple 2-factor model; iterate with telemetry | Policy Team |
| Rekor rate limits in production | Graph-level DSSE only; monitor quotas | Attestor Team |
| Postgres performance degradation | Partitioning by Sprint 3500.0003.0004; load testing | DBA |
| Air-gap verification complexity | Comprehensive testing Sprint 3500.0004.0001 | AirGap Team |
---
## Contact & Escalation
**Epic Owners**:
- Epic A (Score Proofs): Scanner Team Lead + Policy Team Lead
- Epic B (Reachability): Scanner Team Lead
**Blockers**:
- If task is BLOCKED: Update delivery tracker in master plan
- If decision needed: Do NOT ask questions - mark as BLOCKED
- Escalation path: Team Lead → Architecture Guild → Product Management
**Daily Updates**:
- Update sprint delivery tracker (TODO/DOING/DONE/BLOCKED)
- Report blockers in standup
- Link PRs to sprint tasks
---
## Related Documentation
**Product Advisories**:
- `14-Dec-2025 - Reachability Analysis Technical Reference.md`
- `14-Dec-2025 - Proof and Evidence Chain Technical Reference.md`
- `14-Dec-2025 - Determinism and Reproducibility Technical Reference.md`
**Architecture**:
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
**Database**:
- `docs/db/SPECIFICATION.md`
- `docs/operations/postgresql-guide.md`
**Market**:
- `docs/market/competitive-landscape.md`
- `docs/market/claims-citation-index.md`
---
## Metrics Dashboard
**Track during execution**:
| Metric | Target | Current | Trend |
|--------|--------|---------|-------|
| Sprints completed | 10/10 | 0/10 | — |
| Code coverage | ≥85% | — | — |
| Deterministic replay | 100% | — | — |
| TTFRP (p95) | <30s | — | — |
| Precision/Recall | ≥80% | — | — |
| Blocker count | 0 | — | — |
---
## Final Checklist (Before Production)
**Epic A (Score Proofs)**:
- [ ] All 6 tasks in Sprint 3500.0002.0001 complete
- [ ] Database migrations tested
- [ ] API endpoints deployed
- [ ] Proof bundles verified offline
- [ ] Documentation published
**Epic B (Reachability)**:
- [ ] .NET and Java call-graphs working
- [ ] BFS algorithm validated on corpus
- [ ] Graph-level DSSE attestations in Rekor
- [ ] API endpoints deployed
- [ ] Documentation published
**Integration**:
- [ ] End-to-end test: SBOM → scan → proof → replay
- [ ] Load test: 10k scans/day
- [ ] Air-gap verification
- [ ] Runbooks updated
- [ ] Training delivered
---
**🎯 Ready to Start**: Read `SPRINT_3500_0001_0001_deeper_moat_master.md` first, then your assigned sprint file.
**✅ All Documentation Complete**: 4,500+ lines of implementation-ready specs and code.
**🚀 Estimated Delivery**: 20 weeks (10 sprints) from kickoff.
---
**Created**: 2025-12-17
**Maintained By**: Architecture Guild + Sprint Owners
**Status**: ✅ READY FOR EXECUTION
Reference in New Issue View Git Blame Copy Permalink