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