administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages

Close Milestone 1 fast core

Browse source
This commit is contained in:
Andraxion 2026-07-29 06:11:22 -04:00
parent 6253c45a5e
commit a9a75c5c27
6 changed files with 1626 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

52
DEVELOPMENT_NOTES.md
View file

@ -26,7 +26,7 @@ The central measurement was decisive: a 1,000-node warm exact lookup took about
generation-pinned SQLite query path took about 0.4–1.4 ms. Repeated whole-source loading and
validation, not SQLite, is the first optimization target.
## Milestone 1 — active: fast, observable core
## Milestone 1 — complete: fast, observable core
### Outcome
@ -45,13 +45,12 @@ of project size.
and exact retrieval sub-millisecond on a tiny fixture.
- Pinned viewer queries prove the current SQLite schema can serve bounded reads quickly.
### Current work
### Final outcome
1. Audit request-scoped immutable snapshot and persistent-generation options.
2. Audit result receipts, pagination, bounded response contracts, and side-effect-free status.
3. Audit graph validation complexity, indexed traversal, profiling, and zero-source-parse proofs.
4. Reconcile the audits into the smallest additive design that preserves v1 behavior.
5. Implement and measure coherent slices, committing only after their gates pass.
Routine generic reads now parse zero canonical source files, use one generation-pinned SQLite
snapshot, and return bounded results. Status checks perform no hidden rendering or rebuilding.
Structured counters prove those invariants independently of machine timing. Complete loading and
deep validation remain recovery and equivalence oracles.
### Work log
@ -116,20 +115,20 @@ backlinks, dependency, impact, context, and no-change synchronization operations
`Project.load()` is forbidden. They also prove a final source-generation change is rejected before
return and missing/corrupt receipts fall back and repair.
On the maintained 1,000-file fixture, the current work-in-progress measurements are:
The final clean 1,000-file run recorded:
| Operation | Milestone 0 median | Milestone 1 WIP median |
|---|---:|---:|
| Warm no-change synchronize | 142.479 ms | 20.007 ms |
| Exact node | 286.306 ms | 40.277 ms |
| Search, limit 20 | 288.793 ms | 41.455 ms |
| Dependencies, depth 8 | 287.791 ms | 41.551 ms |
| Context, 32k | 436.897 ms | 46.245 ms |
| MCP exact node | 287.094 ms | 40.051 ms |
| MCP context, 32k | 434.853 ms | 46.454 ms |
| Operation | Milestone 0 median | Milestone 1 median | Milestone 1 p95 |
|---|---:|---:|---:|
| Warm no-change synchronize | 142.479 ms | 9.192 ms | 9.324 ms |
| Exact node | 286.306 ms | 17.887 ms | 18.577 ms |
| Search, limit 20 | 288.793 ms | 19.518 ms | 19.884 ms |
| Dependencies, depth 8 | 287.791 ms | 18.117 ms | 19.061 ms |
| Context, 32k, page 20 | 436.897 ms | 25.395 ms | 25.867 ms |
| Render status | 150.591 ms | 18.969 ms | 19.613 ms |
| Visualization status | — | 9.875 ms | 10.836 ms |
The three-sample WIP run is directional, not the final Milestone 1 baseline. The final evidence run
will use the maintained sample counts and committed clean-tree revision.
The recorded run came from clean commit `6253c45a5eca01efa8c73ea3dfe4d85c55878ada`.
Every measured operation passed its p95 threshold and work-counter contract.
#### Read-only audit reconciliation
@ -245,8 +244,8 @@ The result JSON schema contains the same closed operation, stage, and counter se
implementation.
The maintained `tools/milestone1_benchmark.py` harness adds hard counter and p95 latency gates to a
disposable generic project. The smoke target is part of `make gate`; the 1,000-node evidence run
will be recorded only from a clean committed revision. The historical Milestone 0 harness remains
disposable generic project. The smoke target is part of `make gate`; the final 1,000-node evidence
is recorded in `benchmarks/milestone1-2026-07-29.json`. The historical Milestone 0 harness remains
behaviorally unchanged as comparison evidence; it only exposes shared fixture and measurement
helpers to the Milestone 1 harness.
@ -308,6 +307,17 @@ incoming traversal, and measures current/stale/missing/corrupt render receipts p
visualization lifecycle states. A maintained query-plan test prevents the incoming traversal
temporary sort from returning.
#### Milestone closeout
The complete repository gate passed with 138 tests and 77 subtests, zero Pyright diagnostics,
warning-strict execution, package builds, contract checks, and both benchmark smoke gates. The
clean 1,000-node benchmark passed all maintained thresholds and is interpreted in
`docs/MILESTONE_1_BASELINE.md`. Compatibility, measured decisions, limitations, and scope evidence
are frozen in `docs/MILESTONE_1_CLOSEOUT.md`.
Milestone 1 made no storage rewrite, self-hosting change, production integration change, tag, or
release.
### Initial design constraints
- Full rebuild remains the recovery and equivalence oracle.