DocForge2/docs/CONTRACT.md

# DocForge 0.7 contract

## Authority boundary

DocForge is bound to one explicit project root. Canonical project files own documentation facts.
Indexes, query results, context packs, changesets, previews, and renders are derived artifacts.

The generic core validates and retrieves canonical nodes. A project-bound proposal service writes
only isolated changesets. Canonical application, project builds, Git mutation, deployment, and
publication remain external integration actions. Passive revision detection may read the current Git
commit when Git is available; it cannot change repository state.

DFG-9 made manual canonical integration the permanent DocForge 0.x policy. The library, CLI, and
MCP server do not apply changesets to canonical files. Reconsidering that boundary requires a new
approved contract and measured cross-project evidence; it is not an unimplemented 0.x feature. See
`APPLICATION_DECISION.md`.

## Versioned contracts

- Project descriptor schema: `schemas/project.schema.json`, version 1.
- Node schema: `schemas/node.schema.json`, version 1.
- Edge schema: `schemas/edge.schema.json`, version 1.
- Result envelope: `schemas/result.schema.json`, version 1.
- Changeset schema: `schemas/changeset.schema.json`, version 1.
- Index schema: version 1, disposable and reproducible.
- Core, CLI, and MCP server: version 0.7.2.

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.

## Generic node storage

Markdown nodes begin with a TOML metadata block delimited by `+++`. The remaining Markdown is the
node content. TOML sources contain one or more `[[nodes]]` tables and store content in a `content`
field. Every node has a stable project-wide ID.

The generic authority vocabulary is `authoritative`, `approved_plan`, `derived`, `proposal`, and
`historical`. Projects define statuses and allowed relationship names in their descriptor. The core
gives special acyclic validation to `depends_on`; adapters may add stricter rules.

## Result identity

Successful operations identify the project, adapter, current revision when available, and canonical
source hash. Errors use a stable code, direct message, and structured details. Query operations fail
if canonical source no longer matches the derived index.

## Isolated proposal model

Create, update, move, and delete are ordered node operations inside an isolated changeset. Every
operation names its expected base hash. A move preserves the stable node ID. A delete must resolve
every incident relationship. Proposal validation and storage are atomic. Canonical application
remains external, and prose is never auto-merged.

The MCP process binds to one configured writer identity at startup. The project descriptor grants
that writer explicit families and operation types. A changeset records its creator, project root
fingerprint, base revision, canonical source hash, and ordered operations. Every append requires the
current changeset hash, so simultaneous writers cannot silently lose an operation.

Changesets from the same canonical base may coexist only when their touched node and source sets do
not overlap. Exact overlaps return structured conflicts naming the other changesets, nodes, and
sources. A stale canonical base, stale node hash, stale changeset hash, unauthorized family, unsafe
path, invalid graph, dependency cycle, unresolved delete relationship, or configured limit fails
before the proposal file changes.

## Declared rendering and previews

Render configuration is optional. A configured project declares one template root, one isolated
preview root, and one or more stable view IDs. Each view names a built-in renderer, template,
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
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.

An explicit CLI render atomically replaces one declared derived output. MCP can render a validated
changeset only to its isolated preview path. Status recomputes expected output without writing and
reports `current`, `stale`, `missing`, `unsafe`, or `oversized`. Input changes detected before atomic
replacement fail without replacing the prior output.

Normal MCP access does not expose canonical application, declared project-output rendering,
arbitrary renderer execution, arbitrary file writes, shell commands, Git mutation, build commands,
deployment, or publication.

## Project-bound graph visualization

The fixed `docforge_visualize` MCP tool starts one ephemeral read-only graph browser for the
server's already-configured project. It accepts only an optional stable node ID, an optional lexical
query, and a bounded traversal depth. It does not accept a project root, database path, SQL,
template path, bind address, command, or renderer.

The runner validates the complete canonical projection and derived index before it starts. It then
pins the browser to that exact validated SQLite file identity and project metadata so normal UI
queries do not rebuild a large adapter graph. Replacement or alteration of the index file makes the
browser fail closed; the user must invoke the tool again. The browser identifies itself as a
validated snapshot rather than claiming that canonical files are continuously monitored.

The HTTP listener binds to `127.0.0.1` on an operating-system-selected port. A cryptographically
random token is part of every accepted URL path. Only `GET` and `HEAD` are supported. Responses use
no-store caching, a restrictive content-security policy, frame denial, MIME sniffing protection,
and no-referrer policy. The built-in template uses only same-origin JSON endpoints for graph
overview, bounded search, exact node content, and bounded incoming-and-outgoing neighborhoods.
There is no write endpoint, arbitrary query endpoint, static filesystem handler, external asset,
or project-selection control.

The `graph-browser@3` template provides mouse-wheel zoom centered on the pointer, left-button drag
pan, explicit zoom-in and zoom-out buttons, a reset-view button, and a live zoom percentage. A
four-pixel drag threshold preserves node activation for ordinary clicks. Loading another root node
resets the viewport so the new neighborhood begins centered and fully framed.

Activating a graph node opens a modal inspector containing that node's complete validated metadata
and content. Inspection does not replace the current neighborhood or reset the viewport. The modal
supports keyboard activation, Escape, explicit close controls, and backdrop dismissal. Loading the
inspected node as the new root requires the separate Explore neighborhood action.

One MCP process owns at most one listener. Repeated invocations reuse it and may replace its
validated snapshot only after a fresh index check. The listener stops with the MCP process.
Project-specific integrations receive the same tool because it operates on the supplied
`ProjectService` and `ProjectIndex`, not the generic source loader.

## Project adapter boundary

An adapter supplies one deterministically ordered `AdapterProjection` containing core nodes and
edges plus ordered adapter metadata. The core validates root identity, graph integrity, stable
ordering, and metadata-key uniqueness before exposing the projection through the standard derived
index. The loader is called again during an operation so identity or source changes fail closed.

Adapters own stricter project semantics such as authority precedence, phase rules, context
selection, query ordering, and render-model composition. They may not weaken root confinement,
canonical authority, graph validation, hashing, stale-state checks, or derived-output boundaries.
Shadow adapters are explicit local integrations and are not loaded by the normal generic MCP
process. A project integration may explicitly construct a read-only MCP server from one validated
`ProjectService` and an optional project-owned context provider. That server exposes only the fixed
read tool surface. The core does not discover adapters, choose projects or sessions, or import
project policy.

A proposal-enabled adapter declares confined canonical source, changeset, template, preview, and
render paths plus fixed writer permissions. It must supply a proposal validator. The core continues
to enforce optimistic hashes, writer permissions, graph integrity, limits, atomic changeset storage,
conflict detection, and preview confinement. The adapter validator enforces source-format and
project semantics that the generic core cannot infer. Generic projects retain the built-in Markdown
and TOML source-layout validator.

An explicit integration may construct the full fixed MCP surface for a configured adapter project
and one startup-bound writer. This does not add adapter discovery or canonical application. An
adapter without proposal settings or validation remains read-only.