shard-wiki/research/260614-mathematica-deep-dive/findings.md

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