diff --git a/workplans/SHARD-WP-0002-federation-architecture.md b/workplans/SHARD-WP-0002-federation-architecture.md index 74e7c45..33496e4 100644 --- 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) \ No newline at end of file +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) \ No newline at end of file