Close Milestone 3 with measured projection evidence

docs/CONTRACT.md

@@ -24,6 +24,11 @@ commit when Git is available; it cannot change repository state.
 - Latest generation-diff page: `schemas/generation-diff-page.schema.json`, version 1.
 - Generated client configuration: `schemas/client-configuration.schema.json`, version 1.
 - Client doctor result: `schemas/doctor-result.schema.json`, version 1.
+- Manual render plan: `schemas/manual-render-plan.schema.json`, version 1.
+- Graph view plan: `schemas/graph-view-plan.schema.json`, version 1.
+- Projection package: `schemas/projection-package.schema.json`, version 1.
+- Projection receipt: `schemas/projection-receipt.schema.json`, version 1.
+- Independent projection policy: `schemas/projection-policy.schema.json`, version 2.
 - 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.
@@ -82,7 +87,9 @@ the header alone. One top-level pagination object carries the only continuation
 Generated Codex, Claude, and OpenClaw fragments are machine-local projections. They are not
 canonical project content. Version 1 binds the selected project, exact isolated Python
 interpreter, canonical argument layout, effective policy, no-AST projection, render policy,
-timeouts, artifact bytes, and configuration hash.
+timeouts, artifact bytes, and configuration hash. Milestone 3 adds the version-2 projection policy,
+its hash, projection availability, and the exact descriptor hash to that attested configuration
+evidence. Omitted default selectors are recomposed against the bound descriptor.
 
 Preview is side-effect free. Explicit publication creates only one new private standalone
 fragment in an existing real directory. It never merges or replaces different content. Descriptor,
@@ -135,10 +142,12 @@ preview root, and one or more stable view IDs. Each view names a built-in render
 derived output file, title, and optional family filter. Paths are resolved under the project root
 and may not overlap canonical content, authority files, changesets, templates, or previews.
 
-The initial `generic_html` renderer uses pinned CommonMark parsing with raw HTML disabled. Templates
-are UTF-8 files with a fixed token vocabulary; they cannot name commands, modules, or executable
+The `generic_html` renderer uses pinned CommonMark parsing with raw HTML disabled. Templates are
+UTF-8 files with a fixed token vocabulary; they cannot name commands, modules, or executable
 renderers. Render identity covers the canonical source hash, optional changeset hash, selected node
-and edge identities, view configuration, template hash, renderer contract, and exact parser version.
+and edge identities, view configuration, template hash, renderer contract, and exact parser
+version. The frozen version-1 API and alpha bytes are preserved by a compatibility wrapper over the
+manual plan/package/renderer path.
 
 An explicit CLI render atomically replaces one declared derived output. MCP can render a validated
 changeset only to its isolated preview path. Normal status verifies bounded source, configuration,
@@ -146,6 +155,56 @@ template, output, renderer, and publication-receipt identities without reconstru
 Explicit deep status remains the side-effect-free full-render oracle. Input changes detected before
 atomic replacement fail without publishing a current receipt for stale output.
 
+## Independent projection boundary
+
+Manual and portable graph plans are separate version-1 contracts over one immutable validated
+generation. They use canonical JSON, deterministic ordering, fixed structural and serialized-size
+bounds, and content-derived identities. Plans contain selected graph facts and bounded content.
+They contain no live project object, database handle, absolute project or index path, arbitrary
+query, command, executable path, or caller-selected module.
+
+Projection packages bind one plan to inert assets, a closed built-in renderer identity, declared
+component versions, and an artifact inventory with a byte allowance. Receipts bind the exact
+package, plan, renderer, artifact hashes and sizes, diagnostics, timing, and detached peak memory.
+Manual and graph renderer modules accept only validated packages. They cannot select nodes, invent
+relationships, read project state, choose publication paths, or write canonical files.
+
+Detached execution uses one fixed private Python module, isolated mode, a trusted working
+directory, a sanitized environment, exactly one canonical newline-terminated JSON request and
+response, a closed renderer allowlist, a 30-second timeout, disk-spooled stdout, and bounded reads. The package
+contract is capped at 24,000,000 bytes and actual detached artifact transfer at 20,000,000 bytes.
+Project descriptors may retain a larger `max_render_bytes` compatibility allowance, but an actual
+detached transfer above the fixed worker boundary fails closed.
+
+Portable graph configuration is independent of manual render configuration. One view selects
+either an exact root or a bounded metadata-only lexical query plus closed filters and node, edge,
+depth, and work limits. Logic is excluded. The renderer emits a complete static Nodes, Flow, or Web
+artifact and uses JavaScript only as progressive enhancement.
+
+Portable publication commits a content-addressed artifact, renderer receipt, and one bounded
+generation/view manifest in that order. The manifest is the publication commit. Status reads only
+bounded manifest and receipt evidence and never plans or renders. Repair restores declared output
+only from validated content-addressed evidence. A failure after a replacement that cannot be
+proven rolled back returns explicit degraded committed evidence.
+
+Manual fragment records are disposable semantic cache entries. Their keys bind the renderer,
+component version, and complete page semantics. The detached renderer recomputes the expected page
+fragment before accepting cached bytes. Cold creation is compared with a full detached render
+before cache publication. Invalid, corrupt, forged, stale, individually oversized, or
+aggregate-oversized records fall back to the full oracle. The dedicated cache retains only current
+keys and is capped at 10,000 entries and 64,000,000 bytes.
+
+Projection policy version 2 composes manual `auto|explicit|disabled`, portable graph
+`explicit|disabled`, and live viewer `on-demand|disabled` independently. Active plan, render,
+application, onboarding, and viewer-start operations enforce the relevant policy before hidden
+work. Receipt-only status and explicit viewer stop remain available. Effective policy version 1
+and its legacy projections remain unchanged.
+
+The live viewer remains separate from portable graph publication. It consumes one
+generation-pinned validated index through the viewer manager. Source reads come from that pinned
+generation and do not reopen mutable canonical files behind an older snapshot. Neither live nor
+portable visualization is retrieval or canonical authority.
+
 Normal MCP access does not expose canonical application. An explicitly configured canonical
 applier registers one hash-bound application tool. No MCP mode exposes arbitrary renderer
 execution, arbitrary file writes, shell commands, Git mutation, build commands, deployment, or