generated from coulomb/repo-seed
Compare commits
2 Commits
40575045ca
...
d65f9e21f3
| Author | SHA1 | Date | |
|---|---|---|---|
| d65f9e21f3 | |||
| 802a80231a |
2
SCOPE.md
2
SCOPE.md
@@ -22,7 +22,7 @@ Learnings update both SCOPE and INTENT where necessary.
|
||||
| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`); XWiki/TWiki/Foswiki deep dives (`research/260613-*/`); Xanadu + ZigZag + Roam + Obsidian + Notion + Joplin + Logseq + local-first workspaces (Anytype/AFFiNE/AppFlowy) + Trilium + Wiki.js + Federated Wiki + Wikibase + git-forge wikis + TiddlyWiki + ikiwiki + Quip + MojoMojo + Oddmuse + UseModWiki deep dives & shard-spectrum synthesis (`research/260614-*/`) |
|
||||
| Demand | NetKingdom integration asks captured, not yet negotiated |
|
||||
| Spec | CoreArchitectureBlueprint (whole-system architecture, hardened via SHARD-WP-0005) + ArchitectureBlueprint (auth/history) drafted; UseCaseCatalog 84 UCs from research; PRD/TSD scaffolds |
|
||||
| Work | `SHARD-WP-0001` **done** (6 ADRs: yawex-derived federation requirements → `spec/FederationRequirements.md`); `SHARD-WP-0002` active (18 tasks: T1–T10 federation + T11–T16 adapter contract + T17 federation-model taxonomy + T18 computational content, re-folded from synthesis v3 + the computational page model); `SHARD-WP-0003` **done** (9 engine dives complete); `SHARD-WP-0004` **done** (all 8 computational-knowledge dives T1–T8 complete + "computational page model" synthesis); `SHARD-WP-0005` **done** (9 tasks: CoreArchitectureBlueprint hardened against the 260615 review); `SHARD-WP-0006` **done** (5 tasks: round-2 hardening — overview reconciled, event-sourced coordination + append authority, adapter conformance, incremental correctness + I-2 verification) |
|
||||
| Work | `SHARD-WP-0001` **done** (6 ADRs: yawex-derived federation requirements → `spec/FederationRequirements.md`); `SHARD-WP-0002` **done** (18 tasks → `FederationArchitecture.md` [T1–T10, T17] + `TechnicalSpecificationDocument.md` §A adapter contract [T11–T16, T18]); `SHARD-WP-0003` **done** (9 engine dives complete); `SHARD-WP-0004` **done** (all 8 computational-knowledge dives T1–T8 complete + "computational page model" synthesis); `SHARD-WP-0005` **done** (9 tasks: CoreArchitectureBlueprint hardened against the 260615 review); `SHARD-WP-0006` **done** (5 tasks: round-2 hardening — overview reconciled, event-sourced coordination + append authority, adapter conformance, incremental correctness + I-2 verification) |
|
||||
|
||||
## In Scope (today)
|
||||
|
||||
|
||||
220
spec/FederationArchitecture.md
Normal file
220
spec/FederationArchitecture.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# FederationArchitecture
|
||||
|
||||
Status: **draft for review** · Date: 2026-06-15 · Deliverable of **SHARD-WP-0002** (T1–T10, T17)
|
||||
|
||||
The federation **design decisions** for shard-wiki: *what the union does*. It records, per
|
||||
topic, a decision with rationale, tradeoffs, and a **Decided / Deferred / Open** footer. It
|
||||
**references** `spec/CoreArchitectureBlueprint.md` (the whole-system architecture) and
|
||||
`spec/FederationRequirements.md` (yawex-derived ADRs) rather than restating them; the adapter
|
||||
contract (*what a backend must expose*) is the companion deliverable in
|
||||
`spec/TechnicalSpecificationDocument.md` §A (T11–T16, T18). UC references → `UseCaseCatalog.md`.
|
||||
|
||||
Cross-cutting invariants assumed throughout (blueprint §2): orchestrator-not-engine (I-1),
|
||||
three-state canonical/derived (I-2), capability-as-data (I-3), union-without-erasure (I-4),
|
||||
overlay-before-mutation (I-5), git-addressable coordination (I-6), mechanism-over-policy (I-7),
|
||||
graceful degradation (I-8), identity≠placement (I-9), history-as-floor (I-10), authz-in-core
|
||||
(I-11), tenant-partitioned derived state (I-13).
|
||||
|
||||
---
|
||||
|
||||
## T1 — Orchestrator positioning & boundaries
|
||||
|
||||
**Decision.** shard-wiki is an **adapter-layer orchestrator** in a **star** shape (many
|
||||
sovereign shards ↔ one information space), **not** a homogeneous federation network. It
|
||||
**compares, does not equate** (Federated Wiki homogeneous JSON sites, ikiwiki homogeneous git
|
||||
wikis, ActivityPub activity streams are *models it can speak*, §T17 — not shapes it imposes).
|
||||
Core owns: the union, the coordination journal, projection, overlay, resolution, authorization.
|
||||
Adapters own backend specifics; UI and editorial policy live outside core. (Blueprint §1, §5;
|
||||
UC-02, UC-26.)
|
||||
|
||||
*Decided:* star orchestrator; compare-not-equate; core/adapter/UI/policy boundaries.
|
||||
*Deferred:* the reference UI (L6) is out of scope here. *Open:* none.
|
||||
|
||||
## T2 — Remix primitives: reference / projection / overlay / import-fork
|
||||
|
||||
**Decision.** Four primitives, escalating in commitment; **overlay-before-mutation is the
|
||||
default write path** (I-5), fork is *one federation model* (§T17) not the default for editing:
|
||||
|
||||
| Primitive | Trigger | Writes remote? | Coordination-canonical? |
|
||||
|-----------|---------|----------------|--------------------------|
|
||||
| **Reference** | link only | no | no (a link in content) |
|
||||
| **Projection** | read remote page | no (cache) | no (derived) |
|
||||
| **Overlay** | edit a sub-write-through shard | not until explicit apply | **yes** (decision log) |
|
||||
| **Import / fork** | copy into a writable shard / fork-with-provenance | source unchanged | **yes** (fork event) |
|
||||
|
||||
(Blueprint §8.2; FederationRequirements ADR-05; UC-04, UC-26, UC-29.)
|
||||
|
||||
*Decided:* the four primitives + overlay-default. *Deferred:* fork-attribution portability
|
||||
format. *Open:* whether "import" and "fork" are one primitive with a flag or two (impl spike).
|
||||
|
||||
## T3 — Equivalent-page identity & multi-version presentation
|
||||
|
||||
**Decision.** Separate **identity** (stable handle), **placement** (N paths/shards), and
|
||||
**equivalence** (content-fingerprint / span-set overlap *across* identities), per
|
||||
FederationRequirements ADR-01/ADR-02 (I-9). Equivalence signals: normalized title/path, alias
|
||||
table (coordination-canonical), link-graph overlap, fingerprint, **curator binding**. Default
|
||||
presentation = **chorus-of-voices** (all equivalent versions, attributed); **designated-
|
||||
canonical** is a policy preset (§T9). Divergence is data in the provenance envelope (I-4),
|
||||
detected as core mechanism (blueprint §8.6). (UC-07, UC-27; UC-46.)
|
||||
|
||||
*Decided:* identity/placement/equivalence split; chorus default. *Deferred:* fingerprint
|
||||
algorithm + blocking params (blueprint O-1). *Open:* curator-binding UX (L6).
|
||||
|
||||
## T4 — History, attribution & the coordination journal
|
||||
|
||||
**Decision.** Each information space has a **git-addressable, event-sourced coordination
|
||||
journal** (blueprint §8.1, I-6/I-10): coordination-canonical decisions (overlay/binding/alias/
|
||||
merge/fork) are append-only events; current state is a derived fold. **One append authority per
|
||||
space** gives a total order (read-your-writes across instances). Per-shard native history is
|
||||
**adopted** (git-native), **supplemented** (DB/CRDT internal → journal begins-now/mirrors), or
|
||||
**imported** (open file history backfilled) per the history-portability axis (TSD §A T13).
|
||||
Attribution is portable on the event (UC-29). (UC-29, UC-33.)
|
||||
|
||||
*Decided:* event-sourced journal + per-space append authority + adopt/supplement/import.
|
||||
*Deferred:* per-space log sharding for extreme write rates (blueprint O-12). *Open:* none.
|
||||
|
||||
## T5 — Union composition layer
|
||||
|
||||
**Decision.** The **server-side orchestrator union is primary** — the derived tier (union
|
||||
graph, indexes, projections) is composed in core for agents/CLI/non-browser consumers
|
||||
(blueprint §8.4), **incrementally maintained** (not recomputed, §8.7), **tenant-partitioned**
|
||||
(I-13). **Client-side composition** (Federated-Wiki-style browser pull) is a supported
|
||||
*consumer pattern over the same union*, not the only path. Freshness/caching per §8.8. (UC-05,
|
||||
UC-27, UC-03, UC-31.)
|
||||
|
||||
*Decided:* server-primary, client-optional; incremental, partitioned. *Deferred:* client
|
||||
SDK shape. *Open:* persisted-union digest granularity (blueprint O-4, B-4 checker).
|
||||
|
||||
## T6 — Change notification & subscription transports
|
||||
|
||||
**Decision.** Change-notification is an **optional adapter capability** (`notify`), and it is
|
||||
the **primary driver of incremental maintenance** (blueprint §8.7/§8.8). Transports, per
|
||||
profile: git hook / ikiwiki-style ping, ActivityPub Create/Update, webhook, WebDAV/HTTP ETag
|
||||
or `Last-Modified` poll, plain polling fallback. A notification → invalidate affected entries
|
||||
+ enqueue delta refresh + a RecentChanges union entry (FederationRequirements ADR-03; UC-31,
|
||||
UC-17). Rate-limited shards favour event-driven + long TTL (operational-envelope axis).
|
||||
|
||||
*Decided:* notify = optional capability, drives incremental + RecentChanges; transport per
|
||||
profile. *Deferred:* ActivityPub as content-bearing (vs notify-only) — start notify-only.
|
||||
*Open:* fediverse-dependency posture for v1.
|
||||
|
||||
## T7 — Information-space lifecycle
|
||||
|
||||
**Decision.** Root entities have lifecycle states: **active → read-only-archived → retired
|
||||
(detached)**, and **merged-into-successor**. **Carry-forward** is selective import from an
|
||||
archived shard (UC-28, UC-30). **Space-fork / branch** (UC-33) = branch the coordination
|
||||
journal + shard-config (a fork event, §T2/§T17 fork+journal model). Retirement **preserves
|
||||
read-only union entries** by default (history-as-floor, I-10), never hard-deletes projections.
|
||||
(UC-28, UC-30, UC-33.)
|
||||
|
||||
*Decided:* the lifecycle states + carry-forward + space-branch; retire-preserves. *Deferred:*
|
||||
ephemeral "happenings" as a first-class mode. *Open:* GC policy for retired-space derived tier.
|
||||
|
||||
## T8 — Transclusion & projection depth
|
||||
|
||||
**Decision.** Transclusion is **one reference-not-copy primitive** over the addressable union
|
||||
(blueprint §8.4), at three depths:
|
||||
|
||||
| Level | UC | Behaviour |
|
||||
|-------|-----|-----------|
|
||||
| Whole-page projection | UC-03 | lazy full page from a remote shard (replication-projection) |
|
||||
| Block/span transclusion | UC-32 | inline embed by span address, with origin + freshness |
|
||||
| Link reference | UC-08 | pointer only (ADR-06) |
|
||||
|
||||
Every transcluded artifact carries provenance + **staleness** (I-4, §8.8); live-transclusion
|
||||
fragility (link rot / remote down) degrades to last-known + an `unavailable`/`stale` marker
|
||||
(blueprint O-11). Span-level authz under transclusion = the stricter of source/host (O-10).
|
||||
Reference-not-copy unifies Xanadu transclusion, ZigZag clone, embeds, synced blocks, Trilium
|
||||
note-clone, literate named-chunk. (UC-03, UC-32.)
|
||||
|
||||
*Decided:* one primitive, three depths, provenance+staleness mandatory. *Deferred:* snapshot-
|
||||
on-import vs live default (a policy). *Open:* span-authz composition (O-10), addressing (O-6).
|
||||
|
||||
## T9 — Consensus & reconciliation policy catalog
|
||||
|
||||
**Decision.** **Detection is core, resolution is policy** (I-7, blueprint §8.6). Core always
|
||||
detects divergence and represents it as a coexisting (chorus) set; the **resolution preset** is
|
||||
configurable per space / per equivalence set:
|
||||
|
||||
- **chorus-spread** (versions coexist; default) · **designated-canonical** (explicit write
|
||||
target) · **git-merge** (where merge capability allows) · **vote-to-merge / editorial gate**
|
||||
(optional, L6-assisted) · **overlay-only** (no destructive merge on read-only sources).
|
||||
|
||||
(FederationRequirements ADR-03/ADR-05; UC-07, UC-27.)
|
||||
|
||||
*Decided:* the preset catalog; detection-core/resolution-policy. *Deferred:* vote/editorial
|
||||
gate mechanics (L6). *Open:* default preset per persona bundle (blueprint O-8).
|
||||
|
||||
## T10 — Federation-operations capability matrix
|
||||
|
||||
**Decision.** Each federation operation requires a minimum **verified capability profile**
|
||||
(TSD §A T11/§6.6); below it, the op **degrades** along the named interaction axes (blueprint
|
||||
§6.5) rather than failing. The matrix (consuming the T11 vocabulary):
|
||||
|
||||
| Federation op | Min capabilities | Degradation when absent |
|
||||
|---------------|------------------|--------------------------|
|
||||
| **read / project** | `read` | (floor — every shard) |
|
||||
| **transclude span** | `read` + addressing≥span | whole-page projection only |
|
||||
| **overlay** | `read` | always available (overlay is local) |
|
||||
| **write-through** | `write` (+ `merge` for concurrent) | → overlay/patch target |
|
||||
| **diff / 3-way merge** | `diff`,`merge` | → keep-both / chorus |
|
||||
| **notify-driven freshness** | `notify` | → validator-poll → TTL (§8.8) |
|
||||
| **native search delegate** | native-query≥index | → derived index over projection |
|
||||
| **publish / mirror** | `publish` | → read-only / static projection |
|
||||
| **fork+journal federation** | `read` + history (any) | → projection-only participant |
|
||||
|
||||
Every backend, down to the Oddmuse flat-file floor, is usable as **read-only / cache /
|
||||
projection / backup / patch target** (I-8). This matrix and the T11 spectra are kept in sync
|
||||
(it consumes that vocabulary). (UC-02–UC-07.)
|
||||
|
||||
*Decided:* the op→capability matrix + degradation paths. *Deferred:* exhaustive per-op test
|
||||
vectors → the conformance suite (§6.6). *Open:* axis-interaction completeness (blueprint O-5).
|
||||
|
||||
---
|
||||
|
||||
## T17 — Federation-model taxonomy (selectable / composable)
|
||||
|
||||
**Decision.** Federation is **plural and composable**, not one mechanism (blueprint §8.3). A
|
||||
space selects a model (composing per shard); the default is **fork+journal over Git** (the home
|
||||
case):
|
||||
|
||||
| Model | Anchor | Coordination shape | Capability floor | UCs |
|
||||
|-------|--------|--------------------|------------------|-----|
|
||||
| **Fork + journal** *(default)* | Federated Wiki | copy-with-provenance + per-page action journal (story = replay) | `read` + journal | UC-26, UC-71, UC-72 |
|
||||
| **VCS-replication + ping** | ikiwiki | git clone/pull/push + change-ping | git-IS-store | UC-31, UC-33, UC-79 |
|
||||
| **Query-time graph-join** | Wikibase `SERVICE` | join remote graphs at query, no copy | native-query≥graph | UC-74 |
|
||||
| **Feed aggregation** | RSS/Atom | inbound feed → pages | `read` | UC-03 |
|
||||
| **Activity streams** | ActivityPub | Create/Update events (notify or content) | `notify` | UC-31 |
|
||||
| **Engine-mirror** | Wiki.js DB↔Git | engine mirrors its store to git | `publish`/mirror | UC-68, UC-69 |
|
||||
|
||||
The coordination journal (T4) is the fork+journal model's home; **git IS the journal** in
|
||||
VCS-replication and engine-mirror (forge wikis make git the store *and* journal, resolving the
|
||||
engine-mirror write-race). Models compose: e.g. fork+journal locally, query-join for a
|
||||
typed-graph shard, feed-aggregation for an external source. (Mechanism over policy, I-7.)
|
||||
|
||||
*Decided:* the six models, selectable per space + composable per shard, default fork+journal.
|
||||
*Deferred:* activity-streams content-bearing mode. *Open:* multi-model interaction edge cases
|
||||
(when two models touch one shard).
|
||||
|
||||
---
|
||||
|
||||
## Consolidated decisions / deferred / open
|
||||
|
||||
- **Decided (architecture-settling):** star orchestrator (T1); overlay-default remix (T2);
|
||||
identity/placement/equivalence + chorus (T3); event-sourced journal + append authority (T4);
|
||||
server-primary incremental union (T5); notify-driven freshness (T6); space lifecycle (T7);
|
||||
reference-not-copy transclusion (T8); detection-core/resolution-policy preset catalog (T9);
|
||||
op→capability matrix (T10); selectable/composable federation models (T17).
|
||||
- **Deferred (to impl / L6 / persona bundles):** reference UI; fork-attribution format; client
|
||||
SDK; vote/editorial mechanics; ephemeral spaces; ActivityPub content-bearing; default-preset
|
||||
bundles (O-8).
|
||||
- **Open (tracked in blueprint §12):** O-1 equivalence blocking, O-4 union digest, O-5 axis
|
||||
interactions, O-6 addressing, O-8 presets, O-10 span-authz, O-11 unavailability, O-12 log
|
||||
throughput.
|
||||
|
||||
## Acceptance (SHARD-WP-0002 federation half)
|
||||
|
||||
T1–T10 + T17 each have a decision record with a Decided/Deferred/Open footer; all honour INTENT;
|
||||
UC-26–UC-33, UC-56, UC-71–UC-72, UC-74, UC-79 trace here; the adapter-contract companion is
|
||||
`spec/TechnicalSpecificationDocument.md` §A (T11–T16, T18). Conflicts with SHARD-WP-0001 are
|
||||
none (FederationRequirements ADRs are consumed, not duplicated).
|
||||
@@ -7,9 +7,10 @@ Background on document types: InfoTechPrimers on coulomb.social.
|
||||
| File | Status | Role |
|
||||
|------|--------|------|
|
||||
| `CoreArchitectureBlueprint.md` | draft for review | **Whole-system architecture** — layers, abstractions, load-bearing decisions (synthesised from all research) |
|
||||
| `FederationArchitecture.md` | draft for review | federation design — *what the union does*: T1–T10 decision records + the federation-model taxonomy (SHARD-WP-0002) |
|
||||
| `FederationRequirements.md` | draft for review | yawex-derived union/federation design notes — resolution, namespace, derived views, provenance, overlay, links (ADR-01…06; SHARD-WP-0001) |
|
||||
| `ProductRequirementsDocument.md` | draft scaffold | What the product must deliver |
|
||||
| `TechnicalSpecificationDocument.md` | draft scaffold | How the system is built |
|
||||
| `TechnicalSpecificationDocument.md` | draft + §A | How the system is built; **§A = the normative shard adapter contract** (T11–T16, T18; SHARD-WP-0002) |
|
||||
| `UseCaseCatalog.md` | draft | 84 use cases promoted from c2 + yawex + ~23-system research |
|
||||
| `ArchitectureBlueprint.md` | draft | Access, history, and identity sub-blueprint (the L0–L4 authorization ladder; referenced by CoreArchitectureBlueprint §9) |
|
||||
|
||||
|
||||
@@ -33,7 +33,134 @@ per information space.
|
||||
|
||||
## 4. Architecture References
|
||||
|
||||
- `spec/ArchitectureBlueprint.md` — access, history, identity delegation
|
||||
- `spec/CoreArchitectureBlueprint.md` — whole-system architecture (layers, the dual narrow
|
||||
waist, the 15 capability spectra, projection, consistency); the normative source for §A.
|
||||
- `spec/FederationArchitecture.md` — federation design (*what the union does*); §A is its
|
||||
companion (*what a backend must expose*).
|
||||
- `spec/FederationRequirements.md` — yawex-derived ADRs (resolution, page model, overlay).
|
||||
- `spec/ArchitectureBlueprint.md` — access, history, identity delegation (L5).
|
||||
|
||||
---
|
||||
|
||||
# A. Shard Adapter Contract (normative)
|
||||
|
||||
Deliverable of **SHARD-WP-0002** (T11–T16, T18): the versioned interface a backend implements
|
||||
to participate as a shard, and the *normative* rules core relies on. It is the **bottom narrow
|
||||
waist** (blueprint §6); the page model is the top waist (§7). This section is normative where it
|
||||
says **MUST/SHOULD**; design rationale lives in the blueprint (cited, not restated).
|
||||
|
||||
## A.1 (T11) Capability model & versioned interface
|
||||
|
||||
- The contract is a **versioned interface** (`Foswiki::Store`/`Foswiki::Meta` is the proof a
|
||||
swappable-backend-behind-a-stable-interface works). A binding declares the contract version
|
||||
it implements; core checks compatibility at registration.
|
||||
- **Operation verbs:** `read, write, diff, merge, lock, version, publish, notify,
|
||||
transclude-source, translate-syntax, structured-payload, derive-projection, execute`. The
|
||||
last two are **gated, OFF by default** (A.6/T18). Verb support is part of the profile and MUST
|
||||
reconcile with the T10 federation-ops matrix.
|
||||
- **Capability profile = a position on each capability spectrum**, not a boolean checklist. The
|
||||
full set is the **fifteen spectra** (blueprint §6.1); operationally they reduce to a **small
|
||||
orthogonal core** (substrate, write-granularity, content-opacity, operational-envelope,
|
||||
access-grant, computational/liveness) with the rest **implied** via published rules that
|
||||
**forbid impossible profiles** (blueprint §6.5). Degradation reads only the **named
|
||||
axis-interaction subset** (blueprint §6.5 table) — that table *is* the degradation contract.
|
||||
- A profile MUST express **absence** cleanly (the Oddmuse floor); core never guesses a missing
|
||||
capability.
|
||||
|
||||
## A.2 (T11/§6.6) Conformance — profiles are verified, not asserted
|
||||
|
||||
- The contract ships a **versioned conformance suite**. A binding is **admissible only if it
|
||||
passes**: the suite exercises each declared verb and spectrum position and checks observed
|
||||
behaviour matches the claim (a `write` round-trips, `notify` actually fires, an opaque shard
|
||||
refuses plaintext query, implied-position rules hold). A lying/buggy profile is **rejected at
|
||||
registration**, not run in production (blueprint §6.6).
|
||||
- Conformance makes capability-as-data (I-3) and the §6.5 degradation contract **sound**.
|
||||
Mismatch is reported as a capability-by-capability diff; an adapter may register
|
||||
*degraded-but-honest* (drop the unsupported claim).
|
||||
|
||||
## A.3 (T14) Adapter binding — attachment-mode taxonomy
|
||||
|
||||
A backend MAY offer several modes; attach mode is a **per-binding, capability-gated choice**
|
||||
with one declared authoritative (blueprint §6.3):
|
||||
|
||||
- **file-store** (native vault/folder *or* an interchange/sync mirror) · **git-IS-store** (forge
|
||||
wikis & ikiwiki — git is store *and* journal; the home case) · **in-engine-hosted** (XWiki
|
||||
component, Obsidian/Logseq/Roam plugin, Trilium script) · **local-REST** (Joplin Data API,
|
||||
Trilium ETAPI) · **external-API-only** (Notion) · **direct-DB** (MojoMojo schema→model) ·
|
||||
**CRDT-replica** (Anytype/AFFiNE/AppFlowy) · **P2P / no-central-endpoint**.
|
||||
- **Backend-swap tolerance:** identity/provenance MUST survive a substrate change (bind to
|
||||
capabilities, not "it's files"). **Boundary:** an **image / live-memory blob is never an
|
||||
attach target** (I-12) — participation is export→files only.
|
||||
- (UC-38, UC-40, UC-43, UC-50, UC-53, UC-57, UC-60, UC-62, UC-64, UC-65, UC-76, UC-79, UC-81.)
|
||||
|
||||
## A.4 (T12) Page model — structured / computational payload
|
||||
|
||||
The backend-neutral, Markdown-first page model MUST carry, without lossy flattening, every
|
||||
shape in blueprint §7.1: prose; typed/computed records (incl. effective-vs-own computed
|
||||
metadata); typed-graph statements (Wikibase); inline-embedded objects (Quip/Notion);
|
||||
non-Markdown assets (typed asset / opaque blob / content-type registry); and the **four
|
||||
computational shapes** (one-source-many-projections UC-83; notebook-with-embedded-output UC-84;
|
||||
program-as-page; live/temporal). All reduce to `(content|source, structure, provenance
|
||||
envelope, [derivation rule])`. **Identity is a stable handle; placement is separate; equivalence
|
||||
is fingerprint-based** (blueprint §7.2, FederationRequirements ADR-01/02, I-9). The **provenance
|
||||
envelope is layered** (page + span deltas; effective = page ⊕ delta, §7.3). (UC-34, UC-39,
|
||||
UC-55, UC-58, UC-54, UC-44, UC-66, UC-67, UC-73, UC-83, UC-84.)
|
||||
|
||||
## A.5 (T13) History portability — adopt / supplement / import
|
||||
|
||||
Per the history axis: **adopt** git-native history as-is; **supplement** non-portable internal
|
||||
history (DB / Notion / Joplin / Trilium revisions, CRDT-log) — the journal begins-now / mirrors
|
||||
/ snapshots; **import** open file history (RCS, PlainFile, MojoMojo DB-version-rows) backfilled
|
||||
preserving author/timestamp. **Partial/truncated history MUST be reported honestly** ("history
|
||||
begins at", UC-24), never implied complete. Embedded-output documents (notebooks) use
|
||||
paired-text (Jupytext) / cell-aware merge (nbdime). The space's own coordination history is the
|
||||
event-sourced decision log (blueprint §8.1). (UC-36, UC-41, UC-24.)
|
||||
|
||||
## A.6 (T15) Syntax translation & content fidelity
|
||||
|
||||
Translation is a spectrum: **native → lossless → lossy-with-fidelity-report**. Read native
|
||||
markup (TML, XWiki syntax, HTML) into the page model; accept Markdown overlays back via
|
||||
**lossless bidirectional translation** where possible (Foswiki WysiwygPlugin is the proof). For
|
||||
non-round-tripping models (Notion blocks, Trilium HTML, CRDT, typed-graph, notebook JSON/MIME):
|
||||
translate lossily but **make the fidelity loss visible** — a per-shard/per-page report of what
|
||||
projects cleanly vs degrades, with non-mappable elements preserved as provenance/sidecar (I-4).
|
||||
Add a **structured-re-evaluable-value** point to the opacity spectrum (Wolfram expression).
|
||||
Where no acceptable translation exists, the shard is a **read-only/projection** participant
|
||||
(I-8), never silently corrupted. (UC-42, UC-59, UC-03, UC-73.)
|
||||
|
||||
## A.7 (T16) Addressing, identity & navigation
|
||||
|
||||
- **Span addressing:** adopt native span IDs where minted (Roam `:block/uid`, Logseq `id::`,
|
||||
Notion/CRDT UUID), shard-scoped so they survive projection and don't collide; else a
|
||||
position address (path+range) or content-fingerprint address. Portable tumbler is the ideal
|
||||
(blueprint O-6).
|
||||
- **Transclusion** = one reference-not-copy primitive over the addressable union (FederationArch
|
||||
T8). **Query/navigation:** delegate to a shard's native query where capable (Datalog, DB
|
||||
query, XWQL, SPARQL), **else build a derived index over the projection** (Logseq pattern);
|
||||
dimensional/query-defined views are derived-tier. (UC-44–48, UC-51, UC-52, UC-54, UC-63,
|
||||
UC-74.)
|
||||
|
||||
## A.8 (T18) Computational / executable content capability
|
||||
|
||||
**In scope as a page-model + projection concern; out of scope as an execution platform**
|
||||
(blueprint §8.5). Core **recognises** computational types, attaches the **canonical source**,
|
||||
and presents derived forms as **provenance- and liveness-marked projections**. `derive-
|
||||
projection`/`execute` are **gated capabilities, OFF by default**, carrying a **trust/sandbox**
|
||||
concern, **degrading to a captured snapshot / static render / recording**. One snapshot-
|
||||
provenance record (run id, source rev, timestamp, environment "unguaranteed") serves notebooks,
|
||||
renders, recordings. No INTENT amendment required. (UC-54, UC-55, UC-83, UC-84.)
|
||||
|
||||
## A.9 Conformance & module mapping
|
||||
|
||||
The contract maps to `src/shard_wiki/adapters/` (the bottom waist: `AdapterContract`,
|
||||
`CapabilityProfile`, attachment-mode binding, the conformance suite) consuming `model/`
|
||||
(page model + capability value types) and `provenance/` (blueprint §11). Each concrete adapter
|
||||
ships its declared profile + a conformance pass.
|
||||
|
||||
*Decided:* A.1–A.8 (versioned capability contract, verified conformance, binding taxonomy,
|
||||
page model, history portability, translation, addressing, gated computational content).
|
||||
*Deferred:* per-backend adapter specs (one per backend, later). *Open:* blueprint §12 O-items
|
||||
(addressing O-6, axis interactions O-5, span-authz O-10).
|
||||
|
||||
## 5. Integration Boundaries
|
||||
|
||||
@@ -47,10 +174,13 @@ Package scaffold only (`__version__`, smoke tests). Domain model not yet coded.
|
||||
|
||||
## 7. Use Cases
|
||||
|
||||
`spec/UseCaseCatalog.md` — 25 use cases (UC-01–UC-25) promoted from c2 wiki
|
||||
origins and yawex prior-art research.
|
||||
`spec/UseCaseCatalog.md` — 84 use cases (UC-01–UC-84) from c2/yawex origins,
|
||||
the wiki-engine + modern-tool + computational research, and the syntheses.
|
||||
|
||||
## 8. Next Specification Work
|
||||
|
||||
Outputs from `SHARD-WP-0001` tasks (page resolution, namespaces, derived views,
|
||||
provenance, overlays, link semantics) will be incorporated here as they complete.
|
||||
The design layer is complete: `SHARD-WP-0001` (→ `FederationRequirements.md`),
|
||||
`SHARD-WP-0002` (→ `FederationArchitecture.md` + §A above), and the hardened
|
||||
`CoreArchitectureBlueprint.md`. The next workplan is the **implementation** of the
|
||||
domain model + adapter contract (starting from §A and blueprint §11's module layout),
|
||||
likely with a first spike on the keystone (the event-sourced decision log + derived fold).
|
||||
@@ -4,7 +4,7 @@ type: workplan
|
||||
title: "federation architecture design"
|
||||
domain: whynot
|
||||
repo: shard-wiki
|
||||
status: active
|
||||
status: done
|
||||
owner: tegwick
|
||||
topic_slug: whynot
|
||||
created: "2026-06-08"
|
||||
@@ -151,7 +151,7 @@ decision records only.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T1
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "ea8fdb22-6c7f-4ac1-9799-1346abf3c3b7"
|
||||
```
|
||||
@@ -175,7 +175,7 @@ agents/CLI.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T2
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "fb7d4bce-5d2e-4602-9b63-85934d90e82d"
|
||||
```
|
||||
@@ -201,7 +201,7 @@ and attribution portability vs link-only federation.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T3
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "8f2a333d-ddcc-4cc6-b6ed-1ba9b178eee3"
|
||||
```
|
||||
@@ -222,7 +222,7 @@ showing all versions vs default canonical with alternates visible.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T4
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "5f39f48d-5142-4078-a84f-3245ec1add7e"
|
||||
```
|
||||
@@ -245,7 +245,7 @@ import.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T5
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "3ff71e11-d0e9-4fda-b916-d6c34c51aa51"
|
||||
```
|
||||
@@ -266,7 +266,7 @@ composition (fedwiki resilience); cache staleness vs live-pull latency.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T6
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "9596e5e8-8d6b-4ed4-bcbc-ebb45e3168be"
|
||||
```
|
||||
@@ -289,7 +289,7 @@ infrastructure.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T7
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "38134064-51ce-4f5a-80bf-b2cfbe381c59"
|
||||
```
|
||||
@@ -310,7 +310,7 @@ read-only union entries.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T8
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "5607732b-612a-4550-bb17-b8cd34979cf4"
|
||||
```
|
||||
@@ -335,7 +335,7 @@ on import; core orchestrator support vs Markdown extension + adapter.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T9
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "adfca8b3-eb21-497d-9f51-65dc9269c810"
|
||||
```
|
||||
@@ -359,7 +359,7 @@ vs auto-merge when backends support it.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T10
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "c7a93d06-8631-43b4-bc7f-1b0a1cd1436f"
|
||||
```
|
||||
@@ -394,7 +394,7 @@ the versioned-interface-with-swappable-backends pattern** the contract should ad
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T11
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a7379621-6694-488b-94ca-846b8e27e745"
|
||||
```
|
||||
@@ -452,7 +452,7 @@ static profile vs runtime capability negotiation.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T12
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "7334a4a4-ba75-4fac-a8b4-8350d342b299"
|
||||
```
|
||||
@@ -515,7 +515,7 @@ metadata snapshot vs live computation.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T13
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "6837862a-8f57-410d-9200-a6a5dcf1a7b9"
|
||||
```
|
||||
@@ -555,7 +555,7 @@ git-native`.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T14
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "f8835969-d118-4738-952a-5e67e5209f3d"
|
||||
```
|
||||
@@ -622,7 +622,7 @@ snapshot simplicity.
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T15
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "22b57b3a-b06b-4ff0-a34a-667a0386bf25"
|
||||
```
|
||||
@@ -665,7 +665,7 @@ vs native-syntax overlays (safe round-trip); lossy-but-usable vs read-only-but-f
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T16
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "b00ca669-59d6-454a-8d6e-f34694e35192"
|
||||
```
|
||||
@@ -739,7 +739,7 @@ T1–T6); T18 is an adapter-contract concern (cross-links T11–T16).
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T17
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "529b32d2-b681-4711-82c5-5298410cfb37"
|
||||
```
|
||||
@@ -779,7 +779,7 @@ query-time join freshness vs cost; activity-streams reach vs fediverse dependenc
|
||||
|
||||
```task
|
||||
id: SHARD-WP-0002-T18
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "331c2a9b-57bb-4067-8d1f-9a3de10e2873"
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user