From 6878a0c1845007af035ab7e52229aa7d41d001ce Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 14 Jun 2026 20:59:20 +0200 Subject: [PATCH] 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 --- SCOPE.md | 4 +- research/260614-oddmuse-deep-dive/README.md | 13 ++ research/260614-oddmuse-deep-dive/findings.md | 124 ++++++++++++++++++ research/README.md | 3 +- spec/UseCaseCatalog.md | 54 +++++++- workplans/SHARD-WP-0003-engine-dives-batch.md | 2 +- 6 files changed, 194 insertions(+), 6 deletions(-) create mode 100644 research/260614-oddmuse-deep-dive/README.md create mode 100644 research/260614-oddmuse-deep-dive/findings.md diff --git a/SCOPE.md b/SCOPE.md index 2eff49d..db1b31e 100644 --- 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) diff --git a/research/260614-oddmuse-deep-dive/README.md b/research/260614-oddmuse-deep-dive/README.md new file mode 100644 index 0000000..4598e8c --- /dev/null +++ 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). diff --git a/research/260614-oddmuse-deep-dive/findings.md b/research/260614-oddmuse-deep-dive/findings.md new file mode 100644 index 0000000..e994f76 --- /dev/null +++ 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). diff --git a/research/README.md b/research/README.md index 5f2337e..41d4457 100644 --- 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 | \ No newline at end of file +| 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 | \ No newline at end of file diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md index f4ec95a..af21a2c 100644 --- 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.) \ No newline at end of file diff --git a/workplans/SHARD-WP-0003-engine-dives-batch.md b/workplans/SHARD-WP-0003-engine-dives-batch.md index 5f17f0a..ae87f3c 100644 --- 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" ```