Document the 1.4.0 release candidate
This commit is contained in:
parent
2b98059b44
commit
49e1a87c13
13 changed files with 739 additions and 26 deletions
187
docs/MILESTONE_5_BASELINE.md
Normal file
187
docs/MILESTONE_5_BASELINE.md
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
# Milestone 5 baseline
|
||||
|
||||
## Status and method
|
||||
|
||||
This baseline records the frozen DocForge `1.4.0` release candidate. It is release-candidate
|
||||
evidence, not a claim that the tag or Forgejo release already exists.
|
||||
|
||||
The executable implementation freeze is
|
||||
`d2bb95fe6190e659cf66ba57c78be53b63b53240`. Fresh-clone legacy-tag verification was added in
|
||||
`97f3b6b1ae303c972387508557a3d54ea621a702`, and the maintained aggregate recovery proofs were
|
||||
completed in
|
||||
`2b98059b44f4d46b4d4cce776f163e893c647c76`. The final tag must point to the later
|
||||
documentation-bearing commit after its clean fresh-clone gate.
|
||||
|
||||
The clean executable candidate used:
|
||||
|
||||
- Linux 7.1.3-200.nobara.fc44.x86_64 with glibc 2.43.
|
||||
- CPython 3.14.6 on x86_64.
|
||||
- The repository lockfile and offline wheel inputs.
|
||||
- Maintained repository-native gates rather than a self-hosted DocForge development loop.
|
||||
|
||||
No WorldForge, ScrapeStation, legacy repository, production binding, or production MCP
|
||||
configuration was changed.
|
||||
|
||||
## Quality and compatibility gates
|
||||
|
||||
The clean executable candidate passed:
|
||||
|
||||
- Ruff formatting and lint, web lint, strict Pyright with zero diagnostics, and compilation.
|
||||
- 142 contract tests plus 272 subtests.
|
||||
- 371 complete tests plus 419 subtests.
|
||||
- Three Playwright and axe accessibility flows covering the manual, portable graph, and live
|
||||
viewer.
|
||||
- Lockfile, dependency-tree, wheel, source-distribution, generated-reference, and documentation
|
||||
checks.
|
||||
- 116 compatibility tests plus 263 subtests.
|
||||
- 29 concurrency tests plus 2 subtests.
|
||||
- Offline fresh-wheel adoption, exact version identity, reproducible artifact, and secret-scan
|
||||
gates.
|
||||
- The complete maintained Milestone 0 through Milestone 4 benchmark sequence.
|
||||
|
||||
The later maintained recovery proof adds four tests without changing executable product code. Its
|
||||
aggregate recovery gate passes 72 tests plus 62 subtests. A final clean clone must rerun the
|
||||
complete totals from the documentation-bearing commit before tagging.
|
||||
|
||||
Compatibility remains additive:
|
||||
|
||||
- The `docforge` distribution and imports, CLI, generic MCP executable, MCP tool names, generic
|
||||
project descriptor, result envelopes, legacy one-method adapter, and no-AST behavior remain.
|
||||
- Effective policy version 1, projection policy version 2, descriptor schema version 1, and index
|
||||
schema version 3 remain the current authorities.
|
||||
- Complete and incremental maintained adapters produce exact primary-graph and Logic equivalence.
|
||||
|
||||
## Version and artifact identity
|
||||
|
||||
One source file owns version `1.4.0`. The following executable surfaces reported that exact
|
||||
version:
|
||||
|
||||
- `docforge`
|
||||
- `docforge-mcp`
|
||||
- `docforge-viewer-manager`
|
||||
- `python -m docforge.reference_mcp`
|
||||
|
||||
The package metadata also reported `docforge 1.4.0`, Python 3.12 or newer, the MIT license
|
||||
expression, the public Forgejo repository, and its issues URL. Generated client bindings include
|
||||
the version in their validated, hash-bound identity.
|
||||
|
||||
Two independent builds from the executable candidate and the same source-date epoch produced
|
||||
identical artifacts:
|
||||
|
||||
| Artifact | Bytes | Executable-candidate SHA-256 |
|
||||
|---|---:|---|
|
||||
| Wheel | 315,811 | `c3b9bfa320d00d827154e0f858a6b970459ae0eba6ab14e1cd4f6ba470e33b6a` |
|
||||
| Source distribution | 685,891 | `bb5f9333e5fa2365cf0f8ac12d7920122315b4835c9f81b7aa457eb05f1702f5` |
|
||||
|
||||
Both contained the license and version authority. These identify the executable freeze only.
|
||||
Documentation changes alter the final release artifacts, so final checksums must be generated from
|
||||
the exact tagged documentation-bearing commit.
|
||||
|
||||
The release channel is Forgejo only. PyPI is excluded because the `docforge` name is occupied by an
|
||||
unrelated project.
|
||||
|
||||
## Exact migration evidence
|
||||
|
||||
The migration gate archives and executes the real annotated `v1.0.0` lineage:
|
||||
|
||||
- Tag object: `2d7d306a37da89f1c860c7f0be161c45386acf61`.
|
||||
- Peeled commit: `593c173b453236a6872d0a4e88e7a51a67a21cde`.
|
||||
- Canonical byte hash before and after:
|
||||
`9fde91b6b08669177d690cdf9f91b162120baee1f7e24b05fec67f56617f286a`.
|
||||
- Snapshot hash before and after:
|
||||
`45bef8b0e1a4dac976e096dcf8f9048e1268211cd7f7638cdf99951428ec0500`.
|
||||
- Active proposal hash:
|
||||
`2c055dfae45443b4a4d9d4087ef70959e7293beae8d27acb14ffffe52eca7111`.
|
||||
- Active proposal file hash:
|
||||
`4658d494b43bd7c6cc3e3f5933a2c878c817b52bc4566e9e8429e7b8e43ca007`.
|
||||
|
||||
The version-1 disposable index rebuilt from schema 1 to schema 3. Canonical bytes, graph meaning,
|
||||
and the active proposal remained exact. The current CLI is a 28-command superset of the version-1
|
||||
20-command surface. The current generic MCP surface is a 36-tool superset of the version-1
|
||||
25-tool surface.
|
||||
|
||||
The proof also preserves a real inherited version-1 inconsistency: package metadata reports
|
||||
`1.0.0`, while its Python module and server report `0.15.0`. Migration evidence records that fact;
|
||||
it does not rewrite history to make the old identities agree.
|
||||
|
||||
## Recovery and concurrency evidence
|
||||
|
||||
The maintained gates prove:
|
||||
|
||||
- Concurrent canonical-source changes fail closed without publishing or serving mixed
|
||||
generations.
|
||||
- Exact-hash canonical application uses project-owned serialization and compare-and-swap
|
||||
publication, rejects stale proposals, and preserves raced source data.
|
||||
- Extraction caches and SQLite indexes rebuild from canonical sources or complete adapter
|
||||
projections.
|
||||
- Corrupt index attestations, manual render receipts, generation-diff receipts, and portable-graph
|
||||
manifests recover through their normal synchronize, rebuild, or render entry points.
|
||||
- Recovery preserves exact canonical bytes, the canonical collection hash, the complete snapshot
|
||||
hash, and primary-graph-plus-Logic index identity.
|
||||
- Derived publication uses durable atomic replacement and directory synchronization.
|
||||
|
||||
The release does not claim that a multi-file canonical application is process-death atomic. A
|
||||
malicious same-UID process deliberately modifying the private mode-0700 transaction directory is
|
||||
also outside the application race contract. Those limits do not weaken the maintained
|
||||
concurrent-canonical-source compare-and-swap proof.
|
||||
|
||||
## Representative real-task evidence
|
||||
|
||||
The real-package track uses installed, lock-pinned `markdown-it-py 4.2.0`:
|
||||
|
||||
- 66 Python files.
|
||||
- 225,945 source bytes.
|
||||
- Source-tree SHA-256:
|
||||
`bd57c9f332fcf6507282ec2023e6804fce0cf844631696336ee17cbe46e63aad`.
|
||||
- No network, production binding, installed-source mutation, or self-hosting.
|
||||
- Python reference-adapter local-import projection for graph-assisted work.
|
||||
- Independent standard-library AST import inspection for source-only work.
|
||||
|
||||
Both workflows returned the exact reviewed answer for all three tasks:
|
||||
|
||||
| Task | Graph inspected | Source inspected | Graph median | Source median |
|
||||
|---|---:|---:|---:|---:|
|
||||
| Renderer direct dependencies | 349 B | 10,628 B | 0.008 ms | 1.341 ms |
|
||||
| Three-level HTML-block impact | 419 B | 225,945 B | 0.009 ms | 32.108 ms |
|
||||
| CLI-to-core-state path | 212 B | 225,945 B | 0.013 ms | 32.142 ms |
|
||||
|
||||
Per-task latency excludes the separately reported one-time graph preparation. Graph-assisted
|
||||
answers inspected substantially fewer agent-visible bytes and carried generation-bound
|
||||
provenance. The source-only answers were smaller on the final response-size metric. The comparison
|
||||
therefore records the measured tradeoff rather than claiming that every metric favors the graph.
|
||||
|
||||
The real-package semantic evidence SHA-256 is
|
||||
`c8c19b2900fa47abdaff94f5b13fd9ca537241089edc97b30d32d9db8809a2c1`.
|
||||
The combined real and generated-track evidence SHA-256 is
|
||||
`45952883b47449eb4fd862b51854aa2001749928e0d37c5a6e58c2d3292fbee4`.
|
||||
|
||||
## Machine-readable evidence
|
||||
|
||||
The maintained evidence generators emit canonical compact JSON and can write it atomically with
|
||||
their `--output` option:
|
||||
|
||||
```bash
|
||||
.venv/bin/python tools/milestone5_migration.py --output /tmp/docforge-m5-migration.json
|
||||
.venv/bin/python tools/milestone5_task_evidence.py \
|
||||
--mode full --output /tmp/docforge-m5-task-evidence.json
|
||||
.venv/bin/python tools/check_release_identity.py \
|
||||
--mode full --require-clean --tag-state absent \
|
||||
--output /tmp/docforge-m5-release-identity.json
|
||||
.venv/bin/python tools/milestone5_fresh_clone.py \
|
||||
--commit "$(git rev-parse HEAD)" \
|
||||
--output /tmp/docforge-m5-fresh-clone.json
|
||||
```
|
||||
|
||||
Migration, task, release identity, artifact hashes, and the final anonymous-clone result therefore
|
||||
remain reproducible machine evidence rather than prose-only claims. The final Forgejo release
|
||||
attaches the release-identity JSON beside the wheel and source distribution.
|
||||
|
||||
## Remaining release gate
|
||||
|
||||
The baseline is complete for the release candidate. Milestone 5 remains active until:
|
||||
|
||||
1. The documentation closeout is committed.
|
||||
2. `main` and `dev` are synchronized and pushed.
|
||||
3. The exact final commit passes the maintained fresh anonymous clone gate.
|
||||
4. Final artifacts and checksums are generated from that commit.
|
||||
5. The annotated `v1.4.0` tag and Forgejo release are created and verified.
|
||||
Loading…
Add table
Add a link
Reference in a new issue