SPB Git

Repository Public

SHEET_SCHEMA.md 27.2 KB 522 lines markdown

1# Sheet Document Schema — version 123A sheet is one JSON value. It is the single contract between the editor, the AI pipeline, the renderer, the exporters and the database. It contains no HTML, no CSS and no script: everything a sheet can show is one of the block types below.45Source of truth: `src/schema/sheet.ts` (Zod schemas) and `src/schema/index.ts` (parsing, migration, patches, diff). This file is a reading aid; where it and the code disagree, the code is right.67Every object is **strict**: an unknown key is a validation error. "Default" means the key may be omitted in input and is filled in by parsing. Lengths are in characters.89## 1. Top level1011| Field | Type | Default | Constraints |12|---|---|---|---|13| `schemaVersion` | `1` | — | required; older values are migrated first |14| `metadata` | object | — | see below |15| `theme` | `{ preset, accent }` | `scientific-light`, `blue` | preset: a theme; accent: a tone |16| `layout` | `{ type, format, maxWidth }` | `responsive-document`, `article`, `1120` | `maxWidth` 640–1440 (article only) |17| `blocks` | Block[] | — | ≤ 80 top-level blocks |18| `sources` | Source[] | `[]` | ≤ 60 |19| `claims` | Claim[] | `[]` | ≤ 60 |20| `assets` | AssetRef[] | `[]` | ≤ 40 |21| `interactions` | `[]` | `[]` | must be empty; reserved for a later version |2223Document-level rules checked after the shapes:2425- block ids are unique across the whole document, tab contents included;26- source ids are unique;27- every `sourceIds` entry of a block or claim names an existing source;28- an `image` block's `assetRef` and a chart's `datasetRef` name an entry of `assets`;29- a claim's `blockId` names an existing block.3031### `metadata`3233| Field | Type | Default | Constraints |34|---|---|---|---|35| `title` | text | — | 1–160 |36| `slug` | string | — | optional proposal, kebab-case, ≤ 96; the public slug lives on the sheet row |37| `author` | `"Simon-Pierre Boucher"` | that value | a literal; no other value validates |38| `locale` | `fr` \| `en` | — | cannot change once the sheet exists |39| `summary` | text | `""` | ≤ 400 |40| `topics` | text[] | `[]` | ≤ 6, each 1–60 |41| `tags` | text[] | `[]` | ≤ 12, each 1–40 |42| `level` | `beginner` \| `intermediate` \| `advanced` | `intermediate` | |43| `kind` | `explainer` \| `cheatsheet` \| `comparison` \| `architecture` \| `method` \| `case-study` | `explainer` | |44| `objectives` | text[] | `[]` | ≤ 6, each 1–300 |45| `example` | boolean | — | optional; shows the "unreviewed example" banner |4647## 2. Vocabulary4849**Ids** — `^[a-z0-9][a-z0-9-]{0,47}$`: lower-case letters, digits and dashes, 1–48 characters. `newId(prefix)` generates `<prefix>-<8 hex digits>`.5051**Tones** — semantic colours; the theme decides the actual values: `neutral`, `blue`, `teal`, `green`, `amber`, `red`, `violet`, `pink`.5253**Icons** — a fixed set drawn in `src/renderer/icons.tsx`: `brain`, `layers`, `route`, `database`, `server`, `cpu`, `cloud`, `network`, `search`, `filter`, `document`, `code`, `chart`, `trend`, `sigma`, `function`, `clock`, `bolt`, `lock`, `key`, `shield`, `users`, `user`, `globe`, `flask`, `atom`, `book`, `target`, `check`, `cross`, `warning`, `info`, `scale`, `coins`, `bank`, `cube`, `gear`, `arrows`, `split`, `merge`, `token`, `memory`, `queue`, `table`, `eye`, `sparkles`, `puzzle`, `microscope`, `calculator`, `link`.5455**Themes** — `scientific-light`, `scientific-dark`, `editorial`, `blueprint`, `finance`.5657**Formats**5859| Format | Width × height (CSS px) | Safe margin | Behaviour |60|---|---|---|---|61| `article` | 1120 × fluid | 24 | responsive document; `layout.maxWidth` applies |62| `a4` | 794 × 1123 | 48 | fixed canvas |63| `slide-16-9` | 1600 × 900 | 56 | fixed canvas |64| `square` | 1080 × 1080 | 48 | fixed canvas |65| `portrait-4-5` | 1080 × 1350 | 48 | fixed canvas |6667**Data kinds** — the nature of the numbers a chart or matrix shows, printed with the figure: `empirical` (real observations; the quality report requires a source), `synthetic` (generated by a stated process), `illustrative` (hand-chosen values that show a shape).6869**URLs** — `https:` or `mailto:` only, ≤ 2 000 characters.7071## 3. Inline syntax7273Text fields accept a small Markdown subset, parsed by `src/renderer/inline.tsx`. Nothing else is interpreted; raw HTML is shown as text.7475| Syntax | Result | Notes |76|---|---|---|77| `**bold**` | bold | must not start or end with a space |78| `*italic*` | italic | same |79| `` `code` `` | inline code | no nesting inside |80| `$x^2$` | inline LaTeX (KaTeX) | the opening `$` is followed by a non-space and the closing `$` is preceded by one, so "5 $ and 10 $" stays text |81| `[label](https://…)` | link | `https:` or `mailto:` only; other targets stay text; links do not nest; label ≤ 300, target ≤ 2 000 |82| `[^source-id]` | numbered citation linking to the references block | renders nothing if the source does not exist (and the quality report raises an error) |83| `\*`, `` \` ``, `\$`, `\[`, `\]`, `\\` | the literal character | |8485Nesting depth is limited to 4. Labels drawn inside SVG (diagram nodes, chart axes) use the plain text of the string.8687KaTeX runs with `trust: false`, `strict: "ignore"`, `maxExpand: 1000`.8889## 4. Blocks9091### Fields common to every block9293| Field | Type | Default | Meaning |94|---|---|---|---|95| `id` | Id | — | unique in the document |96| `type` | string | — | discriminator |97| `span` | `3` \| `4` \| `6` \| `8` \| `12` | `12` | width on the 12-column desktop grid; below 768 px of sheet width every block is full width, in document order |98| `alt` | text ≤ 600 | — | text alternative; required by the quality report on `diagram`, `chart`, `matrix`, `svg`, `image` (error) and `simulation` (warning) |99| `sourceIds` | Id[] ≤ 12 | — | sources shown under the block |100| `locked` | boolean | — | cannot be moved or deleted in the editor; never touched by AI edits |101102The tables below list the type-specific fields.103104### `heading`105106| Field | Type | Default | Constraints |107|---|---|---|---|108| `level` | `1` \| `2` \| `3` | — | the first level-1 heading is the page's `h1`; others render as `h2` |109| `text` | text | — | 1–200 |110| `eyebrow` | text | — | ≤ 80 |111112### `paragraph`113114| Field | Type | Default | Constraints |115|---|---|---|---|116| `text` | text | — | 1–4 000 |117| `lead` | boolean | — | lead paragraph styling |118119### `list`120121| Field | Type | Default | Constraints |122|---|---|---|---|123| `style` | `bullet` \| `number` \| `check` | — | |124| `items` | text[] | — | 1–30 items, each 1–800 |125126### `equation`127128| Field | Type | Default | Constraints |129|---|---|---|---|130| `latex` | string | — | 1–2 000; display LaTeX; syntax checked by the quality report |131| `label` | text | — | ≤ 80 |132| `explanation` | text | — | ≤ 1 200 |133| `variables` | `{ symbol, meaning, unit? }[]` | — | ≤ 20; `symbol` 1–120 (LaTeX), `meaning` 1–300, `unit` ≤ 60 |134| `derivation` | `standard` \| `derived` \| `unverified` | `standard` | `unverified` is flagged to the reader |135136### `callout`137138| Field | Type | Default | Constraints |139|---|---|---|---|140| `tone` | `note` \| `tip` \| `warning` \| `definition` \| `theorem` \| `example` \| `assumption` | — | a callout kind, not a colour tone |141| `title` | text | — | ≤ 200 |142| `text` | text | — | 1–4 000 |143144### `table`145146| Field | Type | Default | Constraints |147|---|---|---|---|148| `caption` | text | — | ≤ 300 |149| `columns` | `{ label, align }[]` | `align: left` | 1–8; `label` ≤ 200; `align` `left` \| `right` \| `center` |150| `rows` | text[][] | — | 1–40 rows; each cell ≤ 600; **every row has one cell per column** |151| `headerColumn` | boolean | — | first column is a header |152153### `cards`154155| Field | Type | Default | Constraints |156|---|---|---|---|157| `columns` | `2` \| `3` \| `4` | `3` | |158| `items` | `{ icon?, title, text, tone, badge? }[]` | `tone: neutral` | 1–12; `title` 1–200, `text` ≤ 800, `badge` ≤ 40 |159160### `steps`161162| Field | Type | Default | Constraints |163|---|---|---|---|164| `items` | `{ title, text, icon? }[]` | — | 1–12; `title` 1–200, `text` ≤ 800 |165166### `legend`167168| Field | Type | Default | Constraints |169|---|---|---|---|170| `title` | text | — | ≤ 200 |171| `items` | `{ label, tone, shape }[]` | `shape: square` | 1–12; `label` 1–200; `shape` `square` \| `circle` \| `line` \| `dashed` \| `arrow` |172173### `diagram`174175| Field | Type | Default | Constraints |176|---|---|---|---|177| `kind` | `flow` \| `architecture` \| `tree` \| `graph` | `flow` | |178| `direction` | `TB` \| `LR` | `TB` | |179| `routing` | `orthogonal` \| `curved` \| `straight` | `curved` | |180| `title` | text | — | ≤ 200 |181| `caption` | text | — | ≤ 400 |182| `nodes` | Node[] | — | 1–60 |183| `edges` | Edge[] | `[]` | ≤ 120 |184| `groups` | `{ id, label, tone }[]` | `[]`, `tone: neutral` | ≤ 12; `label` ≤ 80 |185| `legend` | `{ label, tone, shape }[]` | `[]`, `shape: square` | ≤ 8 |186| `animation` | `{ steps: Step[] }` | — | optional; 2–20 steps |187188Node:189190| Field | Type | Default | Constraints |191|---|---|---|---|192| `id` | Id | — | unique among nodes |193| `label` | text | — | 1–80 |194| `sublabel` | text | — | ≤ 120 |195| `shape` | `rect` \| `round` \| `pill` \| `diamond` \| `cylinder` \| `circle` \| `hexagon` \| `note` | `round` | |196| `tone` | Tone | `neutral` | |197| `icon` | Icon | — | |198| `group` | Id | — | must name a group |199| `x`, `y` | number | — | −20 000…20 000; manual centre position; **both or neither**; unset = placed by the layout engine |200| `locked` | boolean | — | not moved by the visual editor |201202Edge:203204| Field | Type | Default | Constraints |205|---|---|---|---|206| `id` | Id | — | unique among edges |207| `from`, `to` | Id | — | must name nodes |208| `label` | text | — | ≤ 80 |209| `style` | `solid` \| `dashed` \| `dotted` | `solid` | |210| `arrow` | `end` \| `both` \| `none` | `end` | |211| `tone` | Tone | `neutral` | |212| `fromPort`, `toPort` | `auto` \| `top` \| `right` \| `bottom` \| `left` | `auto` | |213214Animation step: `title` (1–200), `text?` (≤ 600), `nodes` (Id[] ≤ 60, default `[]`), `edges` (Id[] ≤ 120, default `[]`); every id must exist in the diagram. The reader can play, pause and step through them.215216### `timeline`217218| Field | Type | Default | Constraints |219|---|---|---|---|220| `orientation` | `vertical` \| `horizontal` | `vertical` | |221| `items` | `{ when, title, text?, tone }[]` | `tone: neutral` | 2–20; `when` 1–60, `title` 1–200, `text` ≤ 600 |222223### `matrix`224225| Field | Type | Default | Constraints |226|---|---|---|---|227| `title` | text | — | ≤ 200 |228| `caption` | text | — | ≤ 400 |229| `rowLabels`, `colLabels` | text[] | — | 1–16 each, labels ≤ 60 |230| `values` | number[][] | — | finite numbers; **exactly `rowLabels` × `colLabels`** |231| `scale` | `sequential` \| `diverging` \| `none` | `sequential` | |232| `showValues` | boolean | `true` | |233| `decimals` | integer | `2` | 0–4 |234| `dataKind` | data kind | — | required |235236### `code`237238| Field | Type | Default | Constraints |239|---|---|---|---|240| `language` | `python` \| `typescript` \| `javascript` \| `r` \| `sql` \| `bash` \| `json` \| `yaml` \| `latex` \| `julia` \| `rust` \| `go` \| `c` \| `pseudo` \| `text` | — | |241| `code` | string | — | 1–6 000 |242| `caption` | text | — | ≤ 300 |243244### `chart`245246| Field | Type | Default | Constraints |247|---|---|---|---|248| `kind` | `line` \| `area` \| `bar` \| `scatter` \| `histogram` | — | |249| `title` | text | — | ≤ 200 |250| `caption` | text | — | ≤ 400 |251| `dataKind` | data kind | — | required |252| `x` | Axis + `type` | `type: number` | `type` `number` \| `category` |253| `y` | Axis | | |254| `series` | `{ name, tone, points }[]` | `tone: blue` | 1–8 series; `name` 1–200 |255| `series[].points` | `{ x, y, lo?, hi? }[]` | — | 1–600; `x` a finite number or a label ≤ 60; `y`, `lo`, `hi` finite numbers; `lo`/`hi` draw a band or error bar |256| `annotations` | `{ x?, y?, label }[]` | — | ≤ 8; `label` 1–120 |257| `datasetRef` | Id | — | an `assets[]` entry of kind `dataset` the points were built from |258259Axis: `label` (1–200), `unit?` (≤ 40), `scale` (`linear` \| `log`, default `linear`), `min?`, `max?`.260261The quality report adds: non-numeric `x` on a numeric axis, non-positive values on a log scale and an interval that does not contain its value are errors.262263### `svg`264265| Field | Type | Default | Constraints |266|---|---|---|---|267| `tree` | SvgNode | — | a sanitised tree, never markup |268| `caption` | text | — | ≤ 400 |269| `maxWidth` | integer | — | 80–1120 |270271SvgNode: `{ tag, attrs, children }`. `tag` is one of `svg`, `g`, `path`, `rect`, `circle`, `ellipse`, `line`, `polyline`, `polygon`, `text`, `tspan`, `defs`, `linearGradient`, `radialGradient`, `stop`, `clipPath`, `title`, `desc`. `attrs` maps attribute names (`^[a-zA-Z][a-zA-Z0-9:-]{0,40}$`) to strings ≤ 20 000. `children` holds ≤ 400 nodes or strings ≤ 2 000. Trees are produced by `sanitizeSvg` (`POST /api/admin/svg/sanitize`); the renderer re-checks every attribute.272273### `image`274275| Field | Type | Default | Constraints |276|---|---|---|---|277| `assetRef` | Id | — | an `assets[]` entry |278| `caption` | text | — | ≤ 400 |279| `maxWidth` | integer | — | 80–1120 |280281### `comparison`282283| Field | Type | Default | Constraints |284|---|---|---|---|285| `caption` | text | — | ≤ 300 |286| `columns` | `{ title, tone, badge? }[]` | `tone: neutral` | 2–4; `title` 1–200, `badge` ≤ 40 |287| `rows` | `{ label, cells }[]` | — | 1–16; `label` 1–200; `cells` 2–4 texts ≤ 600; **one cell per column** |288| `verdict` | text | — | ≤ 800 |289290### `accordion`291292| Field | Type | Default | Constraints |293|---|---|---|---|294| `items` | `{ title, text }[]` | — | 1–12; `title` 1–200, `text` 1–4 000 |295296### `quiz`297298| Field | Type | Default | Constraints |299|---|---|---|---|300| `question` | text | — | 1–600 |301| `choices` | `{ text, correct, explanation? }[]` | — | 2–6; `text` 1–400, `explanation` ≤ 600; **at least one correct choice** |302303### `simulation`304305| Field | Type | Default | Constraints |306|---|---|---|---|307| `kind` | simulation kind | — | see the catalogue in §9 |308| `title` | text | — | ≤ 200 |309| `caption` | text | — | ≤ 400 |310| `params` | `{ [key]: number }` | `{}` | keys `^[a-zA-Z][a-zA-Z0-9]{0,23}$`; finite numbers |311| `seed` | integer | `1` | 0…2³¹−1 |312| `config` | `{ [key]: string \| number \| boolean }` | `{}` | same key pattern; strings ≤ 300 |313314The schema accepts any key; `validateSimulation` (`src/sim/registry.ts`) checks keys and bounds against the kind, and the quality report turns each problem into a blocking error — including a value outside its bounds, even though the renderer would clamp it.315316### `references`317318| Field | Type | Default | Constraints |319|---|---|---|---|320| `title` | text | — | ≤ 200 |321322Renders the document's `sources`, numbered in array order.323324### `divider`325326No specific field.327328### `tabs`329330| Field | Type | Default | Constraints |331|---|---|---|---|332| `tabs` | `{ id, label, blocks }[]` | — | 2–6 tabs; `label` 1–60; `blocks` 1–12 |333334A tab holds any block type except `tabs` (tabs do not nest). Blocks inside tabs count for id uniqueness and can be addressed by patches.335336## 5. Sources, claims, assets337338### Source339340| Field | Type | Default | Constraints |341|---|---|---|---|342| `id` | Id | — | cited as `[^id]` |343| `type` | `article` \| `book` \| `preprint` \| `documentation` \| `dataset` \| `web` \| `report` \| `upload` | — | |344| `title` | text | — | 1–400 |345| `authors` | text[] | `[]` | ≤ 30, each ≤ 120 |346| `year` | integer | — | 1500–2100 |347| `container` | text | — | ≤ 300 (journal, publisher) |348| `doi` | string | — | `^10\.\d{4,9}/\S+$`, ≤ 200 |349| `url` | URL | — | https or mailto |350| `license` | text | — | ≤ 120 |351| `note` | text | — | ≤ 600 |352| `status` | see below | `unverified` | |353| `checkedAt` | ISO date-time | — | |354355Statuses:356357| Status | Meaning | Set by |358|---|---|---|359| `unverified` | written by the model or typed by hand, never checked | default; forced on everything the model writes |360| `resolved` | the server fetched the DOI or URL and the record exists (title matched for DOIs) | the source check job |361| `reviewed` | the administrator confirmed the reference | the sources panel |362| `unreachable` | the server tried and could not reach it | the source check job |363364### Claim365366| Field | Type | Default | Constraints |367|---|---|---|---|368| `id` | Id | — | |369| `text` | text | — | 1–600 |370| `status` | `sourced` \| `derived` \| `unverified` | — | `derived` = follows from sourced material by an argument given in the sheet |371| `sourceIds` | Id[] | `[]` | ≤ 12 |372| `blockId` | Id | — | the block that makes the claim |373374A `sourced` claim without a source is a blocking quality error; an `unverified` claim is a warning.375376### AssetRef377378| Field | Type | Default | Constraints |379|---|---|---|---|380| `id` | Id | — | local id used by `assetRef` / `datasetRef` |381| `kind` | `image` \| `dataset` | — | |382| `assetId` | UUID | — | row of the `assets` table |383| `alt` | text | `""` | ≤ 400 |384| `credit` | text | — | ≤ 300 |385386Assets are references, not content: an exported JSON does not carry the files, and importing a JSON removes image blocks, removes `datasetRef` from charts (their points stay) and empties `assets`.387388## 6. Patch operations389390Structured changes addressed by id (`PatchOpSchema`, `applyPatch`). They are how the AI edits an existing sheet; a patch holds at most 120 operations.391392| `op` | Fields | Rules |393|---|---|---|394| `replace_block` | `id`, `block` | the block keeps `id`; refused if unknown or locked; a tab child cannot become `tabs` |395| `insert_block` | `block`, `afterId` (`null` = top), `tabId?` | `block.id` must be new; `afterId` must be in the target list; no `tabs` inside a tab |396| `remove_block` | `id` | refused if unknown or locked |397| `move_block` | `id`, `afterId` (`null` = top) | top-level blocks only; refused if locked |398| `set_metadata` | `metadata` (partial, without `author`) | merged into the metadata |399| `set_theme` | `preset?`, `accent?`, `format?` | |400| `upsert_source` | `source` | replaces by id or appends |401| `remove_source` | `id` | also removes the id from block `sourceIds` and claim `sourceIds` |402| `set_claims` | `claims` | replaces the list |403404`applyPatch` works on a copy, throws `PatchError` (with the index of the failing operation) on the first bad operation, and re-validates the result with `SheetSchema`. Locks are honoured unless `respectLocks: false` is passed. A block is protected when it is locked itself, or when it is a `tabs` block that contains a locked child (so a locked child cannot be removed by replacing its tab group). A locked `tabs` block does not lock its children one by one.405406`diffSheets(a, b)` returns `{ added, removed, changed, moved, metadata, theme, sources, claims }` — block ids for the first four, changed metadata keys, and booleans — for the revision history and the Claude panel.407408## 7. Versioning and migrations409410- `SCHEMA_VERSION` is `1`. Every stored document carries `schemaVersion`.411- `parseSheet(raw)` is the only way a document enters the system: `migrateSheet` then `SheetSchema.safeParse`. `mustParseSheet` throws instead of returning issues.412- `migrateSheet` upgrades one step at a time through `MIGRATIONS`. The only step is `0 → 1`: documents without a version (pre-release drafts) kept claims under `evidence`; the step renames it to `claims` and sets the version.413- A document whose version is **newer** than the server's is refused.414- Stored documents are never rewritten by a migration: revisions and publications are migrated when read. When `SCHEMA_VERSION` is bumped, add the step to `MIGRATIONS` in `src/schema/index.ts`.415- `stableStringify` serialises with sorted keys; `sheet_revisions.doc_hash` is the SHA-256 of that string, which is how an unchanged save is detected.416417Helpers in the same module: `allBlocks`, `findBlock`, `blockText`, `sheetText`, `readingMinutes` (220 words a minute plus half a minute per visual, interactive or equation block, at least 1), `tableOfContents`, `slugify`, `emptySheet`, `newId`.418419## 8. A complete example420421This document was passed through `parseSheet` with `node_modules/.bin/tsx` when this file was written; it validates, and the quality report finds no blocking error (one warning: the source is unverified).422423```json424{425  "schemaVersion": 1,426  "metadata": {427    "title": "Ordinary least squares in one page",428    "locale": "en",429    "summary": "What the OLS estimator minimises, and how noise changes the fitted line.",430    "topics": ["Econometrics"],431    "tags": ["regression", "ols"],432    "level": "beginner",433    "kind": "explainer",434    "objectives": ["State the OLS criterion", "Read a fitted line and its confidence band"]435  },436  "theme": { "preset": "scientific-light", "accent": "teal" },437  "layout": { "format": "article" },438  "blocks": [439    { "id": "title", "type": "heading", "level": 1, "eyebrow": "Econometrics", "text": "Ordinary least squares" },440    { "id": "intro", "type": "paragraph", "lead": true, "text": "OLS picks the line that makes the **sum of squared residuals** as small as possible[^s-gauss1809]." },441    { "id": "eq-ols", "type": "equation", "span": 6,442      "latex": "\\hat{\\beta} = \\arg\\min_{\\beta} \\sum_{i=1}^{n} (y_i - x_i^\\top \\beta)^2",443      "variables": [444        { "symbol": "y_i", "meaning": "Observed outcome of unit $i$" },445        { "symbol": "x_i", "meaning": "Vector of regressors of unit $i$" },446        { "symbol": "\\beta", "meaning": "Coefficients" }447      ],448      "derivation": "standard" },449    { "id": "d-flow", "type": "diagram", "span": 6, "direction": "LR",450      "alt": "Data go into the least-squares criterion, which returns the estimated coefficients.",451      "nodes": [452        { "id": "n-data", "label": "Data", "sublabel": "(x, y)", "tone": "blue", "icon": "database" },453        { "id": "n-criterion", "label": "Squared residuals", "tone": "neutral" },454        { "id": "n-beta", "label": "Estimate", "tone": "teal", "shape": "pill" }455      ],456      "edges": [457        { "id": "e-1", "from": "n-data", "to": "n-criterion", "label": "fit" },458        { "id": "e-2", "from": "n-criterion", "to": "n-beta", "label": "minimise" }459      ] },460    { "id": "sim-ols", "type": "simulation", "kind": "regression", "seed": 7,461      "params": { "slope": 1.5, "sigma": 2, "n": 40 },462      "alt": "Scatter of simulated points with the fitted line and its 95 % confidence band." },463    { "id": "quiz-1", "type": "quiz", "question": "What does OLS minimise?",464      "choices": [465        { "text": "The sum of squared residuals", "correct": true },466        { "text": "The sum of absolute residuals", "correct": false, "explanation": "That is least absolute deviations." }467      ] },468    { "id": "refs", "type": "references" }469  ],470  "sources": [471    { "id": "s-gauss1809", "type": "book", "title": "Theoria motus corporum coelestium in sectionibus conicis solem ambientium", "authors": ["Carl Friedrich Gauss"], "year": 1809 }472  ],473  "claims": [474    { "id": "c-1", "text": "OLS minimises the sum of squared residuals.", "status": "sourced", "sourceIds": ["s-gauss1809"], "blockId": "intro" }475  ]476}477```478479To check a document of your own from the project root:480481```bash482cat > /tmp/check.mts <<'EOF'483import { readFileSync } from "node:fs";484const { parseSheet } = await import(process.cwd() + "/src/schema/index.ts");485const r = parseSheet(JSON.parse(readFileSync(process.argv[2], "utf8")));486console.log(r.ok ? "valid" : r.issues);487EOF488node_modules/.bin/tsx /tmp/check.mts my-sheet.json489```490491In the studio, `POST /api/admin/validate` does the same and the dashboard's "Import a JSON" dialog uses it.492493## 9. Simulation catalogue494495Thirteen pre-approved kinds (`src/sim/registry.ts`; details and formulas in `src/sim/README.md`). A document picks a kind and gives numbers; it never supplies code. Every number shown comes from a pure `compute(params, seed, config)`; the same inputs draw the same picture. Values are clamped to their bounds and rounded to the slider step when rendered.496497Config keys accepted by every kind: `autoplay` (boolean; animated kinds play once when first visible, never under reduced motion) and `locale` (set by the block itself).498499Parameters are written `key (min … max, step, default)`.500501| Kind | Random | Animated | Parameters | Config |502|---|---|---|---|---|503| `moe-routing` | yes | one frame per token | `experts` (2…8, 1, 6), `topK` (1…8, 1, 2; capped at `experts`), `tokens` (4…12, 1, 8), `temperature` (0.1…3, 0.1, 1) | — |504| `neural-forward` | yes | one frame per layer | `layers` (2…4, 1, 2), `width` (2…6, 1, 4), `inputs` (2…4, 1, 3), `scale` (0.2…3, 0.1, 1.5) | `activation`: `tanh` \| `relu` \| `sigmoid` |505| `kv-cache` | no | one frame per generated token | `prompt` (1…8, 1, 4), `newTokens` (2…16, 1, 8), `layers` (1…12, 1, 4) | — |506| `attention` | yes | no | `temperature` (0.1…5, 0.1, 1), `dim` (4…32, 4, 16), `locality` (0…3, 0.1, 0) | `tokens` (comma-separated, 2–10), `causal` (boolean) |507| `distribution` | no | no | depends on `family` — normal: `mu` (−3…3, 0.1, 0), `sigma` (0.3…3, 0.1, 1), `a`, `b` (−8…8, 0.1, −1/1); student: `df` (1…30, 1, 4), `a`, `b` (−8…8, 0.1, −2/2); lognormal: `mu` (−1…1.5, 0.1, 0.5), `sigma` (0.1…1.5, 0.05, 0.5), `a`, `b` (0…10, 0.1, 1/3); exponential: `lambda` (0.2…5, 0.1, 1), `a`, `b` (0…10, 0.1, 0/1); uniform: `low` (−5…3, 0.1, 0), `width` (0.5…5, 0.1, 2), `a`, `b` (−6…9, 0.1, 0.5/1.5) | `family`: `normal` \| `student` \| `lognormal` \| `exponential` \| `uniform` |508| `confidence-interval` | yes | no | `n` (2…200, 1, 20), `m` (10…100, 5, 50), `level` (0.5…0.99, 0.01, 0.95), `mu` (−5…5, 0.5, 0), `sigma` (0.5…5, 0.5, 1) | — |509| `regression` | yes | no | `slope` (−3…3, 0.1, 1.5), `intercept` (−5…5, 0.5, 1), `sigma` (0…6, 0.1, 2), `n` (5…200, 1, 40) | — |510| `correlation` | yes | no | `rho` (−0.99…0.99, 0.01, 0.6), `n` (10…500, 10, 150) | — |511| `garch` | yes | no | `omega` (0.01…1, 0.01, 0.05), `alpha` (0…0.5, 0.01, 0.1), `beta` (0…0.99, 0.01, 0.85), `n` (100…600, 50, 400) | — |512| `random-walk` | yes | no | `drift`, `volatility` (bounds depend on `process`), `paths` (1…20, 1, 8), `horizon` (1…20, 1, 5), and for `ou` `reversion` (0.1…5, 0.1, 1) | `process`: `brownian` \| `gbm` \| `ou`; `x0` (number) |513| `impulse-response` | no | no | `a11` (0.6), `a12` (0.2), `a21` (0.3), `a22` (0.5), each −1.2…1.2 step 0.05; `horizon` (5…40, 1, 20) | `shock`: 1 or 2 |514| `event-study` | yes | no | `jump` (−5…5, 0.1, 2), `drift` (−0.5…0.5, 0.01, 0.1), `sigma` (0.5…5, 0.1, 2), `events` (5…200, 5, 50) | `window` (integer 3…20, default 10) |515| `function-plot` | no | no | one slider per name other than `x` found in the expressions (at most 5), default 1 | `expr` (required), `expr2`…`expr4`, `label`, `label2`…`label4`, `xMin`, `xMax`, `yMin`, `yMax`, `xLabel`, `yLabel`, and per parameter `<name>Min`, `<name>Max`, `<name>Step` |516517`random-walk` bounds by process — brownian: `drift` (−2…2, 0.1, 0.5), `volatility` (0.1…3, 0.1, 1); gbm: `drift` (−0.3…0.5, 0.01, 0.08), `volatility` (0.05…0.8, 0.01, 0.2); ou: `drift` = long-run level (−2…2, 0.1, 0), `volatility` (0.1…2, 0.1, 0.5).518519`function-plot` expression grammar: numbers, `x`, names, `+ - * / ^` (`^` right-associative; `-x^2` is `-(x^2)`), parentheses, constants `pi` and `e`, functions `exp log ln log10 sqrt abs sin cos tan tanh sigmoid relu max min pow floor` (`log` is natural). At most 300 characters and 32 nesting levels. The parser is a tokeniser and recursive descent in `src/sim/core/expr.ts`; there is no `eval`.520521In print mode (PDF/PNG export) a simulation is drawn in its initial state.522
Files main
Menu

Theme