generated from coulomb/repo-seed
tegwick
d2c73b02d9
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>
102 lines
3.5 KiB
Markdown
102 lines
3.5 KiB
Markdown
---
|
|
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.
|