Close Milestone 4 with adapter adoption evidence
This commit is contained in:
parent
95271dcf2e
commit
6d06195950
27 changed files with 2870 additions and 325 deletions
165
docs/CORE_CONCEPTS_AND_AUTHORITY.md
Normal file
165
docs/CORE_CONCEPTS_AND_AUTHORITY.md
Normal file
|
|
@ -0,0 +1,165 @@
|
|||
# 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](ADAPTER_AUTHORING_GUIDE.md) and [Incremental
|
||||
indexing](INCREMENTAL_INDEXING.md).
|
||||
|
||||
## 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](RENDERING_AND_VISUALIZATION.md).
|
||||
|
||||
## 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](POLICY_PRECEDENCE.md) and
|
||||
[Legacy and no-AST operation](LEGACY_AND_NO_AST.md).
|
||||
|
||||
## 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](PROJECT_DESCRIPTOR.md), [New-project
|
||||
quickstart](NEW_PROJECT_QUICKSTART.md), or [Core contract](CONTRACT.md).
|
||||
Loading…
Add table
Add a link
Reference in a new issue