generated from coulomb/repo-seed
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:
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user