shard-wiki/workplans/SHARD-WP-0007-foundation-implementation.md

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