spec(SHARD-WP-0002): fold adapter-contract constraints into T11-T15

Distill the cross-cutting adapter-contract constraints from the four engine deep dives (wiki-engines landscape, XWiki, TWiki, Foswiki) into five concrete design tasks, complementing the federation tasks (T1-T10): - T11 adapter contract: capability model & versioned interface (Foswiki::Store prior art; write-granularity as a capability dimension) - T12 page model: structured/typed payload representation (XObjects, %META%, multi-record, bodiless pages) - T13 history portability: supplement (DB-internal) vs import (open file history) - T14 adapter binding: attach path, engine-hosted vs external, backend-swap - T15 syntax translation & content fidelity (non-Markdown round-trip) Adds an adapter-contract decision-topics table, cross-links T10<->T11 on the shared capability vocabulary, and updates context/acceptance/task-order. Tasks registered in the state hub (workstream 2af4c46d). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
research: Foswiki deep dive (store abstraction, ext API); UC-42/43
2026-06-13 23:35:09 +02:00 · 2026-06-13 23:27:24 +02:00 · 2026-06-13 23:20:11 +02:00 · 2026-06-13 19:20:42 +02:00 · 2026-06-13 18:39:30 +02:00
8 changed files with 1147 additions and 33 deletions
--- a/research/260613-foswiki-deep-dive/README.md
+++ b/research/260613-foswiki-deep-dive/README.md
@@ -0,0 +1,36 @@
+# 260613 — Foswiki deep dive (store abstraction, extension API, ecosystem)
+
+Date: 2026-06-13
+
+## What this is
+
+A focused study of **Foswiki** — the community fork of TWiki (2008, from TWiki
+4.2.x) — concentrating on **what Foswiki changed**, not the lineage it shares with
+TWiki. The distinctive material: a **pluggable `Foswiki::Store` backend**
+(RcsWrap / RcsLite / **PlainFileStoreContrib**) behind a versioned interface, the
+`Foswiki::Meta` topic-object indirection, the OO/MVC core rewrite, the cleaner
+`Foswiki::Func` + `registerTagHandler` extension API, **DataForms** (+ MetaDataPlugin,
+FlexFormPlugin), and the **WysiwygPlugin** TML↔HTML round-trip.
+
+Read through shard-wiki's lens: Foswiki is the engine that **already separates its
+store backend from its core via a versioned interface** — i.e. it is concrete prior
+art for shard-wiki's own *shard adapter contract* and *capability-aware adapters*.
+
+Pairs with — and deliberately does not repeat — the shared TWiki material:
+- `research/260613-twiki-deep-dive/` — flat-file/RCS store, Webs/Topics, plugin
+  handler callbacks, per-topic ACL (all inherited; read there for the shared parts)
+- `research/260613-xwiki-deep-dive/` — the Java/DB app-platform sibling
+- `research/260608-wikiengines-overview/` — landscape scan
+
+## Contents
+
+| Path | Role |
+|------|------|
+| `findings.md` | Distinctives vs TWiki, store abstraction, extension API, DataForms, capability profile, INTENT mapping, UC seeds, sources |
+
+## Status
+
+Initial deep dive complete. Two new use cases promoted to
+`spec/UseCaseCatalog.md` (UC-42, UC-43); UC-34/39/40 enriched. The
+`Foswiki::Store`/`Foswiki::Meta` abstraction is logged as adapter-contract prior art
+for `workplans/SHARD-WP-0002-federation-architecture.md`.
--- a/research/260613-foswiki-deep-dive/findings.md
+++ b/research/260613-foswiki-deep-dive/findings.md
@@ -0,0 +1,188 @@
+# Findings — Foswiki: store abstraction, extension API, ecosystem
+
+Date: 2026-06-13 · Status: research draft
+
+Scope: **Foswiki as distinct from TWiki** — only the deltas, since the two share a
+data model, markup, plugin-handler API, and per-topic ACL. The deltas that matter to
+shard-wiki: a **pluggable store backend behind a versioned interface**
+(`Foswiki::Store` + `Foswiki::Meta`), an OO/MVC core rewrite, a cleaner extension
+API (`Foswiki::Func::registerTagHandler`), enhanced DataForms, and a TML↔HTML
+round-trip editor framework. Sources: foswiki.org Development + System docs,
+`foswiki/distro` on GitHub.
+
+**Read first for shared lineage:** `research/260613-twiki-deep-dive/` (flat-file +
+RCS store, Webs/Topics, handler callbacks, per-topic `ALLOW/DENY` ACL). This file
+does **not** repeat those.
+
+---
+
+## 1. Origin and compatibility
+
+Forked from **TWiki 4.2.x** in October 2008 by most of the TWiki community (sources
+cite 4.2.3–4.2.4; the TWiki dive recorded 4.2.4). Design goal: ~100% content
+compatibility — same TML markup, same plugin API — via a **`TWikiCompatibilityPlugin`**
+that maps the `TWiki::` namespace and legacy variables. So everything in the TWiki
+dive still applies; Foswiki then grew the features below.
+
+## 2. The headline delta — a pluggable store behind a versioned interface
+
+This is the reason Foswiki earns its own dive.
+
+### 2.1 `Foswiki::Meta` indirection
+After Foswiki 1.0.4 the core was changed to **delegate almost all store operations
+to a topic object, `Foswiki::Meta`**. Callers manipulate a `Foswiki::Meta` object
+representing the item they're changing and **never touch the store implementation
+directly**; `Foswiki::Meta` talks to the real store through the well-defined
+**`Foswiki::Store`** interface. This is a clean MVC/repository separation.
+
+### 2.2 Swappable backends
+`Foswiki::Store::` ships multiple low-level back-ends behind that one interface:
+- **`RcsWrap`** — RCS via the external `rcs` binaries (classic TWiki behavior)
+- **`RcsLite`** — a pure-Perl RCS implementation
+- **`PlainFileStoreContrib`** — a newer store that saves topics/attachments as
+  **timestamped copies** instead of RCS diffs: more disk, but **no RCS dependency**
+  and much higher performance.
+
+So in Foswiki the **storage format is a configuration choice**, not a fixed property
+of the engine — the same wiki can run on RCS or PlainFile behind an unchanged core.
+
+### 2.3 OO/MVC core rewrite
+Foswiki has steadily rearchitected from "disconnected Perl CGI scripts" toward
+object-oriented, unit-tested, MVC Perl ("solidify the sand piles"), preserving
+backward compatibility through tests. The store abstraction above is the most
+load-bearing result.
+
+## 3. Extension API deltas
+
+Shared with TWiki: handler callbacks (`initPlugin`, `commonTagsHandler`,
+`before/afterSaveHandler`, `afterRenameHandler`, attachment handlers), REST handlers,
+`Config.spec`, package types (Plugin / Skin / AddOn / Contrib). Foswiki refinements:
+
+- **`Foswiki::Func` is the blessed API** — "if there's a `Foswiki::Func` way and
+  another way, the `Foswiki::Func` way is almost always right." Direct use of
+  internal packages is discouraged and governed by **`PluginsApiPolicies`**.
+- **`Foswiki::Func::registerTagHandler($tag, \&sub)`** — register a custom
+  macro/variable **programmatically** (cleaner than TWiki's `commonTagsHandler`
+  string-matching convention).
+- **Contrib-defined APIs** carry an explicit "use at your own risk / awaiting merge"
+  policy — a maturity signal on extension interfaces.
+- `EmptyPlugin` (`lib/Foswiki/Plugins/EmptyPlugin.pm`) is the canonical handler
+  reference/skeleton.
+
+## 4. DataForms and structured data (delta)
+
+DataForms = Foswiki's name for TWiki Forms: typed fields (text, date, single/multi
+value, label) stored as `%META:FIELD%` in the topic text. Foswiki extends the model
+via popular extensions:
+- **MoreFormfieldsPlugin** — additional special-purpose field types.
+- **FlexFormPlugin** — render DataForm interfaces from custom templates
+  (`Foswiki::Form` classes).
+- **MetaDataPlugin** — **multiple structured data records per topic** (beyond the
+  classic one-form-per-topic), closing the gap toward XWiki's multi-XObject model
+  while keeping data in the text file.
+
+## 5. Editing / syntax (delta relevant to "Markdown-first")
+
+- **WysiwygPlugin** — a generic framework that transforms **TML → HTML** for a
+  browser editor and **HTML → TML on save** (lossless round-trip).
+- **TinyMCEPlugin** — pre-installed WYSIWYG editor built on WysiwygPlugin.
+
+This proves **bidirectional, lossless translation between an engine's native markup
+and another representation is feasible** — directly relevant to shard-wiki reading a
+non-Markdown shard and writing Markdown overlays back (UC-42).
+
+## 6. Foswiki as a shard — capability profile (delta from TWiki)
+
+| Capability | Foswiki | Note vs TWiki |
+|------------|---------|---------------|
+| Store backend | **pluggable** | RCS *or* PlainFile behind `Foswiki::Store` — direct-attach target is cleaner on PlainFile (UC-40) |
+| History | RCS *or* timestamped copies | PlainFile = whole-version snapshots, not diffs; both file-format, git-importable (UC-41) |
+| Structured payload | DataForms `%META%`, **multi-record** via MetaDataPlugin | richer than classic TWiki Forms (UC-34/39) |
+| Syntax translation | **WysiwygPlugin TML↔HTML** | bidirectional round-trip exists (UC-42) |
+| Extension host | `Foswiki::Func` + `registerTagHandler` + REST | cleaner adapter-host surface (UC-38) |
+| Store as contract | **`Foswiki::Store` versioned interface** | architectural prior art for shard-wiki's adapter contract |
+
+## 7. Mapping to shard-wiki INTENT (compare, do not equate)
+
+### 7.1 Reinforcements
+| Observation | INTENT principle |
+|-------------|------------------|
+| `Foswiki::Store` versioned interface + swappable backends | **capability-aware adapters** / **shard adapter contract** — an engine that already did exactly this separation |
+| `Foswiki::Meta` mediates all store access | clean **mechanism over policy** boundary worth mirroring in the adapter contract |
+| PlainFile store = timestamped text copies | **git-addressable coordination** / direct-attach (UC-40), history import (UC-41) |
+| WysiwygPlugin TML↔HTML round-trip | **Markdown-first, backend-neutral** is achievable for prose via translation (UC-42) |
+| MetaDataPlugin multi-record topics | structured pages beyond one form (UC-34/39) |
+
+### 7.2 Deliberate divergences (design bugs if conflated)
+| Foswiki assumption | shard-wiki correction |
+|--------------------|----------------------|
+| One pluggable store per wiki, chosen at config | shard-wiki federates **many** heterogeneous stores at once |
+| TML is the canonical syntax; HTML is a render target | shard-wiki is **Markdown-first**; TML↔Markdown is an adapter translation, not core |
+| Store interface is Foswiki-internal Perl | shard-wiki's adapter contract is **cross-language, cross-backend, versioned** |
+| ACL in topic preferences | **authorize in core**; engine ACL is advisory provenance |
+
+### 7.3 What Foswiki teaches that shard-wiki should not lose
+1. **The store-abstraction pattern works in practice** — `Foswiki::Store` is a
+   real-world proof that a stable interface + swappable backends is viable; the shard
+   adapter contract is the same idea generalized across engines.
+2. **Backend format should be swappable under a stable identity** — Foswiki migrates
+   RCS↔PlainFile without changing the wiki; shard-wiki should tolerate a shard's
+   backend changing under it (UC-43).
+3. **Lossless syntax round-trip is a solved problem** — don't treat non-Markdown
+   prose as read-only; translate it (UC-42).
+
+## 8. Use-case seeds → catalog (promoted 2026-06-13)
+
+| Seed | Catalog UC | Disposition |
+|------|------------|-------------|
+| Read/write a non-Markdown shard via lossless syntax translation (TML↔Markdown) | **UC-42** (new) | realizes Markdown-first for prose; WysiwygPlugin is proof |
+| Tolerate a shard's storage-backend swap without losing identity/provenance | **UC-43** (new) | Foswiki RCS↔PlainFile; orchestration robustness |
+| Structured / multi-record pages | UC-34 / UC-39 | enriched: DataForms + MetaDataPlugin multi-record |
+| Attach a file-backed engine's on-disk store directly | UC-40 | enriched: PlainFile store is a cleaner direct-attach target than RCS |
+| `Foswiki::Store` versioned interface | (no UC) | architecture prior art → `SHARD-WP-0002` adapter contract |
+
+## 9. Open questions (for spec / workplans)
+
+1. **Adapter-contract shape** — how much of `Foswiki::Store`'s method set
+   (read/save/move/getRevisionInfo/getRevisionHistory/lock) maps onto shard-wiki's
+   capability-aware adapter contract? (architecture, `SHARD-WP-0002`)
+2. **Syntax-translation fidelity** — is TML↔Markdown lossless enough for overlay
+   round-trips, or must overlays be stored in TML to be safe (UC-42)?
+3. **Backend-swap detection** — how does shard-wiki notice and tolerate a shard
+   changing store format underneath (RCS→PlainFile), and does provenance/history
+   survive it (UC-43)?
+4. **Multi-record metadata** — represent MetaDataPlugin multi-record topics and XWiki
+   multi-XObject pages in one structured-metadata page model (shared open question).
+
+## 10. Sources
+
+| Source | URL |
+|--------|-----|
+| Foswiki — Technical Overview | https://foswiki.org/Development/TechnicalOverview |
+| Foswiki — Core Internals | https://foswiki.org/Development/CoreInternals |
+| Foswiki — PlainFileStoreContrib | https://foswiki.org/Extensions/PlainFileStoreContrib |
+| Foswiki — RCSStoreContrib | https://foswiki.org/Extensions/RCSStoreContrib |
+| Foswiki::Store::PlainFile (source) | https://github.com/foswiki/distro/blob/master/PlainFileStoreContrib/lib/Foswiki/Store/PlainFile.pm |
+| Foswiki — Developing Plugins | https://foswiki.org/System/DevelopingPlugins |
+| Foswiki — Plugins API Policies | https://foswiki.org/Development/PluginsApiPolicies |
+| Foswiki — DataForms | https://foswiki.org/System/DataForms |
+| Foswiki — MetaDataPlugin | https://foswiki.org/Extensions/MetaDataPlugin |
+| Foswiki — WysiwygPlugin | https://foswiki.org/System/WysiwygPlugin |
+| Foswiki — Why this fork | https://foswiki.org/Home/WhyThisFork |
+| Wikipedia — Foswiki | https://en.wikipedia.org/wiki/Foswiki |
+| shard-wiki — TWiki deep dive | `research/260613-twiki-deep-dive/findings.md` |
+| shard-wiki — XWiki deep dive | `research/260613-xwiki-deep-dive/findings.md` |
+
+---
+
+## 11. Traceability
+
+| This document section | Informs (future) |
+|-----------------------|------------------|
+| §2 store abstraction | **adapter contract** design (`SHARD-WP-0002`) — Foswiki::Store as prior art |
+| §3 extension API | UC-38 engine-side adapter host |
+| §4 DataForms | structured-metadata page model (UC-34/39) |
+| §5 WysiwygPlugin | UC-42 syntax-translation adapter |
+| §6 capability profile | adapter capability-profile vocabulary |
+| §7 INTENT mapping | architecture-blueprint guardrails |
+| §8 UC seeds | `spec/UseCaseCatalog.md` (UC-42, UC-43; UC-34/39/40 enrichment) |
--- a/research/260613-twiki-deep-dive/README.md
+++ b/research/260613-twiki-deep-dive/README.md
@@ -0,0 +1,39 @@
+# 260613 — TWiki deep dive (implementation, plugin API, ecosystem)
+
+Date: 2026-06-13
+
+## What this is
+
+A focused study of **TWiki** — the original "structured enterprise wiki / wiki
+application platform" (Peter Thoeny, ~1998), and the **file-based Perl counterpoint**
+to XWiki's Java/DB platform. Covers TWiki's **implementation** (Perl + flat-file +
+RCS store, Webs/Topics, TWiki Forms, TWikiML/variables), the **plugin API and
+handler callbacks** that extend the core, the **extension package types** (Plugin /
+Skin / AddOn / Contrib) and repository, and TWiki's **per-topic access control**
+(the prior art behind yawex's `AccessControl`).
+
+Read through shard-wiki's lens, paired with the XWiki dive: TWiki shows the same
+"wiki-as-application-platform" goal reached with **text files + RCS** instead of a
+database — which changes the adapter story (direct on-disk attach, git-convertible
+history).
+
+Complements:
+- `research/260613-xwiki-deep-dive/` — the DB/Java app-platform sibling
+- `research/260608-wikiengines-overview/` — the landscape scan
+- `research/260608-yawex-prior-art/` — yawex borrowed TWiki's per-topic AccessControl
+
+Note: most of TWiki's community forked to **Foswiki** in Oct 2008 (from TWiki
+4.2.4); findings flag where TWiki/Foswiki differ.
+
+## Contents
+
+| Path | Role |
+|------|------|
+| `findings.md` | Architecture, plugin-handler API, ecosystem, capability profile, INTENT mapping, UC seeds, sources |
+
+## Status
+
+Initial deep dive complete. Two new use cases promoted to
+`spec/UseCaseCatalog.md` (UC-40, UC-41); UC-06/34/36/38/39 enriched with TWiki
+specifics. Adapter-contract implications feed
+`workplans/SHARD-WP-0002-federation-architecture.md`.
--- a/research/260613-twiki-deep-dive/findings.md
+++ b/research/260613-twiki-deep-dive/findings.md
@@ -0,0 +1,210 @@
+# Findings — TWiki: implementation, plugin API, ecosystem
+
+Date: 2026-06-13 · Status: research draft
+
+Scope: TWiki as prior art for the **file-based** wiki-application-platform — the
+counterpoint to XWiki's database/component platform. Two shard-wiki concerns:
+(1) attaching a structured, file-backed engine as a shard (including attaching its
+**on-disk store directly** vs through its runtime), and (2) how TWiki's plugin
+handler API exposes hooks rich enough to host a federation adapter
+(INTENT *composable integration*). Sources: twiki.org dev docs (TWikiPlugins,
+TWikiForms, TWiki::Func, TWikiAccessControl), Foswiki docs, Wikipedia.
+
+**Complements:** `research/260613-xwiki-deep-dive/` (DB/Java sibling),
+`research/260608-wikiengines-overview/` (landscape), and
+`research/260608-yawex-prior-art/` (yawex borrowed TWiki's per-topic AccessControl).
+
+---
+
+## 1. What TWiki is
+
+A **structured enterprise wiki** and **wiki application platform** (Peter Thoeny,
+~1998), written in **Perl 5** (5.10.1+), classically run as CGI. Like XWiki it lets
+pages become forms/records/apps — but it reaches that with **flat text files +
+RCS**, no database. Most of the community forked to **Foswiki** in October 2008
+(from TWiki 4.2.4; Foswiki 1.0 in January 2009); the plugin API and data model below
+are shared lineage, with minor divergences noted.
+
+## 2. Implementation architecture
+
+### 2.1 Storage — flat files + RCS (no DB)
+- Content lives on disk as `data/<Web>/<Topic>.txt`; the directory tree **mirrors
+  the logical Web/Topic hierarchy**. Attachments live under `pub/<Web>/<Topic>/`.
+- **History is RCS** (`<Topic>.txt,v` companion files) — the same GNU RCS yawex used.
+  History is real, per-file, and in an **open, git-convertible format** (unlike
+  XWiki's DB-internal `xwikircs`).
+- Scales to 300k+ topics on a single server (Yahoo) — file store is not a toy.
+
+### 2.2 Webs and Topics
+- **Topic** = page (the unit of content). **Web** = namespace / collection of topics
+  (can be nested). Webs are the natural shard / root-entity boundary.
+
+### 2.3 TWiki Forms — structured data, embedded in text
+- A **form template** is a topic defining fields as a table (one row per field:
+  name, type, size, values). A topic can *attach* a form; the field values are
+  stored as **TWikiMetaData inside the topic `.txt`** (`%META:FIELD{...}%`), shown as
+  a table on view and edited via fields/radios/checkboxes/lists.
+- **Forms + formatted `%SEARCH%`** = TWiki's "database applications" — structured
+  records queried by the SEARCH variable. This is the XWiki XObject/XClass idea, but
+  **file-embedded and git-diffable** rather than rows in a DB.
+
+### 2.4 TWikiML / variables (macros)
+- Markup is **TWikiML** (not Markdown). Dynamic behavior comes from **variables**
+  `%VAR%` / `%VAR{...}%` expanded at render time; `%SEARCH%` is the query engine.
+- Custom variables are provided by plugins (see §3).
+
+### 2.5 TWiki::Func — the official API boundary
+- `lib/TWiki/Func.pm` ("TWikiFuncDotPm") documents **all** interfaces available to
+  plugins, deliberately abstracting the flat-file assumption: `readTopic`,
+  `saveTopic`, `getTopicList`, `getListOfWebs`, `getWorkArea`, `saveAttachment`, …
+  Plugins are told *not* to assume flat files and to go through Func.
+
+## 3. Plugin API — interfaces to extend the core
+
+TWiki extends "without altering core code" by **registering Perl handlers that the
+core calls at defined points** in the request/render/save pipeline. A plugin is
+`lib/TWiki/Plugins/<Name>.pm` + a documentation topic + an optional `Config.spec`.
+
+### 3.1 Handler callbacks (the hook surface)
+| Phase | Handlers |
+|-------|----------|
+| Init / users | `initPlugin` (must return 1), `registrationHandler` |
+| Tag/variable expansion | `commonTagsHandler`, `beforeCommonTagsHandler`, `afterCommonTagsHandler` |
+| Rendering | `preRenderingHandler`, `postRenderingHandler` (`start/endRenderingHandler` deprecated) |
+| Edit lifecycle | `beforeEditHandler`, `afterEditHandler` |
+| Save lifecycle | `beforeSaveHandler`, `afterSaveHandler`, `beforeMergeHandler` |
+| Attachments | `beforeAttachmentSaveHandler`, `afterAttachmentSaveHandler` |
+| Topic mgmt | `afterRenameHandler`, `completePageHandler` |
+
+These are the TWiki analogue of XWiki's `ObservationManager` events — but
+**synchronous pipeline hooks** rather than an async event bus. The save/rename/
+attachment handlers are exactly the interception points a federation adapter needs.
+
+### 3.2 Other extension mechanisms
+- **Custom variables/macros** — registered via `commonTagsHandler` (Foswiki adds
+  `registerTagHandler`); convention `%PLUGINNAME_SETTING%`.
+- **REST handlers** — a plugin registers REST handlers invoked via the `rest`
+  script, for transactions outside the standard `view/edit/save` scripts. This is the
+  natural remote adapter transport.
+- **`Config.spec`** — declares configuration items (BOOLEAN, STRING, SELECT, PATH,
+  PERL) surfaced in the `configure` web UI.
+- **Work area** — `getWorkArea()` gives a plugin a persistent, non-web-accessible
+  data directory.
+
+### 3.3 Extension package types
+| Type | Role |
+|------|------|
+| **Plugin** | handler-based behavior, no core change (`lib/TWiki/Plugins/<Name>.pm`) |
+| **Skin** | visual appearance only; topic content unchanged (e.g. PrintSkin) |
+| **AddOn** | a script in `bin/` callable from a topic |
+| **Contrib** | shared library code, or **alternative implementations of core sections** (e.g. user management) when something "can't be a plugin because it needs close core access" |
+
+## 4. Access control (origin of yawex's model)
+
+TWiki authorizes via **preference settings in topics**: `ALLOWWEBVIEW` /
+`ALLOWWEBCHANGE` at web level and `ALLOWTOPICVIEW` / `ALLOWTOPICCHANGE` /
+`ALLOWTOPICRENAME` (and `DENY*`) at topic level, with **VIEW / CHANGE / RENAME
+grantable separately**. Topic-level settings apply only to that topic. This
+per-topic ACL is the **direct prior art** behind yawex's `AccessControl`
+(denied/view/form/edit/admin) and a concrete reference for shard-wiki's optional
+**per-page ACL at L4** (`spec/ArchitectureBlueprint.md` §5).
+
+## 5. TWiki as a shard — capability profile
+
+| Capability | TWiki | Note |
+|------------|-------|------|
+| Read | ✓ | TWiki::Func / `view` script / `rest`; or read `data/*.txt` directly |
+| Write | ✓ | saveTopic / `save` / `rest`; **per-topic** granularity |
+| Structured payload | ✓ | TWiki Forms → `%META:FIELD%` **in the text file** (git-diffable) |
+| Version/diff | ✓ | RCS `.txt,v` — **open format, git-convertible** (cf. XWiki DB) |
+| Merge | partial | `beforeMergeHandler`; no git 3-way |
+| Change hooks | ✓ | synchronous save/rename/attachment handlers |
+| Auth model | per-web/topic ACL | authorize through shard-wiki core; engine ACL is advisory |
+| Direct-store attach | ✓✓ | `data/<Web>/<Topic>.txt` + RCS is a folder shard on its own |
+| Federation hooks | ✓ | plugin handlers + REST handlers can host an adapter (UC-38) |
+
+## 6. Mapping to shard-wiki INTENT (compare, do not equate)
+
+### 6.1 Reinforcements
+| Observation | INTENT principle |
+|-------------|------------------|
+| Forms store data as `%META%` **in the topic file** | structured pages can be **git-diffable**, strengthening UC-34/39 vs XWiki's DB |
+| RCS `.txt,v` history | **git-addressable coordination** — here history is *convertible*, not just supplementable (UC-36 → UC-41) |
+| `data/<Web>/<Topic>.txt` mirrors logic | an engine's **on-disk store is itself attachable as a folder shard** (UC-40) |
+| Plugin save/rename/REST handlers | **composable integration** — TWiki can host an adapter too, generalizing UC-38 beyond XWiki |
+| Per-topic `ALLOW/DENY` ACL | prior art for **per-page ACL at L4**; lineage TWiki→yawex (UC-06) |
+| Webs as namespaces / shards | namespace navigation (UC-22); webs as roots |
+
+### 6.2 Deliberate divergences (design bugs if conflated)
+| TWiki assumption | shard-wiki correction |
+|------------------|----------------------|
+| TWikiML + variable expansion is the page | **Markdown-first**; TWikiML render stays out of core |
+| ACL lives in topic preference settings | **authorize in core**; topic ALLOW/DENY is advisory provenance |
+| History = RCS files next to content | **coordination journal** is the space-level git layer (may *import* RCS) |
+| Apps = Forms + `%SEARCH%` rendered by TWiki | represent records **without** depending on TWiki to render/search them |
+| Attach = run TWiki and call it | shard-wiki may attach the **bare data dir** with TWiki offline (UC-40) |
+
+### 6.3 What TWiki teaches that shard-wiki should not lose
+1. **File-backed engines are the easy, high-value case** — their store is already a
+   folder of text + open-format history; the adapter can often skip the runtime.
+2. **Structured data in text beats structured data in a DB** for federation —
+   diffable, portable, journal-friendly. Prefer file-embedded metadata where offered.
+3. **One backend, two attachment paths** (runtime API vs on-disk store) is a real
+   capability/consistency trade-off the adapter contract must express.
+
+## 7. Use-case seeds → catalog (promoted 2026-06-13)
+
+| Seed | Catalog UC | Disposition |
+|------|------------|-------------|
+| Attach a live engine's **on-disk store directly** (vs its runtime API) | **UC-40** (new) | dual-path attach; fidelity/consistency trade-off |
+| **Import** an engine's native file-based history (RCS) into the journal | **UC-41** (new) | history *migration* with fidelity, vs UC-36 *supplementation* |
+| Engine hosts adapter via its plugin/handler API | UC-38 | enriched: TWiki save/rename/REST handlers generalize it beyond XWiki |
+| Structured page carries typed data | UC-34 / UC-39 | enriched: TWiki Forms `%META%`, git-diffable |
+| Internal-history engine | UC-36 | enriched: contrast DB (supplement) vs RCS (import, UC-41) |
+| Authenticated team wiki / per-page ACL | UC-06 | enriched: TWiki per-topic ACL is the origin of yawex's model |
+
+## 8. Open questions (for spec / workplans)
+
+1. **Dual-path adapters** — when does shard-wiki attach an engine's on-disk store
+   directly vs go through its API? Consistency risk of reading live files under a
+   running engine; capability-gate it (UC-40)?
+2. **History import fidelity** — can RCS `.txt,v` be converted to git commits
+   preserving author/timestamp, and is that authoritative or a one-time backfill
+   feeding the coordination journal (UC-41, cf. UC-36 Q3)?
+3. **File-embedded metadata mapping** — map TWiki `%META:FIELD%` (and XWiki XObjects)
+   onto one structured-metadata page-model representation (shared with xwiki §8 Q1).
+4. **TWiki vs Foswiki** — target both via one adapter (shared API) or treat as
+   distinct shard types?
+5. **ACL provenance** — surface a topic's `ALLOW/DENY` as read-only provenance even
+   though authorization is decided in core?
+
+## 9. Sources
+
+| Source | URL |
+|--------|-----|
+| TWiki — TWikiPlugins (handlers, package types) | https://twiki.org/cgi-bin/view/TWiki/TWikiPlugins |
+| TWiki — Developing Plugins / EmptyPlugin | https://twiki.org/cgi-bin/view/TWiki/TWikiPlugins |
+| TWiki — TWiki::Func module | https://twiki.org/cgi-bin/view/TWiki/TWikiFuncModule |
+| TWiki — TWiki Forms | https://twiki.org/cgi-bin/view/TWiki/TWikiForms |
+| TWiki — TWiki Access Control | https://twiki.org/cgi-bin/view/TWiki/TWikiAccessControl |
+| TWiki — System Requirements (Perl/RCS) | https://twiki.org/cgi-bin/view/TWiki/TWikiSystemRequirements |
+| TWiki — Source Code | https://twiki.org/cgi-bin/view/TWiki/SourceCode |
+| Foswiki — Why this fork | https://foswiki.org/Home/WhyThisFork |
+| Wikipedia — TWiki | https://en.wikipedia.org/wiki/TWiki |
+| Wikipedia — Foswiki | https://en.wikipedia.org/wiki/Foswiki |
+| shard-wiki — XWiki deep dive | `research/260613-xwiki-deep-dive/findings.md` |
+| shard-wiki — yawex prior art | `research/260608-yawex-prior-art/findings.md` |
+
+---
+
+## 10. Traceability
+
+| This document section | Informs (future) |
+|-----------------------|------------------|
+| §2 architecture | adapter design for file-backed engines |
+| §3 plugin handlers | UC-38 engine-side adapter; composable-integration API shape |
+| §4 access control | per-page ACL at L4 (`spec/ArchitectureBlueprint.md`), UC-06 |
+| §5 capability profile | adapter capability-profile vocabulary (`SHARD-WP-0002`) |
+| §6 INTENT mapping | architecture-blueprint guardrails |
+| §7 UC seeds | `spec/UseCaseCatalog.md` (UC-40, UC-41; UC-06/34/36/38/39 enrichment) |
+| §8 open questions | spec — dual-path adapters, history import, structured-metadata model |
--- a/research/260613-xwiki-deep-dive/README.md
+++ b/research/260613-xwiki-deep-dive/README.md
@@ -0,0 +1,35 @@
+# 260613 — XWiki deep dive (implementation, extension interfaces, ecosystem)
+
+Date: 2026-06-13
+
+## What this is
+
+A focused study of **XWiki** — the canonical "wiki-as-application-platform"
+engine flagged in `research/260608-wikiengines-overview/`. Goes past the landscape
+scan into XWiki's **implementation** (component/DI architecture, document data
+model, storage, rendering, events), the **interfaces it exposes to extend the core
+engine** (components, macros, UI extension points, script services, REST), and the
+**extension ecosystem** (extensions.xwiki.org repository, XAR/JAR/WebJar types,
+notable extensions).
+
+Read through one lens: **what does XWiki teach shard-wiki about (a) adapting a
+structured app-platform engine as a shard, and (b) how a host engine can become
+federation-capable through its own extension mechanism** (INTENT *composable
+integration*).
+
+Complements:
+- `research/260608-wikiengines-overview/` — the landscape scan that surfaced XWiki
+- `research/260608-federation-concepts/` — already covered XWiki's ActivityPub extension
+
+## Contents
+
+| Path | Role |
+|------|------|
+| `findings.md` | Architecture, extension-interface catalog, ecosystem, capability profile, INTENT mapping, UC seeds, sources |
+
+## Status
+
+Initial deep dive complete. Two new use cases promoted to
+`spec/UseCaseCatalog.md` (UC-38, UC-39); existing UC-34/UC-36/UC-31 enriched with
+XWiki specifics. Adapter-contract implications feed
+`workplans/SHARD-WP-0002-federation-architecture.md`.
--- a/research/260613-xwiki-deep-dive/findings.md
+++ b/research/260613-xwiki-deep-dive/findings.md
@@ -0,0 +1,217 @@
+# Findings — XWiki: implementation, extension interfaces, ecosystem
+
+Date: 2026-06-13 · Status: research draft
+
+Scope: XWiki as **prior art for two shard-wiki concerns** — (1) attaching a
+structured "wiki-as-application-platform" engine as a shard, and (2) how an engine
+exposes extension interfaces rich enough to *host* a federation adapter
+(INTENT *composable integration*). Sources are XWiki's own dev docs, the
+DeepWiki code analysis of `xwiki/xwiki-platform`, and the extensions repository.
+
+**Complements:** `research/260608-wikiengines-overview/` (landscape) and
+`research/260608-federation-concepts/` §3.2 (XWiki ActivityPub).
+
+---
+
+## 1. What XWiki is
+
+A **programmable, component-based wiki platform** (Java/Jakarta EE, Hibernate ORM)
+that blurs wiki and lightweight application platform. Pages are not just prose:
+they carry **typed structured objects**, so an XWiki page can be a form, a record,
+or a small application. This is the defining property the landscape scan flagged —
+and the reason XWiki is the hardest case for shard-wiki's Markdown-first page model.
+
+## 2. Implementation architecture
+
+### 2.1 Component system (the spine)
+- **Dependency-injection component model.** Components are interfaces (roles)
+  discovered via `META-INF/components.txt` and instantiated by a `ComponentManager`.
+  Implementations declare `@Component`, an optional `@Named` **role hint**, and
+  `@Singleton`. No interface→impl dependency — impls can ship in separate JARs and
+  **replace defaults at runtime**.
+- Core replaceable roles include `XWikiStoreInterface` (storage), `ObservationManager`
+  (events), `XWikiRightService` (authorization), `XWikiAuthService` (authentication).
+
+### 2.2 oldcore vs modular platform
+- `xwiki-platform-oldcore` holds the foundational document model, persistence, and
+  legacy APIs (`com.xpn.xwiki.*`). A bridge connects it to the newer component world
+  to avoid circular dependencies.
+- Newer modules layer on top: `model` (entity references), `rendering`, `security`,
+  `web` (HTTP actions/templates), `search-solr`.
+
+### 2.3 Data model — document-centric + class/object
+- Central entity: **`XWikiDocument`**, addressed by `DocumentReference`
+  (wiki / space / page). Content is parsed into an **XDOM** (rendering tree).
+- **Structured data via a class-object pattern** (OOP-like):
+  - `BaseClass` / **XClass** — schema (field definitions), like a class declaration
+  - `BaseObject` / **XObject** — an instance conforming to a class, attached to a page
+  - `PropertyClass` / `BaseProperty` — field definition / value
+  - Property types: String, LargeString, Date, Number, List, …
+- A single page can hold content **plus N typed objects** plus attachments. This is
+  the structural fact shard-wiki must represent without flattening.
+
+### 2.4 Storage & history
+- Two-tier: **`XWikiCacheStore`** over **`XWikiHibernateStore`** (Hibernate, multi-DB).
+- Tables: `xwikidoc`, `xwikiobject`, `xwikiproperties`, `xwikiattachment`, and
+  **`xwikircs`** — internal **RCS-style version history**. History is real but
+  **engine-internal and non-portable** (directly relevant to shard-wiki UC-36).
+
+### 2.5 Events & rendering
+- **`ObservationManager`** event bus: cancelable (`DocumentCreatingEvent`,
+  `DocumentUpdatingEvent`, `DocumentDeletingEvent`) and post-facto
+  (`DocumentCreatedEvent`, `DocumentUpdatedEvent`, …). Listeners are components —
+  a natural **change-notification source for incremental sync**.
+- **Rendering pipeline:** source syntax → parse → XDOM → transformations (macros) →
+  serialize (HTML, PDF, …). Pluggable parsers/renderers; XWiki can parse **Markdown**
+  as an input syntax even though its native syntax differs.
+
+### 2.6 Multi-wiki
+- One installation hosts many wikis (`WikiReference`), each with separate documents
+  and configuration — XWiki's own multi-tenancy, conceptually adjacent to
+  shard-wiki's root-entity/tenant boundary.
+
+### 2.7 APIs & security
+- **Dual API surface:** internal `com.xpn.xwiki.*` (full power) and script
+  `com.xpn.xwiki.api.*` (wrapped, enforces **programming rights** and view rights).
+  Privilege is enforced at the script boundary, not the storage boundary.
+
+## 3. Interfaces to extend the core engine
+
+XWiki's extensibility is unusually layered. From lowest/most-powerful to highest:
+
+| # | Mechanism | What it extends | How |
+|---|-----------|-----------------|-----|
+| 1 | **Components** | anything | implement a role interface, `@Component` + `@Named` hint; ship in a JAR with `components.txt`; can override defaults (store, auth, rights) |
+| 2 | **Rendering macros (Java)** | content processing | register `Macro.class` role + hint; participates in the XDOM transformation pipeline |
+| 3 | **Wiki macros** | content processing | a wiki page following a spec — **no Java, no compile**; in-wiki authoring |
+| 4 | **Script services** | scripting API | implement `org.xwiki.script.service.ScriptService`; exposed to Velocity/Groovy as `$services.<hint>` |
+| 5 | **UI Extensions (UIX)** at **UI Extension Points (UIXP)** | the interface, no skin edit | UIX stored as XObjects of `XWiki.UIExtensionClass` (label/target/icon); injected at named hooks (since v4.2), e.g. `org.xwiki.platform.panels.Applications` |
+| 6 | **REST API (JAX-RS)** | remote integration | resources for pages, spaces, **objects**, classes, attachments, comments, tags, annotations, users/groups, **history**; custom JAX-RS resources can be added |
+| 7 | **Event listeners** | reactive behavior | register a component on `ObservationManager` to react to document lifecycle events |
+| 8 | **Resource reference handlers** | new URL/resource types | implement `ResourceReferenceHandler` on the root component manager |
+| 9 | **Skins / templates / Velocity** | presentation | Flamingo skin macros, templates |
+
+Two things stand out for shard-wiki: (a) the **component model lets an extension
+replace authentication, authorization, and storage** — i.e. an XWiki instance could
+delegate auth exactly as shard-wiki's blueprint prescribes; (b) the **REST API plus
+event bus** give a federation adapter both a transport (read/write pages+objects+
+history) and a push-based freshness signal.
+
+## 4. Extension ecosystem
+
+- **`extensions.xwiki.org`** repository: **900+ extensions** (applications, macros,
+  skins, panels, themes, legacy plugins). Browsed/installed/upgraded at runtime via
+  the **Extension Manager Application** from the admin UI.
+- **Extension types:**
+  - **XAR** — a package of wiki pages (an application, a wiki macro, or a snippet)
+  - **JAR** — server-side Java: **components and script services**
+  - **WebJar** — JAR of web resources (JS/CSS/Less)
+- **"Plugin" (legacy) vs Component (modern):** the old plugin API is superseded by
+  the component system; new code is components.
+- **Notable extensions** (relevance to shard-wiki in parentheses):
+  - **AppWithinMinutes** — build structured apps (XClass+XObjects) from the UI
+    (→ pages-as-records, the UC-39 case)
+  - **LDAP / Active Directory** and **Entra ID (Azure AD)** authentication
+    (→ confirms pluggable `XWikiAuthService`; mirrors shard-wiki's delegated authn)
+  - **ActivityPub** — fediverse federation (→ adapter transport, cf. UC-31)
+  - **LiveData / LiveTable** — queryable tabular views over XObjects
+  - draw.io diagrams, PDF viewer, Task Manager, Blog — content/app breadth
+
+## 5. XWiki as a shard — capability profile
+
+Read through shard-wiki's capability-aware adapter lens:
+
+| Capability | XWiki | Note |
+|------------|-------|------|
+| Read | ✓ | REST + render to HTML/Markdown |
+| Write | ✓ | REST PUT page/object; **per-document** granularity (page + its objects) |
+| Structured payload | ✓✓ | XObjects/XClass — *richer* than Markdown; must not be flattened (UC-34/UC-39) |
+| Version/diff | ✓ (internal) | `xwikircs`; **not git-portable** → coordination journal supplies that (UC-36) |
+| Merge | partial | no native git-style 3-way merge |
+| Change events | ✓ | `ObservationManager` → push-based sync/freshness (enriches UC-31) |
+| Auth model | pluggable | `XWikiAuthService`/`XWikiRightService` replaceable — authorize through shard-wiki core, don't trust engine ACLs |
+| Federation hooks | ✓✓ | component + REST + UIX make XWiki able to **host** a shard-wiki adapter (UC-38) |
+| Multi-tenancy | ✓ | `WikiReference` farm → multiple shards / root entities |
+
+## 6. Mapping to shard-wiki INTENT (compare, do not equate)
+
+### 6.1 Reinforcements
+| Observation | INTENT principle |
+|-------------|------------------|
+| Pages = content + typed XObjects | **Markdown-first, backend-neutral** must carry structure, not flatten (UC-34/39) |
+| `xwikircs` internal-only history | **Git-addressable coordination** adds the portable layer (UC-36) |
+| Pluggable `XWikiAuthService` | **authorization in core, authentication delegated** — XWiki already does exactly this |
+| Component + REST + UIX extension surface | **composable integration** — engine becomes federation-capable via its own API (UC-38) |
+| `ObservationManager` events | **explicit provenance/freshness** via push, not poll (UC-31, UC-24) |
+| `WikiReference` multi-wiki | root-entity / tenant boundary has prior art |
+
+### 6.2 Deliberate divergences (design bugs if conflated)
+| XWiki assumption | shard-wiki correction |
+|------------------|----------------------|
+| Native XWiki syntax + macro render is the page | shard-wiki keeps **Markdown-first**; engine render stays out of core, structure travels as metadata |
+| ACLs/rights live in the engine DB | **authorize in core**; engine rights are advisory, not trusted |
+| History is the engine's RCS table | **coordination journal** is space-level and git-backed |
+| Federation = an XWiki extension talking to other XWikis | shard-wiki federates **heterogeneous** backends; XWiki is one shard among many |
+| App = XObjects rendered by XWiki | shard-wiki must represent records **without** depending on XWiki to render them |
+
+### 6.3 What XWiki teaches that shard-wiki should not lose
+1. **A clean role/hint component model** is what makes auth/store/rights swappable —
+   shard-wiki's adapter contract should be similarly role-based and override-friendly.
+2. **Structured objects are first-class**, not an afterthought — the page model needs
+   a typed-metadata escape hatch from day one.
+3. **An engine with a real extension API can host the adapter itself** — the cheapest
+   path to a high-fidelity shard is engine-side, not screen-scraping.
+
+## 7. Use-case seeds → catalog (promoted 2026-06-13)
+
+| Seed | Catalog UC | Disposition |
+|------|------------|-------------|
+| Engine hosts a federation adapter via its native extension API | **UC-38** (new) | composable integration — first UC for the engine-side direction |
+| Attach a wiki-as-application-platform shard (pages are typed records/forms) | **UC-39** (new) | extends UC-34 toward bodiless structured pages |
+| Structured page carries semantic data | UC-34 | enriched with XObject/XClass concretes |
+| Internal-only revision history | UC-36 | enriched with `xwikircs` example |
+| Subscribe to remote shard changes | UC-31 | enriched with `ObservationManager` event-driven transport |
+
+## 8. Open questions (for spec / workplans)
+
+1. **Page-model representation of XObjects** — typed frontmatter, sidecar file, or
+   opaque provenance blob? (shared with `wikiengines` §6 Q1; XWiki makes it urgent)
+2. **Bodiless record pages** — does shard-wiki's page model require a Markdown body,
+   or can a page be purely structured (AppWithinMinutes apps)?
+3. **Adapter placement** — engine-side extension (high fidelity, needs deploy access)
+   vs external REST adapter (zero engine change, lower fidelity). Both? Capability-gated?
+4. **Event transport** — consume `ObservationManager` via a JAR listener, or poll REST
+   history? Affects freshness guarantees (UC-31/UC-24).
+5. **Rights mapping** — translate XWiki `XWikiRightService` rights into shard-wiki
+   actions (read/write/patch/merge/administer), or ignore and authorize purely in core?
+
+## 9. Sources
+
+| Source | URL |
+|--------|-----|
+| XWiki — Developer Guide | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/ |
+| XWiki — Creating XWiki Components | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingComponents/ |
+| XWiki — Available Extension Points | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/ExtensionPoint/ |
+| XWiki — UI Extension Point Tutorial | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/UIXTutorial/ |
+| XWiki — Wiki Macro Tutorial | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/ |
+| XWiki — RESTful API | https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI |
+| XWiki Rendering — Writing a Macro | https://rendering.xwiki.org/xwiki/bin/view/Main/ExtendingMacro |
+| Extension Manager Application | https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Manager%20Application |
+| Extension Module — Extensions/types | https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/Extensions/ |
+| DeepWiki — xwiki/xwiki-platform (code analysis) | https://deepwiki.com/xwiki/xwiki-platform |
+| Mancinelli — Overview of XWiki's RESTful API | http://blog.fabio.mancinelli.me/2011/03/07/XWikis_RESTful_API.html |
+| shard-wiki — wiki engines overview | `research/260608-wikiengines-overview/findings.md` |
+| shard-wiki — federation concepts | `research/260608-federation-concepts/findings.md` |
+
+---
+
+## 10. Traceability
+
+| This document section | Informs (future) |
+|-----------------------|------------------|
+| §2 architecture | adapter design for app-platform engines |
+| §3 extension interfaces | UC-38 engine-side adapter; composable-integration API shape |
+| §5 capability profile | adapter capability-profile vocabulary (`SHARD-WP-0002`) |
+| §6 INTENT mapping | architecture-blueprint guardrails |
+| §7 UC seeds | `spec/UseCaseCatalog.md` (UC-38, UC-39; UC-31/34/36 enrichment) |
+| §8 open questions | spec — page model for structured/bodiless pages |
--- a/spec/UseCaseCatalog.md
+++ b/spec/UseCaseCatalog.md
@@ -1,9 +1,11 @@
 # UseCaseCatalog

-Status: **draft** · Date: 2026-06-08 · Updated: 2026-06-08
+Status: **draft** · Date: 2026-06-08 · Updated: 2026-06-13

 Promoted from `research/260608-c2-wiki-origins/`,
-`research/260608-yawex-prior-art/`, and `research/260608-federation-concepts/`.
+`research/260608-yawex-prior-art/`, `research/260608-federation-concepts/`,
+`research/260608-wikiengines-overview/`, `research/260613-xwiki-deep-dive/`,
+`research/260613-twiki-deep-dive/`, and `research/260613-foswiki-deep-dive/`.
 See InfoTechPrimers on coulomb.social for use-case catalog conventions.

 ## Conventions
@@ -12,7 +14,7 @@ Each use case lists:

 - **Actor** — who initiates the action
 - **Goal** — observable outcome
- **Source** — research lineage (`c2`, `yawex`, `federation`, `intent`, or combined)
+- **Source** — research lineage (`c2`, `yawex`, `federation`, `wikiengines`, `intent`, or combined)
 - **Notes** — shard-wiki-specific constraints or open design points

 Priority hints: **MVP** = likely early value; **Later** = important but not first slice.
@@ -80,7 +82,9 @@ external provider.
 **Source:** intent, yawex  
 **Notes:** yawex htpasswd + per-topic `AccessControl` is prior art only;
 shard-wiki delegates authentication, owns authorization
-(`spec/ArchitectureBlueprint.md`).  
+(`spec/ArchitectureBlueprint.md`). yawex's model traces to **TWiki's per-topic
+`ALLOW/DENY TOPICVIEW/CHANGE/RENAME`** — the origin reference for shard-wiki's
+optional per-page ACL at L4 (`research/260613-twiki-deep-dive/findings.md` §4).  
 **Priority:** Later

 ### UC-07 — Detect and reconcile cross-shard divergence
@@ -152,7 +156,10 @@ coded core behavior. Relates to UC-28.
 triggering projection refresh or reconciliation review.  
 **Source:** federation, intent  
 **Notes:** ikiwiki pinger/pingee; ActivityPub Create/Update; polling fallback.
-Transport is adapter concern; freshness surfaced in UC-24.  
+Transport is adapter concern; freshness surfaced in UC-24. XWiki deep dive adds a
+concrete push transport: an engine event bus (`ObservationManager`
+`DocumentUpdatedEvent`) consumed by a listener, vs polling REST history
+(`research/260613-xwiki-deep-dive/findings.md` §2.5, §8 Q4).  
 **Priority:** Later

 ### UC-32 — Transclude remote span with live freshness
@@ -175,6 +182,166 @@ divergent information space without destroying the original.
 Space-level fork — distinct from UC-26 page-level fork.  
 **Priority:** Later

+### UC-34 — Attach a structured or semantic shard without lossy flattening
+
+**Actor:** Maintainer  
+**Goal:** Attach an engine whose pages carry structured or queryable data beyond
+Markdown (Semantic MediaWiki annotations, XWiki objects/forms) and project it
+without silently discarding the structure.  
+**Source:** wikiengines, intent  
+**Notes:** Engine scan shows "wiki page" spans flat Markdown to queryable
+knowledge objects. Markdown-first must **degrade gracefully**, not flatten:
+needs a passthrough / sidecar-metadata / provenance escape hatch. Page-model
+question deferred to `SHARD-WP-0002` (findings §6 Q1). Distinct from UC-02
+(assumes Markdown-shaped pages). XWiki is the concrete exemplar: pages carry typed
+XObjects against an XClass schema (`research/260613-xwiki-deep-dive/findings.md`
+§2.3); UC-39 covers the extreme where the page is *only* structure. TWiki shows the
+**git-friendly** variant: TWiki Forms store fields as `%META:FIELD%` *inside the
+topic text file*, so structure is diffable rather than locked in a DB
+(`research/260613-twiki-deep-dive/findings.md` §2.3).  
+**Priority:** Later
+
+### UC-35 — Attach a shard with coarse write granularity
+
+**Actor:** Maintainer  
+**Goal:** Attach a backend whose unit of write is not the page — a single-file
+wiki (TiddlyWiki) or a whole-space/DB-transaction engine — and have shard-wiki
+respect that granularity instead of assuming per-page writes.  
+**Source:** wikiengines, intent  
+**Notes:** Capability-aware adapters: the **capability profile must encode write
+granularity** (per-page / per-file / per-space / append-only). Overlay and
+patch flows must adapt (findings §5 #1). Affects conflict scope and locking.  
+**Priority:** Later
+
+### UC-36 — Supply a git-addressable history to an internal-history engine
+
+**Actor:** Maintainer  
+**Goal:** Attach an engine whose revisions live only in its own database
+(Confluence, MediaWiki) and give the information space a portable, git-backed
+history it otherwise lacks.  
+**Source:** wikiengines, intent  
+**Notes:** Many engines expose revisions but not portable, git-style history.
+The **coordination journal** supplies the Git-addressable layer (INTENT). Open:
+is the journal authoritative or a mirror reconciled back to the engine
+(findings §6 Q3)? Complements UC-07 divergence and UC-24 provenance. XWiki's
+internal RCS table (`xwikircs`) is a concrete instance
+(`research/260613-xwiki-deep-dive/findings.md` §2.4). This UC is *supplementation*
+(the engine's past is DB-locked); where history is already in an open file format
+(TWiki RCS `.txt,v`) it can instead be **imported** — see UC-41.  
+**Priority:** Later
+
+### UC-37 — Attach a static engine export as a read-only backup shard
+
+**Actor:** Maintainer  
+**Goal:** Attach a one-shot export with no live origin — a MediaWiki XML dump, an
+HTML mirror, or an archived/read-only C2 — as a read-only cache/backup/patch
+target.  
+**Source:** wikiengines, intent  
+**Notes:** Graceful degradation — a frozen export is still a legitimate
+participant. Distinct from UC-03 (live projection with a reachable origin) and
+UC-28 (carry pages *forward* into a new space); here the dump itself is the
+shard. Read-only mode in `spec/ArchitectureBlueprint.md`.  
+**Priority:** Later
+
+### UC-38 — Make a wiki engine federation-capable via its native extension API
+
+**Actor:** Engine developer / integrator  
+**Goal:** Turn an existing wiki engine into a federation participant by hosting a
+shard-wiki adapter *inside* the engine through its own extension interface, rather
+than scraping it from outside.  
+**Source:** wikiengines, intent  
+**Notes:** Realizes INTENT *composable integration* — first UC for the **engine-side**
+direction (others attach engines from outside). XWiki is the proof case: its
+component model (`@Component` + role hint) can replace auth/storage/rights, its
+REST API and `ObservationManager` give transport + change events, and UIX adds
+surfacing — enough to host a high-fidelity adapter
+(`research/260613-xwiki-deep-dive/findings.md` §3). Trade-off vs an external REST
+adapter (needs deploy access, higher fidelity) is open (findings §8 Q3).
+Generalizes beyond XWiki: TWiki's plugin handler API (`beforeSaveHandler`,
+`afterRenameHandler`, REST handlers) is an equivalent host surface
+(`research/260613-twiki-deep-dive/findings.md` §3).  
+**Priority:** Later
+
+### UC-39 — Attach a wiki-as-application-platform shard (pages as typed records)
+
+**Actor:** Maintainer  
+**Goal:** Attach an engine where pages are structured records or forms with little
+or no prose body (XWiki AppWithinMinutes apps / XObjects), and represent them in the
+union without inventing a fake Markdown body.  
+**Source:** wikiengines, intent  
+**Notes:** The extreme of UC-34 — not *annotations on prose* but **bodiless
+structured pages**. Forces the question: does the page model require a Markdown body,
+or can a page be purely typed data (`research/260613-xwiki-deep-dive/findings.md`
+§8 Q2)? Affects union views, diff, and search. Deferred to `SHARD-WP-0002`.
+Foswiki shows a middle point: MetaDataPlugin stores **multiple** structured records
+per topic, still as `%META%` in text (`research/260613-foswiki-deep-dive/findings.md`
+§4) — the page model must allow N typed records, not one form.  
+**Priority:** Later
+
+### UC-40 — Attach a file-backed engine's on-disk store directly
+
+**Actor:** Maintainer  
+**Goal:** Attach a live engine whose content is plain files on disk — TWiki
+`data/<Web>/<Topic>.txt`, DokuWiki pages, a Gollum/ikiwiki repo — by reading its
+**backing store directly** as a folder shard, instead of (or alongside) going
+through its runtime API.  
+**Source:** wikiengines, intent  
+**Notes:** One backend, **two attachment paths** with different fidelity/consistency:
+the on-disk store (offline-capable, git-native for repo-backed engines, but risks
+reading inconsistent state under a running engine) vs the runtime API (consistent,
+respects engine logic, but requires the engine up). Capability profile must express
+the choice (`research/260613-twiki-deep-dive/findings.md` §5–§6, §8 Q1). Distinct
+from UC-37 (no live origin) and broader than UC-02's generic attach. Foswiki's
+**PlainFile** store (timestamped whole-version copies, no RCS) is a cleaner
+direct-attach target than RCS diffs (`research/260613-foswiki-deep-dive/findings.md`
+§2.2).  
+**Priority:** Later
+
+### UC-41 — Import an engine's native file history into the coordination journal
+
+**Actor:** Maintainer  
+**Goal:** When an engine already keeps history in an open file format (TWiki/yawex
+RCS `.txt,v`), **import that history** into the Git-backed coordination journal
+preserving authorship and timestamps — not just start a fresh journal going forward.  
+**Source:** wikiengines, intent  
+**Notes:** History *migration with fidelity*, distinct from UC-36 *supplementation*
+(where the engine's past is locked in a DB and the journal can only begin now). Open:
+is the imported history authoritative or a one-time backfill
+(`research/260613-twiki-deep-dive/findings.md` §8 Q2)? Strengthens recoverability
+(INTENT *History as the safety net*).  
+**Priority:** Later
+
+### UC-42 — Read and write a non-Markdown shard via lossless syntax translation
+
+**Actor:** Author or maintainer  
+**Goal:** Attach a shard whose native markup is not Markdown (TWiki/Foswiki TML,
+XWiki syntax) and read it into the Markdown-first model — and write Markdown overlays
+back — through **bidirectional, lossless syntax translation**, instead of treating it
+as read-only.  
+**Source:** wikiengines, intent  
+**Notes:** Realizes *Markdown-first, backend-neutral* for **prose** (UC-34/39 cover
+*structure*). Feasibility proven by Foswiki's **WysiwygPlugin** (TML→HTML for editing,
+HTML→TML losslessly on save) (`research/260613-foswiki-deep-dive/findings.md` §5).
+Open: is round-trip lossless enough, or must overlays be stored in the shard's native
+syntax to be safe (findings §9 Q2)? Without this, non-Markdown shards degrade to
+read-only (UC-03) — a graceful-degradation floor, not the goal.  
+**Priority:** Later
+
+### UC-43 — Tolerate a shard's storage-backend swap without losing identity
+
+**Actor:** Maintainer  
+**Goal:** Keep a shard attached, with its provenance and history intact, when its
+underlying storage backend changes — e.g. a Foswiki wiki migrated RCS→PlainFile, or a
+folder shard promoted into Git.  
+**Source:** wikiengines, intent  
+**Notes:** Foswiki proves backends are swappable under a stable identity via its
+versioned `Foswiki::Store` interface (`research/260613-foswiki-deep-dive/findings.md`
+§2). shard-wiki orchestration robustness: a shard's identity/attachment is **not** its
+storage format. Open: detect the swap and preserve history across it (findings §9 Q3).
+Relates to UC-40 (attach path) and UC-41 (history import) but is about *change under a
+live attachment*, not initial attach.  
+**Priority:** Later
+
 ---

 ## B. Knowledge work and collaboration
@@ -370,23 +537,33 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.

 ## Traceability

-| UC | c2 research | yawex research | federation research | INTENT |
-|----|-------------|----------------|---------------------|--------|
-| UC-01 | ✓ | | | ✓ |
-| UC-02 | | ✓ | | ✓ |
-| UC-03 | | ✓ | ✓ | ✓ |
-| UC-04 | ✓ | ✓ | ✓ | ✓ |
-| UC-05 | ✓ | ✓ | ✓ | ✓ |
-| UC-06 | | ✓ | | ✓ |
-| UC-07 | | | ✓ | ✓ |
-| UC-26 | | | ✓ | ✓ |
-| UC-27 | | | ✓ | ✓ |
-| UC-28 | | | ✓ | |
-| UC-29 | | | ✓ | ✓ |
-| UC-30 | | | ✓ | |
-| UC-31 | | | ✓ | ✓ |
-| UC-32 | | | ✓ | ✓ |
-| UC-33 | | | ✓ | ✓ |
+| UC | c2 research | yawex research | federation research | wikiengines research | INTENT |
+|----|-------------|----------------|---------------------|----------------------|--------|
+| UC-01 | ✓ | | | | ✓ |
+| UC-02 | | ✓ | | | ✓ |
+| UC-03 | | ✓ | ✓ | | ✓ |
+| UC-04 | ✓ | ✓ | ✓ | | ✓ |
+| UC-05 | ✓ | ✓ | ✓ | | ✓ |
+| UC-06 | | ✓ | | | ✓ |
+| UC-07 | | | ✓ | | ✓ |
+| UC-26 | | | ✓ | | ✓ |
+| UC-27 | | | ✓ | | ✓ |
+| UC-28 | | | ✓ | | |
+| UC-29 | | | ✓ | | ✓ |
+| UC-30 | | | ✓ | | |
+| UC-31 | | | ✓ | | ✓ |
+| UC-32 | | | ✓ | | ✓ |
+| UC-33 | | | ✓ | | ✓ |
+| UC-34 | | | | ✓ | ✓ |
+| UC-35 | | | | ✓ | ✓ |
+| UC-36 | | | | ✓ | ✓ |
+| UC-37 | | | | ✓ | ✓ |
+| UC-38 | | | | ✓ | ✓ |
+| UC-39 | | | | ✓ | ✓ |
+| UC-40 | | | | ✓ | ✓ |
+| UC-41 | | | | ✓ | ✓ |
+| UC-42 | | | | ✓ | ✓ |
+| UC-43 | | | | ✓ | ✓ |
 | UC-08 | ✓ | | |
 | UC-09 | ✓ | | |
 | UC-10 | ✓ | | |
@@ -448,6 +625,35 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | UC-FED-07 Transclude remote span | UC-32 |
 | UC-FED-08 Git-branch information space | UC-33 |

+### wikiengines mapping
+
+| Engine-landscape finding | Catalog UC |
+|--------------------------|------------|
+| Structured/semantic engines (Semantic MediaWiki, XWiki) — pages as queryable objects | UC-34 |
+| Coarse write granularity (TiddlyWiki single-file; whole-space DB writes) | UC-35 |
+| Internal-only revision history (Confluence, MediaWiki) needs portable git history | UC-36 |
+| Static exports / read-only archives (MediaWiki XML dump, archived C2, HTML mirror) | UC-37 |
+| Engine hosts adapter via native extension API (XWiki components/REST/UIX) | UC-38 |
+| Wiki-as-application-platform, bodiless typed pages (XWiki AppWithinMinutes/XObjects) | UC-39 |
+| Attach a file-backed engine's on-disk store directly (TWiki data dir, DokuWiki) | UC-40 |
+| Import an engine's native file history (TWiki RCS `.txt,v`) into the journal | UC-41 |
+| Lossless syntax translation for a non-Markdown shard (Foswiki WysiwygPlugin TML↔HTML) | UC-42 |
+| Tolerate a shard's storage-backend swap (Foswiki RCS↔PlainFile) under stable identity | UC-43 |
+
+Note: the landscape scan mostly **reinforced** existing UCs and the L0→L4 ladder
+rather than adding scenarios — its primary yield is adapter-contract constraints
+(`research/260608-wikiengines-overview/findings.md` §3, §5), tracked in
+`workplans/SHARD-WP-0002-federation-architecture.md`. UC-34–UC-37 are the
+attachment scenarios it surfaced. UC-38–UC-39 come from the **XWiki deep dive**
+(`research/260613-xwiki-deep-dive/findings.md` §7); UC-40–UC-41 from the **TWiki
+deep dive** (`research/260613-twiki-deep-dive/findings.md` §7), which also enriched
+UC-06 (TWiki per-topic ACL → yawex), UC-34 (file-embedded `%META%`), UC-36 (RCS vs
+DB history), and UC-38 (TWiki plugin handlers as an adapter host). UC-42–UC-43 come
+from the **Foswiki deep dive** (`research/260613-foswiki-deep-dive/findings.md` §8),
+which also enriched UC-39 (MetaDataPlugin multi-record), UC-40 (PlainFile store), and
+logged the `Foswiki::Store` versioned interface as **adapter-contract prior art** for
+`SHARD-WP-0002` (no UC — architecture).
+
 ---

 ## Open questions
--- a/workplans/SHARD-WP-0002-federation-architecture.md
+++ b/workplans/SHARD-WP-0002-federation-architecture.md
@@ -8,7 +8,7 @@ status: active
 owner: tegwick
 topic_slug: whynot
 created: "2026-06-08"
-updated: "2026-06-08"
+updated: "2026-06-13"
 depends_on:
  - SHARD-WP-0001
 state_hub_workstream_id: "2af4c46d-cbfd-40ea-a94b-d9e60b0f9945"
@@ -27,11 +27,27 @@ UC-26–UC-33.
 Primary deliverable: `spec/FederationArchitecture.md` (created and filled by
 this workplan's tasks).

+Secondary deliverable (T11–T15, added 2026-06-13): the **shard adapter contract**
+constraints distilled from the engine deep dives, feeding
+`spec/TechnicalSpecificationDocument.md`. Federation architecture decides *what the
+union does*; the adapter contract decides *what a backend must expose to participate*.
+The two are co-dependent (the capability matrix T10 consumes the contract vocabulary
+T11 defines), so they live in one workplan.
+
 ## Context

- Research: `research/260608-federation-concepts/findings.md`
- Use cases: `spec/UseCaseCatalog.md` § A (UC-26–UC-33)
- Aspiration: `INTENT.md` (orchestrator, not engine; mechanism over policy)
+- Federation research: `research/260608-federation-concepts/findings.md`
+- Engine deep dives (adapter-contract inputs, T11–T15):
+  - `research/260608-wikiengines-overview/findings.md` (landscape; capability
+    heterogeneity, write granularity)
+  - `research/260613-xwiki-deep-dive/findings.md` (DB/component app-platform)
+  - `research/260613-twiki-deep-dive/findings.md` (file+RCS app-platform)
+  - `research/260613-foswiki-deep-dive/findings.md` (`Foswiki::Store` versioned
+    store interface = adapter-contract prior art)
+- Use cases: `spec/UseCaseCatalog.md` § A (UC-26–UC-43; UC-34–43 are the
+  engine-attachment / adapter-contract cases)
+- Aspiration: `INTENT.md` (orchestrator, not engine; mechanism over policy;
+  capability-aware adapters; Markdown-first, backend-neutral)
 - Related workplan: `SHARD-WP-0001` (page resolution, namespaces, overlays,
  provenance — federation architecture must align with, not duplicate, those
  outputs)
@@ -54,6 +70,16 @@ decision records only.
 | Consensus presets | Spread, merge, designated canonical — policy not core | UC-07, UC-27 |
 | Capability matrix | Which federation ops require which adapter capabilities | UC-02–UC-07 |

+### Adapter-contract topics (T11–T15, from engine deep dives)
+
+| Topic | Key tradeoff | Primary UCs |
+|-------|--------------|-------------|
+| Adapter contract & capabilities | Versioned interface + capability vocabulary; write granularity | UC-02, UC-35, UC-38 |
+| Structured page model | Typed frontmatter vs sidecar vs blob; bodiless / multi-record pages | UC-34, UC-39 |
+| History portability | Supplement (DB-internal) vs import (open file history) | UC-36, UC-41 |
+| Adapter binding | Runtime API vs on-disk store; engine-hosted vs external; backend-swap | UC-38, UC-40, UC-43 |
+| Syntax translation | Lossless non-Markdown round-trip vs read-only degradation | UC-42, UC-03 |
+
 ---

 ## Architecture positioning and boundaries
@@ -281,28 +307,185 @@ Cross-check against INTENT capability-aware adapters principle. Identify
 graceful degradation paths for limited backends (read-only participant,
 projection-only, patch target).

-Feeds `spec/TechnicalSpecificationDocument.md` adapter contract section.
+This matrix **consumes the capability vocabulary defined in T11** — keep the two
+in sync. Feeds `spec/TechnicalSpecificationDocument.md` adapter contract section.
+
+---
+
+# Shard adapter contract (folded from engine deep dives, 2026-06-13)
+
+These tasks distill the cross-cutting **adapter-contract constraints** surfaced by
+the four engine deep dives (wiki-engines landscape, XWiki, TWiki, Foswiki). They
+answer *what a backend must expose to participate as a shard*, complementing the
+federation tasks above (which answer *what the union does*). Output target:
+`spec/TechnicalSpecificationDocument.md` (adapter contract section), cross-linked
+from `spec/FederationArchitecture.md`.
+
+Recurring cross-engine insight to honor: **structure and history in text files
+federate far more easily than in a database**, and **Foswiki::Store already proves
+the versioned-interface-with-swappable-backends pattern** the contract should adopt.
+
+## Adapter contract: capability model & versioned interface
+
+```task
+id: SHARD-WP-0002-T11
+status: todo
+priority: high
+state_hub_task_id: "a7379621-6694-488b-94ca-846b8e27e745"
+```
+
+Define the **capability-aware shard adapter contract** as a *versioned* interface,
+taking `Foswiki::Store` + `Foswiki::Meta` as direct prior art (a real engine that
+already separates store backend from core behind a stable interface).
+
+- Capability vocabulary: `read, write, diff, merge, lock, version, publish, notify,
+  transclude-source, translate-syntax, structured-payload` (reconcile with T10).
+- **Write granularity** as a first-class capability dimension: per-page / per-file /
+  per-space / append-only (TiddlyWiki single-file vs DB whole-space vs TWiki per-topic).
+- Versioning/compatibility rules for the contract itself; capability discovery.
+
+**Inputs:** `260608-wikiengines-overview` §3, §5; `260613-foswiki-deep-dive` §2, §6.
+**Provides** the vocabulary T10's matrix consumes. **UCs:** UC-02, UC-35, UC-38.
+
+**Tradeoffs:** Rich capability set (precise degradation) vs contract complexity;
+static profile vs runtime capability negotiation.
+
+---
+
+## Page model: structured / typed payload representation
+
+```task
+id: SHARD-WP-0002-T12
+status: todo
+priority: high
+state_hub_task_id: "7334a4a4-ba75-4fac-a8b4-8350d342b299"
+```
+
+Decide how the **backend-neutral, Markdown-first page model carries structured data
+without flattening**:
+
+- Source shapes: XWiki XObjects against an XClass; TWiki/Foswiki DataForms stored as
+  `%META:FIELD%` in text; Foswiki MetaDataPlugin **multiple records per topic**;
+  Semantic MediaWiki annotations.
+- Representation choice: typed frontmatter vs sidecar file vs opaque provenance blob.
+- **Bodiless pages** (UC-39): may a page be purely structured, no Markdown body?
+- **N typed records per page** (not one form) must be representable.
+
+**Inputs:** `xwiki` §2.3; `twiki` §2.3; `foswiki` §4. **UCs:** UC-34, UC-39.
+
+**Tradeoffs:** Lossless fidelity vs a uniform queryable model; diff/search over
+structured fields vs prose.
+
+---
+
+## History portability: supplement vs import
+
+```task
+id: SHARD-WP-0002-T13
+status: todo
+priority: high
+state_hub_task_id: "6837862a-8f57-410d-9200-a6a5dcf1a7b9"
+```
+
+Define how the **coordination journal** relates to an engine's native history (aligns
+with and refines T4):
+
+- **Supplement** — engine history is DB-internal and non-portable
+  (Confluence, MediaWiki, XWiki `xwikircs`): the journal begins now / mirrors forward
+  (UC-36).
+- **Import** — engine history is an open file format (TWiki/yawex RCS `.txt,v`,
+  Foswiki PlainFile timestamped copies): backfill into Git preserving author/timestamp
+  (UC-41).
+- Authoritative journal vs mirror-reconciled-back; one-time vs continuous.
+
+**Inputs:** `xwiki` §2.4; `twiki` §2.1; `foswiki` §2.2. **UCs:** UC-36, UC-41.
+
+**Tradeoffs:** Import fidelity vs effort; duplicated history vs single source of truth.
+
+---
+
+## Adapter binding: attach path, hosting, backend-swap
+
+```task
+id: SHARD-WP-0002-T14
+status: todo
+priority: medium
+state_hub_task_id: "f8835969-d118-4738-952a-5e67e5209f3d"
+```
+
+Decide **how and where an adapter binds to a backend**:
+
+- **Dual-path attach** — runtime API vs reading the on-disk store directly
+  (consistency vs offline/fidelity); capability-gate the choice (UC-40).
+- **Hosting** — engine-side adapter via native extension API (XWiki components/REST/
+  UIX; TWiki/Foswiki plugin handlers + REST + `registerTagHandler`) vs external
+  adapter (no engine change, lower fidelity) (UC-38).
+- **Backend-swap tolerance** — shard identity/provenance survives a storage-format
+  change (Foswiki RCS↔PlainFile; folder→Git) (UC-43).
+
+**Inputs:** `twiki` §5, §6; `xwiki` §3; `foswiki` §2. **UCs:** UC-38, UC-40, UC-43.
+
+**Tradeoffs:** Fidelity vs deploy access; consistency vs offline capability.
+
+---
+
+## Syntax translation & content fidelity
+
+```task
+id: SHARD-WP-0002-T15
+status: todo
+priority: medium
+state_hub_task_id: "22b57b3a-b06b-4ff0-a34a-667a0386bf25"
+```
+
+Specify how **non-Markdown shards** participate in the Markdown-first model:
+
+- Read native markup (TWiki/Foswiki TML, XWiki syntax) into the page model and accept
+  Markdown overlays back via **bidirectional, lossless translation** (UC-42).
+- Feasibility proof: Foswiki **WysiwygPlugin** (TML→HTML for editing, HTML→TML
+  losslessly on save).
+- **Graceful degradation:** when lossless translation is unavailable, the shard is a
+  read-only/projection participant (UC-03), never silently corrupted.
+- Open: may overlays be stored in Markdown, or must they round-trip in native syntax?
+
+**Inputs:** `foswiki` §5; `twiki` §2.4; `xwiki` §2.5. **UCs:** UC-42, UC-03.
+
+**Tradeoffs:** Translation coverage vs read-only floor; Markdown overlays (portable)
+vs native-syntax overlays (safe round-trip).

 ---

 ## Acceptance criteria

- `spec/FederationArchitecture.md` exists with all ten topic sections and an
-  explicit **decisions / deferred / open** table per topic.
+- `spec/FederationArchitecture.md` exists with all ten federation topic sections
+  (T1–T10) and an explicit **decisions / deferred / open** table per topic.
+- The **adapter contract** section of `spec/TechnicalSpecificationDocument.md` exists,
+  populated by T11–T15, with the capability vocabulary (T11) reconciled against the
+  T10 federation-ops matrix.
 - Each decision honors INTENT: mechanism over policy, union without erasure,
-  overlay before mutation, no silent remote mutation, shard sovereignty.
- UC-26–UC-33 are traceable to architecture sections.
+  overlay before mutation, no silent remote mutation, shard sovereignty,
+  capability-aware adapters, Markdown-first / backend-neutral.
+- UC-26–UC-43 are traceable to architecture / adapter-contract sections
+  (UC-34–UC-43 to T11–T15 specifically).
 - Conflicts or dependencies on `SHARD-WP-0001` outputs are listed (e.g.
-  namespace model affects equivalent-page identity).
+  namespace model affects equivalent-page identity; page model T12 affects
+  resolution/overlays).
 - `SHARD-WP-0001` and `SHARD-WP-0002` can proceed in parallel where topics
  are independent; merge conflicts in spec are resolved before implementation
  workplan starts.

 ## Suggested task order

+**Federation architecture (T1–T10):**
 1. T1 positioning (frames everything)
 2. T2 remix primitives + T3 equivalent identity (parallel)
 3. T4 history model
 4. T5 composition + T6 notification (parallel)
 5. T7 lifecycle + T8 transclusion (parallel)
-6. T9 policy catalog + T10 capability matrix (parallel, finalize doc)
+6. T9 policy catalog + T10 capability matrix (parallel, finalize doc)
+
+**Adapter contract (T11–T15)** — can start in parallel with T1; T11 first as it
+frames the rest, and pair it with T10 (shared capability vocabulary):
+7. T11 contract & capabilities (frames T12–T15; sync with T10)
+8. T12 page model + T13 history portability (parallel; T13 aligns with T4)
+9. T14 binding + T15 syntax translation (parallel, finalize adapter-contract spec)
Author	SHA1	Message	Date
tegwick	316fdeedc2	spec(SHARD-WP-0002): fold adapter-contract constraints into T11-T15 Distill the cross-cutting adapter-contract constraints from the four engine deep dives (wiki-engines landscape, XWiki, TWiki, Foswiki) into five concrete design tasks, complementing the federation tasks (T1-T10): - T11 adapter contract: capability model & versioned interface (Foswiki::Store prior art; write-granularity as a capability dimension) - T12 page model: structured/typed payload representation (XObjects, %META%, multi-record, bodiless pages) - T13 history portability: supplement (DB-internal) vs import (open file history) - T14 adapter binding: attach path, engine-hosted vs external, backend-swap - T15 syntax translation & content fidelity (non-Markdown round-trip) Adds an adapter-contract decision-topics table, cross-links T10<->T11 on the shared capability vocabulary, and updates context/acceptance/task-order. Tasks registered in the state hub (workstream 2af4c46d). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-13 23:35:09 +02:00
tegwick	fa7adab239	research: Foswiki deep dive (store abstraction, ext API); UC-42/43 Deep dive into Foswiki focused on its deltas from TWiki (not the shared lineage): the pluggable Foswiki::Store backend (RcsWrap/RcsLite/PlainFile) behind a versioned interface via Foswiki::Meta, the OO/MVC core rewrite, Foswiki::Func + registerTagHandler, DataForms + MetaDataPlugin multi-record, and WysiwygPlugin TML<->HTML round-trip. The store abstraction is logged as prior art for shard-wiki's own adapter contract (SHARD-WP-0002). Catalog (now 43 UCs): - UC-42 read/write a non-Markdown shard via lossless syntax translation (Markdown-first for prose; Foswiki WysiwygPlugin is proof) - UC-43 tolerate a shard's storage-backend swap (RCS<->PlainFile) under a stable identity - enrich UC-39 (multi-record metadata) and UC-40 (PlainFile direct-attach) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-13 23:27:24 +02:00
tegwick	ffd5459b3e	research: TWiki deep dive (impl, plugin API, ecosystem); UC-40/41 Deep dive into TWiki as the file-based Perl counterpoint to XWiki: flat-file + RCS store (data/<Web>/<Topic>.txt), Webs/Topics, TWiki Forms storing fields as %META% in the topic text, TWikiML/variables, TWiki::Func API; the plugin handler callback surface (initPlugin, commonTagsHandler, before/afterSaveHandler, afterRenameHandler, REST handlers) and package types (Plugin/Skin/AddOn/Contrib); per-topic ALLOW/DENY access control (origin of yawex's model); Foswiki fork. Catalog (now 41 UCs): - UC-40 attach a file-backed engine's on-disk store directly (dual-path attach) - UC-41 import an engine's native file history (RCS .txt,v) into the journal - enrich UC-06 (TWiki per-topic ACL lineage), UC-34 (file-embedded %META%), UC-36 (RCS-import vs DB-supplement), UC-38 (TWiki handlers as adapter host) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-13 23:20:11 +02:00
tegwick	27da940df1	research: XWiki deep dive (impl, extension interfaces, ecosystem); UC-38/39 Deep dive into XWiki past the landscape scan: component/DI architecture, document + class/object data model, oldcore, Hibernate storage + xwikircs history, ObservationManager events, rendering pipeline, multi-wiki; the full extension-interface surface (components, Java/wiki macros, script services, UIX/UIXP, JAX-RS REST, event listeners, resource handlers); and the extensions.xwiki.org ecosystem (XAR/JAR/WebJar, 900+ extensions). Catalog: - UC-38 make a wiki engine federation-capable via its native extension API (composable integration — first engine-side-direction UC; XWiki is proof) - UC-39 attach a wiki-as-application-platform shard (bodiless typed pages) - enrich UC-31 (ObservationManager event-driven sync), UC-34 (XObject model), UC-36 (xwikircs internal history) with concrete XWiki specifics Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-13 19:20:42 +02:00
tegwick	0473c3f043	spec: extract use cases from wiki-engines landscape research (UC-34–UC-37) Mine the one research dir not yet promoted (260608-wikiengines-overview) into the catalog. Adds four heterogeneous-backend attachment scenarios the other research didn't surface: - UC-34 attach structured/semantic shard without lossy flattening (SMW, XWiki) - UC-35 attach shard with coarse write granularity (TiddlyWiki single-file) - UC-36 supply git-addressable history to internal-history engine (Confluence) - UC-37 attach static export as read-only backup shard (MediaWiki dump) Adds a `wikiengines` source token + traceability column and a wikiengines mapping subsection. The scan mostly reinforced existing UCs and the L0→L4 ladder; its main yield is adapter-contract constraints tracked in SHARD-WP-0002. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-13 18:39:30 +02:00