99 lines
4.6 KiB
Markdown
99 lines
4.6 KiB
Markdown
# DocForge2 Milestone 1 closeout
|
|
|
|
Milestone 1 establishes a fast, observable core without changing graph meaning, canonical
|
|
authority, the supported `docforge` identity, or the legacy adapter boundary.
|
|
|
|
## Completed contracts
|
|
|
|
- Generic projects publish a versioned source-generation receipt only after complete stable
|
|
verification.
|
|
- Routine reads validate file and membership-directory identities without parsing canonical
|
|
sources.
|
|
- Every indexed read uses one immutable read-only SQLite transaction pinned between source and
|
|
index identity checks.
|
|
- Dependency validation is linear in nodes and edges and uses an iterative deterministic cycle
|
|
check.
|
|
- Search, filtering, backlinks, dependency, impact, context, and changeset review results are
|
|
bounded independently of project size.
|
|
- Version-1 cursors bind the project, adapter, canonical generation, query, collection, and
|
|
position. Corrupt and stale cursors fail closed.
|
|
- Mutation tools preflight their minimum receipt and never report `result_too_large` after a
|
|
committed operation.
|
|
- Render status uses a publication receipt and performs no hidden render, source parse, index
|
|
rebuild, or repair.
|
|
- Visualization status separates lifecycle from source and index freshness and performs no hidden
|
|
SQLite validation or source parse.
|
|
- Request-local diagnostics expose fixed bounded stage timings and work counters without recording
|
|
source text, paths, node IDs, queries, or SQL.
|
|
|
|
Complete loading, deep index checking, deep render status, and full adapter projection remain the
|
|
recovery and equivalence oracles.
|
|
|
|
## Compatibility
|
|
|
|
The distribution, import package, three executable names, existing CLI commands, existing MCP tool
|
|
names, and required arguments remain supported. New limits, cursors, deep-status switches, and
|
|
diagnostics are additive.
|
|
|
|
A one-method `load_projection()` adapter remains supported. Incremental behavior remains optional.
|
|
The no-AST binding continues to reject Logic publication and every Logic retrieval surface,
|
|
including application refresh and live visualization.
|
|
|
|
The disposable SQLite index schema is version 3. Version 2 indexes rebuild automatically. No
|
|
canonical source or stored proposal is migrated to satisfy the new index.
|
|
|
|
## Verification
|
|
|
|
The complete repository gate passed at clean commit
|
|
`6253c45a5eca01efa8c73ea3dfe4d85c55878ada`:
|
|
|
|
- Ruff formatting and lint.
|
|
- HTML, rendered-manual HTML, CSS, and JavaScript lint.
|
|
- Pyright with zero diagnostics.
|
|
- Python compilation.
|
|
- Public-contract and no-AST checks.
|
|
- 138 tests and 77 subtests under warnings-as-errors.
|
|
- Lock and JavaScript dependency-tree checks.
|
|
- Wheel and source-distribution builds.
|
|
- Milestone 0 benchmark smoke.
|
|
- Milestone 1 counter and latency smoke.
|
|
|
|
The maintained clean 1,000-node benchmark passed every latency and work-counter threshold. Exact
|
|
retrieval measured 18.577 ms p95. Paged 32,000-token context measured 25.867 ms p95. Warm no-change
|
|
synchronization measured 9.324 ms p95. Render receipt status measured 19.613 ms p95.
|
|
Visualization status measured 10.836 ms p95.
|
|
|
|
Detailed evidence is in
|
|
[`MILESTONE_1_BASELINE.md`](MILESTONE_1_BASELINE.md) and
|
|
[`benchmarks/milestone1-2026-07-29.json`](../benchmarks/milestone1-2026-07-29.json).
|
|
|
|
## Measured decisions
|
|
|
|
SQLite remains the derived retrieval store. The benchmark demonstrates that whole-source
|
|
validation around SQLite, not SQLite retrieval itself, caused the inherited latency. No speculative
|
|
storage rewrite was made.
|
|
|
|
Receipt caches remain disposable and fail closed. A missing, corrupt, incompatible, foreign, or
|
|
changed receipt falls back to the complete oracle or reports an explicit unverified state according
|
|
to the operation's safety contract.
|
|
|
|
Pagination is transport state, not project authority. It adds no database and grants no
|
|
authorization.
|
|
|
|
## Remaining weaknesses
|
|
|
|
- Context selection is bounded but not yet streaming internally.
|
|
- Scaled incremental-adapter performance remains unmeasured.
|
|
- Generic cheap generation proof uses filesystem identity rather than content hashing on every
|
|
read.
|
|
- Legacy adapters without incremental state cannot always prove current identity cheaply.
|
|
- One oversized context entry requires targeted retrieval after an explicit omission.
|
|
- Operation-local and detached-worker memory need a maintained isolated harness.
|
|
- Tree-sitter and its JavaScript and C++ grammars remain mandatory package dependencies.
|
|
- `ManualRenderPlan`, `GraphViewPlan`, and independent renderer packages remain Milestone 3 work.
|
|
|
|
## Scope confirmation
|
|
|
|
Milestone 1 did not self-host DocForge2, change WorldForge or ScrapeStation, repoint a production
|
|
MCP integration, modify the legacy Forgejo repository, create a tag, or create a release.
|
|
|