92 lines
6.4 KiB
Markdown
92 lines
6.4 KiB
Markdown
|
# 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.
|