generated from coulomb/repo-seed
workplans: register follow-up implementation roadmap (WP-0009..0012)
WP-0009 git-backed DecisionLog + per-space append authority (keystone backing); WP-0010 derived views (wikilinks, BackLinks, RecentChanges, AllPages/SiteMap); WP-0011 incremental union + equivalence index + I-2 verification; WP-0012 second adapter (git-IS-store) validating the contract on a new substrate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
101
workplans/SHARD-WP-0009-git-decision-log.md
Normal file
101
workplans/SHARD-WP-0009-git-decision-log.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
id: SHARD-WP-0009
|
||||
type: workplan
|
||||
title: "git-backed DecisionLog + per-space append authority"
|
||||
domain: whynot
|
||||
repo: shard-wiki
|
||||
status: active
|
||||
owner: tegwick
|
||||
topic_slug: whynot
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
depends_on:
|
||||
- SHARD-WP-0007
|
||||
---
|
||||
|
||||
# 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)
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0009-T1
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
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)
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0009-T2
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0009-T3
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
`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
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0009-T4
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user