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>

spec/UseCaseCatalog.md

@@ -4,7 +4,8 @@ Status: **draft** · Date: 2026-06-08 · Updated: 2026-06-13
 
 Promoted from `research/260608-c2-wiki-origins/`,
 `research/260608-yawex-prior-art/`, `research/260608-federation-concepts/`,
-`research/260608-wikiengines-overview/`, and `research/260613-xwiki-deep-dive/`.
+`research/260608-wikiengines-overview/`, `research/260613-xwiki-deep-dive/`, and
+`research/260613-twiki-deep-dive/`.
 See InfoTechPrimers on coulomb.social for use-case catalog conventions.
 
 ## Conventions
@@ -81,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
@@ -192,7 +195,10 @@ 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.  
+§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
@@ -219,7 +225,9 @@ 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).  
+(`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
@@ -248,7 +256,10 @@ 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).  
+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)
@@ -264,6 +275,36 @@ 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`.  
 **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.  
+**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
+
 ---
 
 ## B. Knowledge work and collaboration
@@ -482,6 +523,8 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | UC-37 | | | | ✓ | ✓ |
 | UC-38 | | | | ✓ | ✓ |
 | UC-39 | | | | ✓ | ✓ |
+| UC-40 | | | | ✓ | ✓ |
+| UC-41 | | | | ✓ | ✓ |
 | UC-08 | ✓ | | |
 | UC-09 | ✓ | | |
 | UC-10 | ✓ | | |
@@ -553,14 +596,18 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | 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 |
 
 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), which also enriched UC-31
-(event-driven sync), UC-34 (XObject model), and UC-36 (`xwikircs` history).
+(`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).
 
 ---