shard-wiki/history/260615-core-architecture-blueprint-review-2.md

Critical review (round 2) — CoreArchitectureBlueprint.md (hardened)

Date: 2026-06-15 · Reviewer: tegwick (with Claude) · Subject: spec/CoreArchitectureBlueprint.md after SHARD-WP-0005 (commit f21b7b5) · Feeds: SHARD-WP-0006

A second hostile pass over the hardened blueprint. Round 1 found design bugs; this round finds (a) self-consistency regressions the surgical hardening introduced, and (b) deeper second-order gaps — some of which the hardening sharpened. Verdict: the architecture is now substantially sound; what remains in §B/§C are hard distributed-systems/operational questions, not design smells — except §A (a real regression) and three foundational gaps in §B.

---

A. Self-consistency regressions introduced by surgical hardening

The 9 edits deepened §6–§9 but did not propagate to the overview surfaces, so the document now contradicts itself between its summary and its body (and readers trust the summary).

• A-1 (real contradiction). §4 still says "Addressing, equivalence, and transclusion key on identity" — the exact conflation T2 fixed in §7.2 (equivalence keys on content fingerprint across distinct identities). → WP-0006 T1
• A-2. §4 "Projection — typed on two axes" and §4 "Provenance envelope … every artifact carries [full wrapper]" are stale vs T7's §8.4 (two-axis = extension point; trivial default) and §7.3 (layered effective-vs-own). → T1
• A-3. §10 policy surface omits knobs the hardening added (freshness/staleness §8.8, squash-compaction §8.1, conflict-resolution preset §8.6, tenant-partition) — yet §11 defines policy/ as "owns the §10 surface." The module contract points at a stale list. → T1
• A-4 (cosmetic). §3 diagram + §11 header still say "L4 rebuildable cache" / "15 spectra," advertising the pre-hardening model (§8.7 incremental-first; §6.5 orthogonal-core). → T1

Meta-point: surgical editing hardened the body but regressed whole-document coherence; v2 needs an overview-reconciliation pass.

B. Foundational gaps (serious; some sharpened by the hardening)

• B-1 — The journal is now a concurrent-write DB, but it's single-writer Git. §8.6's consistency model assumes "the journal is local Git, read-your-writes." L4 multi-tenant + the L6 Orchestrator API imply a server; HA/scale implies multiple instances. Concurrent commits of coordination-canonical state to one git journal = lock contention / merge races; Git is not a concurrent-write store. Either single-writer-per-space (an unstated HA ceiling) or a real concurrent coordination store with Git as an export. T1 of WP-0005 worsened this by loading more canonical state into the journal. The keystone unanswered question. → T2
• B-2 — Capability-as-data trusts self-reported profiles with no conformance check. I-3 + §6.5's degradation contract assume the profile tells the truth. A buggy adapter (claims merge=git/text, corrupts; claims notify, never emits) silently poisons every degradation decision. No adapter conformance suite (declared profile == observed behavior) exists. Foundational for an architecture whose correctness rests on profile accuracy. → T3
• B-3 — "Coordination-canonical state in the journal" has no representation design. T1 relocated overlays/bindings/aliases/equivalence-sets/merges into "the journal" without saying how Git stores structured mutable state. "All equivalences touching X" over a git-of-files is O(scan) unless indexed — and an index is L4/derived. The new central concept is a black box; resolve with B-1. → T2
• B-4 — Incremental equivalence is under-specified/likely incorrect; I-2 only eventually true. §8.7 re-verifies a changed page's new candidate set but not the pairs it leaves (a page exiting an LSH bucket can break an existing equivalence edge); the delta is not additive. Deeper: incremental maintenance drifts from f(canonical), so I-2 holds only eventually, guaranteed solely by an expensive reconcile-against-rebuild. Needs a stated verification mechanism (background checker / digest-vs-sampled-rebuild). → T4

C. Real but second-tier (track as open problems O-8…O-11)

• C-1 — Mechanism-over-policy → operator burden; no preset bundles. ~7 knob families with sub-modes and interactions; only authz (L0–L4) bundles into personas. Need named bundles ("personal vault" / "team wiki" / "enterprise federation"). → O-8 / T5
• C-2 — Tenant partitioning (I-13) vs shard sharing + lazy projection. A shard in two roots is cached twice → duplicate storage + double refresh on rate-limited backends. Shard exclusive-to-one-root or shareable? Unresolved. → O-9 / T5
• C-3 — Span-level authz + transclusion is an unmodeled leak path. Authz is per page/shard/tenant; transclusion crosses shards at span granularity → a page can leak a span past its ACL (aggregation/inference). §7.3's ⊕ also stops being simple two-level inheritance across a transclusion boundary. → O-10 / T5
• C-4 — Union-under-unavailability undefined. Freshness covers stale, nothing covers down. The dead-shard read path (partial union? error? last-known?) is unspecified though it's the commonest real failure. → O-11 / T5

D. Recommended resolution (→ SHARD-WP-0006)

1. §A reconciliation (T1) — make the overview match the hardened body.
2. Journal & coordination-state model (T2) — settle single-vs-multi-writer and separate the coordination-state store from the content-history journal. Likely resolution: event-sourced coordination — an append-only decision log is the coordination-canonical tier (git-addressable, I-6 preserved); the queryable current state (alias table, equivalence set) is a derived fold of the log (disposable). Append-logs tolerate concurrency far better than mutable-file Git; state a concurrency model. Resolves B-1 + B-3 together.
3. Adapter conformance suite (T3) — make a passing conformance run part of the contract (B-2): every adapter proves declared profile == observed behavior.
4. Incremental correctness + I-2 verification (T4) — fix the leaving-bucket re-verification and propagation; add a background consistency-checker / derived-tier digest so I-2 is verifiable, not merely asserted (B-4).
5. Track §C (T5) — O-8…O-11 with chosen direction + revisit trigger; close-out.