generated from coulomb/repo-seed
tegwick
a2f15806f5
Delivers spec/FederationRequirements.md — six ADR-ready design notes mapping the yawex prior art onto the hardened CoreArchitectureBlueprint: ADR-01 cross-shard resolution (yawex PageLookUp states as a checklist, keyed on identity), ADR-02 namespace/path + shard roles (path=placement not identity), ADR-03 derived views core-vs-adapter (BackLinks/RecentChanges/AllPages/SiteMap core, Search hybrid), ADR-04 concrete provenance envelope fields, ADR-05 overlay/ patch/append lifecycle, ADR-06 wikilink+red-link extension (model core, render UI). Resolves findings open-Qs #1-#3; access-model thread ratified. Flips WP-0001 done. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
120 lines
3.6 KiB
Markdown
120 lines
3.6 KiB
Markdown
---
|
||
id: SHARD-WP-0001
|
||
type: workplan
|
||
title: "shard-wiki requirements from yawex prior art"
|
||
domain: whynot
|
||
repo: shard-wiki
|
||
status: done
|
||
owner: tegwick
|
||
topic_slug: whynot
|
||
created: "2026-06-08"
|
||
updated: "2026-06-15"
|
||
state_hub_workstream_id: "0ed023a2-760b-4990-b931-8ee1f41ea08f"
|
||
---
|
||
|
||
# SHARD-WP-0001 — shard-wiki requirements from yawex prior art
|
||
|
||
## Goal
|
||
|
||
Turn the yawex (2004–05 Perl wiki engine) prior-art review into shard-wiki
|
||
requirements and design decisions. Produce federation-relevant specifications
|
||
that map onto `INTENT.md` without inheriting yawex's monolithic engine shape.
|
||
|
||
## Context
|
||
|
||
- Prior art: `research/260608-yawex-prior-art/sources/yawex-0.7.4/`
|
||
- Research findings: `research/260608-yawex-prior-art/findings.md`
|
||
- Architecture: `spec/ArchitectureBlueprint.md`
|
||
- Inbound demand: `demand/260608-netkingdom-integration-requirements.md`
|
||
|
||
Open architectural thread: a minimal authorization model in core revises an
|
||
INTENT non-goal and needs a ratified INTENT amendment before the access model
|
||
is treated as settled.
|
||
|
||
## Design federation page-resolution model
|
||
|
||
```task
|
||
id: SHARD-WP-0001-T1
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "ebc036e4-1c3c-4e39-959b-1e37bc1049ad"
|
||
```
|
||
|
||
Design shard-wiki's cross-shard name resolution fresh. Use yawex's
|
||
LOCAL/CLIMB/DROP/GLOBAL/REMOTE/SWITCH/JUMP/VIRTUAL/FAILED states as a checklist
|
||
of cases to handle (especially REMOTE for remote shards and VIRTUAL for
|
||
projections), not as the interface. Decision 2026-06-08: inspiration only.
|
||
|
||
## Define namespace/path model and page+shard roles
|
||
|
||
```task
|
||
id: SHARD-WP-0001-T2
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "431b4d28-3768-468f-b76f-4767f5aa1888"
|
||
```
|
||
|
||
Union path/namespace model with relative/absolute paths and normalization (from
|
||
yawex topics-as-dirs). Map page classes local/global/virtual to shard roles
|
||
canonical/cross-cutting/projected-computed.
|
||
|
||
## Specify union-level derived views
|
||
|
||
```task
|
||
id: SHARD-WP-0001-T3
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "564545ec-84f7-4c3d-a779-5b9c356919f4"
|
||
```
|
||
|
||
Decide which derived views are core vs adapter-provided: BackLinks,
|
||
RecentChanges, AllPages, SiteMap, Search. BackLinks (link-graph over the
|
||
federated union) is the strongest core candidate.
|
||
|
||
## Provenance and freshness model
|
||
|
||
```task
|
||
id: SHARD-WP-0001-T4
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "738326f5-b76c-4ecf-8843-7c762c3647d8"
|
||
```
|
||
|
||
Generalize yawex Page::info (modtime, TODO lasteditor/hits/edits) into
|
||
INTENT's explicit provenance: source shard, freshness, cached?, has-overlay?,
|
||
diverges-from?.
|
||
|
||
## Overlay / lightweight-patch model
|
||
|
||
```task
|
||
id: SHARD-WP-0001-T5
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "a268de6a-d1ef-4ed9-9828-c70991e1a772"
|
||
```
|
||
|
||
Non-destructive edits against remote/read-only shards as drafts/patches/overlays
|
||
before mutation (INTENT: overlay-before-mutation). Seeded by yawex's append +
|
||
threaded-comment workflow.
|
||
|
||
## Markdown link semantics
|
||
|
||
```task
|
||
id: SHARD-WP-0001-T6
|
||
status: done
|
||
priority: low
|
||
state_hub_task_id: "a7499f3e-911c-455b-afc3-eefc401eb60d"
|
||
```
|
||
|
||
TRANSFORM yawex CamelCase/[[free]]/red-? links into a CommonMark wikilink +
|
||
red-link extension. Open question: core vs reference-UI concern.
|
||
|
||
## Acceptance criteria
|
||
|
||
- Each task produces a written spec or ADR-ready design note in `spec/`.
|
||
- Designs honor INTENT boundaries: mechanism over policy, union without erasure,
|
||
overlay before mutation, capability-aware adapters.
|
||
- Access-model and NetKingdom integration drafts are either ratified or explicitly
|
||
deferred with tracked open questions.
|
||
- The next implementation workplan (domain model / adapter contract) can start
|
||
without unresolved yawex-derived design gaps. |