shard-wiki/research/260608-yawex-prior-art/findings.md

# Requirements seed — review of yawex prior art

Source: `research/260608-yawex-prior-art/sources/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?