research: Oddmuse deep dive (minimal single-script wiki); UC-82

SHARD-WP-0003 T7. The minimal file-store floor: one Perl CGI script over plain-text page files + a keep/ revision dir, no DB/API. Anchors the graceful-degradation baseline / minimal capability-profile floor -- every richer shard is measured against it; capability-awareness in its purest form (profile must express absence; truncated history reported honestly). UC-82. Enriched UC-40/01/36/41. Marks T7 done. Feeds SHARD-WP-0002 T11/T13. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-14 20:59:20 +02:00
parent 87f30e7c62
commit 6878a0c184
6 changed files with 194 additions and 6 deletions
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -19,9 +19,9 @@ Learnings update both SCOPE and INTENT where necessary.
 |-------|-------|
 | Code | Python package scaffold (`src/shard_wiki/`, smoke tests only) |
 | Intent | `INTENT.md` established; authorization-in-core amendments drafted |
-| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`); XWiki/TWiki/Foswiki deep dives (`research/260613-*/`); Xanadu + ZigZag + Roam + Obsidian + Notion + Joplin + Logseq + local-first workspaces (Anytype/AFFiNE/AppFlowy) + Trilium + Wiki.js + Federated Wiki + Wikibase + git-forge wikis + TiddlyWiki + ikiwiki + Quip + MojoMojo deep dives & shard-spectrum synthesis (`research/260614-*/`) |
+| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`); XWiki/TWiki/Foswiki deep dives (`research/260613-*/`); Xanadu + ZigZag + Roam + Obsidian + Notion + Joplin + Logseq + local-first workspaces (Anytype/AFFiNE/AppFlowy) + Trilium + Wiki.js + Federated Wiki + Wikibase + git-forge wikis + TiddlyWiki + ikiwiki + Quip + MojoMojo + Oddmuse deep dives & shard-spectrum synthesis (`research/260614-*/`) |
 | Demand | NetKingdom integration asks captured, not yet negotiated |
-| Spec | Architecture blueprint drafted; UseCaseCatalog 81 UCs from research; PRD/TSD scaffolds |
+| Spec | Architecture blueprint drafted; UseCaseCatalog 82 UCs from research; PRD/TSD scaffolds |
 | Work | `SHARD-WP-0001` active (6 tasks); `SHARD-WP-0002` active (16 tasks: T1–T10 federation + T11–T16 adapter contract); `SHARD-WP-0003` active (9 engine dives); `SHARD-WP-0004` active (8 computational-knowledge dives) |

 ## In Scope (today)
