shard-wiki/spec/TechnicalSpecificationDocument.md

TechnicalSpecificationDocument

Status: draft scaffold · Date: 2026-06-08

See InfoTechPrimers on coulomb.social for TSD conventions.

1. System Overview

Python package (src/shard_wiki/) implementing a federation orchestration layer. Markdown-first, backend-neutral page model. Git-addressable coordination per information space.

2. Implementation Stack

Concern	Choice
Language	Python ≥ 3.11
Layout	src/ package, hatchling build
Tests	pytest
Lint/format	ruff

3. Core Abstractions (to be specified)

Abstraction	Description
Shard	Independently meaningful page store with sovereignty
Root entity	Joined information space shards attach to
Shard adapter contract	Versioned, capability-aware backend interface
Wiki page model	Paths, links, metadata, revisions
Projection	Lazy local view of remote content
Overlay	Non-destructive edit before remote mutation
Coordination journal	Git-backed change record

4. Architecture References

• 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

• Authentication delegated to external identity provider (reference: net-kingdom + user-engine). See demand/260608-netkingdom-integration-requirements.md.
• No credential or secret storage in shard-wiki core.

6. Current Implementation

Package scaffold only (__version__, smoke tests). Domain model not yet coded.

7. Use Cases

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

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).