From 46ec6f2a5f78c18f5b98dd2556dc619d578e0d56 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 15 Jun 2026 22:16:06 +0200 Subject: [PATCH] spec(SHARD-WP-0013 T2): engine-facing capability structure layer over the UC catalog 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 --- spec/UseCaseCatalog.md | 65 +++++++++++++++++++++ workplans/SHARD-WP-0013-wiki-engine-prep.md | 2 +- 2 files changed, 66 insertions(+), 1 deletion(-) diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md index e40d284..0fd265f 100644 --- a/spec/UseCaseCatalog.md +++ b/spec/UseCaseCatalog.md @@ -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).* diff --git a/workplans/SHARD-WP-0013-wiki-engine-prep.md b/workplans/SHARD-WP-0013-wiki-engine-prep.md index 26b7ac7..fdc9148 100644 --- a/workplans/SHARD-WP-0013-wiki-engine-prep.md +++ b/workplans/SHARD-WP-0013-wiki-engine-prep.md @@ -88,7 +88,7 @@ capabilities visible + assessable on the reuse surface. ```task id: SHARD-WP-0013-T2 -status: todo +status: done priority: high state_hub_task_id: "d83d0f96-7d95-405e-93cf-03314ab34636" ```