--- a/research/260614-oddmuse-deep-dive/README.md
+++ b/research/260614-oddmuse-deep-dive/README.md
@@ -0,0 +1,13 @@
+# 260614 — Oddmuse deep dive
+
+Deep dive on **Oddmuse**: a deliberately minimal wiki — a **single Perl CGI script** over
+**plain-text page files** (one file per page, old revisions in a `keep/` dir), no database.
+The low-complexity **file-store floor** — useful as the **minimal-adapter / graceful-
+degradation baseline** of the capability profile.
+
+- `findings.md` — the minimal model, storage layout, capability profile, INTENT mapping, UC
+  seed (UC-82), architecture notes for SHARD-WP-0002, open questions, sources, traceability.
+
+Catalog yield: UC-82 (attach a **minimal flat-file wiki** — plain-text page files + a simple
+revision dir — as the **graceful-degradation baseline / minimal capability-profile floor**).
+Enriched UC-40/01/36/41. Feeds SHARD-WP-0002 T11 (minimal capability profile).
--- a/research/260614-oddmuse-deep-dive/findings.md
+++ b/research/260614-oddmuse-deep-dive/findings.md
@@ -0,0 +1,124 @@
+# Oddmuse — deep dive (findings)
+
+**Date:** 2026-06-14 · **Source:** SHARD-WP-0003 T7 · **Subject:** Oddmuse, Alex Schroeder's
+minimal single-script wiki (EmacsWiki, Community Wiki).
+
+## Why this dive
+
+After the structure/graph/SaaS far-ends, Oddmuse anchors the **opposite** corner: the
+*minimal* file-store wiki. It is the reference for shard-wiki's **graceful-degradation**
+promise — *a limited backend must still be usable* — and defines the **floor** of the
+capability profile (T11): what the simplest possible real wiki looks like as a shard.
+
+## 1. The minimal model
+
+- **One Perl CGI script** (`wiki.pl`) is the whole engine — drop it on any CGI host. No
+  framework, no database, minimal dependencies.
+- **Plain-text page files**: each page is a text file in a **page directory** (`page/`),
+  with a small header of metadata and the body; **old revisions** are kept in a **`keep/`**
+  directory (recent history retained, older optionally expired).
+- **Locking** via lock files; edits append a new keep-revision.
+- **Markup:** simple wiki markup; **CamelCase** and **free links** `[[Like This]]`;
+  InterWiki/near-links; tags and "clusters."
+- **No DB, no API** (beyond the CGI itself); content *is* the files on disk.
+
+## 2. The shard view — the file-store floor
+
+Because pages are **plain-text files on disk**, Oddmuse is **trivially attachable** as a
+**file-store shard** even though the engine offers nothing fancy:
+
+- Read the `page/` files → pages (parse the tiny header + body).
+- Read `keep/` → recent revision history (import to the journal; note it may be **truncated**
+  — older revisions can be expired, so history is *partial*).
+- Write = write a page file + a keep-revision (respecting the lock) — but the engine's own
+  invariants (indexes) mean **write-through is best done via the engine or carefully**.
+
+This is the **minimal capability profile**: file-store, page-granularity, plain-text,
+possibly-truncated history, no query, no structured fields, open editing. Everything richer
+in the synthesis matrix is measured *against this floor*.
+
+## 3. Capability profile (the floor)
+
+| Dimension (synthesis spectrum) | Oddmuse |
+|--------------------------------|---------|
+| Attachment mode | **file-store** (plain-text files); CGI, no API |
+| Addressing granularity | page = file |
+| Content identity | page name = filename |
+| Identity vs placement | name-bound |
+| Structure | none beyond tags/clusters; flat page space |
+| History | **`keep/` revisions — recent, possibly truncated** |
+| Merge model | lock-file; last-writer |
+| Native query | none |
+| Translation | simple wiki markup (→ Markdown translation needed) |
+| Write granularity | page (file) |
+| Operational envelope | a CGI script; tiny |
+| Access grant | open by default (optional password) |
+| Content opacity | transparent text |
+| Provenance | minimal (timestamp, optional username) |
+
+## 4. INTENT mapping
+
+### Reinforcements
+
+- **Graceful degradation** (INTENT): Oddmuse is the *definition* of the limited-backend case
+  — still a perfectly good read/projection/overlay/backup shard via its files.
+- **Union without erasure**: even a minimal shard contributes pages with provenance; its
+  **truncated history** must be surfaced honestly (don't imply full history when `keep/` is
+  partial).
+- **Open wiki** (UC-01): Oddmuse is open-editing by default — the c2-era ethos.
+- **Markdown-first but backend-neutral**: its wiki markup needs translation to the
+  Markdown-first page model (UC-42-style), a small lossy step.
+
+### Divergences (boundaries / notes)
+
+- **Partial history**: `keep/` may expire old revisions — the journal import must record that
+  history is **truncated/partial**, not complete (a freshness/provenance honesty point).
+- **Minimal profile** means many capabilities are simply **absent** — the adapter advertises
+  a sparse profile; the orchestrator must not assume query/structure/locking semantics it
+  doesn't have (T11 capability-awareness in its purest form).
+
+### What to keep
+
+1. **Minimal flat-file wiki as the graceful-degradation baseline** (UC-82): plain-text files
+   + simple revision dir = the floor every richer profile extends.
+2. **Honest partial-history reporting** when a shard's revision store is truncated.
+3. **Sparse capability profile** handling — absence of a capability is first-class (T11).
+
+## 5. UC seed
+
+| # | Seed | Disposition |
+|---|------|-------------|
+| UC-82 | Attach a **minimal flat-file wiki** (plain-text page files + a simple revision dir, Oddmuse) as the **graceful-degradation baseline / minimal capability-profile floor**, surfacing **partial history** honestly | **new** |
+| — | plain-text file-store at the simple end | enrich **UC-40** |
+| — | open-editing wiki | enrich **UC-01** |
+| — | `keep/` plain-text revision history (possibly truncated) | enrich **UC-36** / **UC-41** |
+
+## 6. Architecture notes for SHARD-WP-0002
+
+- **T11 (capability model):** Oddmuse defines the **minimal/floor profile** — file-store,
+  page granularity, plain-text, **partial** history, no query/structure. Validate that the
+  capability vocabulary can express **absence** cleanly and that the orchestrator degrades
+  to read/projection/overlay/backup against it.
+- **History portability (T13):** `keep/` revisions import as journal entries but may be
+  **truncated** — record completeness as metadata (full vs partial history).
+
+## 7. Open questions
+
+1. How does shard-wiki represent a shard with **partial/truncated history** in the journal
+   and provenance UI (UC-24) — explicit "history begins at" marker?
+2. Is write-through to a minimal CGI wiki (write page + keep-revision under its lock) ever
+   sanctioned, or read/projection/overlay/backup only by default?
+
+## 8. Sources
+
+- oddmuse.org — Oddmuse wiki (single-script install, `page/` + `keep/` storage, markup,
+  CamelCase/free links, clusters/tags)
+- EmacsWiki / Community Wiki (Oddmuse in production)
+- prior: `research/260608-c2-wiki-origins/` (open-wiki ethos); `research/260613-twiki-deep-dive/`
+  (file-store + RCS contrast)
+
+## 9. Traceability
+
+New UC **UC-82** carries the marker **⊚** in the wikiengines column of
+`spec/UseCaseCatalog.md`. Enriched: UC-40, UC-01, UC-36, UC-41. Architecture cross-refs:
+SHARD-WP-0002 T11 (minimal/floor profile), T13 (partial-history import).
--- a/research/README.md
+++ b/research/README.md
@@ -34,4 +34,5 @@ when multiple files or sources are involved. Findings here inform `spec/` and
 | 2026-06-14 | `260614-tiddlywiki-deep-dive/` | TiddlyWiki — entire wiki (content + app) in one self-contained HTML file = whole-file write-granularity extreme; Node `.tid` file-per-tiddler substrate (git-diffable); tiddler/field records, filter-expression query; UC-78 |
 | 2026-06-14 | `260614-ikiwiki-deep-dive/` | ikiwiki — wiki compiler: git-canonical Markdown source → static HTML (derived publish/projection); git-distributed clone federation + XML-RPC pinger (third federation flavor); UC-79 |
 | 2026-06-14 | `260614-quip-deep-dive/` | Salesforce Quip — closed-SaaS live docs + embedded spreadsheets/live apps; REST + lossy HTML import/export; Salesforce enterprise ACL; external-API payload-format facet + inline-object page model; UC-80 |
