shard-wiki/docs/requirements-from-yawex.md

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?