generated from coulomb/repo-seed
172 lines
4.8 KiB
Markdown
172 lines
4.8 KiB
Markdown
---
|
|
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.
|