-| 2026-06-14 | `260614-mojomojo-deep-dive/` | MojoMojo — Perl Catalyst/DBIx::Class DB-backed wiki; pages + history in SQL tables, no file store/API → direct-DB-read binding; DB version rows as history source; UC-81 |
+| 2026-06-14 | `260614-mojomojo-deep-dive/` | MojoMojo — Perl Catalyst/DBIx::Class DB-backed wiki; pages + history in SQL tables, no file store/API → direct-DB-read binding; DB version rows as history source; UC-81 |
+| 2026-06-14 | `260614-oddmuse-deep-dive/` | Oddmuse — single Perl CGI, plain-text `page/` files + `keep/` revisions, no DB; the minimal file-store floor / graceful-degradation baseline; partial-history honesty; UC-82 |
--- a/spec/UseCaseCatalog.md
+++ b/spec/UseCaseCatalog.md
@@ -18,7 +18,8 @@ Promoted from `research/260608-c2-wiki-origins/`,
 `research/260614-tiddlywiki-deep-dive/`, and
 `research/260614-ikiwiki-deep-dive/`, and
 `research/260614-quip-deep-dive/`, and
-`research/260614-mojomojo-deep-dive/`.
+`research/260614-mojomojo-deep-dive/`, and
+`research/260614-oddmuse-deep-dive/`.
 See InfoTechPrimers on coulomb.social for use-case catalog conventions.

 ## Conventions
@@ -44,7 +45,10 @@ Priority hints: **MVP** = likely early value; **Later** = important but not firs
 **Goal:** Read and write wiki pages with full history and no external dependencies.  
 **Source:** intent, c2  
 **Notes:** Ward Cunningham / c2-style open mode (`WhyWikiWorks`). Recovery via Git
-history, not gatekeeping. Aligns with L0 in `spec/ArchitectureBlueprint.md`.
+history, not gatekeeping. Aligns with L0 in `spec/ArchitectureBlueprint.md`. **Oddmuse** is
+a living minimal instance — one CGI script, open editing, plain-text files (UC-82,
+`research/260614-oddmuse-deep-dive/findings.md` §1) — the graceful-degradation floor a
+standalone open wiki can sit on.
 **Priority:** MVP

 ### UC-02 — Attach a shard to an information space
@@ -1144,6 +1148,23 @@ risks app invariants → default read/projection/overlay. Feeds SHARD-WP-0002 T1
 binding), T13.  
 **Priority:** Later

+### UC-82 — Attach a minimal flat-file wiki as the graceful-degradation baseline
+
+**Actor:** Maintainer / adapter  
+**Goal:** Attach a **minimal flat-file wiki** (plain-text page files + a simple revision
+directory, Oddmuse) as the **graceful-degradation baseline** — the **floor** of the
+capability profile — surfacing **partial/truncated history** honestly.  
+**Source:** wikiengines, c2, intent  
+**Notes:** Oddmuse is one Perl CGI script over plain-text page files (`page/`) with recent
+revisions in `keep/` (older may be expired), no DB/API
+(`research/260614-oddmuse-deep-dive/findings.md` §1, §2). The **minimal profile**:
+file-store, page granularity, plain-text, **possibly-truncated** history, no query/structure,
+open editing — every richer shard in the matrix is measured against this floor. The adapter
+advertises a **sparse profile**; the orchestrator degrades to read/projection/overlay/backup
+and must report history as **partial** when `keep/` is truncated (provenance honesty, UC-24).
+Feeds SHARD-WP-0002 T11 (minimal/floor capability profile), T13 (partial-history import).  
+**Priority:** Later
+
 ---

 ## B. Knowledge work and collaboration
@@ -1422,6 +1443,7 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | UC-79 | | | ✓ | ⊟ | ✓ |
 | UC-80 | | | | ◧ | ✓ |
 | UC-81 | | | | ⊙ | ✓ |
+| UC-82 | ✓ | | | ⊚ | ✓ |
 | UC-08 | ✓ | | |
 | UC-09 | ✓ | | |
 | UC-10 | ✓ | | |
@@ -2034,6 +2056,31 @@ is the lossy last resort. Architecture logged for `SHARD-WP-0002` (T14/T13/T11):
 binding (or external-store-via-SQL-schema sub-mode), DB-version-row history import, sparse
 "has-readable-DB" capability profile.

+### oddmuse mapping
+
+(⊚ UC-82 lineage = the **Oddmuse deep dive**, `research/260614-oddmuse-deep-dive/findings.md`;
+also marked in the c2 column for the open-wiki ethos.)
+
+| Oddmuse mechanism (findings §) | Catalog UC |
+|--------------------------------|------------|
+| Single Perl CGI; plain-text `page/` files + `keep/` revisions; no DB/API (§1, §2) | UC-82 (new) |
+| Plain-text file-store at the simple end (§2) | UC-40 (enriched) |
+| Open-editing by default (§3) | UC-01 (enriched) |
+| `keep/` plain-text revisions, possibly truncated (§2) | UC-36 / UC-41 (enriched) |
+| Sparse capability profile = absence is first-class (§3) | links UC-35 (capability-awareness) |
+| Partial/truncated history must be surfaced honestly (§4) | links UC-24 |
+
+Note: Oddmuse is the **minimal file-store floor** — one Perl CGI script over plain-text page
+files (`page/`) with recent revisions in `keep/` (older may expire), no DB and no API. It is
+the **graceful-degradation baseline** (UC-82): every richer shard in the synthesis matrix is
+measured against this floor (file-store, page granularity, plain-text, **partial** history,
+no query/structure, open editing). Its lesson for the contract is **capability-awareness in
+its purest form** — the profile must express **absence** cleanly, and **truncated history**
+must be reported honestly (history "begins at", UC-24), never implied as complete. **Boundary
+recorded:** degrade to read/projection/overlay/backup; write-through (page + keep-revision
+under the lock) only carefully. Architecture logged for `SHARD-WP-0002` (T11/T13): minimal/
+floor capability profile, partial-history import with completeness metadata.
+
 ---

 ## Open questions
@@ -2116,5 +2163,8 @@ binding (or external-store-via-SQL-schema sub-mode), DB-version-row history impo
    restrict them (schema coupling/drift, UC-43) to a best-effort mode — and is
    **write-through by direct DB** ever allowed, or are DB-backed no-API engines
    read/projection/overlay/backup only? (MojoMojo dive §7.)
+30. How does shard-wiki represent a shard with **partial/truncated history** (UC-82, Oddmuse
+    `keep/` expiry) in the journal and provenance UI — an explicit "history begins at"
+    marker / completeness metadata? (Oddmuse dive §7.)
 23. How does shard-wiki **honor/surface a shard's path-based access rules** (UC-06) in a
    projection without re-implementing its ACL engine? (Wiki.js dive §9.)
--- a/workplans/SHARD-WP-0003-engine-dives-batch.md
+++ b/workplans/SHARD-WP-0003-engine-dives-batch.md
@@ -149,7 +149,7 @@ spreadsheet/structured content), UC-36 (internal history), UC-06 (enterprise ACL

 ```task
 id: SHARD-WP-0003-T7
-status: todo
+status: done
 priority: low
 state_hub_task_id: "581e0a96-62e9-4074-86c3-c6df18b72f06"
 ```