165 lines
11 KiB
Markdown
165 lines
11 KiB
Markdown
# 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.8.1.
|
|
|
|
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 leased 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, bounded incoming-and-outgoing neighborhoods, and one
|
|
lease heartbeat. The heartbeat changes no project or index state. There is no write endpoint,
|
|
arbitrary query endpoint, static filesystem handler, external asset, or project-selection control.
|
|
|
|
The `graph-browser@5` 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 defers pointer capture and preserves node activation for ordinary clicks.
|
|
Loading another root node resets the viewport so the new neighborhood begins centered and fully
|
|
framed. Empty-canvas guidance is hidden whenever a neighborhood is rendered.
|
|
|
|
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. Both side panels
|
|
support pointer and keyboard resizing. The unblurred modal supports native resizing and constrained
|
|
title-bar dragging.
|
|
|
|
The browser derives presentation roles only from the returned bounded graph. The current root is
|
|
the primary focus. Nodes reachable through outgoing edges are children. Remaining incoming and
|
|
cross-boundary nodes are edge/context nodes. These roles receive distinct palettes and navigation
|
|
sections. An undirected shortest-hop calculation places nodes on distance rings and darkens each
|
|
role palette progressively, capped at fifty percent. This presentation does not reinterpret,
|
|
replace, or add project relationships.
|
|
|
|
Each invocation launches the validated snapshot in a detached local worker. The worker is outside
|
|
the short-lived MCP transport process, so transport teardown cannot close an active browser. It
|
|
tracks the longer-lived MCP client host and closes when that owner process exits. A repeated
|
|
invocation in the same MCP process replaces its tracked worker after a fresh index check.
|
|
|
|
The page renews a 180-second lease every 15 seconds and when it becomes visible; a link never opened
|
|
receives a 120-second startup grace. An abandoned page stops renewing and the detached worker closes
|
|
after the bounded lease. Explicit service shutdown closes the worker tracked by that service
|
|
immediately. Project-specific integrations receive the same tool because the parent validates and
|
|
serializes only the supplied `ProjectService` and `ProjectIndex` snapshot; the detached worker does
|
|
not discover projects or load canonical sources.
|
|
|
|
## 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.
|