spec(SHARD-WP-0006 T2): event-sourced coordination + per-space append authority

Resolves B-1+B-3. Coordination-canonical state = an append-only decision log
in the git journal (events: overlay/binding/alias/merge); queryable current
state = a derived fold (tier-3, indexed). Concurrency: one append authority
per space (lease/leader) → totally-ordered per-space log, read-your-writes
across instances, HA via re-grantable lease, partition yields to log integrity.
Updates §1, §4, §8.1, §8.6, §11. I-6 strengthened (coordination state is now
git-addressable history/patch/review), not bypassed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-15 02:00:43 +02:00
parent cbd29e0a32
commit 08a2148079
2 changed files with 53 additions and 9 deletions

View File

@@ -30,7 +30,10 @@ Everything in shard-wiki follows from one organising decision — that state com
> **2. Coordination-canonical** — durable state *born inside shard-wiki* that encodes human
> or cross-shard decisions and exists nowhere else: overlays (the local truth against a
> read-only shard), curator equivalence bindings, alias tables, merge/reconciliation
> decisions. It lives in the **Git coordination journal**.
> decisions. It is recorded as an **append-only decision log in the Git coordination
> journal** (event-sourced, §8.1); the *queryable current form* of that state (the effective
> alias table, the equivalence set) is a **derived fold** of the log — i.e. tier 3, not tier 2.
> What is canonical is the **log of decisions**, not any mutable snapshot of them.
> **3. Derived-disposable** — everything shard-wiki *computes* from (1)+(2): the union graph,
> equivalence index, query indexes, projections, views. It can be deleted and recomputed.
>
@@ -170,10 +173,11 @@ parallel terms.
- **Provenance envelope** — the metadata each artifact carries (source shard, freshness,
liveness, authz context, overlay status, divergence, lineage), stored **layered**: a
page-level envelope + span-level *deltas*, so per-span cost is near-zero when uniform (§7.3).
- **Coordination journal** — the L3 Git-backed record of change flows for a space, and the
durable home of all **coordination-canonical** state (§1): overlays, curator equivalence
bindings, alias tables, merge/reconciliation decisions. This state is born inside shard-wiki,
exists nowhere else, and is *not* derived — it must be committed, never recomputed.
- **Coordination journal** — the L3 Git-backed, **append-only decision log** for a space: the
durable home of all **coordination-canonical** state (§1, §8.1) as *events* (overlay-created,
binding-made, alias-set, merge-decided), plus the content change-flow record. It is event-
sourced — committed, never overwritten; the queryable current coordination state is a derived
fold of it (§8.1).
- **Overlay** — a non-destructive local edit against a remote/read-only/limited shard,
representable as draft/patch/commit/MR before destructive apply. Coordination-canonical: an
unapplied overlay is the local truth and lives in the journal.
@@ -396,6 +400,42 @@ operations (fork, import, reconcile, overlay-apply, space-branch) and **is** the
the journal supplements (begins-now / mirrors-forward / snapshots-replica) or imports
(backfill open file history). History portability is a spectrum, handled per profile (axis 5).
**The journal is an append-only decision log; current coordination state is a derived fold
(review B-3).** The first draft said coordination-canonical state "lives in the journal"
without saying how Git — excellent for history, poor for mutable structured state — represents
an alias table or an equivalence graph. Resolution: **event sourcing.** The journal stores
*decisions as events* (`overlay-created`, `binding-made`, `alias-set`, `merge-decided`,
`page-forked`), append-only and git-addressable (so history/patch/review/backup over
coordination state come for free — I-6 is *strengthened*, not bypassed). The **queryable
current state** (the effective alias table, the live equivalence set) is a **derived fold** of
the log — tier-3 disposable, indexed like any other derived structure (§8.7), rebuilt by
replaying the log. So "all equivalences touching X" is an index lookup, not an O(scan) of Git.
This is the clean form of the §1 three-state model: **the log is canonical; its folded current
state is derived.**
**Concurrency: who may append (review B-1).** A multi-tenant L4 deployment runs several
orchestrator instances, so "the journal is local Git, single writer" is not given. The model:
- **One *append authority* per information space.** Appends to a space's log are serialized
through a single logical writer (a per-space lease/leader; instances without the lease forward
their append intents to it). This makes the log a **totally-ordered event sequence** per space
— the ordering authority §8.6 relies on — without a distributed transaction. Spaces are
independent, so this scales horizontally *across* spaces (the unit of partition is the space /
root entity, matching the tenant partition, I-13); it is a per-space serialization point, not
a global one.
- **Git is the durable, addressable form; appends are commits** (or fast objects batched into
commits) under the lease — no concurrent-writer merge races because there is one writer at a
time per space.
- **Read-your-writes** holds within a space because every reader resolves current state from
the same ordered log (or its fold); across spaces there is no shared state to be inconsistent.
- **HA / failover:** the lease is time-bounded and re-grantable; a failed append-authority is
replaced and resumes from the log's head (the log is the recovery point). A partition that
splits the authority degrades that *space* to read-only until a single writer is re-elected —
it never forks the log (availability yields to log integrity; an explicit, stated trade).
- **Open residual (→ §12, O-3-adjacent):** whether very high append rates need per-space log
*sharding* (sub-logs merged by a deterministic order) is an implementation spike, not an
architectural change.
**History must stay recoverable *and* bounded (review C-3).** "Every write is a commit" + open
L0 means an unbounded, bot-/vandalism-amplified journal that eventually degrades Git itself.
Recoverability (I-10) is non-negotiable, so the answer is *compaction, not deletion*:
@@ -495,8 +535,10 @@ mechanism (not policy) that makes concurrent editing safe (review bug B-2).
**The consistency guarantee — causal, anchored on the journal:**
- **Read-your-writes for coordination-canonical state.** Once an overlay/binding/merge is
committed to the journal, this client always sees it (the journal is the client's own causal
spine). This is a *strong* local guarantee, cheap because the journal is local Git.
appended to the space's decision log, every reader of that space sees it — because the log is
a **single totally-ordered sequence per space** (one append authority, §8.1), and all readers
resolve current state from that one order. The guarantee holds across orchestrator instances,
not just within one process; it is cheap because ordering is per-space, never global.
- **Causal consistency across the derived tier.** The union/index/projections reflect a causal
cut of `(sharded inputs seen so far, journal)`. Effects never appear before their causes; a
projection that has seen journal commit *C* has seen everything *C* depends on.
@@ -705,7 +747,9 @@ src/shard_wiki/
adapters/ # L1 bottom waist: AdapterContract (versioned iface), CapabilityProfile,
# attachment-mode binding; concrete adapters:
git/ folder/ gitea/ obsidian/ webdav/ notion/ … # each: profile + verbs
coordination/ # L3: GitJournal, OverlayEngine (draft→patch→MR), reconcile
coordination/ # L3: DecisionLog (append-only, git-backed, per-space append authority/
# lease), OverlayEngine (draft→patch→MR), reconcile
# (current coordination state = a derived fold → lives in union/)
federation/ # L3: FederationModel strategies (fork_journal, vcs_ping,
# graph_join, feed, activitypub, engine_mirror)
union/ # L4 (derived): IdentityResolver, EquivalenceGraph, UnionGraph,