coulomb/shard-wiki
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

research: ikiwiki deep dive (compile-to-static, git-distributed); UC-79

Browse Source 
SHARD-WP-0003 T4. Wiki compiler: git-canonical Markdown source -> static HTML
(derived publish/projection, not the canonical store). Two new insights atop
the git-IS-store home case: compile-to-static = clean canonical-source vs
derived-output separation (attach source repo, UC-37/UC-56), and a third
federation flavor -- git replication + XML-RPC change-ping (pinger), beside
fedwiki fork/journal (UC-72) and Wikibase SERVICE (UC-74). UC-79. Enriched
UC-31/56/37/33. Marks T4 done. Feeds SHARD-WP-0002 T4/T6/T14.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-06-14 20:40:29 +02:00
parent 188643b0f5
commit ee805d5af7
6 changed files with 229 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
spec/UseCaseCatalog.md
View File

@@ -15,7 +15,8 @@ Promoted from `research/260608-c2-wiki-origins/`,
`research/260614-federated-wiki-deep-dive/`, and
`research/260614-wikibase-deep-dive/`, and
`research/260614-forge-wikis-deep-dive/`, and
`research/260614-tiddlywiki-deep-dive/`.
`research/260614-tiddlywiki-deep-dive/`, and
`research/260614-ikiwiki-deep-dive/`.
See InfoTechPrimers on coulomb.social for use-case catalog conventions.
## Conventions
@@ -197,7 +198,11 @@ concrete push transport: an engine event bus (`ObservationManager`
eventual consistency and the rate limit (`research/260614-notion-deep-dive/findings.md`
§4). **Joplin** is poll-based and turns concurrent edits into **conflict notes**
(keep-both, not silent overwrite) — conflict-as-data, links UC-07
(`research/260614-joplin-deep-dive/findings.md` §2).
(`research/260614-joplin-deep-dive/findings.md` §2). The **ikiwiki** dive details the
canonical pinger: an instance sends an **XML-RPC ping** to a peer when it changes, prompting
the peer to **pull and rebuild** — a subscribe/notify *mechanism* over a **git-distributed
mesh** (UC-79, `research/260614-ikiwiki-deep-dive/findings.md` §2), the federation flavor
beside fedwiki fork/journal (UC-72) and Wikibase `SERVICE` (UC-74).
**Priority:** Later
### UC-32 — Transclude remote span with live freshness
@@ -1075,6 +1080,23 @@ ignore the embedded engine). Feeds SHARD-WP-0002 T11 (whole-file tier), T14 (sin
`.tid` binding; cf. UC-43/UC-62).
**Priority:** Later
### UC-79 — Attach a git-backed compile-to-static wiki (source is the shard)
**Actor:** Orchestrator / adapter
**Goal:** Attach a **compile-to-static** wiki (ikiwiki) where the **git Markdown source is
the shard** and the **compiled static HTML is a derived publish/projection**; optionally
participate in **git-distributed clone federation** with change-**pings**.
**Source:** wikiengines, federation, intent
**Notes:** ikiwiki compiles a VCS-backed (git) Markdown tree to static HTML; web edits are
commits, so git is canonical and HTML is regenerable build output
(`research/260614-ikiwiki-deep-dive/findings.md` §1, §3). **Attach the source repo, never
the build output** (the static site is a projection, UC-37/UC-56). Its federation is **git
replication + an XML-RPC pinger** (notify a peer to pull/rebuild, UC-31) — a third
federation flavor beside fedwiki fork/journal (UC-72) and Wikibase `SERVICE` (UC-74). Shares
the git+Markdown adapter with forge wikis (UC-76). Feeds SHARD-WP-0002 T4 (federation), T6
(publish/projection).
**Priority:** Later
---
## B. Knowledge work and collaboration
@@ -1350,6 +1372,7 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
| UC-76 | | | | ⎇ | ✓ |
| UC-77 | | | | ⎇ | ✓ |
| UC-78 | | | | ⊡ | ✓ |
| UC-79 | | | ✓ | ⊟ | ✓ |
| UC-08 | ✓ | | |
| UC-09 | ✓ | | |
| UC-10 | ✓ | | |
@@ -1881,6 +1904,33 @@ are a real native-query tier (UC-52). **Boundary recorded:** treat the single HT
Architecture logged for `SHARD-WP-0002` (T11/T14): whole-file as the coarsest write tier,
single-file-container vs `.tid`-dir dual binding.
### ikiwiki mapping
(⊟ UC-79 lineage = the **ikiwiki deep dive**, `research/260614-ikiwiki-deep-dive/findings.md`;
marked in both federation and wikiengines columns.)
| ikiwiki mechanism (findings §) | Catalog UC |
|--------------------------------|------------|
| VCS(git)-backed Markdown source compiled to static HTML; web edits = commits (§1, §3) | UC-79 (new) |
| `pinger`/`pingee` XML-RPC = notify a peer to pull/rebuild (§2) | UC-31 (enriched) |
| Compile union/shard to a static site = outbound publish (§3) | UC-56 (enriched) |
| Static HTML = read-only regenerable backup (§3) | UC-37 (enriched) |
| Clone/pull/push between instances; wiki = git branch-space (§2) | UC-33 (enriched) |
| `aggregate` (RSS/Atom → pages) = inbound feed projection (§2) | links UC-03 |
| VCS-agnostic backend behind a plugin layer (§1) | links UC-43 |
Note: ikiwiki is a **wiki compiler** — git-canonical Markdown **source** built into **static
HTML** — so it mostly **reinforces** the git-IS-store home case (UC-76/40), but adds two
genuinely new things: **compile-to-static** as a clean *canonical-source vs derived-output*
separation (attach the **source repo**, treat static HTML as a regenerable
projection/publish target, UC-37/UC-56), and a **third federation flavor** — **git
replication + an XML-RPC change-ping** (peers hold clones, merge to reconcile, notify to
pull) beside fedwiki fork/journal (UC-72) and Wikibase `SERVICE` (UC-74). **Boundary
recorded:** never attach the build output as canonical; the pinger is a subscribe/notify
*mechanism* (peers/timing/conflict stay policy). Architecture logged for `SHARD-WP-0002`
(T4/T6/T14): git-replication+ping federation, compile-to-static publish, source-repo attach
sharing the git+Markdown adapter.
---
## Open questions
@@ -1951,5 +2001,9 @@ single-file-container vs `.tid`-dir dual binding.
26. For a **single-file wiki** (UC-78), does shard-wiki support per-page overlays by
buffering and re-serializing the whole file, or require the Node `.tid` substrate for
write-through and treat single-file as read/projection/backup only? (TiddlyWiki dive §9.)
27. For a **compile-to-static** wiki (UC-79), does shard-wiki ever *drive* the build to
**publish the union** as a static site (act as the compiler), or only attach existing
source repos — and is the **pinger** modeled as shard-wiki's own subscribe/notify
primitive or only recognized when bridging two ikiwiki instances? (ikiwiki dive §8.)
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.)