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

research: literate programming deep dive (WEB/weave/tangle); UC-83 (SHARD-WP-0004 T1)

Browse Source 
One source → N co-equal derived projections (weave=docs, tangle=code);
named-chunk transclusion; splits replication- vs derivation-projection.
Generalizes compile-to-static (UC-79). Enriches UC-32/44/79; links UC-54.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-06-14 22:43:30 +02:00
parent 2397c2c4b3
commit d4afce3699
6 changed files with 297 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
spec/UseCaseCatalog.md
View File

@@ -1056,6 +1056,32 @@ lossy export. Feeds SHARD-WP-0002 T11 (payload-format + content-opacity), T12 (i
objects), T14.
**Priority:** Later
---
### UC-83 — Attach a single-source-multiple-projection (literate) artifact
**Actor:** Orchestrator / adapter
**Goal:** Attach a **literate / woven source** (a Knuth-WEB / noweb / org-babel-style
artifact) as a shard whose canonical content is **one source** that derives **multiple
co-equal projections** (e.g. a documentation view *and* a code view), presenting each
derived form **with provenance back to the one source** and targeting edits at the source.
**Source:** wikiengines, intent
**Notes:** Literate programming is the deepest ancestor of shard-wiki's projection +
transclusion (`research/260614-literate-programming-deep-dive/findings.md`). It generalizes
**compile-to-static** (UC-79, *single* derived output) to **N co-equal, semantically
different** derivations (`weave`→docs, `tangle`→code), and its **named chunks** are
transclusion / compose-by-reference of executable fragments (UC-32, UC-44). Distinguishes
**derivation-projection** (transform/compile/weave/evaluate a source) from the default
**replication-projection** (lazy cache of remote content) — derivation-projection is
regenerable, may delegate to the source's own tool, and **degrades to a captured static
snapshot** when the tool is absent (graceful degradation). Every derived view must carry
**output→source provenance** (never present derivation without the link, union-without-
erasure). shard-wiki **recognizes and presents** such sources; it does not re-implement a
build system (driving derivation is capability-gated). Feeds SHARD-WP-0002 T12
(one-source-many-projections page shape), T16 (replication- vs derivation-projection;
named-chunk transclusion).
**Priority:** Later
## D. Addressing, identity & query
*Span / identity addressing, transclusion-as-reference, dimensional navigation, and query over the union.*
@@ -1557,6 +1583,7 @@ marker's true lineage is its per-source mapping subsection below):
| ⚓ | wiki.js | ⊞ | federated-wiki | ⬡ | wikibase |
| ⎇ | forge-wikis (Gitea/GitLab/GitHub) | ⊡ | tiddlywiki | ⊟ | ikiwiki |
| ◧ | quip | ⊙ | mojomojo | ⊚ | oddmuse (UseModWiki reinforces, no marker) |
| ⊛ | literate-programming (WEB/weave/tangle) | | | | |
| UC | c2 research | yawex research | federation research | wikiengines research | INTENT |
|----|-------------|----------------|---------------------|----------------------|--------|
@@ -1624,6 +1651,7 @@ marker's true lineage is its per-source mapping subsection below):
| UC-80 | | | | ◧ | ✓ |
| UC-81 | | | | ⊙ | ✓ |
| UC-82 | ✓ | | | ⊚ | ✓ |
| UC-83 | | | ✓⊛ | | ✓ |
| UC-08 | ✓ | | |
| UC-09 | ✓ | | |
| UC-10 | ✓ | | |
@@ -2284,6 +2312,35 @@ attach-compatible with that ancestor (flat files + CamelCase identities + partia
Architecture: a second instance of the **minimal/floor profile** (T11) and the CamelCase
identity surface (UC-25) the adapter must parse/translate.
### literate-programming mapping
(⊛ UC-83 lineage = the **literate-programming deep dive**,
`research/260614-literate-programming-deep-dive/findings.md`; design prior art, not a
candidate shard — marked in the federation/projection family column.)
| Literate-programming mechanism (findings §) | Catalog UC |
|---------------------------------------------|------------|
| One WEB source → `weave` (docs) + `tangle` (code): N co-equal derived projections (§1) | UC-83 (new) |
| Generalizes compile-to-static (single output) to many co-equal projections (§1, §5) | UC-79 (enriched) |
| Named chunks `<<name>>` = transclusion / compose-by-reference of executable fragments (§2) | UC-32 / UC-44 (enriched) |
| org-babel/knitr **evaluated** projection = computed/derivation projection (§3) | links UC-54 (→ T3 Jupyter) |
| Output→source cross-reference index = derivation provenance (§5) | links UC-24 |
Note: Literate programming (Knuth's WEB; noweb/CWEB/org-babel/Sweave/knitr/Jupytext) is the
**deepest ancestor** of shard-wiki's projection + transclusion, applied to *executable*
content. Its defining contribution is **one canonical source → multiple co-equal,
semantically different derived projections** (`weave`→human docs, `tangle`→compiler code),
which **generalizes** ikiwiki's single compile-to-static output (UC-79) and splits
projection into **replication-projection** (lazy cache — the current default) vs
**derivation-projection** (transform/compile/weave/evaluate a source). **Named chunks** are
the executable-content face of transclusion / compose-by-reference (UC-32/UC-44), resolved
by name at derivation time. **Boundary recorded:** shard-wiki *recognizes and presents*
such sources (attach the source, surface derived views with output→source provenance);
driving the derivation is **capability-gated** and **degrades to a captured static
snapshot** — never present a derivation without its source link (union-without-erasure).
Architecture logged for `SHARD-WP-0002` (T12/T16): one-source-many-projections page shape,
replication- vs derivation-projection, named-chunk transclusion.
---
## Open questions