shard-wiki/workplans/SHARD-WP-0009-git-decision-log.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-0009	workplan	git-backed DecisionLog + per-space append authority	whynot	shard-wiki	active	tegwick	whynot	2026-06-15	2026-06-15	SHARD-WP-0007	4fb5b29b-955c-4f37-85cf-58b4643ab1ca

SHARD-WP-0009 — git-backed DecisionLog + per-space append authority

Goal

Back the keystone with real storage: swap the in-memory DecisionLog (SHARD-WP-0007 T5) for a git-addressable, append-only log with a per-space append authority (lease), exactly as CoreArchitectureBlueprint §8.1 specifies and SHARD-WP-0006 T2 decided (resolves review B-1/B-3). The log API and the derived fold are unchanged; only storage + the concurrency model become real. This makes coordination-canonical state git-addressable (history/patch/review/ backup — I-6) and read-your-writes correct across processes, not just in-process.

Non-goal: distributed multi-node leasing beyond a single coordinator; per-space log sharding (blueprint O-12). Single append authority per space is the target.

Context

• Keystone spec: CoreArchitectureBlueprint.md §8.1; decision SHARD-WP-0006 T2.
• Current impl: src/shard_wiki/coordination/decision_log.py (in-memory; same API to preserve).

---

Git event-store backend (append = commit/object)

id: SHARD-WP-0009-T1
status: todo
priority: high
state_hub_task_id: "a8fcbb3e-fbc4-4f68-9cf0-d8a6ee057191"

A git-backed DecisionLog storage backend: each space is a ref/branch (or an objects stream); append writes an immutable event object and advances the ref; events(space) reads the ordered log; events serialize deterministically (stable JSON). Preserve the in-memory backend as the test/default double behind the same interface. Tests: append→git→read round-trips; ordering preserved; deterministic serialization.

Per-space append authority (lease)

id: SHARD-WP-0009-T2
status: todo
priority: high
state_hub_task_id: "62abd162-4243-4659-8d27-9fc967ab11a0"

A single append authority per space: a lease/leader abstraction that serializes appends so the log is a total order (the ordering authority §8.6 relies on). Non-holders forward append intents to the holder; the lease is time-bounded and re-grantable (HA: a failed holder is replaced and resumes from the log head). Tests: concurrent append attempts serialize; lease hand-off resumes from head; a partitioned non-holder cannot fork the log.

Fold over the git log + read-your-writes across processes

id: SHARD-WP-0009-T3
status: todo
priority: high
state_hub_task_id: "8cc3691e-05a7-443f-9292-a3fdf3fd59a4"

fold reads the git log into CoordinationState (unchanged semantics); verify read-your- writes across separate processes/handles against the same space ref. Tests: process A appends, process B (new handle) sees it; fold equals the in-memory fold for the same event sequence.

Migration + wiring

id: SHARD-WP-0009-T4
status: todo
priority: medium
state_hub_task_id: "281e1db4-6a75-456b-a2bc-b761feb10609"

Make InformationSpace use the git backend (configurable; in-memory remains for tests). A one-time importer replays an in-memory/JSON log into git. Update SCOPE; pytest + pyflakes green; no behavioural change to overlay/union (same fold).

---

Acceptance criteria

• DecisionLog git backend passes the same tests as the in-memory one (API/fold parity).
• Appends are totally ordered per space via a single append authority; read-your-writes holds across processes; a non-holder never forks the log.
• Coordination-canonical state is git-addressable (history/patch/review/backup).
• pytest + pyflakes green; each task committed; state-hub synced.

Suggested task order

T1 git store → T2 append authority → T3 cross-process fold → T4 migration + wiring.