generated from coulomb/repo-seed
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>
This commit is contained in:
@@ -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)
|
||||
Reference in New Issue
Block a user