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
|
|
@ -96,3 +96,33 @@ The release candidate must prove all of the following from maintained, reproduci
|
|||
artifacts.
|
||||
|
||||
The completed Milestone 4 contract and exclusions remain preserved in `SLICE_HISTORY.md`.
|
||||
|
||||
## Release-candidate evidence — 2026-07-29
|
||||
|
||||
The executable implementation is frozen at
|
||||
`d2bb95fe6190e659cf66ba57c78be53b63b53240`. The proof-bearing candidate base is
|
||||
`2b98059b44f4d46b4d4cce776f163e893c647c76`; it includes exact legacy-tag verification for the
|
||||
fresh-clone gate and four maintained aggregate derived-recovery tests.
|
||||
|
||||
The clean executable release gate passed formatting, Python and web lint, strict Pyright,
|
||||
compilation, lock and dependency checks, builds, generated documentation, three accessibility
|
||||
flows, fresh-wheel adoption, artifact reproducibility, secret scans, and the full Milestone 0
|
||||
through Milestone 4 benchmark sequence. Its exact test evidence was:
|
||||
|
||||
- 142 contract tests plus 272 subtests.
|
||||
- 371 complete tests plus 419 subtests.
|
||||
- 116 compatibility tests plus 263 subtests.
|
||||
- 29 concurrency tests plus 2 subtests.
|
||||
- 68 recovery tests plus 62 subtests.
|
||||
|
||||
The real migration gate preserves exact canonical and proposal bytes from the annotated `v1.0.0`
|
||||
lineage while rebuilding the disposable index from schema 1 to schema 3. The real-package task
|
||||
gate uses the lock-pinned `markdown-it-py 4.2.0` tree and proves exact graph-assisted and
|
||||
source-only answers for all reviewed tasks.
|
||||
|
||||
The later proof-only recovery commit adds four maintained tests without changing executable
|
||||
product code. The current recovery aggregate passes 72 tests plus 62 subtests.
|
||||
|
||||
Milestone 5 remains active. Documentation closeout, final branch synchronization, a fresh
|
||||
anonymous clone at the exact documentation-bearing remote commit, final artifact checksums, the
|
||||
annotated `v1.4.0` tag, and the Forgejo release are still pending. No PyPI publication is planned.
|
||||
|
|
|
|||
57
CHANGELOG.md
Normal file
57
CHANGELOG.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
# Changelog
|
||||
|
||||
Notable changes in the DocForge product line are recorded here. Historical milestone evidence
|
||||
remains in `docs/MILESTONE_*_BASELINE.md` and `docs/MILESTONE_*_CLOSEOUT.md`.
|
||||
|
||||
## Unreleased
|
||||
|
||||
### DocForge 1.4.0 release candidate
|
||||
|
||||
Version `1.4.0` is frozen as an additive successor release. The annotated tag and Forgejo release
|
||||
do not exist yet; Milestone 5 remains active until the final documentation-bearing commit passes
|
||||
the fresh-clone gate and publication is verified.
|
||||
|
||||
Added:
|
||||
|
||||
- One authoritative version shared by package metadata, Python, CLI, generic MCP, reference MCP,
|
||||
viewer manager, generated client bindings, and release checks.
|
||||
- Public adapter SDK and complete graph-plus-Logic conformance checks.
|
||||
- Base Python and optional JavaScript, TypeScript, and C++ reference adapters.
|
||||
- Task-shaped retrieval, generation diffs, generated client configuration, doctor checks, and
|
||||
bounded response continuation.
|
||||
- Independent manual, portable-graph, and live-viewer projections with immutable packages,
|
||||
receipts, policy enforcement, and accessibility gates.
|
||||
- Maintained compatibility, migration, concurrency, recovery, representative-task,
|
||||
fresh-wheel, artifact-reproducibility, secret-scan, and benchmark gates.
|
||||
- MIT licensing and Forgejo repository metadata.
|
||||
|
||||
Changed:
|
||||
|
||||
- Warm graph reads use generation-bound SQLite state without reparsing canonical project sources.
|
||||
- Incremental adapters use bounded extraction caches while retaining a complete-build equivalence
|
||||
oracle.
|
||||
- Generated client configuration is bound to the exact DocForge version.
|
||||
- Derived publication uses durable atomic replacement and fails closed on malformed, foreign,
|
||||
stale, oversized, or incompatible state.
|
||||
- Generic canonical application uses project-owned locking, compare-and-swap publication, and
|
||||
exact-hash proposal checks while preserving raced source data.
|
||||
|
||||
Compatibility:
|
||||
|
||||
- The `docforge` distribution and Python package, `docforge` CLI, `docforge-mcp`, MCP tool names,
|
||||
legacy one-method adapters, generic projects, and descriptor schema version 1 remain supported.
|
||||
- Version `1.4.0` rebuilds disposable version-1 indexes as version 3 without rewriting canonical
|
||||
source or active proposal bytes.
|
||||
- The base wheel has no Tree-sitter dependency. Optional language extras remain explicit.
|
||||
|
||||
Release channels:
|
||||
|
||||
- The intended release channel is the public Forgejo repository and its release artifacts.
|
||||
- PyPI publication is not planned because the `docforge` name is occupied by an unrelated
|
||||
project.
|
||||
|
||||
## 1.0.0 - 2026-07-25
|
||||
|
||||
The first stable release established the project-scoped graph, generic Markdown/TOML adapter,
|
||||
SQLite index, project-bound CLI and MCP server, reviewable exact-hash changesets, declared manual
|
||||
rendering, visualization, and the original versioned compatibility surface.
|
||||
|
|
@ -31,6 +31,51 @@ policy, projection, task-comparison, package, clone, browser, benchmark, and sec
|
|||
pass before documentation closeout, tag creation, or publication. `main` remains the Milestone 4
|
||||
baseline while implementation proceeds on `dev`.
|
||||
|
||||
### Release-candidate freeze — 2026-07-29
|
||||
|
||||
The executable implementation froze at
|
||||
`d2bb95fe6190e659cf66ba57c78be53b63b53240`. It centralizes version `1.4.0`, binds generated
|
||||
clients to that version, adds MIT license and package metadata, proves reproducible artifacts,
|
||||
migrates a real archived `v1.0.0` project, maintains comparative real-task evidence, and hardens
|
||||
derived and canonical publication against measured race and durability failures.
|
||||
|
||||
The clean executable release gate passed:
|
||||
|
||||
- Ruff formatting and lint, web lint, strict Pyright, compilation, lock, dependency, build,
|
||||
generated-reference, and documentation checks.
|
||||
- 142 contract tests plus 272 subtests and 371 complete tests plus 419 subtests.
|
||||
- Three manual, portable-graph, and live-viewer accessibility flows.
|
||||
- 116 compatibility tests plus 263 subtests.
|
||||
- 29 concurrency tests plus 2 subtests.
|
||||
- Offline fresh-wheel adoption, reproducible artifacts, version checks, and secret scans.
|
||||
- Every maintained full Milestone 0 through Milestone 4 benchmark.
|
||||
|
||||
Commit `97f3b6b` made the fresh-clone rehearsal require and verify the exact annotated legacy tag.
|
||||
Commit `2b98059b44f4d46b4d4cce776f163e893c647c76` added four maintained recovery proofs without
|
||||
changing product code. The recovery aggregate now passes 72 tests plus 62 subtests. Those tests
|
||||
record exact canonical bytes, canonical collection hash, complete snapshot hash, and index
|
||||
graph-plus-Logic identity before corrupting and repairing the index attestation, manual render
|
||||
receipt, generation-diff receipt, and portable-graph manifest through normal public work paths.
|
||||
|
||||
The real migration evidence uses tag object
|
||||
`2d7d306a37da89f1c860c7f0be161c45386acf61`, peeled commit
|
||||
`593c173b453236a6872d0a4e88e7a51a67a21cde`, and a real schema-1 index plus active proposal.
|
||||
Canonical bytes, the graph snapshot, proposal hash, and proposal file bytes remain exact after the
|
||||
schema-3 rebuild. The proof retains the inherited version-1 metadata/runtime mismatch: package
|
||||
metadata is `1.0.0`, while the module and server report `0.15.0`.
|
||||
|
||||
The representative real-task track pins `markdown-it-py 4.2.0` at 66 Python files and 225,945
|
||||
bytes. Both workflows answer all three reviewed questions exactly. Graph-assisted work inspects
|
||||
349 versus 10,628 bytes, 419 versus 225,945 bytes, and 212 versus 225,945 bytes, with medians of
|
||||
0.008 versus 1.341 ms, 0.009 versus 32.108 ms, and 0.013 versus 32.142 ms. Source-only final
|
||||
responses are smaller, so the evidence claims reduced inspected source and faster maintained task
|
||||
latency rather than a universal response-size advantage.
|
||||
|
||||
Documentation closeout is now being prepared against this frozen lineage. Milestone 5 remains
|
||||
active until the final documentation-bearing commit is pushed, passes the exact fresh-clone
|
||||
rehearsal, and is published through one annotated `v1.4.0` tag and Forgejo release. PyPI remains
|
||||
excluded.
|
||||
|
||||
## Milestone 0 — complete
|
||||
|
||||
Milestone 0 established the public successor, preserved the complete lineage and v1 tag, integrated
|
||||
|
|
|
|||
28
README.md
28
README.md
|
|
@ -9,10 +9,10 @@ DocForge never treats indexed text as instructions. It does not run project buil
|
|||
compilers, Git operations, deployments, or arbitrary renderers, and it does not select projects
|
||||
globally.
|
||||
|
||||
DocForge 1.0.0 remains the first stable release in this product line. This checkout is the
|
||||
post-1.0 development line (`1.3.0.dev0`) and contains the Milestone 4 adapter-platform work.
|
||||
Milestone 4 is not a new product release, and Milestone 5 release and publication work remains
|
||||
separate.
|
||||
DocForge 1.0.0 remains the latest published stable release in this product line. This checkout is
|
||||
the `1.4.0` release candidate and contains the complete Milestone 4 adapter platform plus
|
||||
Milestone 5 stabilization evidence. The `v1.4.0` tag and Forgejo release are still pending; this
|
||||
candidate is not published yet.
|
||||
|
||||
## Start here
|
||||
|
||||
|
|
@ -23,6 +23,8 @@ separate.
|
|||
- Agent and client setup: [Agent integration](docs/AGENT_INTEGRATION.md)
|
||||
- Exact live command and tool inventory: [Generated command reference](docs/COMMAND_REFERENCE.md)
|
||||
- Task-oriented operating guide: [User manual](docs/USER_MANUAL.md)
|
||||
- Release-candidate changes and evidence: [Changelog](CHANGELOG.md) and [Milestone 5
|
||||
baseline](docs/MILESTONE_5_BASELINE.md)
|
||||
|
||||
## Current capabilities
|
||||
|
||||
|
|
@ -210,6 +212,8 @@ paths.
|
|||
|
||||
### Milestone evidence
|
||||
|
||||
- [Milestone 5 baseline](docs/MILESTONE_5_BASELINE.md)
|
||||
- [Milestone 5 release-candidate closeout](docs/MILESTONE_5_CLOSEOUT.md)
|
||||
- [Milestone 4 baseline](docs/MILESTONE_4_BASELINE.md)
|
||||
- [Milestone 4 closeout](docs/MILESTONE_4_CLOSEOUT.md)
|
||||
- [Milestone 3 baseline](docs/MILESTONE_3_BASELINE.md) and [closeout](docs/MILESTONE_3_CLOSEOUT.md)
|
||||
|
|
@ -244,6 +248,22 @@ Python reference plus a real isolated read-only MCP retrieval. The optional-lang
|
|||
have their own focused tests and extras. `benchmark-m4` runs the maintained full adapter workload;
|
||||
the smoke target is for routine gate coverage, not final performance evidence.
|
||||
|
||||
Milestone 5 adds focused and aggregate release-candidate gates:
|
||||
|
||||
```bash
|
||||
make compatibility-m5
|
||||
make migration-m5
|
||||
make concurrency-m5
|
||||
make recovery-m5
|
||||
make task-evidence-m5
|
||||
make release-gate
|
||||
make fresh-clone-m5
|
||||
```
|
||||
|
||||
`release-gate` includes the complete repository, accessibility, adoption, artifact-reproducibility,
|
||||
secret-scan, and full maintained benchmark sequence. `fresh-clone-m5` is the final remote-commit
|
||||
rehearsal and must pass before the annotated tag and Forgejo release are created.
|
||||
|
||||
Pass `--diagnostics` to `docforge` or `docforge-mcp` for bounded request-local timings and compiler
|
||||
work counters. Diagnostics are disabled by default and do not displace a primary result when the
|
||||
configured output budget is tight.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,46 @@
|
|||
# Completed slices
|
||||
# Release candidates and completed slices
|
||||
|
||||
## DocForge2 Milestone 5 release candidate — active
|
||||
|
||||
### Changed
|
||||
|
||||
- Centralized version `1.4.0` across package metadata, Python, executable surfaces, generated
|
||||
clients, and release validation.
|
||||
- Added MIT licensing, public Forgejo metadata, reproducible artifact checks, a real archived-v1
|
||||
migration proof, focused compatibility/concurrency/recovery gates, and representative
|
||||
graph-assisted versus source-only task evidence.
|
||||
- Hardened durable derived publication and generic exact-hash canonical application against
|
||||
measured race windows.
|
||||
- Added a fresh-clone rehearsal that requires the exact annotated legacy tag.
|
||||
|
||||
### Verification
|
||||
|
||||
- The clean executable candidate passed 371 tests and 419 subtests, 142 contract tests and 272
|
||||
subtests, three accessibility flows, lint, strict types, compilation, dependencies, builds,
|
||||
adoption, reproducible artifacts, secret scans, and every maintained full benchmark.
|
||||
- Focused compatibility passed 116 tests plus 263 subtests. Concurrency passed 29 tests plus 2
|
||||
subtests.
|
||||
- Four later proof-only tests brought the recovery gate to 72 tests plus 62 subtests without
|
||||
changing executable product code.
|
||||
- Real `v1.0.0` migration preserved canonical, graph, and proposal evidence while rebuilding the
|
||||
disposable index from schema 1 to schema 3.
|
||||
- The lock-pinned real-package comparison returned exact answers from both workflows and measured
|
||||
substantially less inspected source for graph-assisted work.
|
||||
|
||||
### Limits
|
||||
|
||||
- This is release-candidate evidence, not a completed milestone or published release.
|
||||
- Multi-file canonical application does not claim process-death atomicity.
|
||||
- Source-only task responses were smaller even where graph-assisted work inspected fewer bytes and
|
||||
ran faster.
|
||||
- No WorldForge, ScrapeStation, legacy repository, production binding, self-hosting, PyPI, tag, or
|
||||
Forgejo release was changed.
|
||||
|
||||
### Final gate
|
||||
|
||||
Commit the documentation closeout, synchronize the final branches, pass the exact fresh anonymous
|
||||
clone, build final checksummed artifacts, and then create and verify the annotated `v1.4.0` tag and
|
||||
Forgejo release. Milestone 5 remains active until that sequence succeeds.
|
||||
|
||||
## DocForge2 Milestone 4 adapter SDK and product documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,9 @@
|
|||
# DocForge2 Milestone 0 compatibility contract
|
||||
# DocForge compatibility contract
|
||||
|
||||
Milestone 0 establishes DocForge2 as the successor repository without renaming or replacing the
|
||||
working DocForge interfaces. Compatibility changes require an explicit decision, a contract-test
|
||||
update, and migration guidance.
|
||||
update, and migration guidance. DocForge 1.4.0 preserves that baseline and adds the adapter,
|
||||
rendering, recovery, and release surfaces recorded below.
|
||||
|
||||
The compatibility gate is:
|
||||
|
||||
|
|
@ -16,6 +17,11 @@ The complete repository gate is:
|
|||
make gate
|
||||
```
|
||||
|
||||
Milestone 5 also maintains `make compatibility-m5` for the frozen public, adapter, policy,
|
||||
projection, rendering, and retrieval matrix. `make release-gate` aggregates that matrix with
|
||||
migration, concurrency, recovery, task-evidence, adoption, version, artifact, secret-scan, browser,
|
||||
and benchmark proofs.
|
||||
|
||||
## Distribution and Python imports
|
||||
|
||||
The Python distribution and import package remain `docforge`.
|
||||
|
|
@ -63,6 +69,12 @@ names and arguments remain supported. Additive commands, tools, and response fie
|
|||
Removing or changing an existing name, required argument, stable error code, or safety boundary
|
||||
requires an explicit compatibility decision.
|
||||
|
||||
Version `1.4.0` comes from one `docforge._version` authority. The four maintained executable
|
||||
surfaces report `docforge 1.4.0`, `docforge-mcp 1.4.0`,
|
||||
`python -m docforge.reference_mcp 1.4.0`, and `docforge-viewer-manager 1.4.0` for `--version`.
|
||||
Generated generic and adapter client configurations include and hash-bind the same
|
||||
`docforge_version`.
|
||||
|
||||
MCP results retain:
|
||||
|
||||
- A structured `status`.
|
||||
|
|
@ -191,6 +203,14 @@ The following guarantees remain stable:
|
|||
6. Canonical application is absent unless one startup-bound applier is configured.
|
||||
7. Derived refresh failures produce an explicit degraded receipt after canonical application. They
|
||||
do not make an applied proposal safe to apply twice.
|
||||
8. Generic canonical publication compares exact target identity at the commit boundary. Concurrent
|
||||
create, update, and delete mutations fail closed, roll back when exact state remains provable, or
|
||||
retain recovery evidence without overwriting foreign data.
|
||||
9. Per-file publication is atomic and in-process rollback covers earlier publications, but
|
||||
canonical application has no process-death journal and does not promise multi-file crash
|
||||
atomicity.
|
||||
10. Cleanup degradation after semantic commit closes the proposal as `applied` and persists bounded
|
||||
`application_recovery` lifecycle metadata instead of returning a retryable ordinary failure.
|
||||
|
||||
## Rendering and visualization
|
||||
|
||||
|
|
@ -260,6 +280,15 @@ symbolic-link escapes. Documentation text remains untrusted data. Normal MCP ope
|
|||
arbitrary filesystem access, renderer execution, shell command, Git mutation, deployment,
|
||||
publication, or project switching.
|
||||
|
||||
DocForge is not a filesystem sandbox. Mode-0700 canonical transaction directories protect against
|
||||
other users and ordinary path access; deliberate arbitrary tampering by another process with the
|
||||
same operating-system UID is outside the compatibility boundary.
|
||||
|
||||
The historical `v1.0.0` release carried distribution metadata `1.0.0` while its module and MCP
|
||||
runtime reported `0.15.0`. Version 1.4.0 records that inherited mismatch in its maintained
|
||||
migration proof and resolves current identity through one authority. See
|
||||
[migrating from v1](MIGRATING_FROM_V1.md).
|
||||
|
||||
## Recorded weaknesses, not compatibility promises
|
||||
|
||||
Milestone 0 records rather than redesigns these areas:
|
||||
|
|
@ -268,7 +297,6 @@ Milestone 0 records rather than redesigns these areas:
|
|||
- The base wheel intentionally omits Tree-sitter. JavaScript, TypeScript, and C++ syntax evidence
|
||||
requires the matching `docforge[javascript]`, `docforge[typescript]`, or `docforge[cpp]` extra.
|
||||
Python reference evidence uses the standard library and remains available in the base wheel.
|
||||
- Several version strings and defaults remain duplicated.
|
||||
- One individually oversized context entry is represented as explicit bounded omission evidence;
|
||||
callers use targeted retrieval for that node.
|
||||
- One individually oversized changeset diff is transported as reconstructable canonical-JSON
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# DocForge post-1.0 development contract
|
||||
# DocForge 1.4 contract
|
||||
|
||||
## Authority boundary
|
||||
|
||||
|
|
@ -34,13 +34,19 @@ commit when Git is available; it cannot change repository state.
|
|||
- Reference adapter configuration: `schemas/reference-adapter.schema.json`, version 1.
|
||||
- Index schema: version 3, disposable and reproducible.
|
||||
- Index attestation: schema version 1, disposable and reproducible.
|
||||
- Core, CLI, and MCP server: version 1.3.0.dev0.
|
||||
- Distribution, Python package, CLI, generic MCP, reference MCP, and viewer manager: version 1.4.0.
|
||||
- Incremental extraction cache: version 1, disposable and reproducible.
|
||||
|
||||
Schema files describe the generic interchange contract. Runtime validation remains responsible for
|
||||
path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
|
||||
state, and adapter-specific rules that JSON Schema cannot prove by itself.
|
||||
|
||||
`src/docforge/_version.py` is the sole package-version authority. The maintained executable
|
||||
surfaces report exactly `docforge 1.4.0`, `docforge-mcp 1.4.0`,
|
||||
`python -m docforge.reference_mcp 1.4.0`, and `docforge-viewer-manager 1.4.0` for `--version`.
|
||||
Generated generic and adapter client configurations bind `docforge_version` into their validated
|
||||
hashes.
|
||||
|
||||
## Generic node storage
|
||||
|
||||
Markdown nodes begin with a TOML metadata block delimited by `+++`. The remaining Markdown is the
|
||||
|
|
@ -73,6 +79,13 @@ Index replacement is the derived publication commit point. Attestation, cheap so
|
|||
and latest-generation-diff receipts are independent post-commit evidence. Their failure produces
|
||||
bounded degraded success and never falsely reports that a committed index mutation failed.
|
||||
|
||||
Derived publication stages and flushes one complete bounded artifact before atomic replacement or
|
||||
no-clobber publication, then flushes the containing directory. An interruption therefore leaves
|
||||
the preceding complete artifact, the new complete artifact, or explicit degraded post-commit
|
||||
evidence. Index attestations, manual render receipts, generation-diff baselines, and portable-graph
|
||||
manifests have maintained exact-oracle corruption-and-repair proofs. Canonical project files remain
|
||||
unchanged throughout those recoveries.
|
||||
|
||||
Before replacement, a build accepts a predecessor only when its exact main-file inode has a
|
||||
matching whole-file attestation, has no WAL, journal, or shared-memory sidecar, and passes the
|
||||
published SQLite identity, row, hash, FTS, integrity, and policy checks. It uses an immutable
|
||||
|
|
@ -174,6 +187,30 @@ default active listing contains only draft and ready work. Stale, applied, and a
|
|||
remain queryable by explicit status or history request. Terminal proposals do not block new
|
||||
proposals.
|
||||
|
||||
## Canonical application durability
|
||||
|
||||
Generic canonical application stages replacements and backups in a mode-0700
|
||||
`.docforge/application/transaction-*` directory. Before each canonical create, update, or delete,
|
||||
it compares exact file identity at the publication boundary. Creates use no-clobber publication.
|
||||
Updates and deletes use atomic exchange and no-replace detachment. A concurrent canonical-target
|
||||
mutation fails closed, is rolled back only when exact displaced state remains provable, or is
|
||||
retained without overwriting foreign data.
|
||||
|
||||
This is per-file compare-and-swap publication, not multi-file crash atomicity. In-process failures
|
||||
run rollback across already published files, but there is no process-death journal. Process or host
|
||||
death between publications may leave a partial canonical application and requires operator
|
||||
inspection before a new proposal or restoration.
|
||||
|
||||
The private transaction namespace is integrity-confined against ordinary path access. It is not a
|
||||
filesystem sandbox, and deliberate arbitrary tampering by another process with the same operating-
|
||||
system UID is outside the contract. DocForge identity-checks private files before consuming or
|
||||
removing them.
|
||||
|
||||
After the serializer reproduces the approved graph, canonical success is final. If private cleanup
|
||||
then degrades, application still returns `applied`, closes the proposal, and persists bounded
|
||||
`application_recovery` lifecycle metadata with status `cleanup_required`, retained paths, and
|
||||
remediation. The reviewed changeset must not be applied twice.
|
||||
|
||||
## Declared rendering and previews
|
||||
|
||||
Render configuration is optional. A configured project declares one template root, one isolated
|
||||
|
|
|
|||
|
|
@ -19,6 +19,36 @@ Read [compatibility](COMPATIBILITY.md), [legacy and no-AST operation](LEGACY_AND
|
|||
|
||||
Disposable index and cache schemas may change. Rebuild them rather than copying them as authority.
|
||||
|
||||
## Maintained v1.0.0 migration evidence
|
||||
|
||||
`make migration-m5` archives and executes the actual annotated `v1.0.0` release, then opens its
|
||||
fixture, index, and active proposal through DocForge 1.4.0. The frozen tag object is
|
||||
`2d7d306a37da89f1c860c7f0be161c45386acf61`; it identifies commit
|
||||
`593c173b453236a6872d0a4e88e7a51a67a21cde`.
|
||||
|
||||
The tagged release contains an inherited identity mismatch that the migration proof records
|
||||
rather than hiding: distribution metadata says `1.0.0`, while `docforge.__version__` and the MCP
|
||||
server report `0.15.0`. DocForge 1.4.0 replaces that duplicated state with one authoritative
|
||||
version and requires its package and server values to agree.
|
||||
|
||||
The maintained fixture evidence is exact:
|
||||
|
||||
- Canonical collection hash:
|
||||
`9fde91b6b08669177d690cdf9f91b162120baee1f7e24b05fec67f56617f286a`.
|
||||
- Graph snapshot hash:
|
||||
`45bef8b0e1a4dac976e096dcf8f9048e1268211cd7f7638cdf99951428ec0500`.
|
||||
- Source hash: `0aa6ad13a95355102300a69b2f9d06883c301d63e2624b083e45f15102dab504`.
|
||||
- Active proposal hash:
|
||||
`2c055dfae45443b4a4d9d4087ef70959e7293beae8d27acb14ffffe52eca7111`.
|
||||
- Proposal-file hash:
|
||||
`4658d494b43bd7c6cc3e3f5933a2c878c817b52bc4566e9e8429e7b8e43ca007`.
|
||||
|
||||
Current loading preserves all five identities and every canonical byte. It rebuilds the disposable
|
||||
index from schema 1 to schema 3 without changing the graph or active proposal. All 20 tagged CLI
|
||||
commands remain in the current 28-command surface, and all 25 tagged MCP tools remain in the
|
||||
current 36-tool application-enabled surface. These counts describe the maintained rehearsal, not
|
||||
a promise that every additive current command belongs in a legacy binding.
|
||||
|
||||
## Recommended migration
|
||||
|
||||
1. Record the v1 package version, adapter identity, project descriptor, canonical source hash,
|
||||
|
|
|
|||
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.
|
||||
101
docs/MILESTONE_5_CLOSEOUT.md
Normal file
101
docs/MILESTONE_5_CLOSEOUT.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
# Milestone 5 release-candidate closeout
|
||||
|
||||
## Outcome
|
||||
|
||||
DocForge `1.4.0` has reached its documentation closeout candidate. Compatibility, migration,
|
||||
determinism, concurrency, recovery, policy, projection isolation, accessibility, performance,
|
||||
adoption, artifact reproducibility, and representative real-task evidence are maintained and
|
||||
passing.
|
||||
|
||||
This is not the final publication record. Milestone 5 remains active, and DocForge `1.0.0` remains
|
||||
the latest published stable release, until the documentation-bearing commit passes its final
|
||||
fresh-clone gate and the annotated `v1.4.0` tag and Forgejo release are verified.
|
||||
|
||||
## Candidate lineage
|
||||
|
||||
- Merged Milestone 4 baseline:
|
||||
`6d06195950d33bcd2d712f8819bbfb3d6652ad03`.
|
||||
- Frozen executable implementation:
|
||||
`d2bb95fe6190e659cf66ba57c78be53b63b53240`.
|
||||
- Fresh-clone legacy-tag verification:
|
||||
`97f3b6b1ae303c972387508557a3d54ea621a702`.
|
||||
- Maintained aggregate recovery proof:
|
||||
`2b98059b44f4d46b4d4cce776f163e893c647c76`.
|
||||
- Intended release version and tag: `1.4.0` and `v1.4.0`.
|
||||
- Publication channel: public Forgejo release only.
|
||||
|
||||
The tag does not exist yet. It must resolve to the final documentation-bearing descendant of this
|
||||
lineage, never to the earlier executable-only commit.
|
||||
|
||||
## Closed release evidence
|
||||
|
||||
The clean executable release gate passed:
|
||||
|
||||
- Formatting, Python and web lint, strict types, compilation, lock, dependency, package-build,
|
||||
generated-reference, and documentation checks.
|
||||
- 142 contract tests plus 272 subtests.
|
||||
- 371 complete tests plus 419 subtests.
|
||||
- Three interactive accessibility flows.
|
||||
- 116 compatibility tests plus 263 subtests.
|
||||
- 29 concurrency tests plus 2 subtests.
|
||||
- Offline fresh-wheel adoption.
|
||||
- Reproducible wheel and source-distribution builds with exact version and MIT license identity.
|
||||
- Gitleaks scans of reachable history and the candidate directory with no findings.
|
||||
- Full maintained Milestone 0, 1, 2, 3, and 4 benchmarks.
|
||||
|
||||
The later proof-only recovery commit adds four maintained tests. The aggregate recovery gate now
|
||||
passes 72 tests plus 62 subtests. The final fresh clone owns the final complete-suite total.
|
||||
|
||||
Detailed migration identities, artifact evidence, recovery boundaries, and task measurements are
|
||||
in the [Milestone 5 baseline](MILESTONE_5_BASELINE.md).
|
||||
|
||||
## Compatibility and migration result
|
||||
|
||||
Version `1.4.0` preserves the established distribution, imports, CLI, MCP, schema-1 descriptor,
|
||||
generic-project, one-method adapter, exact-hash changeset, rendering, result-envelope, and no-AST
|
||||
surfaces. New adapter, retrieval, projection, and release capabilities are additive.
|
||||
|
||||
The real annotated `v1.0.0` archive migrates without canonical or proposal changes. Its schema-1
|
||||
index rebuilds as schema 3, and its graph identity remains exact. The current CLI and MCP
|
||||
registrations are supersets of the version-1 surfaces. The proof reports the inherited version-1
|
||||
metadata/runtime mismatch instead of hiding it.
|
||||
|
||||
## Representative task result
|
||||
|
||||
The pinned real-package comparison uses `markdown-it-py 4.2.0`, 66 Python files, and 225,945 bytes.
|
||||
Graph-assisted and source-only workflows both return exact reviewed answers for direct
|
||||
dependencies, bounded reverse impact, and a dependency path.
|
||||
|
||||
Graph-assisted medians were 0.008, 0.009, and 0.013 ms after one-time preparation, versus 1.341,
|
||||
32.108, and 32.142 ms for source-only inspection. Graph-assisted work also reduced inspected bytes
|
||||
from 10,628 to 349, from 225,945 to 419, and from 225,945 to 212. Source-only final responses were
|
||||
smaller, so no universal response-size advantage is claimed.
|
||||
|
||||
## Preserved boundaries
|
||||
|
||||
- Canonical project files remain authoritative. Indexes, caches, receipts, render output, graph
|
||||
output, client fragments, and viewer state remain disposable.
|
||||
- Full rebuild remains the recovery and equivalence oracle.
|
||||
- Derived publication is durable and atomic. Multi-file canonical application does not claim
|
||||
process-death atomicity.
|
||||
- `--no-ast` remains a restrictive binding policy, not a parser detector or filesystem sandbox.
|
||||
- Reference adapters publish narrow static evidence and do not claim resolved calls, types,
|
||||
inheritance, runtime behavior, compiler semantics, or semantic ownership.
|
||||
- Reference MCP remains read-only.
|
||||
- No WorldForge, ScrapeStation, legacy repository, production binding, storage, or self-hosting
|
||||
change belongs to this release.
|
||||
- No PyPI publication belongs to this release.
|
||||
|
||||
## Publication still pending
|
||||
|
||||
The remaining sequence is exact:
|
||||
|
||||
1. Commit this coherent documentation closeout on the verified candidate lineage.
|
||||
2. Run documentation-only checks and confirm the final worktree contains no unrelated changes.
|
||||
3. Merge and push the final candidate so `main`, `dev`, `origin/main`, and `origin/dev` agree.
|
||||
4. Run the complete fresh-clone release rehearsal at that exact remote commit.
|
||||
5. Build the final artifacts and checksum manifest from the verified commit.
|
||||
6. Create and push one annotated `v1.4.0` tag at that commit.
|
||||
7. Publish and verify the Forgejo release and attached artifacts.
|
||||
|
||||
Until all seven steps succeed, the milestone status is release candidate rather than complete.
|
||||
|
|
@ -41,14 +41,42 @@ reported as degraded committed success, not as permission to repeat a mutation.
|
|||
The live viewer pins one validated index identity. Index replacement makes the running snapshot
|
||||
stale and causes a later visualize request to start a fresh worker.
|
||||
|
||||
Milestone 5 maintains exact-oracle recovery proofs for four independently disposable artifacts:
|
||||
|
||||
- A corrupt index attestation is rejected, then `synchronize()` recreates the exact attestation
|
||||
after complete verification while preserving canonical bytes, snapshot hash, and index identity.
|
||||
- A corrupt manual-render receipt reports `unverified/receipt_corrupt`; explicit rendering restores
|
||||
the exact output bytes and semantic receipt, and normal and deep status return `current`.
|
||||
- A corrupt generation-diff receipt reports `unverified/corrupt_receipt`; a complete index build
|
||||
recreates the exact current-graph baseline with `baseline/no_meaningful_transition`.
|
||||
- A corrupt portable-graph manifest reports missing publication evidence; explicit rendering
|
||||
restores the exact artifact bytes and semantic manifest, and status returns `current`.
|
||||
|
||||
These proofs are maintained by `tests/test_milestone5_recovery.py`. They do not promote receipts,
|
||||
attestations, or manifests to canonical authority.
|
||||
|
||||
## Proposal and application recovery
|
||||
|
||||
Hash or base conflicts are not cache failures. Retrieve the current changeset and diff, then
|
||||
review the new exact hash. Rebase is allowed only when every touched node, relationship, source,
|
||||
permission, and graph invariant still matches. A content conflict requires a new proposal.
|
||||
|
||||
If a canonical serializer fails its round-trip check, use its reported rollback state. Do not
|
||||
reapply a changeset whose application may already have committed. See
|
||||
Generic canonical create, update, and delete publication compares exact target identity at the
|
||||
commit boundary. Concurrent target mutation fails closed. In-process failures roll back only when
|
||||
the exact displaced state remains provable; otherwise DocForge preserves foreign data and returns
|
||||
`application_recovery_required` with retained evidence.
|
||||
|
||||
Canonical application is not journaled across several files. Each file publication is atomic, but
|
||||
process or host death between publications can leave a partial canonical application. Inspect the
|
||||
named canonical targets, the active proposal, and `.docforge/application/transaction-*` before
|
||||
deciding whether to restore or create a new proposal. Do not retry the old approved hash merely
|
||||
because a process ended.
|
||||
|
||||
If semantic application committed but private transaction cleanup degraded, the result remains
|
||||
`applied`. The proposal is closed and its compact lifecycle receipt records
|
||||
`application_recovery.status = "cleanup_required"`, retained paths, and remediation. Preserve and
|
||||
inspect those files. Remove only artifacts proven to be DocForge-owned. If a canonical serializer
|
||||
fails its round-trip check before success, use its reported rollback state. See
|
||||
[migrating from v1](MIGRATING_FROM_V1.md) for rollback planning.
|
||||
|
||||
## Milestone 4 scale evidence
|
||||
|
|
@ -80,7 +108,18 @@ make gate
|
|||
make adoption-m4
|
||||
make benchmark-m4-full
|
||||
make docs-check
|
||||
make compatibility-m5
|
||||
make migration-m5
|
||||
make concurrency-m5
|
||||
make recovery-m5
|
||||
make task-evidence-m5
|
||||
make release-gate
|
||||
make fresh-clone-m5
|
||||
```
|
||||
|
||||
The main gate includes smoke benchmarks. Full milestone evidence is recorded separately from a
|
||||
clean candidate so smoke or dirty-tree results cannot become release claims.
|
||||
clean candidate so smoke or dirty-tree results cannot become release claims. `release-gate`
|
||||
aggregates the complete quality, compatibility, migration, concurrency, recovery, task-evidence,
|
||||
fresh-wheel, identity, reproducible-artifact, secret-scan, and full benchmark proofs.
|
||||
`fresh-clone-m5` repeats that aggregate gate from anonymous HTTPS at one exact published commit
|
||||
after verifying the frozen annotated `v1.0.0` migration tag.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
# Security model
|
||||
|
||||
DocForge is a project-bound knowledge compiler. Its security boundary is an explicit project root,
|
||||
closed configuration, bounded data, and exact identities. It is not a general process sandbox.
|
||||
closed configuration, bounded data, and exact identities. It is not a general process or
|
||||
filesystem sandbox.
|
||||
|
||||
Start with [core authority](CORE_CONCEPTS_AND_AUTHORITY.md), then use
|
||||
[policy precedence](POLICY_PRECEDENCE.md) to decide which capabilities a server should expose.
|
||||
|
|
@ -18,6 +19,13 @@ Confinement protects DocForge operations. It does not stop another process with
|
|||
from changing files. Long-running bindings revalidate descriptor and adapter implementation
|
||||
identity and require a restart after drift.
|
||||
|
||||
Generic canonical application stages backups and replacements below
|
||||
`.docforge/application/transaction-*` in mode-0700 directories. That private namespace confines
|
||||
ordinary path access and prevents access by other users. Deliberate arbitrary tampering by another
|
||||
process running as the same operating-system user is outside this boundary. DocForge still
|
||||
identity-checks private files before using or removing them, but mode `0700` is not isolation from
|
||||
the same UID.
|
||||
|
||||
## Untrusted project content
|
||||
|
||||
Documentation, source text, templates, adapter metadata, compiler-database entries, and changeset
|
||||
|
|
@ -56,16 +64,33 @@ the exact changeset hash that was reviewed. Source identity, content hashes, per
|
|||
conflicts, graph validity, and serializer round trips are checked before success. DocForge never
|
||||
turns prose approval into a fuzzy merge.
|
||||
|
||||
The generic applier compares exact canonical file identity immediately before each publication.
|
||||
Create uses no-clobber publication. Update and delete use atomic exchange and no-replace moves.
|
||||
Concurrent canonical-target mutation therefore fails closed, rolls back when the exact displaced
|
||||
state is still provable, or retains recovery evidence without overwriting foreign data.
|
||||
|
||||
This compare-and-swap protection is not a process-death journal. One file publication is atomic,
|
||||
and an in-process failure runs exact rollback, but an application spanning several canonical files
|
||||
does not promise crash atomicity if the process or host dies between publications. Operators must
|
||||
inspect canonical state and retained transaction evidence before retrying after such an
|
||||
interruption.
|
||||
|
||||
## Derived state and publication
|
||||
|
||||
SQLite indexes, source-generation receipts, extraction caches, render fragments, previews, and
|
||||
portable artifacts are disposable. Corrupt, stale, foreign, oversized, or mismatched derived
|
||||
state is rejected or rebuilt from current project evidence.
|
||||
|
||||
Generated command-reference publication serializes cooperating writers and uses no-clobber or
|
||||
compare-and-swap publication. A raced target is restored or retained for recovery instead of being
|
||||
silently discarded. Projection publication records when an artifact was committed but later
|
||||
receipt verification degraded, so a completed mutation is never reported as an ordinary failure.
|
||||
Derived publication stages complete bounded output, flushes file and directory state, and commits
|
||||
with atomic replacement or no-clobber compare-and-swap. It is crash-safe: an interruption leaves
|
||||
the prior verified artifact, the complete new artifact, or explicit degraded post-commit evidence,
|
||||
not a mixed publication. Generated command-reference publication also serializes cooperating
|
||||
writers. A raced target is restored or retained for recovery instead of being silently discarded.
|
||||
|
||||
Projection and canonical-application lifecycles record when semantic content committed but later
|
||||
private cleanup or receipt verification degraded. Canonical success closes the applied proposal
|
||||
and persists compact `application_recovery` metadata with retained paths and remediation. A
|
||||
completed mutation is never reported as an ordinary retryable failure.
|
||||
|
||||
## Limits and denial-of-service resistance
|
||||
|
||||
|
|
|
|||
|
|
@ -5,9 +5,11 @@ people and AI agents can search, inspect, visualize, and change through reviewab
|
|||
Canonical project files remain authoritative. The SQLite graph, previews, rendered manuals, and
|
||||
viewer processes are derived and can be rebuilt.
|
||||
|
||||
DocForge 1.0.0 is the first stable product release. It includes the project-scoped graph,
|
||||
CLI and MCP query surfaces, hash-approved proposal application, generic and project-owned adapters,
|
||||
declared rendering, and the Nodes/Flow/Web visualization model documented below.
|
||||
This manual describes the DocForge 1.4.0 release candidate. The tagged `v1.0.0` baseline was the
|
||||
first stable product release. Version 1.4.0 preserves its project-scoped graph, CLI and MCP query
|
||||
surfaces, hash-approved proposal application, generic and project-owned adapters, declared
|
||||
rendering, and Nodes/Flow/Web model while adding the maintained incremental, projection, adapter
|
||||
SDK, recovery, and release proofs documented below.
|
||||
|
||||
Later incremental-compiler capabilities are additive. A Release 1 adapter with only
|
||||
`load_projection()` remains valid and follows the same complete-rebuild path. No existing project
|
||||
|
|
@ -76,6 +78,12 @@ The generic adapter can serialize its Markdown and TOML nodes directly. A custom
|
|||
provide its own canonical applier because only that project knows how a graph node maps back to its
|
||||
source format.
|
||||
|
||||
Generic canonical application compare-and-swaps each target against its exact expected identity.
|
||||
A concurrent create, update, or delete fails closed, rolls back when the exact displaced state is
|
||||
still provable, or preserves recovery evidence without overwriting foreign data. Per-file
|
||||
publication is atomic, but an application spanning several canonical files has no process-death
|
||||
journal and does not claim crash atomicity across the group.
|
||||
|
||||
## Setup
|
||||
|
||||
### Requirements
|
||||
|
|
@ -115,6 +123,20 @@ The base wheel contains the Python reference adapter and no Tree-sitter distribu
|
|||
TypeScript, and C++ require their matching optional extras. `docforge[languages]` installs all
|
||||
three optional frontend groups.
|
||||
|
||||
Verify the four executable surfaces from the exact installed environment:
|
||||
|
||||
```bash
|
||||
python -m docforge.cli --version
|
||||
python -m docforge.mcp_server --version
|
||||
python -m docforge.reference_mcp --version
|
||||
python -m docforge.viewer_manager --version
|
||||
```
|
||||
|
||||
For version 1.4.0 these report `docforge 1.4.0`, `docforge-mcp 1.4.0`,
|
||||
`python -m docforge.reference_mcp 1.4.0`, and `docforge-viewer-manager 1.4.0`. Package metadata,
|
||||
Python imports, generated generic and adapter configurations, and these commands share the same
|
||||
version authority.
|
||||
|
||||
### Configure a reference source project
|
||||
|
||||
Reference adapters are a narrow alternative to the generic documentation descriptor. Create
|
||||
|
|
@ -996,6 +1018,10 @@ effective policy. A replacement receipt returns `stale_cursor`; restart from its
|
|||
Canonical application records its terminal receipt immediately after the project-owned serializer
|
||||
verifies the new canonical state. A later index or render refresh failure is reported as degraded
|
||||
derived state with remediation, not as permission to apply the same canonical change again.
|
||||
Likewise, failure to remove a private transaction artifact after semantic commit returns
|
||||
`applied`, closes the proposal, and persists compact `application_recovery` lifecycle metadata
|
||||
with `cleanup_required`, retained paths, and remediation. Inspect and remove only files proven to
|
||||
be DocForge-owned.
|
||||
|
||||
Every successful declared render publishes a bounded version-1 receipt below the disposable cache.
|
||||
Normal `render-status` compares cheap source-generation, view-configuration, template-file, and
|
||||
|
|
@ -1115,6 +1141,13 @@ process verifies the unchanged database against that receipt instead of reconstr
|
|||
row. Missing or mismatched receipts fall back to complete verification and are recreated only after
|
||||
the full check succeeds.
|
||||
|
||||
Milestone 5 maintains exact recovery for four corrupt derived artifacts. Synchronization restores
|
||||
a corrupt index attestation after complete verification. Explicit `render` restores a corrupt
|
||||
manual receipt to the exact output and receipt semantics. A complete `reindex` recreates a corrupt
|
||||
generation-diff baseline against the exact current graph. Explicit `graph-render` recreates a
|
||||
corrupt portable-graph manifest and exact artifact. Status operations diagnose these conditions
|
||||
without hidden repair.
|
||||
|
||||
### `visualization_manager_unavailable`
|
||||
|
||||
The per-user manager is not installed, is stopped, or points to an old virtual environment.
|
||||
|
|
@ -1159,9 +1192,28 @@ content or relationship conflict remains fail-closed and requires a newly review
|
|||
|
||||
### `application_mismatch`
|
||||
|
||||
The written sources did not reproduce the validated projection. DocForge rolls the generic
|
||||
canonical files back. For a custom adapter, fix its serializer or node-to-source mapping before
|
||||
retrying.
|
||||
The written sources did not reproduce the validated projection. During an ordinary in-process
|
||||
failure, DocForge rolls generic canonical files back when their exact publication identities are
|
||||
still provable. If another process raced a target, DocForge preserves foreign and displaced data
|
||||
and returns `application_recovery_required` rather than overwriting either. For a custom adapter,
|
||||
fix its serializer or node-to-source mapping before retrying.
|
||||
|
||||
### `application_recovery_required` or `cleanup_required`
|
||||
|
||||
`application_recovery_required` means canonical publication or rollback encountered concurrent or
|
||||
unprovable state. Preserve every retained file named in the error. Compare it with the canonical
|
||||
target and resolve the project before creating a newly reviewed proposal. Do not retry the old
|
||||
approved hash.
|
||||
|
||||
`cleanup_required` means semantic application already committed. The proposal is closed as
|
||||
`applied`, and its lifecycle receipt names private transaction artifacts that could not be removed.
|
||||
Inspect those files and remove only confirmed DocForge-owned artifacts. The canonical change must
|
||||
not be applied again.
|
||||
|
||||
Generic application uses mode-0700 transaction directories, but DocForge is not a filesystem
|
||||
sandbox. Deliberate arbitrary tampering by another process running as the same operating-system
|
||||
user is outside that integrity boundary. A process or host death can also interrupt a multi-file
|
||||
application because canonical application has no process-death journal.
|
||||
|
||||
### `path_escape`, `unsafe_template`, or missing source
|
||||
|
||||
|
|
@ -1178,7 +1230,7 @@ ambiguous adapter evidence.
|
|||
|
||||
### Full inspector content does not fit
|
||||
|
||||
DocForge 1.0 uses a fixed header and footer with a scrollable inspector body. If an older page is
|
||||
DocForge 1.4 uses a fixed header and footer with a scrollable inspector body. If an older page is
|
||||
still open, stop and reopen the visualization so it loads the current `graph-browser@17` template.
|
||||
|
||||
### Render output is stale
|
||||
|
|
@ -1219,7 +1271,7 @@ the process so it binds the new descriptor deliberately.
|
|||
|
||||
## Development and verification
|
||||
|
||||
Run the complete release gate from the DocForge repository:
|
||||
Run the ordinary repository gate:
|
||||
|
||||
```bash
|
||||
make gate
|
||||
|
|
@ -1234,5 +1286,25 @@ and recovery benchmark. `make adoption-m4` performs the offline fresh-wheel proo
|
|||
the maintained documentation graph. `make accessibility` runs the generated manual, portable
|
||||
graph, and live viewer axe and keyboard flows.
|
||||
|
||||
Milestone 5 adds maintained compatibility, migration, concurrency, recovery, comparative-task,
|
||||
release-identity, reproducible-artifact, secret-scan, and fresh-clone gates:
|
||||
|
||||
```bash
|
||||
make compatibility-m5
|
||||
make migration-m5
|
||||
make concurrency-m5
|
||||
make recovery-m5
|
||||
make task-evidence-m5
|
||||
make release-gate
|
||||
make fresh-clone-m5
|
||||
```
|
||||
|
||||
`release-gate` aggregates the full quality, browser, compatibility, migration, concurrency,
|
||||
recovery, task-evidence, fresh-wheel, version, artifact, secret-scan, and benchmark suite.
|
||||
`fresh-clone-m5` anonymously clones the exact published candidate over HTTPS, fetches and verifies
|
||||
the frozen annotated `v1.0.0` migration tag, and repeats `release-gate`. Release operators use
|
||||
`make release-pretag` before creating `v1.4.0` and `make release-posttag` after the annotated tag
|
||||
points to the exact release commit.
|
||||
|
||||
Project-specific vocabulary, extraction rules, and serialization belong in the project adapter.
|
||||
Generic core behavior must remain deterministic, project-bound, and recoverable.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue