shard-wiki/spec/FederationRequirements.md

# FederationRequirements — yawex-derived design notes

Status: **draft for review** · Date: 2026-06-15 · Deliverable of **SHARD-WP-0001**

Concrete, ADR-ready design decisions for the union/federation layer, distilled from the yawex
prior-art review (`research/260608-yawex-prior-art/findings.md`) and made **consistent with**
`spec/CoreArchitectureBlueprint.md` (the whole-system architecture) and `INTENT.md`. yawex is
*inspiration and a case checklist*, never an interface to inherit (decision 2026-06-08).

These are **requirements** (what the union must do); `spec/FederationArchitecture.md`
(SHARD-WP-0002) is the architecture that realises them. UC references are to
`spec/UseCaseCatalog.md`.

**Resolved precondition.** The yawex "minimal access model in core" thread is **settled**:
authorization-in-core / authentication-delegated, the L0–L4 ladder — INTENT amended,
`ArchitectureBlueprint.md` ratified. Auth is therefore *not* re-litigated here; these ADRs
assume it (the resolver and overlay paths run behind the L5 PEP/PDP).

---

## ADR-01 — Cross-shard page resolution

**Status:** accepted · **CoreArchitectureBlueprint:** §8.4 (union), §7.2 (identity)

**Context.** yawex's most-tested component was `PageLookUp`, a context-relative resolver with
ordered states `LOCAL, CLIMB, DROP, GLOBAL, REMOTE, SWITCH, JUMP, VIRTUAL, FAILED`. Decision
(2026-06-08): **inspiration only** — use the states as a *checklist of cases*, design the
federation resolver fresh.

**Decision.** Resolution is a pure function over the derived union:
`resolve(name, from_context, policy) → ResolutionResult`, evaluated in a defined order and
keyed on **page identity** (the stable handle), not path (I-9):

1. **Same-namespace, same-shard** exact identity match — *(yawex LOCAL)*.
2. **Namespace walk** — climb/descend ancestor namespaces of `from_context` — *(CLIMB/DROP)*.
3. **Union lookup** — match identity / alias-table entry across all attached shards — *(GLOBAL)*.
4. **Equivalence set** — if several shards hold an equivalent page, return the **chorus set**;
   the *canonical-source* policy preset (chorus / designated-canonical) decides presentation —
   never silently pick one (union without erasure, I-4). *(implicit in yawex; explicit here.)*
5. **Projection / virtual** — a page whose content lives in a remote shard (lazy replication,
   *REMOTE*) or is computed/query-defined (derivation, *VIRTUAL*).
6. **Explicit address** — a shard- or space-qualified reference resolves directly — *(SWITCH/JUMP)*.
7. **Not found** → **red-link**: a resolvable *target* with no page yet, createable (UC-23) —
   *(FAILED)*.

`ResolutionResult` carries the resolved identity (or red-link), the placement(s), the
provenance envelope (ADR-04), and — on ambiguity — the full chorus set. Resolution is a
**derived-tier read** (union graph + equivalence index, §8.4); it is incremental-maintained and
respects the L5 authz filter (a principal never resolves to content it can't see).

**Consequences.** Deterministic, policy-driven, no privileged shard; every yawex state has a
home without inheriting its structure. **Open:** cross-space `JUMP` addressing syntax ties to
the portable-address scheme (CoreArchitectureBlueprint O-6).

---

## ADR-02 — Namespace / path model & shard roles

**Status:** accepted · **CoreArchitectureBlueprint:** §7.2 (identity≠placement), §4 (shard mode)

**Context.** yawex modelled **topics as directories** (a topic's gateway page shares the dir
name) with relative (`../`) / absolute (`/`) paths and normalization, and page classes
`local / global / virtual`.

**Decision.**
- The union exposes a **namespace tree**; a **path is a placement coordinate, not an identity**
  (I-9). One identity may have **N placements** (paths/shards) → a DAG, no single canonical path.
- **Path grammar:** relative (`../`, `./`) resolved against `from_context`; absolute (`/`)
  against the space root; **normalization** (collapse `.`/`..`; case & separator handling) is a
  per-space **policy** knob (§10) — defaulting to case-preserving, `/`-separated.
- **yawex page classes → shard roles / modes:** `local → canonical`, `global → cross-cutting`
  (a shard whose pages augment/overlay across namespaces), `virtual → projected/computed`. These
  are the INTENT shard modes (read-only · write-through · mirrored · projected · cached ·
  canonical), selected by policy, constrained by the capability profile.
- Cross-shard name collisions are resolved by ADR-01's order + equivalence, not by a global
  flat namespace.

**Consequences.** The namespace is a navigable view over placements (a dimension of the union),
not a storage layout. **Open:** per-space normalization policy defaults (case-sensitivity,
unicode) — a policy preset, bundled per persona (O-8).

---

## ADR-03 — Union-level derived views: core vs adapter

**Status:** accepted · **CoreArchitectureBlueprint:** §8.4 (derived query index), §8.7
(incremental) · **resolves findings open-Q #3**

**Context.** yawex shipped BackLinks, RecentChanges, AllPages, SiteMap, full-text Search.

**Decision.** Each is a **derived-tier** view (rebuildable, incrementally maintained); classify
by where it is computed:

| View | Tier | Rationale |
|------|------|-----------|
| **BackLinks** | **core** | the link-graph over the union — squarely shard-wiki's concern (UC-18); the strongest core view |
| **RecentChanges** | **core** | merge the coordination journal (§8.1) with shard change events (notify/poll, §8.8) across the union (UC-17) |
| **AllPages / SiteMap** | **core** | an enumeration/projection of the union graph; cheap |
| **Search (full-text)** | **hybrid** | **delegate** to a shard's native search where the native-query axis allows; **else** build a derived index over projections (the Logseq DataScript-over-files pattern, UC-19/UC-63) |

All are computed in the derived tier and carry provenance; **presentation is L6 (UI)**, never
hard-coded in core (mechanism over policy, I-7).

**Consequences.** BackLinks/RecentChanges/AllPages/SiteMap are core deliverables; Search is a
capability-gated delegate-or-derive. **Open:** cross-shard search ranking/relevance is a policy
concern, not core mechanism.

---

## ADR-04 — Provenance & freshness model (concrete fields)

**Status:** accepted · **CoreArchitectureBlueprint:** §7.3 (layered provenance), §8.8 (freshness)

**Context.** yawex `Page::info` exposed modtime (and TODO'd last-editor / hits / edits). INTENT
mandates explicit provenance & freshness (I-4).

**Decision.** Concretise the **provenance envelope** (layered: page-level + span-level deltas):

```
ProvenanceEnvelope (page-level):
  source_shard         # which shard this came from
  source_rev?          # shard-native revision id, if the shard exposes one
  observed_at          # when shard-wiki last read it
  liveness             # static | captured-snapshot | live-over-files | view-time | irreducibly-live
  staleness_state      # live | fresh | stale | unavailable
  authz_context        # the L5 context under which it was read (no-leak, §9)
  overlay_state        # none | draft | patch-pending | applied
  divergence[]         # equivalence-set peers that differ (the chorus, ADR-01 step 4)
  derivation_lineage?  # for derived/derivation-projection content (source → this view)
Span-level: only the fields that differ from the page envelope (effective = page ⊕ delta).
```

`freshness = (observed_at, source_rev?, staleness_state)`; `unavailable` is the dead-shard
state (feeds ADR-03 RecentChanges and the union-under-unavailability open item O-11). This
envelope is the data behind union-without-erasure and the input to conflict display.

**Consequences.** Provenance is queryable, layered (cheap per-span), and drives views/conflict
UI. **Open / DROP:** hits/edits *analytics* are an L6/analytics concern, out of core (dropped
from the yawex feature set).

---

## ADR-05 — Overlay / lightweight-patch model

**Status:** accepted · **CoreArchitectureBlueprint:** §8.2 (overlay engine), §8.1 (decision
log), §8.6 (apply-under-drift)

**Context.** yawex had an append + threaded-comment workflow (edit a page without a full
rewrite). INTENT mandates overlay-before-mutation (I-5).

**Decision.** The overlay lifecycle for any shard below write-through capability:

1. **Draft** — an edit becomes a draft recorded as a **coordination-canonical event** in the
   space's decision log (§8.1); the unapplied overlay is the **local truth**, fully attributed
   (`overlay_state`, ADR-04).
2. **Patch / MR** — rendered in the shard's **native syntax (lossless)** or **Markdown
   (lossy-with-fidelity-report)** per the translation axis.
3. **Apply** — only on explicit intent, only where profile + policy permit, with
   **apply-under-drift** semantics (§8.6: fast-forward / three-way / refuse-and-re-present).
4. **Append / comment** = a **constrained overlay subtype** (purely additive, low-conflict) —
   the direct generalisation of yawex's workflow; safe even on the most limited shards.

This makes read-only, rate-limited, and lossy shards **editable** without silent remote
mutation (graceful degradation, I-8; no silent mutation).

**Consequences.** One overlay mechanism spans drafts, patches, MRs, and comments; storage is the
decision log (no separate store). **Open:** whether threaded-comment threading is a first-class
overlay subtype or a generic structured-append — defer to implementation.

---

## ADR-06 — Markdown link semantics (wikilink + red-link)

**Status:** accepted · **CoreArchitectureBlueprint:** §7 (page model), ADR-01 (resolution) ·
**resolves findings open-Q #2**

**Context.** yawex had CamelCase WikiLinks, `[[free links]]`, red-`?` links for nonexistent
pages, `::` labels. INTENT mandates Markdown-first; TRANSFORM the *semantics*, drop the bespoke
syntax.

**Decision.**
- Adopt a **CommonMark wikilink extension**: `[[Target]]` / `[[Target|label]]`, resolved via
  ADR-01 (by identity/name across the union).
- **Red-link** = a wikilink whose target resolves to FAILED (ADR-01 step 7): a valid,
  *createable* target with no page yet (the soft-create affordance, UC-23).
- **CamelCase auto-linking is OFF by default** (a legacy affordance); opt-in **per space** for
  migrating CamelCase wikis (UseModWiki/c2 lineage, UC-25).
- Links are stored **as text** (git-diffable; structure/links federate iff in-text).
- **Boundary (resolves open-Q #2):** the link **model + resolution is core**; the **visual
  rendering** of wikilinks/red-links is a **reference-UI (L6)** concern. Core decides *what a
  link resolves to and whether it's a red-link*; the UI decides how it looks.

**Consequences.** Markdown-first, backend-neutral, resolution-unified with ADR-01. **Open:**
cross-shard wikilink target disambiguation syntax ties to the portable-address scheme (O-6).

---

## Coverage & open questions

- **Findings open-Q #1** (per-page vs per-shard ACL) — answered by the settled access model:
  per-shard / per-namespace default, per-page ACL opt-in at L4 (`ArchitectureBlueprint.md`).
- **Findings open-Q #2** (wikilink core vs UI) — ADR-06: model/resolution core, presentation UI.
- **Findings open-Q #3** (derived views core vs adapter) — ADR-03.
- Carried to CoreArchitectureBlueprint §12: cross-space addressing syntax (O-6), namespace
  normalization presets (O-8), cross-shard search ranking (policy), union-under-unavailability
  (O-11).

## Acceptance (SHARD-WP-0001)

Each task T1–T6 has an ADR (T1→ADR-01, T2→ADR-02, T3→ADR-03, T4→ADR-04, T5→ADR-05, T6→ADR-06);
all honour INTENT (mechanism over policy, union without erasure, overlay before mutation,
capability-aware adapters) and are consistent with `CoreArchitectureBlueprint.md`. The
access-model thread is ratified (not deferred). The next implementation workplan (domain model /
adapter contract) can proceed without unresolved yawex-derived design gaps.