diff --git a/spec/CoreArchitectureBlueprint.md b/spec/CoreArchitectureBlueprint.md index 12ced51..6670472 100644 --- a/spec/CoreArchitectureBlueprint.md +++ b/spec/CoreArchitectureBlueprint.md @@ -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, diff --git a/workplans/SHARD-WP-0006-architecture-hardening-2.md b/workplans/SHARD-WP-0006-architecture-hardening-2.md index 60e87d5..5e3ae29 100644 --- a/workplans/SHARD-WP-0006-architecture-hardening-2.md +++ b/workplans/SHARD-WP-0006-architecture-hardening-2.md @@ -43,7 +43,7 @@ where mutable coordination state actually lives*. ```task id: SHARD-WP-0006-T1 -status: todo +status: done priority: high state_hub_task_id: "b0b4087b-ec19-4ae7-94b1-9a813a6133b9" ```