shard-wiki/workplans/SHARD-WP-0006-architecture-hardening-2.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on	state_hub_workstream_id
SHARD-WP-0006	workplan	core architecture hardening II (round-2 review fixes)	whynot	shard-wiki	done	tegwick	whynot	2026-06-15	2026-06-15	SHARD-WP-0005	badb83f8-2806-4018-9d7f-d4666d3510ba

SHARD-WP-0006 — Core architecture hardening II

Goal

Resolve the round-2 review (history/260615-core-architecture-blueprint-review-2.md): reconcile the document's overview with its hardened body (§A), settle the three foundational gaps (§B: journal concurrency + coordination-state representation; adapter conformance; incremental-maintenance correctness + I-2 verification), and track the second-tier items (§C) as open problems. Deliverable: a revised spec/CoreArchitectureBlueprint.md that is self-consistent and answers the keystone question — single- vs multi-writer journal, and where mutable coordination state actually lives.

Context

• Round-2 review: history/260615-core-architecture-blueprint-review-2.md (A-1…A-4, B-1…B-4, C-1…C-4; resolution §D).
• Round-1 review + first hardening: history/260615-core-architecture-blueprint-review.md, SHARD-WP-0005.
• Constraint to honour: INTENT I-6 / "Git-addressable coordination layer" — any coordination store must remain git-addressable (history/patches/review/backup), not abandon Git.

Non-goal: Implement anything. Architecture spec revision only.

---

§A overview-reconciliation pass

id: SHARD-WP-0006-T1
status: done
priority: high
state_hub_task_id: "b0b4087b-ec19-4ae7-94b1-9a813a6133b9"

Make the overview match the hardened body (review A-1…A-4):

• A-1 (bug): §4 "Page identity vs placement" — remove "equivalence … key on identity"; state equivalence keys on content fingerprint across identities (align with §7.2).
• A-2: §4 "Projection" → trivial-default + extension-point framing (align §8.4); §4 "Provenance envelope" → layered effective-vs-own (align §7.3).
• A-3: §10 policy surface — add the missing knobs (freshness/staleness mode, history squash-compaction, conflict-resolution preset, tenant-partition); keep §11's policy/ pointer accurate.
• A-4: §3 diagram + §11 header — "incremental-maintained derived tier (rebuild = fallback)" and "orthogonal-core capability profile," not "rebuildable cache / 15 spectra."

---

Journal & coordination-state model (single vs multi-writer)

id: SHARD-WP-0006-T2
status: done
priority: high
state_hub_task_id: "fd17f7b9-ca9e-4c86-95c0-9b51cb2df7b5"

Settle the keystone (review B-1 + B-3 together). Decide and document:

• Separate the content-history journal from the live coordination state. Proposed resolution: event-sourced coordination — an append-only decision log (overlays, bindings, aliases, merges as events) is the coordination-canonical tier and is git-addressable (preserves I-6); the queryable current coordination state (effective alias table, equivalence set) is a derived fold of the log (disposable, indexable, L4). This resolves B-3 (representation = event log; queries = derived index) and refines the §1 three-state framing (coordination-canonical = the decision log, not a mutable file).
• State the concurrency model (B-1). How multiple orchestrator instances append safely: serialized append per space (with the HA story made explicit) and/or conflict-free ordering of independent appends; what "read-your-writes" means across instances; where Git is authoritative vs a materialised export.
• Update §1 (refine coordination-canonical = decision log), §4 (Coordination journal / Overlay), §8.1/§8.2, §8.6 (consistency now grounded on the log + a stated concurrency model), §11 (a coordination/ event-log store + derived-fold index).

---

Adapter conformance suite (profiles must be verified, not asserted)

id: SHARD-WP-0006-T3
status: done
priority: high
state_hub_task_id: "900c8234-ca73-4225-b2c5-77d218ded28c"

Fix B-2. Make capability-as-data trustworthy: add to the adapter contract (§6) a conformance-suite requirement — a published battery that, given a binding, verifies its declared capability profile matches observed behaviour (each declared verb/position is exercised; mismatches fail registration). State that an adapter is only admissible if it passes; that the suite is versioned with the contract; and that profile claims are verified, never self-asserted (this is what makes I-3 / §6.5 sound). Update §6.4/§6.5 and add the conformance obligation to the acceptance posture.

---

Incremental-maintenance correctness & I-2 verification

id: SHARD-WP-0006-T4
status: done
priority: medium
state_hub_task_id: "adf4ed28-8338-49ed-a552-c9fbe11c43ee"

Fix B-4. In §8.7: correct the incremental equivalence algorithm — a changed page must re-verify the candidate pairs it leaves (bucket exits) and propagate to pages whose equivalence depended on it, not only its new candidates; the delta is not additive. Add an I-2 verification mechanism: a background consistency-checker comparing a digest of the derived tier against a sampled/periodic recompute, so derived = f(canonical) is verified, not merely asserted; on mismatch, recompute the affected partition. State that I-2 is an eventually-verified property with a named checker, and note the residual in §12.

---

Track second-tier items; close-out

id: SHARD-WP-0006-T5
status: done
priority: medium
state_hub_task_id: "18cb718a-e507-41d0-ae14-b144a56e3d57"

Add review §C as open problems in §12 (each with chosen direction + revisit trigger):

• O-8 preset bundles ("personal vault" / "team wiki" / "enterprise federation") over the §10 policy surface — direction: ship a small set of named personas; trigger: operators mis-configuring interacting knobs.
• O-9 shard sharing across roots vs tenant partition (I-13) — direction: shard exclusive to one root by default, explicit shared-read binding otherwise; trigger: a shard legitimately needed live in two tenants.
• O-10 span-level authz under transclusion (aggregation/inference leak) + ⊕ composition across transclusion boundaries — direction: a transcluded span inherits the stricter of source and host authz; provenance ⊕ composes source-page-envelope under the host; trigger: a cross-authz transclusion in practice.
• O-11 union-under-shard-unavailability — direction: partial union + per-shard "unavailable" provenance + last-known-projection where policy allows; trigger: SLA needs on partial reads.

Refresh §14 decisions and §16 traceability (link this review + SHARD-WP-0006); refresh invariants if any added. Final check_repo_consistency pass.

---

Acceptance criteria

• Every round-2 finding A-1…A-4, B-1…B-4 is resolved in the blueprint; C-1…C-4 are tracked as O-8…O-11 with a chosen direction (none silently dropped).
• The blueprint is self-consistent: overview (§1–§5, §10) agrees with body (§6–§9).
• The journal/coordination-state model answers single-vs-multi-writer and preserves I-6 (git-addressable coordination).
• The adapter conformance obligation makes capability-as-data (I-3) verified, not asserted.
• Each task committed; SCOPE/spec-README updated where status changes; state-hub synced.

Suggested task order

T1 (reconcile, fast) → T2 (keystone journal/coordination model) → T3 (conformance) → T4 (incremental correctness) → T5 (track §C + close-out).