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
parent 0473c3f043
commit 27da940df1
3 changed files with 302 additions and 8 deletions
--- 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
@@ -3,8 +3,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/`, and
-`research/260608-wikiengines-overview/`.
+`research/260608-yawex-prior-art/`, `research/260608-federation-concepts/`,
+`research/260608-wikiengines-overview/`, and `research/260613-xwiki-deep-dive/`.
 See InfoTechPrimers on coulomb.social for use-case catalog conventions.

 ## Conventions
@@ -153,7 +153,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
@@ -187,7 +190,9 @@ without silently discarding the structure.
 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).  
+(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.  
 **Priority:** Later

 ### UC-35 — Attach a shard with coarse write granularity
@@ -212,7 +217,9 @@ history it otherwise lacks.
 **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.  
+(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).  
 **Priority:** Later

 ### UC-37 — Attach a static engine export as a read-only backup shard
@@ -228,6 +235,35 @@ 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).  
+**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`.  
+**Priority:** Later
+
 ---

 ## B. Knowledge work and collaboration
@@ -444,6 +480,8 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | UC-35 | | | | ✓ | ✓ |
 | UC-36 | | | | ✓ | ✓ |
 | UC-37 | | | | ✓ | ✓ |
+| UC-38 | | | | ✓ | ✓ |
+| UC-39 | | | | ✓ | ✓ |
 | UC-08 | ✓ | | |
 | UC-09 | ✓ | | |
 | UC-10 | ✓ | | |
@@ -513,12 +551,16 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | 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 |

-Note: the scan mostly **reinforced** existing UCs and the L0→L4 ladder rather than
-adding scenarios — its primary yield is adapter-contract constraints
+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
-genuinely new attachment scenarios it surfaced.
+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).

 ---