diff --git a/research/260613-xwiki-deep-dive/README.md b/research/260613-xwiki-deep-dive/README.md new file mode 100644 index 0000000..7589812 --- /dev/null +++ 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`. diff --git a/research/260613-xwiki-deep-dive/findings.md b/research/260613-xwiki-deep-dive/findings.md new file mode 100644 index 0000000..a8b2eda --- /dev/null +++ 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.` | +| 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 | diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md index 0c273ce..cc96811 100644 --- 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). ---