---
id: MKTT-WP-0006
type: workplan
title: "Optional Cache Backend Architecture Core"
domain: markitect
status: done
owner: markitect-tool
topic_slug: markitect
planning_priority: P1
planning_order: 50
depends_on_workplans:
  - MKTT-WP-0004
depends_on_tasks:
  - MKTT-WP-0003-T005
related_workplans:
  - MKTT-WP-0010
  - MKTT-WP-0011
created: "2026-05-03"
updated: "2026-05-04"
state_hub_workstream_id: "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

```task
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

```task
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

```task
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

```task
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

```task
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

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

Add read-only commands:

```text
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.