DocForge2/docs/CORE_CONCEPTS_AND_AUTHORITY.md

Core concepts and authority

DocForge is a project-bound knowledge compiler. It turns explicit canonical project facts into validated graphs and bounded derived views without transferring authority to the index, an agent, or a renderer.

One project, one explicit root

Every operation is bound to one canonical real project directory. Paths in descriptors and adapter configuration are project-relative and confined beneath that root. A CLI or MCP process does not discover or switch projects after startup.

The project root determines:

• which descriptor and canonical sources may be read;
• where derived cache and changeset roots may exist;
• which project identity, revision, source hash, and generation appear in results;
• which writer, applier, rendering, and viewer policies can be selected.

Generated client fragments preserve that binding. They are machine-local configuration projections, not portable project authority.

Canonical facts and derived evidence

Canonical inputs own the facts:

• generic Markdown or TOML node sources;
• authority files named by a generic descriptor;
• an adapter's declared canonical sources and implementation boundary;
• .docforge/project.toml for a generic project;
• .docforge/reference-adapter.toml for a fixed reference integration.

Everything DocForge builds from those inputs is derived:

• SQLite indexes, attestations, generation receipts, and generation diffs;
• incremental extraction caches;
• task-context capsules and query responses;
• changeset previews;
• render plans, immutable packages, fragments, artifacts, and receipts;
• portable graph publications and live-viewer processes;
• generated Codex, Claude, and OpenClaw fragments.

Derived state may be discarded and rebuilt. A derived artifact can prove what it was bound to, but it cannot override current canonical content.

Nodes, relationships, and Logic

The primary graph contains nodes and directed relationships.

A node has a stable project-wide ID, title, family, authority, status, tags, summary, content, source identity, and content hash. A generic Markdown file contains one node beneath a TOML metadata block; a generic TOML source may contain multiple nodes. Adapter nodes use the same public graph contract.

A relationship is an exact (source, relation, target) triple. The project descriptor defines the allowed relation names. DocForge gives depends_on special acyclic validation, but it does not invent domain meaning for a project's other relation names. Retrieval recognizes only a versioned alias set for task planning and reports unknown allowed relations as unclassified.

Logic is deliberately separate. It is a lazy function-scoped control-flow projection owned by one primary node. Decisions, actions, loops, convergence points, returns, and exceptions connect through explicit branch edges. Logic does not add statement-level nodes to ordinary Nodes, Flow, Web, search, or generation-diff results. Python, JavaScript, TypeScript, and C++ integrations may publish Logic when their adapter contract supports it.

Authority, status, family, and tags

These fields answer different questions:

• authority describes the role of the content. The generic vocabulary is authoritative, approved_plan, derived, proposal, and historical.
• status is project-defined lifecycle state such as current, active, or verified.
• family is a project-defined content grouping used for filtering, profiles, rendering, and writer permissions.
• tags are exact project labels for retrieval and presentation.

An authoritative node can still become stale; authority is not a freshness claim. A derived node is still canonical if it is stored in a declared canonical source; the label describes its role, not whether DocForge may silently regenerate it. Status and authority never grant an MCP writer permission.

Validation, synchronization, and generations

Validation loads the complete canonical graph and rejects unsafe paths, invalid source formats, duplicate IDs, unresolved relationships, prohibited cycles, violated project limits, and adapter-specific contract failures.

The disposable index is published atomically only after the complete graph and SQLite integrity checks pass. Its attestation binds the whole index file. A successful replacement is the derived publication commit point; later receipt-writing trouble is reported as degraded evidence rather than as a false claim that the replacement failed.

MCP operations automatically synchronize derived state under a project lock before normal work. A graph generation identifies one validated indexed snapshot. Generation-pinned retrieval and rendering do not reopen mutable sources behind an older snapshot.

The latest generation diff is one bounded primary-graph transition, not a history database. It contains no Logic details or source text.

Complete and incremental adapters

load_projection() is the compatibility baseline and clean graph oracle. An incremental adapter adds:

• load_manifest() for cheap project identity, source inventory, fingerprints, and dependencies;
• extract_source() for one cacheable source contribution;
• optionally assemble_projection() to normalize overlapping contributions.

When incremental contributions contain Logic, load_complete_assembly() supplies a cache-independent complete graph-plus-Logic oracle. Warm cache behavior is an optimization, never a different authority path. Corrupt or incompatible extraction caches are treated as misses, and a clean complete build remains the equivalence and recovery boundary.

The public types, validators, and conformance helper are exported from docforge.adapter_sdk. See the Adapter authoring guide and Incremental indexing.

Proposals are not canonical changes

A changeset is an isolated, ordered proposal over an exact canonical base. Each operation names preconditions, and the final changeset has a content-derived hash. Validation projects the complete resulting graph before application.

Canonical application requires:

1. a writer declared in the descriptor;
2. a process started with the matching proposal and application authority;
3. one explicit final changeset hash;
4. unchanged source, relationship, permission, and graph preconditions.

Application does not perform Git mutation, build, deployment, or publication. Until exact-hash application succeeds, canonical project files remain unchanged.

Three independent output projections

Manual rendering, portable graph publication, and the live viewer are separate:

• a manual is a declared derived HTML view over selected nodes;
• a portable graph is a content-addressed static Nodes, Flow, or Web artifact;
• the live viewer is a managed loopback process pinned to one validated index generation and can request lazy Logic.

Their policies compose independently. Disabling one does not transfer its authority to another. None is canonical documentation or a retrieval authority. See Rendering and visualization.

Binding policy is not project truth

Capability mode, no-AST preservation, diagnostics, and projection modes describe one running process or generated client binding. They do not rewrite the descriptor or canonical graph.

--no-ast forbids AST-family adapter evolution and Logic publication/retrieval for that binding. It does not inspect parser implementation, sandbox the filesystem, or convert an existing AST/Tree-sitter adapter into a no-AST adapter. Read Policy precedence and Legacy and no-AST operation.

Trust the narrowest evidence

DocForge reports stable IDs, hashes, generations, omissions, truncation, and provenance limits so a consumer can distinguish proof from inference. A source inventory is not a semantic graph; a syntax-level relationship is not compiler resolution; a configuration doctor is not a connection test; a viewer snapshot is not continuous monitoring; and a benchmark is not a release.

Continue with the Project descriptor, New-project quickstart, or Core contract.