generated from coulomb/repo-seed
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:
@@ -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/
|
||||
|
||||
Reference in New Issue
Block a user