From cbd29e0a322cb42a9e3a214eebf061dc4bf463e3 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 15 Jun 2026 01:58:48 +0200 Subject: [PATCH] =?UTF-8?q?spec(SHARD-WP-0006=20T1):=20overview-reconcilia?= =?UTF-8?q?tion=20pass=20(=C2=A7A)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes A-1..A-4: §4 identity/placement/equivalence (removes the equivalence- keys-on-identity contradiction), §4 projection (trivial default + extension point) and provenance (layered), §10 policy surface (adds freshness, conflict-resolution, compaction, tenant-partition knobs + preset-bundle note), §3 diagram + §11 header (incremental-first, orthogonal-core). Overview now matches the hardened body. Co-Authored-By: Claude Opus 4.8 --- spec/CoreArchitectureBlueprint.md | 38 +++++++++++++------ .../SHARD-WP-0006-architecture-hardening-2.md | 6 +++ 2 files changed, 33 insertions(+), 11 deletions(-) diff --git a/spec/CoreArchitectureBlueprint.md b/spec/CoreArchitectureBlueprint.md index 567c184..12ced51 100644 --- a/spec/CoreArchitectureBlueprint.md +++ b/spec/CoreArchitectureBlueprint.md @@ -114,7 +114,7 @@ principles fused with the research through-lines. X-cut │ L5 Authorization (PEP/PDP, identity-provider iface) → │ X-cut Prove- │ see ArchitectureBlueprint.md (L0–L4 ladder) │ Capa- nance ├───────────────────────────────────────────────────────────────┤ bility - ▲ │ L4 Union & Projection (DERIVED, rebuildable cache) │ ▲ + ▲ │ L4 Union & Projection (DERIVED · rebuild=fallback) │ ▲ │ │ identity resolution · equivalence/chorus · union graph · │ │ │ │ replication+derivation projections · moldable view registry│ │ │ │ · derived query index │ │ @@ -127,7 +127,7 @@ principles fused with the research through-lines. │ │ provenance envelope · the page shapes │ │ │ ├───────────────────────────────────────────────────────────────┤ │ │ │ L1 Shard Adapter Contract ── BOTTOM WAIST ── │ │ - │ │ versioned iface · capability profile (15 spectra) · │ │ + │ │ versioned iface · capability profile (orthogonal) · │ │ │ │ attachment-mode binding · operation verbs │ │ └──── ├───────────────────────────────────────────────────────────────┤ ──┘ │ L0 Backends (not ours): git repos, wiki/ subdirs, Gitea/ │ @@ -163,10 +163,13 @@ parallel terms. - **Capability profile** — a shard binding's position on each of the 15 spectra (§6) plus its supported verbs. *The* data structure that drives degradation. - **Wiki page model** — the L2 backend-neutral page; the top waist. -- **Page identity vs placement** — a page is an entity (identity); it may have N placements - (paths/shards). Addressing, equivalence, and transclusion key on identity (I-9). -- **Provenance envelope** — the metadata wrapper every artifact carries: source shard, - freshness, liveness, authorization context, overlay status, divergence, derivation lineage. +- **Page identity vs placement vs equivalence** — a page is an entity with a *stable handle* + (identity); it may have N placements (paths/shards); **addressing and transclusion key on + identity, but equivalence keys on content fingerprint *across* identities** (§7.2, I-9). The + three are distinct mechanisms — never conflate identity with a fingerprint. +- **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, @@ -174,8 +177,10 @@ parallel terms. - **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. -- **Projection** — a derived view of shard content, typed on two axes (§8): *kind* - (replication | derivation) × *liveness* (static … irreducibly-live). +- **Projection** — a derived view of shard content. The default is a **plain lazy + replication-projection** (a freshness-stamped cache); only *source* content needing + transform/evaluate uses the **derivation-projection** extension point with its two-axis + typing (kind × liveness) and the moldable view registry (§8.4–§8.5). - **Federation model** — the selected coordination strategy for a space (§ taxonomy, T17). - **Shard mode** — read-only · write-through · mirrored · projected · cached · canonical (a *policy* selection constrained by the capability profile). @@ -668,19 +673,30 @@ The configurable presets are: (constrained by the capability profile). - **Reconciliation cadence & conflict exposure** — push/poll/manual; show-conflicts vs auto-merge-when-supported. +- **Conflict-resolution preset** — chorus / designated-canonical / git-merge / vote-to-merge / + overlay-only (the *resolution* policy over §8.6's core detection; per space or equivalence set). +- **Freshness / invalidation mode** — event-driven / validator-poll / TTL / hybrid, and + stale-but-fast vs block-for-fresh on read (§8.8; constrained by the operational envelope). +- **History compaction** — squash policy for low-value churn, gc/repack cadence, per-shard + offload (§8.1), always preserving recoverable endpoints. +- **Tenant partition mapping** — tenant ↔ root-entity, and any explicit cross-root federation + (§9.1, I-13). - **Execution policy** — derive/execute off (default) / sandboxed / per-shard-allowed. - **Authorization mode** — the L0–L4 ladder. - **Projection materialization** — lazy/eager; snapshot vs view-time; recording retention. -Core ships sane defaults (L0 open; fork+journal; lazy replication-projection; overlay-before- -mutation; execution off) and never hard-codes any of the above. +Core ships sane defaults (L0 open; fork+journal; lazy replication-projection; event-driven+TTL +freshness; overlay-before-mutation; execution off; one tenant = one root) and never hard-codes +any of the above. (**Preset bundles** that package coherent knob-sets per persona are tracked +as O-8, §12 — flexibility without bundles is operator burden.) --- ## 11. Concrete module structure (bridge to implementation) A proposed package layout for `src/shard_wiki/`, mapping 1:1 to the layers so the dependency -rule (downward only; L4 rebuildable) is enforceable by import lint: +rule (downward only; the derived tier is incrementally maintained, rebuild = fallback) is +enforceable by import lint: ``` src/shard_wiki/ diff --git a/workplans/SHARD-WP-0006-architecture-hardening-2.md b/workplans/SHARD-WP-0006-architecture-hardening-2.md index 4b7123e..60e87d5 100644 --- a/workplans/SHARD-WP-0006-architecture-hardening-2.md +++ b/workplans/SHARD-WP-0006-architecture-hardening-2.md @@ -11,6 +11,7 @@ created: "2026-06-15" updated: "2026-06-15" depends_on: - SHARD-WP-0005 +state_hub_workstream_id: "badb83f8-2806-4018-9d7f-d4666d3510ba" --- # SHARD-WP-0006 — Core architecture hardening II @@ -44,6 +45,7 @@ where mutable coordination state actually lives*. id: SHARD-WP-0006-T1 status: todo priority: high +state_hub_task_id: "b0b4087b-ec19-4ae7-94b1-9a813a6133b9" ``` Make the overview match the hardened body (review A-1…A-4): @@ -66,6 +68,7 @@ Make the overview match the hardened body (review A-1…A-4): id: SHARD-WP-0006-T2 status: todo priority: high +state_hub_task_id: "fd17f7b9-ca9e-4c86-95c0-9b51cb2df7b5" ``` Settle the keystone (review B-1 + B-3 together). Decide and document: @@ -93,6 +96,7 @@ Settle the keystone (review B-1 + B-3 together). Decide and document: id: SHARD-WP-0006-T3 status: todo 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 @@ -111,6 +115,7 @@ add the conformance obligation to the acceptance posture. id: SHARD-WP-0006-T4 status: todo 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 @@ -129,6 +134,7 @@ not merely asserted; on mismatch, recompute the affected partition. State that I id: SHARD-WP-0006-T5 status: todo 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):