From 3d137c96b65350a3b73c9361628f8659b3280018 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 15 Jun 2026 00:12:03 +0200 Subject: [PATCH] research: SHARD-WP-0004 synthesis (the computational page model); workplan done Consolidates the 8 computational/interactive-knowledge dives into one source/derivation/projection model on two axes (replication<->derivation, live<->snapshot); four computational page shapes; recommendation that executable content is in scope as a page-model+projection concern, out of scope as an execution platform (capability-gated, degrade to snapshot; no INTENT amendment). Flips SHARD-WP-0004 status: done. Co-Authored-By: Claude Opus 4.8 --- SCOPE.md | 2 +- .../README.md | 38 ++++ .../findings.md | 178 ++++++++++++++++++ research/README.md | 3 +- ...WP-0004-computational-knowledge-systems.md | 4 +- 5 files changed, 221 insertions(+), 4 deletions(-) create mode 100644 research/260614-computational-page-model-synthesis/README.md create mode 100644 research/260614-computational-page-model-synthesis/findings.md diff --git a/SCOPE.md b/SCOPE.md index ee013fd..9b46f89 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -22,7 +22,7 @@ Learnings update both SCOPE and INTENT where necessary. | 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 + UseModWiki deep dives & shard-spectrum synthesis (`research/260614-*/`) | | Demand | NetKingdom integration asks captured, not yet negotiated | | Spec | Architecture blueprint drafted; UseCaseCatalog 84 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` **done** (9 engine dives complete); `SHARD-WP-0004` active (8 computational-knowledge dives: T1 literate programming, T2 Mathematica, T3 Jupyter, T4 Processing, T5 Strudel, T6 Squeak + T8 Pharo (merged), T7 Glamorous Toolkit done — all 8 dives complete) | +| Work | `SHARD-WP-0001` active (6 tasks); `SHARD-WP-0002` active (16 tasks: T1–T10 federation + T11–T16 adapter contract); `SHARD-WP-0003` **done** (9 engine dives complete); `SHARD-WP-0004` **done** (all 8 computational-knowledge dives T1–T8 complete + "computational page model" synthesis) | ## In Scope (today) diff --git a/research/260614-computational-page-model-synthesis/README.md b/research/260614-computational-page-model-synthesis/README.md new file mode 100644 index 0000000..6b45ef9 --- /dev/null +++ b/research/260614-computational-page-model-synthesis/README.md @@ -0,0 +1,38 @@ +# 260614 — The computational page model (SHARD-WP-0004 synthesis) + +Date: 2026-06-15 · Source: **SHARD-WP-0004** post-batch synthesis (T1–T8) + +## What this is + +The acceptance-criteria synthesis for SHARD-WP-0004 — *"the computational page model"* — +reading the eight computational/interactive-knowledge dives across each other and distilling +them into **one model**: **source is canonical; everything rendered/computed is a +projection**, placed on **two axes** (projection-kind: replication vs derivation; liveness: +live↔snapshot), with a recommendation on an executable-content capability. + +## The answer to the carried question + +*Can a shard-wiki page be a live computational artifact?* **Yes — as a page-model + +projection concern, not as an execution platform.** Every system externalizes to a canonical +source and treats the live/computed form as derived; shard-wiki **recognizes** computational +content, **attaches the source**, and **presents derivations as provenance- and +liveness-marked projections**, with **execution as a gated capability (off by default, +degrade to snapshot)**. No INTENT amendment required. + +## Key contributions + +- **One model:** `(source, derivation rule, projection with provenance + liveness)` covers + all four computational page shapes (one-source-many-projections UC-83; notebook UC-84; + program-as-page; live/temporal content). +- **Two axes for T16:** replication vs **derivation-projection** (timing / multiplicity / + continuity facets) × the **live↔snapshot** axis (bounded at the irreducibly-live far end by + Strudel). +- **One snapshot-provenance record** reused for notebook outputs, renders, recordings. +- **Hard boundaries:** never host a kernel/runtime as store; **image-is-not-a-store**; never + present a derivation without output→source provenance. + +## Contents + +| Path | Role | +|------|------| +| `findings.md` | The source/derivation/projection model, the two axes, the four page shapes, provenance/reproducibility, the recommendation, the SHARD-WP-0002 fold-in, escalated open questions | diff --git a/research/260614-computational-page-model-synthesis/findings.md b/research/260614-computational-page-model-synthesis/findings.md new file mode 100644 index 0000000..072a904 --- /dev/null +++ b/research/260614-computational-page-model-synthesis/findings.md @@ -0,0 +1,178 @@ +# The computational page model — synthesis (SHARD-WP-0004) + +**Date:** 2026-06-15 · **Source:** SHARD-WP-0004 (post-batch synthesis, T1–T8) · **Kind:** +synthesis (no new external research) reading the eight computational/interactive-knowledge +dives *across* each other. + +## What this is + +The acceptance-criteria synthesis for SHARD-WP-0004. The batch asked one carried question: +*can a shard-wiki page be a live computational artifact — a source woven/evaluated into +rendered forms — and if so, how do projection, transclusion, provenance, and the adapter +contract treat the source, the environment, and the computed output?* This memo answers it +by distilling the eight dives into **one model**: the **source / derivation / projection** +view of computational content, anchored on two axes, plus a recommendation on whether +shard-wiki needs an executable-content capability. + +Dives consolidated: **T1** literate programming (WEB/weave/tangle), **T2** Mathematica, +**T3** Jupyter, **T4** Processing/p5.js, **T5** Strudel, **T6** Squeak, **T7** Glamorous +Toolkit, **T8** Pharo. Catalog yield: **UC-83** (literate one-source-many-projections), +**UC-84** (notebook with computed-output provenance); the other six are **enrichment/boundary** +dives (UC-54/55/47/48 + the projection model). + +## 1. The one finding: source is canonical, everything rendered is a projection + +Every system in the batch, however "live," **externalizes to a canonical artifact** and +treats the rendered/computed form as **derived**: + +| System | Canonical (attach this) | Derived (a projection) | +|--------|-------------------------|------------------------| +| Literate (WEB) | the WEB/`.nw`/`.org` **source** | woven docs **and** tangled code | +| Mathematica | the `.nb` (a Wolfram expression) | cached `Output` cells; CDF; `Dynamic` widgets | +| Jupyter | `.ipynb` source (ideally paired text) | embedded outputs; nbconvert/nbviewer renders | +| Processing | the **sketch source** | the view-time canvas render | +| Strudel | the **pattern source** | the live audio performance / a recording | +| GT / Lepiter | git-versionable **page/Tonel files** | moldable `gtView`s; live snippet results | +| Squeak/Pharo | exported **files** (Tonel/git) | the live image / running objects | + +**This is the same principle shard-wiki already holds** (files-canonical, index/render +derived — ikiwiki UC-79, Logseq UC-62, nbstripout). The computational batch did not break it; +it **stress-tested it to the live extreme and it held**. *The image (Squeak/Pharo) is the +only would-be exception, and it is a boundary, not a counterexample: an image is not a store.* + +## 2. Two axes the contract must add + +The batch refines the **projection model** (SHARD-WP-0002 T16) with two orthogonal axes: + +### 2.1 Projection kind: replication vs derivation +- **Replication-projection** (the existing default): a lazy **cache/copy** of remote content + (Obsidian/Notion mirrors, UC-53/57). +- **Derivation-projection** (new, from T1): a **transform/compile/weave/evaluate** of a + source into rendered forms — regenerable, may delegate to the source's tool, **degrades to + a captured snapshot** when the tool is absent. Covers weave/tangle, nbconvert, CDF, sketch + render, audio recording, `gtView`. + +Sub-facets of derivation (from T4): **materialization timing** = *ahead-of-time* (CDF, +nbconvert, static HTML) vs *view-time* (Processing/Strudel); **multiplicity** = one output +(UC-79) vs **N co-equal projections** (UC-83 weave+tangle; UC-47/48/54 moldable views). + +### 2.2 Liveness: the live↔snapshot axis (from T6, bounded by T5) +Every derived view sits on a spectrum, and the more live the source, the more its static form +is a clearly-marked degrading snapshot: + +``` +static source ── captured output ── live-over-files ── view-time one-shot ── continuous/ +(literate) (notebook UC-84) (GT/Lepiter) (Processing) interactive + ── irreducibly + live/temporal + (Strudel: source + + recording only) +``` + +**Honesty rule (union-without-erasure):** a computed/live view must always declare *what it +is* — "captured at run N, environment unguaranteed" (UC-84), "one performance, time T, source +rev R" (UC-83/Strudel), "live render needs the runtime." Never present a snapshot as live or a +static page as capturing a live artifact. + +## 3. The computational page-model shapes (T12) + +The batch adds these page shapes (beyond prose / typed records / query-defined / inline- +embedded objects / typed-graph already catalogued): + +1. **One-source-many-projections** (UC-83) — a source whose presented forms are co-equal + derivations (docs + code), each with output→source provenance; **named-chunk transclusion** + assembles fragments by name at derivation time (UC-32/44). +2. **Notebook** (UC-84) — **ordered/nestable cells** (Mathematica adds the outline tree) + where code cells own **embedded computed outputs** (the derived output is stored *inside* + the source) with **weak execution provenance**; outputs may be MIME blobs or **structured + re-evaluable values** (Mathematica) — a new point on the content-opacity spectrum. +3. **Program-as-page** (Processing) — canonical content = **source text**, presentation = an + **executable render** with **no cached output**; non-Markdown executable content. +4. **Live/temporal/generative content** (Strudel) — source canonical, render irreducibly + live; static = source + a marked recording. + +All four reduce to **(source, derivation rule, projection with provenance + liveness)** — one +model, four positions. + +## 4. Provenance & reproducibility (the honest weakness) + +Computed output provenance is **real but fragile** everywhere: Jupyter/Mathematica +`execution_count`/`In`-`Out` can be **out-of-order**; **environment/versions/data are not +captured**; Strudel/Processing may be **non-deterministic**. Implication for the contract: +treat a computed output as a **snapshot with declared, incomplete provenance** (run id, source +rev, timestamp; environment "unguaranteed"), reusing **one snapshot-provenance machinery** +across notebooks, recordings, and renders (UC-84 is the template). This is consistent with +shard-wiki's existing "surface freshness/completeness, never imply more than you have" +(Oddmuse partial-history UC-82). + +## 5. The recommendation + +**Does shard-wiki need an executable/computational content capability? — Yes, but only as +recognition + projection + capability-gating, never as an execution engine.** + +1. **Adopt the source/derivation/projection model** (no execution required). shard-wiki + **recognizes** computational content types (literate source, notebook, sketch, pattern), + **attaches the canonical source**, and **presents derived forms as projections with + provenance + liveness markers**. This alone delivers UC-83/UC-84 and the enrichment of + UC-54/55 — and needs **no kernel, no sandbox, no runtime**. +2. **Make execution a capability, off by default.** "Drive a derivation" (run tangle/weave, + re-execute a notebook, render a sketch, evaluate a pattern in the viewer) is a **gated + capability** with a **trust/sandbox** sub-concern (T11). Absent it, **degrade to the + captured snapshot / static render / recording** — the graceful-degradation rule, which the + batch shows always has an honest fallback (source is tiny and diffable everywhere). +3. **One projection model, two axes** (T16): projection-kind (replication vs derivation; with + timing + multiplicity facets) × liveness (live↔snapshot). The **moldable view registry** + (T7) is the unifying structure — an open, type-keyed set of co-equal projections, none + canonical-by-fact (display-canonical is policy). +4. **One snapshot-provenance record** reused for notebook outputs, renders, and recordings + (run id, source rev, timestamp, environment "unguaranteed"). +5. **Hard boundaries** (design-bugs if violated): never host a kernel/runtime as the store; + **image-is-not-a-store** (attach exported files); never present a derivation without + output→source provenance; never imply a static view captures a live artifact. + +**Net:** computational content is **in scope as a page-model + projection concern**, **out of +scope as an execution platform** — exactly the mechanism-over-policy, capability-aware, +degradable posture INTENT already mandates. No INTENT amendment is required; this extends the +page model and projection model within existing constraints. + +## 6. Fold into SHARD-WP-0002 + +- **T12 (page model):** add the four computational shapes (§3); allow nestable cells and + structured re-evaluable outputs; "derived output may live inside the source" (notebook). +- **T16 (projection):** the **two-axis model** (§2) + the **moldable view registry** (§3/T7); + materialization-timing, multiplicity, continuity, and the live↔snapshot far end as explicit + projection metadata. +- **T11 (capabilities):** "derive/execute/render/evaluate" as gated capabilities with trust/ + sandbox; default off → snapshot. +- **T15 (fidelity):** non-Markdown executable/computed content; lossy renders; the + structured-re-evaluable-value point on the content-opacity spectrum. +- **T13 (history):** paired-text (Jupytext) / cell-aware (nbdime) strategies for embedded- + output documents; outputs-as-derived (nbstripout ethos). +- **T14 (binding):** **image-is-not-a-store** boundary (export→files only). + +## 7. Open questions (escalated) + +1. Is **liveness** (and "irreducibly live / no faithful static form") an explicit first-class + metadata flag on every projection, so the union renders the honest fallback automatically? + (T5/T6 far-end question.) +2. Does shard-wiki **ever drive a derivation** (sandboxed), or strictly attach + present + snapshots? (Recurs UC-56/UC-83/UC-84/T4/T5 — a single capability/trust policy decision.) +3. Is a computed output's **structured re-evaluable value** (Mathematica/Wolfram) modeled as a + typed value or stored opaquely with provenance? (UC-55 open-Q #10; UC-84 Q3.) +4. Should **UC-83** and **UC-84** eventually merge as two positions of one "source + + derivations" shape, or stay distinct? (Kept distinct: UC-84's defining trait is *output + embedded in source with weak provenance*; UC-83's is *N co-equal external derivations*.) + +## 8. Sources + +The eight SHARD-WP-0004 dives: `research/260614-{literate-programming,mathematica,jupyter, +processing,strudel,squeak-pharo,glamorous-toolkit}-deep-dive/`. Prior projection/structure +anchors: `research/260614-{ikiwiki,logseq,zigzag}-deep-dive/`, +`research/260614-shard-spectrum-synthesis/`. + +## 9. Traceability + +No new UC (consolidation). Consolidates **UC-83, UC-84** and enrichments to **UC-32, UC-44, +UC-47, UC-48, UC-54, UC-55, UC-79, UC-37, UC-35**. Feeds **SHARD-WP-0002 T11/T12/T13/T14/T15/ +T16** (see §6). Recommendation: computational content is **in scope as page-model + projection +mechanism, out of scope as an execution platform**; no INTENT amendment required. diff --git a/research/README.md b/research/README.md index deda23d..e05b87f 100644 --- a/research/README.md +++ b/research/README.md @@ -43,4 +43,5 @@ when multiple files or sources are involved. Findings here inform `spec/` and | 2026-06-14 | `260614-mathematica-deep-dive/` | Mathematica Notebooks — the original computational notebook (`.nb` = a Wolfram expression); nestable cell groups, structured re-evaluable outputs, `Manipulate` live widgets, CDF; confirms UC-84 notebook shape is a genus; SHARD-WP-0004 T2; enrichment-only (reinforces UC-84; UC-54/55) | | 2026-06-14 | `260614-squeak-pharo-deep-dive/` | Squeak & Pharo (image-based Smalltalk) — the live-object image (purest "live" end); image-is-not-a-store boundary (export→files only); Pharo Tonel/Iceberg externalizes code to git text; names the live↔snapshot projection axis; SHARD-WP-0004 **T6 + T8** (merged); boundary/enrichment-only, no new UC | | 2026-06-14 | `260614-processing-deep-dive/` | Processing / p5.js — program-as-page rendered live at view time (no cached output); adds materialization-timing + continuity facets to projection; execute-in-viewer = capability+trust; SHARD-WP-0004 T4; enrichment-only (UC-54/55) | -| 2026-06-14 | `260614-strudel-deep-dive/` | Strudel.cc (TidalCycles JS) live-coding REPL — code as live time-based audio performance; the far live end (no faithful static form; static = source + marked recording); honesty test for graceful degradation; SHARD-WP-0004 T5; enrichment-only (UC-54/55) | \ No newline at end of file +| 2026-06-14 | `260614-strudel-deep-dive/` | Strudel.cc (TidalCycles JS) live-coding REPL — code as live time-based audio performance; the far live end (no faithful static form; static = source + marked recording); honesty test for graceful degradation; SHARD-WP-0004 T5; enrichment-only (UC-54/55) | +| 2026-06-15 | `260614-computational-page-model-synthesis/` | **SHARD-WP-0004 synthesis** — *the computational page model*: source canonical / everything rendered is a projection; two axes (replication↔derivation, live↔snapshot); four computational page shapes; recommendation — executable content in scope as page-model+projection, out of scope as an execution platform (no INTENT amendment); feeds SHARD-WP-0002 T11–T16 | \ No newline at end of file diff --git a/workplans/SHARD-WP-0004-computational-knowledge-systems.md b/workplans/SHARD-WP-0004-computational-knowledge-systems.md index 0b79483..e983c1c 100644 --- a/workplans/SHARD-WP-0004-computational-knowledge-systems.md +++ b/workplans/SHARD-WP-0004-computational-knowledge-systems.md @@ -4,11 +4,11 @@ type: workplan title: "computational / interactive-knowledge systems research" domain: whynot repo: shard-wiki -status: active +status: done owner: tegwick topic_slug: whynot created: "2026-06-14" -updated: "2026-06-14" +updated: "2026-06-15" state_hub_workstream_id: "5fc3911a-1c68-4826-bbd2-b892dec8f981" ---