From fe731081d0e853339c36900711c3db618b582ddd Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 8 Jun 2026 09:31:48 +0200 Subject: [PATCH] Add requirements seed from yawex prior-art review Distill the yawex-0.7.4 Perl wiki engine into shard-wiki requirements: KEEP federation-relevant ideas (page-resolution state space as inspiration, namespace hierarchy, page/shard roles, derived views, provenance, blueprints, overlay/append, multi-shard config), TRANSFORM markup to CommonMark + wikilink extension, DROP engine/era artifacts. Flags a contested decision: a minimal access model in core revises an INTENT non-goal and needs an INTENT amendment. Co-Authored-By: Claude Opus 4.8 --- docs/requirements-from-yawex.md | 103 ++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/requirements-from-yawex.md diff --git a/docs/requirements-from-yawex.md b/docs/requirements-from-yawex.md new file mode 100644 index 0000000..dcd8c0b --- /dev/null +++ b/docs/requirements-from-yawex.md @@ -0,0 +1,103 @@ +# Requirements seed — review of yawex prior art + +Source: `history/priorart/yawex-0.7.4/` — a filesystem-backed CGI/Perl wiki engine +(2004–2005, "Yet Another Wiki engine eXtended"). This document distills that prior +art into requirements for `shard-wiki`, the Markdown-first, Git-backed wiki +**federation/orchestration layer** described in `INTENT.md`. + +Each item is tagged **KEEP** (adopt the idea), **TRANSFORM** (keep the intent, change +the mechanism), or **DROP** (engine/era artifact or INTENT non-goal). Decisions below +reflect a review discussion on 2026-06-08. + +--- + +## Orientation: what yawex was + +- Pages = plain files on disk. **Topics = directories.** A topic's "gateway" page + shares the directory name (`SubContext/SubContext`). +- One CGI/Perl binary did everything: routing, page resolution, markup rendering, + auth, templating, storage. +- The most-developed and most-tested component is **`PageLookUp`** — a context-relative + page-resolution state machine. It is the part most worth mining. + +--- + +## KEEP — ideas that prefigure federation + +- **Page-resolution state space.** yawex resolved a requested name from a current page + through ordered states: `LOCAL, CLIMB, DROP, GLOBAL, REMOTE, SWITCH, JUMP, VIRTUAL, + FAILED`. Two states foreshadow federation directly: + - `REMOTE` — "jump to pages in a remote wiki" → a **remote shard**. + - `VIRTUAL` — "process locally but get content elsewhere" → a **projection / cache**. + - **Decision (2026-06-08): _inspiration only_.** Do NOT inherit yawex's structure as + the resolve contract. Design shard-wiki resolution fresh for the federation case; + treat these states as prior art and a checklist of cases the new resolver must + handle, not as the interface. +- **Topic = namespace hierarchy** with relative (`../`) and absolute (`/`) paths, plus + path normalization. Becomes the union path/namespace model across shards. +- **Page classes (local / global / virtual).** Map to **shard roles** + (canonical / cross-cutting / projected-computed). +- **Derived/computed views**: BackLinks, RecentChanges, AllPages, SiteMap, full-text + Search. Natural **union-level views** over the federated page graph; BackLinks + (link-graph) is squarely shard-wiki's concern. +- **Provenance hooks.** `Page::info` exposed modtime and TODO'd last-editor/hits/edits. + Serves INTENT's explicit-provenance-and-freshness principle. +- **Blueprint pages** — create-from-template, duplicating topic structure. A + page/topic templating primitive. +- **Append/comment workflow** — add to a page without a full edit. Maps to the + **overlay / lightweight-patch** model for shards you don't fully own. +- **Multi-wiki config** (`Conf::TestWiki / FriendsWiki / ManusysWiki`). Literally + multiple distinct wikis with their own storage/identity = **multiple shards/roots**. + +## TRANSFORM — keep intent, change mechanism + +- **Markup → CommonMark + extension.** yawex had CamelCase WikiLinks, `[[free links]]`, + red-`?` links for nonexistent pages, `::` labels, `**bold**`. Keep the *semantics* + (auto-link, link-to-nonexistent) as a wikilink/red-link Markdown extension; drop the + bespoke syntax. INTENT mandates Markdown-first. +- **Backup-on-write → Git history.** The `page~` rename hack becomes Git commits. Keep + the recoverability intent. +- **Render pipeline → mostly out of scope.** The chunk+line renderer is engine/UI work. + Keep only the **link-resolution / normalization** slice that federation needs. + +## DROP — engine/era artifacts and non-goals + +- CGI/Perl runtime, Makefile install, `eval("action_$x")`, shell-outs (`rm`, `htpasswd`, + `echo >`), `umask 0000`, `fatalsToBrowser` — implementation and security debt. +- JS editor toolbar / textarea editor — UI layer; INTENT decouples UI from storage. +- Form chunks (`Formular` + KEY= data store) and Blog chunks — app-specific page + semantics that INTENT says core must not own. + +--- + +## Contested decision: a minimal access model IN CORE + +yawex coupled identity and permissions into the engine: Apache/htpasswd auth, a members +file, self-registration with auto-created user pages, and per-topic `AccessControl` files +with levels `denied / view / form / edit / admin`. + +INTENT.md currently lists this as a **non-goal**: *"Solve organizational permissions, +identity management, or secret storage by itself."* + +**Decision (2026-06-08): shard-wiki WILL own _some_ auth in core** — a deliberate +revision of that non-goal. Proposed tight scope so it doesn't become an identity system: + +- **In scope:** a thin, pluggable **authorization gate** expressed as capabilities — + who may read / write / patch / merge a given page or shard — layered on top of the + per-adapter capability model (read/write/diff/merge/lock/publish). +- **Out of scope (still):** credential storage, organizational identity management, user + directories. Identity is supplied by a pluggable provider; shard-wiki authorizes, it + does not authenticate-from-scratch or store secrets. + +> ⚠️ **This revises an INTENT non-goal and therefore needs an INTENT amendment plus a +> ratified decision** (per INTENT's Stability Note, redefining scope is an architectural +> change). Tracked as an open decision; do not treat the access model as settled until +> INTENT is updated. + +--- + +## Open questions for the next pass + +1. Exact boundary of "some auth in core" — is per-page ACL in scope, or only per-shard? +2. Does the wikilink/red-link extension belong in shard-wiki core, or in a reference UI? +3. Which derived views (BackLinks / RecentChanges / Search) are core vs. adapter-provided?