markitect-tool/workplans/MKTT-WP-0006-cache-backend-architecture-core.md

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, depends_on_workplans, depends_on_tasks, related_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	depends_on_tasks	related_workplans	created	updated	state_hub_workstream_id
MKTT-WP-0006	workplan	Optional Cache Backend Architecture Core	markitect	done	markitect-tool	markitect	P1	50	MKTT-WP-0004	MKTT-WP-0003-T005	MKTT-WP-0010 MKTT-WP-0011	2026-05-03	2026-05-04	0c585f8a-5c7e-4c89-b785-5b0089180256

MKTT-WP-0006: Optional Cache Backend Architecture Core

Purpose

Create the optional backend fabric that lets markitect-tool attach cached ASTs, indexes, query adapters, context packages, and policy gateways without making persistent infrastructure mandatory for core CLI use.

Background

Research and architecture are captured in:

• docs/research-lab-cache-backend-research.md
• docs/cache-backend-architecture-blueprint.md
• docs/content-reference-literate-workflow-research.md

Decision

Do not start this before the current deterministic transform/composition slice has enough shape to show what cache invalidation must preserve. Start it before WP-0003 P3.7 caching becomes implementation work.

Keep the backend fabric open for MKTT-WP-0010 content-unit identities, reference graphs, processor provenance, and weave/tangle source maps. Those features do not need to be implemented here, but the capability model should not make them awkward later.

P6.1 - Define backend capability model

id: MKTT-WP-0006-T001
status: done
priority: high
state_hub_task_id: "8c04f146-942c-45b8-9a7b-3bd61916aa4b"

Define capability names, backend manifests, and compatibility checks for:

• snapshots
• JSON/AST query
• full-text search
• SQL
• vector/hybrid search
• context packages
• policy enforcement
• provenance

Implemented as BACKEND_CAPABILITIES, backend manifests, and compatibility checks in the optional backend package. Unknown extension capabilities are preserved as metadata while known capabilities remain stable for dispatch.

P6.2 - Define snapshot model and content identity

id: MKTT-WP-0006-T002
status: done
priority: high
state_hub_task_id: "5debc135-908a-47ed-ba15-564610970e38"

Specify content-addressed document snapshots keyed by source content hash, parser version, parse options, and contract version where relevant.

Include a placeholder for stable content-unit identities and dependency edges so references/chunks can be cached and invalidated later.

Implemented with SnapshotIdentity, DocumentSnapshot, DependencyEdge, and snapshot_identity_for_file, keyed by content hash, parser id/version, parse options hash, and optional contract hash.

P6.3 - Define backend interfaces

id: MKTT-WP-0006-T003
status: done
priority: high
state_hub_task_id: "a3e37112-1197-4f6f-8de8-7b3067ef060e"

Add protocol classes for snapshot backends, index backends, query adapters, context package registries, and access policy gateways.

Leave room for processor-result stores, reference graph adapters, and source-map or provenance adapters.

Implemented protocol interfaces for snapshot backends, index backends, query adapters, context package registries, access policy gateways, and processor result stores.

P6.4 - Implement local backend registry

id: MKTT-WP-0006-T004
status: done
priority: medium
state_hub_task_id: "6c9b8765-4d14-436d-a2c9-c028a31aaade"

Load backend manifests from project config and expose registered capabilities without importing optional dependencies unless needed.

Implemented BackendRegistry, YAML/Markdown markitect-backend manifest loading, default local manifest paths, examples, and capability filtering without importing backend implementation dependencies.

P6.5 - Add provenance envelope

id: MKTT-WP-0006-T005
status: done
priority: medium
state_hub_task_id: "7b551eae-99c8-4c8a-b781-18d59d318707"

Add provenance metadata shared by snapshots, query results, context packages, and diagnostics.

Implemented ProvenanceEnvelope with operation, snapshot, source, content hash, dependency edges, backend id, policy decision id, and extension metadata.

P6.6 - Add CLI scaffolding

id: MKTT-WP-0006-T006
status: done
priority: medium
state_hub_task_id: "921e589c-8b0d-4eeb-8834-4a4c6c73da65"

Add read-only commands:

mkt backend list
mkt backend inspect <id>
mkt cache status

No persistent write behavior is required in this task.

Implemented read-only mkt backend list, mkt backend inspect, and mkt backend snapshot-id. The existing mkt cache status remains the lightweight file-manifest status command.

Exit Criteria

• Core CLI still works without any backend.
• Backends can declare capabilities in Markdown/YAML manifests.
• Query and future cache work can target backend interfaces.
• Provenance is represented consistently.