shard-wiki/research/260614-oddmuse-deep-dive/findings.md

# 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).