DocForge2/docs/COMPATIBILITY.md

# 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. DocForge 2.0.0 preserves that baseline and the complete 1.4
adapter, rendering, recovery, and release surfaces recorded below.

The compatibility gate is:

```bash
make contract
```

The complete repository gate is:

```bash
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`.

The installed executable names remain:

- `docforge`
- `docforge-mcp`
- `docforge-viewer-manager`

The top-level imports recorded by `docforge.__all__` remain supported. The documented adapter,
model, index, rendering, application, and MCP factory names imported from these submodules also
remain supported:

- `docforge.adapter_contract`
- `docforge.adapter_sdk`
- `docforge.adapter_launcher`
- `docforge.application`
- `docforge.client_config`
- `docforge.index`
- `docforge.mcp_server`
- `docforge.models`
- `docforge.policy`
- `docforge.render_contract`
- `docforge.reference_config`
- `docforge.reference_mcp`

Names beginning with an underscore are implementation details. New public names may be added
without breaking this contract.

The repository Python, JavaScript/TypeScript, and C++ adapters are supported reference
implementations. Their documented configuration, evidence limits, and unsupported-fact reports are
compatibility surfaces; their internal parser helpers are not adapter-authoring imports.

Milestone 4 adds three version-1 schemas without changing existing descriptor or result schemas:

- `schemas/adapter-launcher.schema.json`
- `schemas/adapter-client-configuration.schema.json`
- `schemas/reference-adapter.schema.json`

## CLI and MCP surfaces

Existing `docforge` command names and arguments remain supported. Existing `docforge-mcp` tool
names and arguments remain supported. Additive commands, tools, and response fields are allowed.
Removing or changing an existing name, required argument, stable error code, or safety boundary
requires an explicit compatibility decision.

Version `2.0.0` comes from one `docforge._version` authority. The four maintained executable
surfaces report `docforge 2.0.0`, `docforge-mcp 2.0.0`,
`python -m docforge.reference_mcp 2.0.0`, and `docforge-viewer-manager 2.0.0` for `--version`.
Generated generic and adapter client configurations include and hash-bind the same
`docforge_version`.

MCP results retain:

- A structured `status`.
- Project and source identity when available.
- Stable structured domain errors.
- A bounded content warning.
- Staleness information.
- The configured output-size limit.

The result schema describes the common envelope. Operation-specific fields are additive and remain
bounded by the configured tool-output limit.

The following Milestone 2 CLI additions do not change existing command signatures:

- `docforge configure codex|claude|openclaw --project ROOT`
- `docforge doctor --client codex|claude|openclaw`

Configuration output is a new version-1 machine-local contract. It preserves the `docforge`
package and executable names and emits the existing `docforge.mcp_server` module entrypoint.
Existing hand-written client configurations remain valid and are never rewritten automatically.
Doctor is inspection-only and does not become a hidden bootstrap, synchronization, or migration
path.

The following Milestone 3 CLI additions are also additive:

- `docforge graph-plan VIEW_ID`
- `docforge graph-render VIEW_ID`
- `docforge graph-render-status [VIEW_ID]`
- `--manual-render-policy auto|explicit|disabled`
- `--portable-graph-policy explicit|disabled`
- `--live-viewer-policy on-demand|disabled`

MCP adds the read-only `docforge_graph_plan` and `docforge_graph_render_status` tools. Portable
graph publication remains an explicit local CLI integration action. Existing manual render,
preview, visualization, and status names remain supported.

## Versioned data contracts

Milestone 0 preserves:

- Project descriptor schema version 1.
- Node schema version 1.
- Edge schema version 1.
- Changeset schema version 1.
- Result-envelope schema version 1.
- SQLite index schema version 3. Version 2 indexes remain disposable and automatically rebuild;
  version 3 adds a source-ordered incoming-edge index for bounded impact traversal.
- Index-attestation schema version 1.
- Incremental extraction-cache schema version 1.
- Effective process-policy schema version 1. The project descriptor remains schema version 1;
  machine-specific capability selection is a startup binding, not canonical project content.
- Read-pagination schema version 1. Existing tool names and required arguments are unchanged.
  Context and changeset MCP reads accept optional limits and opaque generation-bound cursors.
  Direct Python changeset methods and the ordinary CLI context command retain full legacy results
  when pagination is not requested.
- Latest-generation-diff receipt schema version 1. The additive `generation-diff` CLI command and
  `docforge_get_generation_diff` MCP read accept only optional pagination fields. They record one
  primary-graph transition and do not create a history store or expose Logic details.
- Latest-generation-diff page schema version 1. Pages use one top-level pagination object and a
  nested `receipt_header`. `stored_receipt_hash` names the complete stored receipt. Opaque cursors
  may be restarted after a server or receipt change and are not durable public identifiers.
- Manual render-plan schema version 1.
- Graph view-plan schema version 1.
- Projection-package schema version 1.
- Projection-receipt schema version 1.
- Independent projection-policy schema version 2. Effective policy version 1 remains frozen.

Indexes, attestations, extraction caches, previews, and rendered artifacts are disposable. A schema
change may rebuild them. Canonical project content and stored proposals may not be silently
rewritten to satisfy a new implementation.

## Adapter compatibility

An adapter implementing only:

```python
load_projection()
```

remains first-class. Incremental manifests, source extraction, deterministic assembly, Logic
projection, and proposal or application support are optional capabilities. Incremental adapters
must retain `load_projection()` as their independent clean-build and equivalence oracle.

Project adapters remain explicitly composed. Generic DocForge does not discover arbitrary adapter
modules or choose a project globally.

