generated from coulomb/repo-seed
tegwick
d65f9e21f3
Adds the normative Shard Adapter Contract as TechnicalSpecificationDocument §A: A.1 versioned capability contract (verbs + orthogonal-core spectra), A.2 verified conformance suite (profiles not self-asserted), A.3 attachment-mode taxonomy + image-is-not-a-store boundary, A.4 page model (incl. computational shapes, identity/placement/equivalence, layered provenance), A.5 history portability, A.6 syntax translation + fidelity report, A.7 addressing/navigation, A.8 gated computational content. Updates TSD references/UC-count/next-work. Flips all 18 WP-0002 tasks + workplan done. Design layer complete. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
186 lines
10 KiB
Markdown
186 lines
10 KiB
Markdown
# 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). |