spec(SHARD-WP-0006 T1): overview-reconciliation pass (§A)

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 <noreply@anthropic.com>
This commit is contained in:
2026-06-15 01:58:48 +02:00
parent 079652b61f
commit cbd29e0a32
2 changed files with 33 additions and 11 deletions

View File

@@ -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 (L0L4 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 L0L4 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/