The supported generation-diff Python boundary is `ProjectIndex.generation_diff()`. Helpers in the
`docforge.generation_diff` module implement the disposable publication contract and are internal;
they are not frozen as adapter-authoring imports.

## Preserved no-AST binding

`docforge-mcp --project-root /project --no-ast` is a stable shorthand for the
`preserve-no-ast` binding policy.

The binding:

- Keeps one-method complete-projection adapters working.
- Keeps non-AST incremental fingerprinting and caching working.
- Rejects nonempty function-Logic publication.
- Rejects a pre-existing index containing function Logic.
- Blocks `docforge_get_logic`.
- Prevents the live viewer from pinning an index containing Logic.
- Applies the same restriction during hash-bound canonical-application refresh.
- Reports the effective policy through bootstrap and contract results.

The legacy `adapter_policy` payload and error codes remain unchanged. The version-1
`effective_policy` is additive and makes precedence, capability mode, render behavior, blocked
tools, and prohibitions machine-readable.

DocForge does not inspect arbitrary adapter source to prove which parser implementation it uses.
The no-AST binding is an owner-selected process policy backed by Logic publication and retrieval
enforcement. It is not a filesystem sandbox and cannot stop an unrelated process with repository
write access from changing adapter code.

## Changesets and application

The following guarantees remain stable:

1. Registration writes one complete proposal atomically.
2. Proposal identity includes its project, root, base revision, canonical source hash, writer, and
   ordered operations.
3. Validation and diff inspection precede application.
4. Append, rebase, abandonment, and application use exact current hashes.
5. Stale, conflicting, unauthorized, unsafe, or invalid proposals fail closed.
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

The `generic_html` renderer remains the supported version-1 manual projection. Its public
`GenericHtmlRenderer.prepare()` signature, renderer identity, frozen alpha bytes, confined paths,
raw-HTML suppression, fixed template tokens, deterministic identities, atomic replacement, and
side-effect-free status remain compatible. It now delegates through a versioned manual plan,
immutable package, and independent renderer.

The `portable_graph_html` renderer and `graph_render` descriptor table are additive. Manual and
portable graph declarations, plans, policies, publication receipts, and status remain separate.
The portable renderer does not replace the existing live viewer or `docforge_visualize`.

Existing project descriptors may retain any positive `max_render_bytes` accepted by schema version
1. A value above 20,000,000 bytes does not make the descriptor invalid, and a smaller actual
artifact still renders. Actual detached worker transfer is a separate fixed 20,000,000-byte
runtime boundary.

The live graph viewer remains a read-only consumer of a generation-pinned validated index. It does
not become project authority or MCP retrieval authority. Source reads use the pinned index
generation instead of reopening mutable canonical files behind that generation.

## Task-context compatibility

`docforge_get_task_context` is an additive MCP read tool. The legacy `docforge_get_context`
signature, profile compiler, direct Python results, and custom three-argument context-provider
contract remain unchanged.

The new `ContextCapsuleV1` and `RetrievalPlanV1` types live in the public
`docforge.retrieval` submodule. Version 1 guarantees:

- A closed task-kind vocabulary and core-derived plan. Callers cannot inject arbitrary operations,
  SQL, paths, relations, or Logic requests.
- One immutable index transaction and one exact project, adapter, revision, source, policy,
  request, plan, collection, and capsule identity.
- Deterministic bounded focus, traversal, hydration, token accounting, response packing, and
  continuation, with fixed version-1 ceilings of 1,000 evidence items, 100,000 candidate edges, and
  10,000 task-query characters.
- Raw preservation of project-owned relation names. Only the documented versioned alias map gains
  task semantics; all other relations remain `unclassified`.
- Separate missing, incomplete, blocked, and provenance-limitation evidence.
- No-AST bindings retain task context but never add a Logic retrieval step or weaken the existing
  Logic prohibition.

An integration that replaces the legacy context provider does not silently receive the core task
planner. Version 1 has no custom task-planner protocol. The task-context tool remains registered
for additive name compatibility but returns `task_context_unavailable` without loading or
synchronizing the custom projection.

The exact version-1 relation aliases are frozen by the MCP contract and repository contract tests.
Changing an alias category requires a new planner version; it is not a silent implementation
detail.

Milestone 3 adds `ManualRenderPlanV1`, `GraphViewPlanV1`, projection package and receipt version 1,
and projection policy version 2. These are additive submodule and schema contracts. They do not
change the legacy task-context, adapter, changeset, or effective-policy contracts described above.

Milestone 4 adds `docforge.adapter_sdk`, the fixed reference configuration and read-only MCP
binding, immutable adapter launchers, and generated adapter client fragments. A legacy adapter with
only `load_projection()` remains first-class and need not adopt incremental extraction, Logic, a
reference configuration, or launcher metadata.

## Safety boundary

DocForge remains bound to one explicit project root. It rejects absolute paths, root escapes, and
symbolic-link escapes. Documentation text remains untrusted data. Normal MCP operation exposes no
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 2.0.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:

- Generic warm reads still repeat whole-project discovery, parsing, and validation.
- 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.
- 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
  chunks. Cursors are corruption-detecting read tokens, not authenticated authorization tokens.
- Production fragment validation is currently slower than forced-full rendering at the maintained
  1,000-page fixture. Full rendering remains the equivalence and recovery oracle.
- Remote render services, render farms, third-party renderer ecosystems, and a separate render MCP
  remain deferred.
- DocForge2 does not self-host its bootstrap documentation.