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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on	state_hub_workstream_id
SHARD-WP-0007	workplan	foundation implementation — model, contract, decision log, union read	whynot	shard-wiki	done	tegwick	whynot	2026-06-15	2026-06-15	SHARD-WP-0002	d551fba1-9c48-4841-a9a5-a9f190f73a60

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 + ⊕

id: SHARD-WP-0007-T1
status: done
priority: high
state_hub_task_id: "be8f9efe-cfba-46d0-be91-f9b6e87bc0d2"

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

id: SHARD-WP-0007-T2
status: done
priority: high
state_hub_task_id: "780ad01f-c3e1-4b49-9ae9-60e0324178a7"

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)

id: SHARD-WP-0007-T3
status: done
priority: high
state_hub_task_id: "f6e35ddb-ab1e-406a-82f8-563244455f6b"

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

id: SHARD-WP-0007-T4
status: done
priority: medium
state_hub_task_id: "12d7fb8d-3842-4142-a462-9d1e6efe58bd"

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

id: SHARD-WP-0007-T5
status: done
priority: high
state_hub_task_id: "c87b1896-59a5-4cde-a292-1086caebd085"

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

id: SHARD-WP-0007-T6
status: done
priority: high
state_hub_task_id: "fed38b60-dc0b-40cf-93e9-ab0260aa3ff9"

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

id: SHARD-WP-0007-T7
status: done
priority: medium
state_hub_task_id: "86c0b255-e373-460d-859d-a39bf6ea4ffb"

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.