# 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.