coulomb/shard-wiki
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

spec(SHARD-WP-0013 T2): engine-facing capability structure layer over the UC catalog

Browse Source 
Adds 'Capability structure for the wiki engine (reuse-surface-aligned)' to
UseCaseCatalog.md (no UC renumbered): a small always-on engine core (EC-1..EC-5),
ten typed per-shard-activatable extensions (X-OVERLAY/AUTHZ/VIEW/STRUCT/ADDR/COMP/
PROV/COLLAB/FED/ATT) each mapped to a reuse-surface capability with activation
defaults, and a conflict-mediation map turning conflicting requirements into
mechanisms. Bridges demand -> the engine typed-extension model (T5). Marks T2 done.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-06-15 22:16:06 +02:00
parent ad4a2dbf5a
commit 46ec6f2a5f
2 changed files with 66 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
spec/UseCaseCatalog.md
View File

@@ -45,6 +45,71 @@ of the shard-spectrum work; E–G carry the c2/yawex authoring and reading patte
---
## Capability structure for the wiki engine (reuse-surface-aligned)
*Added by SHARD-WP-0013 T2 — a structural **layer over** the thematic catalog (UC IDs unchanged),
mapping the 84 UCs onto a small **engine core** plus **typed, per-shard-activatable extensions**.
This is the bridge from demand (UCs) to the engine's typed-extension model
(`WikiEngineCoreArchitecture.md`, T5) and is aligned with the shard-wiki capability entries on the
reuse surface (`capability.wiki.*`).*
**Reading rule:** the engine is a **small always-on core**; everything else is a **typed extension
a shard activates only if it needs it** (the activation mechanism itself reuses
`capability.feature-control.evaluate`). "Default" = on/off for a standalone single-shard wiki.
### Engine core (always on — the irreducible kernel)
| Core unit | What it is | UCs | reuse-surface |
|-----------|------------|-----|---------------|
| **EC-1 Page lifecycle & content** | author / read / edit a Markdown page; delete is a history event | UC-08, UC-09 | `capability.wiki.page-model` |
| **EC-2 Identity, naming & placement** | stable page identity ≠ placement; namespace/path | UC-22 (placement), page-model kernel | `capability.wiki.page-model` |
| **EC-3 History & recoverability** | every write recoverable; history is the floor | UC-24 | `capability.wiki.coordination-journal` |
| **EC-4 Links (wikilink + red-link)** | `[[Target]]` resolution; createable red-links | UC-23 | `capability.wiki.page-model` |
| **EC-5 Storage via the adapter contract** | the engine *is* a canonical-mode shard behind §A | — | `capability.wiki.adapter-contract` (minimal profile) |
EC-1…EC-5 are the Ward-Cunningham/c2 open-wiki minimum: write a page, link pages, never lose
an edit. A shard can run with **only** the core.
### Typed extensions (activate per shard)
| Ext | Cluster | UCs | reuse-surface capability | Activatable | Default (standalone) |
|-----|---------|-----|--------------------------|-------------|----------------------|
| **X-OVERLAY** | overlay / lightweight-patch write path | UC-04, 26, 29 | `capability.wiki.overlay` | yes | on (no-op without remote/limited targets) |
| **X-AUTHZ** | access-control ladder L0→L4 | UC-06 + the L-ladder | `capability.authorization.policy-evaluate` (reuse) | yes (tiered) | L0 (open) |
| **X-VIEW** | derived views (RecentChanges, BackLinks, AllPages, SiteMap, Search) | UC-17–UC-21, UC-63 | (planned `capability.wiki.derived-views` — gap, T3) | yes | BackLinks/RecentChanges on; Search off |
| **X-STRUCT** | structured / typed / computed page data + typed-graph | UC-34, 39, 58, 67, 73 | `capability.wiki.page-model` (typed) | yes | off |
| **X-ADDR** | span addressing, transclusion, dimensional / query navigation | UC-32, 44–49, 51, 52, 74 | `capability.wiki.page-model` + query | yes (transclusion is core-lite) | transclusion on; dimensional/query off |
| **X-COMP** | computational / executable content (literate, notebook, program-as-page, live) | UC-54, 55, 83, 84 | `capability.wiki.engine-typed-extensions` (computational) | yes (gated, trust/sandbox) | off |
| **X-PROV** | rich provenance & page metadata | UC-25, 75 | `capability.wiki.page-model` (provenance) | yes (base provenance is core) | base on; rich off |
| **X-COLLAB** | c2 collaboration / social patterns | UC-10–UC-16 | (UI/convention; partial gap, T3) | yes | varies (mostly UI-layer) |
| **X-FED** | federation & union across shards | UC-01–07, 27, 28, 30–33, 56, 71, 72, 79 | `capability.wiki.shard-orchestration` + `…federation-models` | yes | off (single-shard engine) |
| **X-ATT** | attach *foreign* backends as shards | UC-35–43, 50, 53, 57, 60–62, 64–66, 68–70, 76–82 | `capability.wiki.adapter-contract` | yes | off (orchestrator role, not the engine's own shard) |
Note: X-FED and X-ATT are the **orchestrator** capabilities — for a *standalone* engine they are
off; when shard-wiki orchestrates, the engine is simply one attached (canonical) shard among many.
That is the engine↔orchestrator boundary made concrete (engine = a canonical-mode shard).
### Conflict-mediation map (how the framework reconciles tensions into one whole)
The collected UCs embed genuinely conflicting requirements. The framework mediates each with a
**mechanism**, never a hard-coded policy — so one consistent featureset serves all:
| Tension (conflicting UCs) | Mediation mechanism |
|---------------------------|---------------------|
| **Open vs governed** (UC-01 open edit ↔ UC-06 enterprise ACL) | the **L0→L4 authz ladder** (X-AUTHZ, additive); **history is the floor** at L0 — recoverability, not gatekeeping |
| **Lossless vs lossy content** (UC-42 ↔ UC-59) | **translation spectrum + fidelity report** (TSD §A.6); native form stays canonical, loss is shown not hidden |
| **Live vs snapshot** (UC-32 live transclusion ↔ UC-84/UC-3 cached) | the **live↔snapshot axis** + projection kind; degrade to a **marked** snapshot, never imply live |
| **Canonical vs chorus** (UC-07 reconcile ↔ UC-27 coexist) | **conflict detection is core, resolution is a policy preset** (chorus / designated-canonical / …) |
| **Eager vs lazy** (UC-03 projection ↔ UC-05 union) | **projection materialization** policy (lazy default; eager opt-in) |
| **Single vs multi-writer** (concurrent edits) | **per-space append authority** on the coordination journal (total order, read-your-writes) |
| **Integrated whole vs only-what-you-need** | the **typed-extension framework** + **per-shard activation** (reuse `feature-control`) — *the headline mediation*; extensions compose against typed contracts, so the featureset is one integrated whole yet selectively enabled |
| **Minimal core vs feature-rich** | **small core (EC-1…EC-5)** + extensions; nothing beyond the c2 minimum is mandatory |
This table is the seed of the engine's design rationale (T5): every conflict has a *mechanism*
that lets a shard sit anywhere on the spectrum without forking the framework.
---
## A. Information space, federation & coordination
*Federation, union, overlay, projection, and the Git-backed coordination layer (INTENT + yawex/federation seeds).*