From 1546ca09bfcea8c6219c3da427047f3c90d737e8 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 14 Jun 2026 23:45:45 +0200 Subject: [PATCH] research: Mathematica Notebooks deep dive; SHARD-WP-0004 T2 Original computational notebook (.nb = a Wolfram expression); confirms UC-84 notebook page shape is a genus. Refinements: nestable cell groups (outline tree), structured re-evaluable outputs (new opacity point). Manipulate/Dynamic = snapshot-only. Enrichment-only (UC-84/54/55). Marks T2 done. Co-Authored-By: Claude Opus 4.8 --- SCOPE.md | 2 +- .../260614-mathematica-deep-dive/README.md | 32 ++++ .../260614-mathematica-deep-dive/findings.md | 139 ++++++++++++++++++ research/README.md | 3 +- spec/UseCaseCatalog.md | 29 ++++ ...WP-0004-computational-knowledge-systems.md | 2 +- 6 files changed, 204 insertions(+), 3 deletions(-) create mode 100644 research/260614-mathematica-deep-dive/README.md create mode 100644 research/260614-mathematica-deep-dive/findings.md diff --git a/SCOPE.md b/SCOPE.md index f8230cf..ff93e51 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, T3 Jupyter, T7 Glamorous Toolkit done) | +| 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, T7 Glamorous Toolkit done) | ## In Scope (today) diff --git a/research/260614-mathematica-deep-dive/README.md b/research/260614-mathematica-deep-dive/README.md new file mode 100644 index 0000000..4eabb5e --- /dev/null +++ b/research/260614-mathematica-deep-dive/README.md @@ -0,0 +1,32 @@ +# 260614 — Mathematica Notebooks deep dive + +Date: 2026-06-14 · Source: **SHARD-WP-0004 T2** + +## What this is + +A deep dive into **Wolfram Mathematica Notebooks** — the **original computational notebook** +(1988), the ancestor Jupyter descends from. The `.nb` document **is itself a Wolfram Language +expression** (`Notebook[{Cell[…], …}]`) with **nested cell groups**, kernel evaluation +(`In`/`Out`), **structured (symbolic/graphics) results**, live `Manipulate`/`Dynamic` +widgets, and CDF as a reduced-runtime distribution projection. + +## Why it matters + +- Confirms the **notebook page shape (UC-84) is a genus**, not a Jupyter quirk: cells + + cached outputs + fragile counter provenance + kernel-gated re-execution predate `.ipynb`. +- Two refinements: notebooks have **nestable cell groups (an outline tree)**, not just an + ordered list; outputs can be **structured re-evaluable values**, not only MIME blobs → + adds a "structured re-evaluable value" point to the content-opacity spectrum. +- `Manipulate`/`Dynamic` join the **static-projection-impossible** end (snapshot-only) — + foreshadows Strudel (T5). + +## Yield + +- **No new UC** (lineage/reinforcement). Reinforces **UC-84**; enriches **UC-54, UC-55**; + links UC-34, UC-83. + +## Contents + +| Path | Role | +|------|------| +| `findings.md` | `.nb` expression/cell model, evaluation & provenance, CDF, capability delta vs Jupyter, INTENT mapping, UC disposition (enrichment-only), architecture notes | diff --git a/research/260614-mathematica-deep-dive/findings.md b/research/260614-mathematica-deep-dive/findings.md new file mode 100644 index 0000000..ea156c9 --- /dev/null +++ b/research/260614-mathematica-deep-dive/findings.md @@ -0,0 +1,139 @@ +# Mathematica Notebooks — deep dive (findings) + +**Date:** 2026-06-14 · **Source:** SHARD-WP-0004 T2 · **Subject:** Wolfram Mathematica +Notebooks — the `.nb` format, the cell/expression model, symbolic evaluation. + +## Why this dive + +Mathematica (1988) is the **original computational notebook** — the ancestor Jupyter (T3) +descends from. This dive checks whether the notebook page-model conclusions from UC-84 hold +at the genus level or need extension. It is **medium priority / lineage**: a candidate +*content type* like Jupyter, but closed/proprietary, so the expected yield is **reinforcement +of UC-84** plus a couple of distinct wrinkles (the document *is itself* a Wolfram-language +expression; symbolic, not just textual, results). + +## 1. The `.nb` document model + +A Mathematica notebook is itself a **Wolfram Language expression** — `Notebook[{Cell[...], +Cell[...], ...}, opts]`. So the document format and the language are the *same* substrate: + +- **Cells** are typed: `Input`, `Output`, `Text`, `Title`/`Section` (structure), `Code`, + with **cell groups** nesting into an **outline tree** (the document has real hierarchy, not + just a flat list like `.ipynb`). +- An **`Input` cell** holds an expression; evaluating it produces a linked **`Output` cell`** + containing the **result expression** (symbolic, graphical via `Graphics[...]`, or + typeset). The result is a **first-class expression**, not a MIME blob — it can be + re-evaluated, edited, transcluded. +- The whole `.nb` is **plain-text-serializable** (it's an expression) but verbose and + proprietary in conventions; output cells are **cached results** stored in the file. + +So like Jupyter: **source + cached computed output fused in one document**, with **out-of- +band reproducibility** (kernel + package/version state). Unlike Jupyter: **nested cell +groups (a tree)** and **results that are structured Wolfram expressions** rather than MIME +bundles. + +## 2. Evaluation, provenance, reproducibility + +- A **kernel** evaluates input cells; `In[n]`/`Out[n]` counters mirror Jupyter's + `execution_count` and carry the **same fragility** (out-of-order evaluation, hidden + symbol/global state, kernel-version dependence). No environment capture in the file. +- **Dynamic/interactive output** (`Manipulate`, `Dynamic`) embeds **live interactive + widgets** whose state is computed on view — these have **no faithful static form** beyond a + snapshot frame (echoes Strudel T5's "live, time/interaction-based content" limit). +- **CDF (Computable Document Format)** is Wolfram's *projection-for-distribution*: a notebook + rendered with a free runtime so readers can interact without a full license — a + derivation-projection (T1) with a reduced-capability viewer. + +## 3. Capability profile (delta vs Jupyter UC-84) + +| Dimension | Mathematica `.nb` (delta from Jupyter) | +|-----------|----------------------------------------| +| Structure | **nested cell groups → outline tree** (richer than `.ipynb`'s flat cell list) | +| Output type | **structured Wolfram expressions** (symbolic/graphics), not MIME blobs | +| Document = language | the `.nb` **is** a Wolfram expression (format ≡ language) | +| Liveness | `Manipulate`/`Dynamic` = **interactive widgets**, snapshot-only when static | +| Opacity | proprietary serialization; results re-evaluable only with a Wolfram kernel | +| Projection-for-distribution | **CDF** = reduced-runtime interactive projection | +| Otherwise | same as UC-84: cells, cached outputs, fragile `In/Out` provenance, kernel-gated | + +## 4. INTENT mapping + +### Reinforcements (mostly confirms UC-84) + +- **Notebook page shape (UC-84) is a genus, not a Jupyter quirk.** Mathematica predates and + matches it: cells + cached computed outputs + fragile counter provenance + kernel-gated + re-execution. Confirms the page model should carry a **notebook shape** generically (T12), + not a `.ipynb`-specific one. +- **Outputs as derivation-projection snapshots (UC-83/84).** Cached `Output` cells are + snapshots; honest treatment marks them "evaluated run N, kernel/env unguaranteed." +- **Derivation-projection for distribution (T1).** CDF is a clean "reduced-capability + interactive projection of a source" — a real-world instance of degrade-by-capability. + +### Distinct wrinkles (extend the notes, not new UCs) + +- **Nested cell-group outline** — the notebook page model should allow **hierarchical cell + grouping**, not just an ordered list (generalize UC-84's "ordered cells" to "ordered/ + *nestable* cells"). Feeds T12. +- **Structured (non-MIME) results** — outputs can be **typed structured values** (symbolic + expressions), not only MIME blobs; reinforces UC-55's "typed asset" reading over "opaque + blob," and links the typed-record page model (UC-34) — the content-opacity spectrum needs a + "structured re-evaluable value" point, not just text↔blob. +- **Format ≡ language** — a curiosity, not actionable for us beyond noting that some shards' + document format is *the same artifact* as their computation (don't assume doc/code split). +- **Live interactive widgets** — `Manipulate`/`Dynamic` join Strudel (T5) at the + **static-projection-impossible** end: capture a snapshot frame, never imply interactivity. + +### Boundaries + +- Proprietary + kernel-gated → default **read/projection/snapshot**; attach the `.nb` + (or an exported form), present cached outputs as snapshots, offer a static/CDF projection; + **no kernel host** (same rule as Jupyter UC-84, GT T7). + +## 5. UC disposition (enrichment-only — no new UC) + +| Mechanism (findings §) | Catalog UC | +|------------------------|------------| +| Cells + cached computed outputs + fragile In/Out provenance; kernel-gated (§1, §2) | UC-84 (reinforced) | +| Nested cell groups → outline tree (richer than flat `.ipynb`) (§1) | UC-84 (enriched: nestable cells); links UC-34 | +| Output = structured re-evaluable Wolfram expression, not MIME blob (§1) | UC-55 (enriched: structured value point on opacity spectrum) | +| Input cell = computation-defined content (§1) | UC-54 (enriched) | +| `Manipulate`/`Dynamic` interactive output = snapshot-only (§2) | links UC-55, foreshadows T5 | +| CDF = reduced-runtime interactive distribution projection (§2) | links UC-83 (derivation-projection) | + +Mathematica is a **lineage/reinforcement** dive — it **adds no new UC**, confirming UC-84's +notebook page shape as a genus and contributing two refinements (nestable cells; a +**structured re-evaluable value** point on the content-opacity spectrum). + +## 6. Architecture notes for SHARD-WP-0002 + +- **T12 (page model):** generalize the notebook shape from "ordered cells" (UC-84) to + **ordered/nestable cell groups (an outline tree)**; allow code-cell outputs to be **typed + structured values**, not only MIME blobs. +- **T11/T15 (content opacity / fidelity):** add a **"structured re-evaluable value"** point + to the content-opacity spectrum between transparent-text and opaque-blob (Wolfram + expression, symbolic result) — relevant to how outputs are stored/surfaced. +- **T16 (projection):** CDF is a **reduced-capability interactive projection**; with + `Manipulate`/`Dynamic`, static projection is a **snapshot frame only** (join the + live-content limit recorded for Strudel T5). + +## 7. Open questions + +1. Is a **structured re-evaluable result** (Wolfram expression) modeled as a typed value in + the page model, or stored opaquely with provenance like other computed outputs? (Ties + UC-55 open-Q #10 and UC-84 Q3.) +2. Do interactive outputs (`Manipulate`, `Dynamic`, and Jupyter widgets) deserve a shared + **"interactive, snapshot-only" content marker** in the contract? (Recurs at T4/T5.) + +## 8. Sources + +- Wolfram documentation: notebook format (`Notebook`/`Cell` expressions), cell types & + groups, evaluation (`In`/`Out`), `Manipulate`/`Dynamic`, CDF. +- prior: `research/260614-jupyter-deep-dive/` (UC-84 notebook shape; the descendant); + `research/260614-literate-programming-deep-dive/` (derivation-projection, UC-83). + +## 9. Traceability + +**No new UC** (lineage/reinforcement). Reinforced: UC-84; enriched: UC-54, UC-55; links +UC-34, UC-83. Architecture cross-refs: SHARD-WP-0002 T12 (nestable cell-group outline; typed +structured outputs), T11/T15 (structured-re-evaluable-value point on the opacity spectrum), +T16 (CDF reduced-capability projection; interactive = snapshot-only). diff --git a/research/README.md b/research/README.md index 0e85351..1347a14 100644 --- a/research/README.md +++ b/research/README.md @@ -39,4 +39,5 @@ when multiple files or sources are involved. Findings here inform `spec/` and | 2026-06-14 | `260614-usemodwiki-deep-dive/` | UseModWiki — flat-file ancestor (Wikipedia's MediaWiki Phase I); CamelCase linking; lineage grounding for the minimal file-store floor; enrichment-only (reinforces UC-82, UC-25) | | 2026-06-14 | `260614-literate-programming-deep-dive/` | Literate programming (Knuth's WEB / weave / tangle) — one source → N co-equal derived projections (docs + code); named-chunk transclusion; splits replication- vs derivation-projection; SHARD-WP-0004 T1; UC-83 | | 2026-06-14 | `260614-jupyter-deep-dive/` | Jupyter Notebooks — `.ipynb` JSON cells + embedded computed outputs with fragile execution provenance; derived output stored *inside* the source; non-Markdown/lossy; kernel = capability; SHARD-WP-0004 T3; UC-84 | -| 2026-06-14 | `260614-glamorous-toolkit-deep-dive/` | Glamorous Toolkit (moldable development on Pharo) — `gtView` open set of co-equal type-keyed computed views (none canonical) = moldable view registry; Lepiter live notebook over git files; SHARD-WP-0004 T7; enrichment-only (UC-47/48/54) | \ No newline at end of file +| 2026-06-14 | `260614-glamorous-toolkit-deep-dive/` | Glamorous Toolkit (moldable development on Pharo) — `gtView` open set of co-equal type-keyed computed views (none canonical) = moldable view registry; Lepiter live notebook over git files; SHARD-WP-0004 T7; enrichment-only (UC-47/48/54) | +| 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) | \ No newline at end of file diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md index 03fb810..7055195 100644 --- a/spec/UseCaseCatalog.md +++ b/spec/UseCaseCatalog.md @@ -2429,6 +2429,35 @@ logged for `SHARD-WP-0002` (T16/T12/T14): a moldable view registry unifying repl derivation-/dimensional-/query-projection; content types declaring their views; attach Lepiter files, not the Pharo image. +### mathematica mapping + +(Lineage dive — **no new UC**; reinforces UC-84. Source: the **Mathematica deep dive**, +`research/260614-mathematica-deep-dive/findings.md`.) + +| Mathematica mechanism (findings §) | Catalog UC | +|------------------------------------|------------| +| Cells + cached computed outputs + fragile In/Out provenance; kernel-gated (§1, §2) | UC-84 (reinforced) | +| Nested cell groups → outline tree (richer than flat `.ipynb`) (§1) | UC-84 (enriched: nestable cells); links UC-34 | +| Output = structured re-evaluable Wolfram expression, not MIME blob (§1) | UC-55 (enriched: structured-value opacity point) | +| Input cell = computation-defined content (§1) | UC-54 (enriched) | +| `Manipulate`/`Dynamic` interactive output = snapshot-only (§2) | links UC-55 (→ T5 Strudel) | +| CDF = reduced-runtime interactive distribution projection (§2) | links UC-83 | + +Note: Mathematica is the **original computational notebook** (1988) and confirms the +**notebook page shape (UC-84) is a genus**, not a Jupyter quirk — cells + cached outputs + +fragile `In`/`Out` provenance + kernel-gated re-execution all predate `.ipynb`. Two +refinements: notebooks have **nestable cell groups (an outline tree)**, not just an ordered +list (generalize UC-84's "ordered cells" to "ordered/nestable"); and outputs can be +**structured re-evaluable values** (Wolfram expressions, symbolic/graphics), adding a +**"structured re-evaluable value"** point to the content-opacity spectrum between +transparent-text and opaque-blob. `Manipulate`/`Dynamic` interactive output is **snapshot- +only** (joins the live-content limit at T5). **Boundary recorded:** proprietary + kernel- +gated → default read/projection/snapshot, **no kernel host** (same rule as Jupyter UC-84, GT +T7); attach the `.nb`/export, present cached outputs as snapshots, offer a static/CDF +projection. Architecture logged for `SHARD-WP-0002` (T12/T11/T15/T16): nestable cell-group +outline + typed structured outputs, structured-re-evaluable-value opacity point, CDF +reduced-capability projection. + --- ## Open questions diff --git a/workplans/SHARD-WP-0004-computational-knowledge-systems.md b/workplans/SHARD-WP-0004-computational-knowledge-systems.md index e162d49..66af387 100644 --- a/workplans/SHARD-WP-0004-computational-knowledge-systems.md +++ b/workplans/SHARD-WP-0004-computational-knowledge-systems.md @@ -77,7 +77,7 @@ projection model; log "source-with-multiple-projections" as a page-model pattern ```task id: SHARD-WP-0004-T2 -status: todo +status: done priority: medium state_hub_task_id: "6e46ec45-3c4a-4eb0-815d-d401d72394d5" ```