Backend fabric extension

docs/backend-fabric.md

@@ -0,0 +1,119 @@
+# Optional Backend Fabric
+
+Date: 2026-05-04
+
+## Purpose
+
+The backend fabric is the WP-0006 architecture layer for persistent snapshots,
+indexes, query adapters, context packages, policy gateways, and provenance.
+
+It is optional. The core parser, contracts, query engine, transforms, includes,
+processors, templates, and generation commands keep working without any backend
+manifest or persistent service.
+
+## Capability Model
+
+Backend manifests declare capabilities by name. The initial common vocabulary
+is:
+
+- `snapshots`
+- `ast`
+- `json`
+- `jsonpath`
+- `fts`
+- `sql`
+- `vector`
+- `hybrid`
+- `context_packages`
+- `policy`
+- `policy_pushdown`
+- `provenance`
+- `reference_graph`
+- `processor_results`
+- `source_maps`
+
+Unknown capabilities are preserved in manifest metadata as extension hints, but
+compatibility checks only reason over declared names.
+
+## Manifests
+
+Backends can be declared as YAML files or Markdown files with a
+`markitect-backend` fenced YAML block:
+
+````markdown
+```yaml markitect-backend
+id: local-sqlite-cache
+kind: cache-backend
+capabilities:
+  - snapshots
+  - json
+  - fts
+  - provenance
+storage:
+  engine: sqlite
+  path: .markitect/cache/index.sqlite
+policy:
+  mode: labels
+```
+````
+
+The loader reads manifests only. It does not import optional dependencies or
+open a database.
+
+## Snapshot Identity
+
+Snapshot identity is content addressed and includes:
+
+- source path
+- source content hash
+- parser id
+- parser version
+- parse options hash
+- optional contract hash
+
+The resulting `snapshot_id` is a stable hash over those identity fields. This
+lets future AST, JSONPath, FTS, SQL, vector, policy, and context-package
+backends invalidate derived data without guessing what changed.
+
+## Provenance Envelope
+
+The shared backend provenance envelope records:
+
+- operation
+- snapshot id
+- source path
+- content hash
+- dependency edges
+- backend id
+- policy decision id
+- extension metadata
+
+This complements the operation-level provenance added in WP-0010 and gives
+future snapshot/query/context/policy results a common metadata shape.
+
+## Interfaces
+
+Protocol interfaces are provided for:
+
+- `SnapshotBackend`
+- `IndexBackend`
+- `QueryAdapter`
+- `ContextPackageRegistry`
+- `AccessPolicyGateway`
+- `ProcessorResultStore`
+
+These are contracts for future implementations. They are intentionally light
+and do not force the current CLI through a persistent backend.
+
+## CLI
+
+Read-only inspection commands:
+
+```bash
+mkt backend list --path examples/backends
+mkt backend inspect local-sqlite-cache --path examples/backends --require snapshots --require provenance
+mkt backend snapshot-id docs/content-references.md
+```
+
+The existing `mkt cache status` remains the lightweight file-manifest change
+detector. Backend manifests are a separate optional fabric.

docs/workplan-planning-map.md

@@ -31,7 +31,7 @@ and descriptions mirror the operational view.
 | `MKTT-WP-0002` | complete | done | `MKTT-WP-0001` | Legacy scope extraction is complete. |
 | `MKTT-WP-0004` | complete | done | `MKTT-WP-0001`, `MKTT-WP-0002` | Contract framework is complete and informs later validation/generation work. |
 | `MKTT-WP-0003` | complete | done | `MKTT-WP-0001`, `MKTT-WP-0002`, `MKTT-WP-0004` | Core toolkit implementation is complete. |
-| `MKTT-WP-0006` | P1 | todo | `MKTT-WP-0004`; task-level trigger: `MKTT-WP-0003-T005` | Ready after transform/composition shape is clear; should account for future reference/provenance needs. |
+| `MKTT-WP-0006` | complete | done | `MKTT-WP-0004`; task-level trigger: `MKTT-WP-0003-T005` | Optional backend fabric is complete: manifests, capabilities, snapshot identity, interfaces, registry, provenance, and read-only CLI scaffolding. |
 | `MKTT-WP-0010` | complete | done | `MKTT-WP-0004`; task-level trigger: `MKTT-WP-0003-T006` | Content references, processors, explode/implode, weave/tangle, content classes, and migration examples are complete as the first WP-0010 extension layer. |
 | `MKTT-WP-0007` | P2 | todo | `MKTT-WP-0006` | First practical cache backend use case: AST/JSONPath/SQLite/FTS. |
 | `MKTT-WP-0005` | P2 | todo | `MKTT-WP-0003`, `MKTT-WP-0004` | Pick up when generation/form/context or semantic assessment pressure appears. |