generated from coulomb/repo-seed
workplan: SHARD-WP-0007 foundation implementation (first vertical slice)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
152
workplans/SHARD-WP-0007-foundation-implementation.md
Normal file
152
workplans/SHARD-WP-0007-foundation-implementation.md
Normal file
@@ -0,0 +1,152 @@
|
||||
---
|
||||
id: SHARD-WP-0007
|
||||
type: workplan
|
||||
title: "foundation implementation — model, contract, decision log, union read"
|
||||
domain: whynot
|
||||
repo: shard-wiki
|
||||
status: active
|
||||
owner: tegwick
|
||||
topic_slug: whynot
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
depends_on:
|
||||
- SHARD-WP-0002
|
||||
---
|
||||
|
||||
# SHARD-WP-0007 — Foundation implementation
|
||||
|
||||
## Goal
|
||||
|
||||
Begin implementation: a **first vertical slice** of the architecture in `src/shard_wiki/`,
|
||||
faithful to `spec/CoreArchitectureBlueprint.md` (esp. §11 module layout, §6 contract, §7 page
|
||||
model, §8.1 keystone) and `spec/TechnicalSpecificationDocument.md §A`. Target capability:
|
||||
**attach folder shard(s) → resolve a page through the union → read it with layered provenance**,
|
||||
plus the **event-sourced decision log keystone**. All code typed, tested (pytest), linted
|
||||
(ruff), pure-stdlib (no new deps).
|
||||
|
||||
**Non-goal (this slice):** write-through, federation transports, derivation/computational
|
||||
projection, authz beyond the null provider, a network API. Those are later workplans.
|
||||
|
||||
## Guiding rules
|
||||
|
||||
- Honour the blueprint **dependency rule** (§11): `provenance/` and `policy/` are
|
||||
dependency-free leaves; `model/`/`adapters/` import only leaves; `union/`/`projection/` are
|
||||
the derived tier and may import down but nothing imports them.
|
||||
- **Identity ≠ placement ≠ equivalence** (§7.2). **Provenance is layered** (§7.3).
|
||||
- Mechanism over policy; capability-as-data; union without erasure.
|
||||
|
||||
---
|
||||
|
||||
## provenance/ leaf — layered ProvenanceEnvelope + ⊕
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0007-T1
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
`src/shard_wiki/provenance/`: the `ProvenanceEnvelope` value type (source_shard, source_rev?,
|
||||
observed_at, liveness, staleness_state, authz_context, overlay_state, divergence, lineage) and
|
||||
the **effective composition `⊕`** (page envelope ⊕ span delta → effective; uniform span = zero
|
||||
delta). Frozen dataclasses, no tree deps. Tests: ⊕ identity (no delta), override, partial delta.
|
||||
|
||||
## model/ — Identity, Placement, Span, Page, CapabilityProfile
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0007-T2
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
`src/shard_wiki/model/`: `Identity` (shard-scoped stable handle, value-equal, survives edits),
|
||||
`Placement` (path + shard), `Span`, `Page` (identity, body, spans, page-level envelope),
|
||||
page-shape enum; `CapabilityProfile` with the **orthogonal core axes** + a `validate()` applying
|
||||
implication rules that **reject impossible profiles** (§6.5). Imports only `provenance/`. Tests:
|
||||
identity stability vs content change; profile validation accepts/rejects.
|
||||
|
||||
## adapters/ — versioned AdapterContract + FolderAdapter (read)
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0007-T3
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
`src/shard_wiki/adapters/`: `AdapterContract` (a `Protocol`/ABC with the operation verbs;
|
||||
`profile()` + `read()` mandatory, others optional/`NotSupported`), `contract_version`; a
|
||||
`FolderAdapter` (file-store attachment) that reads a directory of Markdown into `Page`s with a
|
||||
provenance envelope, declaring a verified-shape profile (read-only, file-store, path addressing,
|
||||
git-or-none history). Imports `model/`, `provenance/`. Tests: read a temp folder → pages.
|
||||
|
||||
## adapters/ — conformance suite
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0007-T4
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
`src/shard_wiki/adapters/conformance.py`: a battery that, given a binding, **verifies declared
|
||||
profile == observed behaviour** (read round-trips; unsupported verbs raise `NotSupported`;
|
||||
absence is honest) and returns a capability-by-capability report; `assert_conformant()` for
|
||||
registration. Run it against `FolderAdapter`. Tests: a conformant adapter passes; a deliberately
|
||||
lying stub fails with a precise diff.
|
||||
|
||||
## coordination/ — the event-sourced DecisionLog keystone
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0007-T5
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
`src/shard_wiki/coordination/`: `DecisionLog` — append-only, **totally ordered per space**
|
||||
(single append-authority abstraction; in-memory now, git-backed adapter later), event types
|
||||
(`overlay_created`, `binding_made`, `alias_set`, `merge_decided`, `page_forked`), and a
|
||||
**derived fold** to current coordination state (effective alias table, equivalence set). Tests:
|
||||
append→ordered read; fold reproduces current state; read-your-writes.
|
||||
|
||||
## policy/ leaf + union/ — IdentityResolver + minimal union read
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0007-T6
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
`src/shard_wiki/policy/` (leaf: presets + `resolve()` for canonical-source = chorus default);
|
||||
`src/shard_wiki/union/`: `IdentityResolver` + a minimal `UnionGraph` that, over ≥1 attached
|
||||
folder shard plus the decision-log fold (aliases), resolves a name → page(s) with provenance,
|
||||
returning a **chorus set** on ambiguity (ADR-01). Imports down only. Tests: two shards holding
|
||||
the same name → chorus; alias from the log redirects resolution.
|
||||
|
||||
## Orchestrator wiring + slice integration test
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0007-T7
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
A thin `shard_wiki` entry (attach shard, resolve, read) tying the slice together; an
|
||||
**integration test** for the target capability (attach two folder shards → resolve → read union
|
||||
page with layered provenance + chorus). Replace the smoke tests' role (keep them). Update SCOPE +
|
||||
spec/README; ensure `pytest` and `ruff check` are green.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- `pytest` green, `ruff check` clean, no new runtime dependencies.
|
||||
- The vertical slice works end-to-end: attach folder shard(s) → resolve → read union page with
|
||||
layered provenance and chorus-on-ambiguity.
|
||||
- Module boundaries match blueprint §11 (leaf rails dependency-free; derived tier imported by
|
||||
nothing) — checkable by inspection/import.
|
||||
- Identity/placement/equivalence are distinct in code; provenance is layered; capability
|
||||
profiles are validated and conformance-checked.
|
||||
- Each task committed; state-hub synced.
|
||||
|
||||
## Suggested task order
|
||||
|
||||
T1 provenance → T2 model → T3 folder adapter → T4 conformance → T5 decision log →
|
||||
T6 resolver/union → T7 wiring + integration.
|
||||
Reference in New Issue
Block a user