@a-company/gnomon 0.0.0-stage → 8.0.2

package/gnomon-mods/paradigm-context/fixtures/stale.golden.json

@@ -0,0 +1,205 @@
+{
+  "schemaVersion": "display-block:v1",
+  "type": "Box",
+  "title": "Paradigm",
+  "direction": "column",
+  "children": [
+    {
+      "type": "Box",
+      "direction": "row",
+      "children": [
+        {
+          "type": "Text",
+          "text": "●",
+          "tone": "hue-0"
+        },
+        {
+          "type": "Text",
+          "text": "ledgerette"
+        }
+      ]
+    },
+    {
+      "type": "Text",
+      "text": "stale · last entry 2026-08-30 (51 days ago)",
+      "tone": "warn"
+    },
+    {
+      "type": "Box",
+      "direction": "column",
+      "children": [
+        {
+          "type": "Box",
+          "direction": "row",
+          "children": [
+            {
+              "type": "Text",
+              "text": "tasks",
+              "tone": "head"
+            },
+            {
+              "type": "Text",
+              "text": "1 of 1 open",
+              "tone": "quiet"
+            }
+          ]
+        },
+        {
+          "type": "Box",
+          "direction": "row",
+          "children": [
+            {
+              "type": "Text",
+              "text": "task",
+              "tone": "quiet"
+            },
+            {
+              "type": "Text",
+              "text": "T-2026-08-12-002",
+              "tone": "quiet"
+            },
+            {
+              "type": "Text",
+              "text": "“Typecheck packages/ledger after the Cents migration”",
+              "tone": "quiet"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "Box",
+      "direction": "column",
+      "children": [
+        {
+          "type": "Box",
+          "direction": "row",
+          "children": [
+            {
+              "type": "Text",
+              "text": "decisions",
+              "tone": "head"
+            },
+            {
+              "type": "Text",
+              "text": "1 of 3",
+              "tone": "quiet"
+            }
+          ]
+        },
+        {
+          "type": "Box",
+          "direction": "row",
+          "children": [
+            {
+              "type": "Text",
+              "text": "decision",
+              "tone": "quiet"
+            },
+            {
+              "type": "Text",
+              "text": "TD-2026-08-30-118",
+              "tone": "quiet"
+            },
+            {
+              "type": "Text",
+              "text": "2026-08-30",
+              "tone": "quiet"
+            },
+            {
+              "type": "Text",
+              "text": "“Money is integer cents end to end”",
+              "tone": "quiet"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "Box",
+      "direction": "column",
+      "children": [
+        {
+          "type": "Box",
+          "direction": "row",
+          "children": [
+            {
+              "type": "Text",
+              "text": "lore",
+              "tone": "head"
+            },
+            {
+              "type": "Text",
+              "text": "1 of 4",
+              "tone": "quiet"
+            }
+          ]
+        },
+        {
+          "type": "Box",
+          "direction": "row",
+          "children": [
+            {
+              "type": "Text",
+              "text": "lore milestone",
+              "tone": "quiet"
+            },
+            {
+              "type": "Text",
+              "text": "L-2026-08-29-matt-101500-001",
+              "tone": "quiet"
+            },
+            {
+              "type": "Text",
+              "text": "“Ledger import lands”",
+              "tone": "quiet"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "Box",
+      "direction": "column",
+      "children": [
+        {
+          "type": "Box",
+          "direction": "row",
+          "children": [
+            {
+              "type": "Text",
+              "text": "symbols",
+              "tone": "head"
+            },
+            {
+              "type": "Text",
+              "text": "2",
+              "tone": "quiet"
+            }
+          ]
+        },
+        {
+          "type": "Box",
+          "direction": "row",
+          "children": [
+            {
+              "type": "Text",
+              "text": "#ledger-post",
+              "tone": "chip"
+            },
+            {
+              "type": "Text",
+              "text": "$import-flow",
+              "tone": "chip"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "Text",
+      "text": "skipped · 1 refused · 2 secret",
+      "tone": "quiet"
+    }
+  ]
+}

package/gnomon-mods/paradigm-context/fixtures/stale.json

@@ -0,0 +1,69 @@
+{
+  "view": "paradigm-context.sheet",
+  "input": {
+    "paradigm": {
+      "v": "paradigm-slice:v1",
+      "state": "ok",
+      "project": 0,
+      "name": "ledgerette",
+      "at": "2026-10-20",
+      "newest": "2026-08-30",
+      "tasks": {
+        "open": 1,
+        "high": 0,
+        "items": [
+          {
+            "id": "T-2026-08-12-002",
+            "title": "Typecheck packages/ledger after the Cents migration",
+            "priority": "medium"
+          }
+        ],
+        "count": {
+          "n": 1,
+          "of": 1
+        }
+      },
+      "decisions": {
+        "items": [
+          {
+            "id": "TD-2026-08-30-118",
+            "title": "Money is integer cents end to end",
+            "date": "2026-08-30"
+          }
+        ],
+        "count": {
+          "n": 1,
+          "of": 3
+        }
+      },
+      "lore": {
+        "items": [
+          {
+            "id": "L-2026-08-29-matt-101500-001",
+            "title": "Ledger import lands",
+            "type": "milestone"
+          }
+        ],
+        "count": {
+          "n": 1,
+          "of": 4
+        }
+      },
+      "symbols": [
+        "#ledger-post",
+        "$import-flow"
+      ],
+      "skipped": {
+        "malformed": 0,
+        "refused": 1,
+        "secret": 2,
+        "truncated": false
+      }
+    }
+  },
+  "width": 40,
+  "prefs": {
+    "motion": "full",
+    "theme": "day"
+  }
+}

package/gnomon-mods/paradigm-context/fixtures/unfocused.golden.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": "display-block:v1",
+  "type": "Box",
+  "title": "Paradigm",
+  "direction": "column",
+  "children": [
+    {
+      "type": "Box",
+      "direction": "row",
+      "children": [
+        {
+          "type": "Text",
+          "text": "◌",
+          "tone": "quiet"
+        },
+        {
+          "type": "Text",
+          "text": "paradigm"
+        }
+      ]
+    },
+    {
+      "type": "Text",
+      "text": "focus a live session to see its project context",
+      "tone": "quiet"
+    }
+  ]
+}

package/gnomon-mods/paradigm-context/fixtures/unfocused.json

@@ -0,0 +1,14 @@
+{
+  "view": "paradigm-context.sheet",
+  "input": {
+    "paradigm": {
+      "v": "paradigm-slice:v1",
+      "state": "unfocused"
+    }
+  },
+  "width": 40,
+  "prefs": {
+    "motion": "full",
+    "theme": "day"
+  }
+}

package/gnomon-mods/paradigm-context/gnomon-manifest.json

@@ -0,0 +1,15 @@
+{
+  "manifest": 2,
+  "kind": "mod",
+  "publisher": "gnomon",
+  "name": "paradigm-context",
+  "version": "1.1.1",
+  "abi": "mod-abi:v1",
+  "description": "Paradigm Context: the focused session's project knowledge (open tasks, recent decisions, recent lore and the symbols they touch), read-only, from the kernel's bounded paradigm-slice.",
+  "provides": {
+    "views": [
+      { "id": "paradigm-context.sheet", "slot": "sidebar", "placement": "append", "fixtures": ["fixtures/empty.json", "fixtures/full.json", "fixtures/full-dark.json", "fixtures/stale.json", "fixtures/unfocused.json"] }
+    ]
+  },
+  "requires": { "capabilities": ["paradigm.read:summary"], "egress": "none" }
+}

package/gnomon-mods/paradigm-context/index.mjs

@@ -0,0 +1,64 @@
+// #paradigm-context-mod (Paradigm Context; first-party, mod-abi:v1, no effects
+// beyond `read`, egress none). The #ledger-mod stdio loop, minus the feed:
+// this mod requires paradigm.read:summary only, so it gets no kernel events.
+// Its ONLY input is the host-composed view input: `input.paradigm`, the K1
+// paradigm-slice:v1 the KERNEL computed for the focused LIVE session's repo
+// (the host joins {focus:{hsid}} server-side, K3). It reads no file and
+// never sees a path. Self-contained on purpose: it imports nothing outside
+// this folder, so its packageHash (pinned in the kernel's first-party
+// allowlist) never depends on a build of the SDK.
+import { VIEWS } from './model.mjs';
+
+const ABI = 'mod-abi:v1';
+// Echoed at init; the host refuses any other id (a mod-ABI change needs a new build).
+const MOD_ABI_ID = 'sha256:7aaf92f46dc35fc35141557c1f89088958f220e6bf53ea31a630bb06430ba082';
+
+const send = (msg) => process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', ...msg })}\n`);
+
+function handle(method, p) {
+  switch (method) {
+    case 'init':
+      if (p.abi !== ABI) throw Object.assign(new Error(`unsupported abi ${String(p.abi)}`), { code: -32602 });
+      return { abi: ABI, features: [], modAbiId: MOD_ABI_ID };
+    case 'health':
+      return { ok: true, abi: ABI };
+    case 'shutdown':
+      setImmediate(() => process.exit(0));
+      return {};
+    case 'view.render': {
+      const render = Object.hasOwn(VIEWS, p.viewId) ? VIEWS[p.viewId] : null;
+      if (!render) throw Object.assign(new Error(`no view ${String(p.viewId)}`), { code: -32601 });
+      const prefs = p.prefs && typeof p.prefs === 'object' ? p.prefs : {};
+      return { block: render(p.input && typeof p.input === 'object' ? p.input : {}, prefs) };
+    }
+    default:
+      throw Object.assign(new Error(`unknown method ${method}`), { code: -32601 });
+  }
+}
+
+let buf = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf('\n')) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (typeof msg.method !== 'string') continue; // the mod makes no mod → host requests
+    if (msg.method === 'event' || msg.method === 'cancel' || msg.id === undefined) continue;
+    const params = msg.params && typeof msg.params === 'object' ? msg.params : {};
+    try {
+      send({ id: msg.id, result: handle(msg.method, params) });
+    } catch (e) {
+      send({ id: msg.id, error: { code: typeof e.code === 'number' ? e.code : -32000, message: String(e.message) } });
+    }
+  }
+});
+process.stdin.on('end', () => process.exit(0));

package/gnomon-mods/paradigm-context/model.mjs

@@ -0,0 +1,137 @@
+// #paradigm-context-mod model: a PURE render of the kernel's paradigm-slice:v1
+// (K1, host-composed view input; granted by paradigm.read:summary) to
+// display-block:v1 (kit:v1 only). Read-only: no Button, no command, no
+// effect. Nothing here reads a file or a path; the slice is the only input
+// and it is re-validated here (a mod never trusts a count or a string).
+
+export const SLICE_V1 = 'paradigm-slice:v1';
+export const HUES = 8;
+export const TOP = 5;
+export const TITLE_MAX = 80;
+export const MAX_SYMBOLS = 24;
+/** A slice whose newest decision or lore entry is older than this (days, against its own `at`) is shown stale. */
+export const STALE_DAYS = 14;
+
+const ID = /^[A-Za-z0-9._-]{1,64}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TOKEN = /^[a-z][a-z0-9-]{0,31}$/;
+const SYMBOL = /^[#$^!~][a-z0-9][a-z0-9-]{0,63}$/;
+const PRIORITIES = ['high', 'medium', 'low'];
+
+/** A finite non-negative safe integer (anything else is 0). */
+export function count(v) {
+  if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) return 0;
+  return Math.min(Math.floor(v), Number.MAX_SAFE_INTEGER);
+}
+
+/** One display line: no newline or tab, capped at `max` code points (… when cut). */
+export function clip(s, max = TITLE_MAX) {
+  const one = String(typeof s === 'string' ? s : '').replace(/[\n\t\r]+/g, ' ').replace(/ {2,}/g, ' ').trim();
+  const cps = [...one];
+  return cps.length > max ? `${cps.slice(0, max - 1).join('').trimEnd()}…` : one;
+}
+
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const arr = (v) => (Array.isArray(v) ? v : []);
+const items = (zone, extra) =>
+  arr(obj(zone).items)
+    .filter((it) => it && typeof it === 'object' && typeof it.id === 'string' && ID.test(it.id) && typeof it.title === 'string')
+    .slice(0, TOP)
+    .map((it) => ({ id: it.id, title: clip(it.title), ...extra(it) }));
+
+/** The slice, re-validated and bounded; null when it is not a paradigm-slice:v1. */
+export function readSlice(input) {
+  const s = obj(obj(input).paradigm);
+  if (s.v !== SLICE_V1) return null;
+  const state = s.state === 'ok' || s.state === 'absent' ? s.state : 'unfocused';
+  const project = Number.isInteger(s.project) && s.project >= 0 && s.project < HUES ? s.project : null;
+  const name = typeof s.name === 'string' ? clip(s.name, 64) : '';
+  const at = typeof s.at === 'string' && DATE.test(s.at) ? s.at : null;
+  const newest = typeof s.newest === 'string' && DATE.test(s.newest) ? s.newest : null;
+  const t = obj(s.tasks);
+  const d = obj(s.decisions);
+  const l = obj(s.lore);
+  const sk = obj(s.skipped);
+  const of = (z, n) => Math.max(count(obj(obj(z).count).of), n);
+  const tasks = items(t, (it) => ({ priority: PRIORITIES.includes(it.priority) ? it.priority : 'medium' }));
+  const decisions = items(d, (it) => ({ date: typeof it.date === 'string' && DATE.test(it.date) ? it.date : null }));
+  const lore = items(l, (it) => ({ type: typeof it.type === 'string' && TOKEN.test(it.type) ? it.type : 'note' }));
+  const open = Math.max(count(t.open), tasks.length);
+  return {
+    state,
+    project,
+    name,
+    at,
+    newest,
+    tasks: { open, high: Math.min(count(t.high), open), items: tasks, of: of(t, open) },
+    decisions: { items: decisions, of: of(d, decisions.length) },
+    lore: { items: lore, of: of(l, lore.length) },
+    symbols: arr(s.symbols).filter((x) => typeof x === 'string' && SYMBOL.test(x)).filter((x, i, a) => a.indexOf(x) === i).slice(0, MAX_SYMBOLS),
+    skipped: { malformed: count(sk.malformed), refused: count(sk.refused), secret: count(sk.secret), truncated: sk.truncated === true },
+  };
+}
+
+/** Days from `newest` to `at` (both YYYY-MM-DD), or null. */
+export function ageDays(newest, at) {
+  if (!newest || !at) return null;
+  return Math.max(0, Math.round((Date.parse(`${at}T00:00:00Z`) - Date.parse(`${newest}T00:00:00Z`)) / 86_400_000));
+}
+
+const text = (t, tone) => ({ type: 'Text', text: t, ...(tone ? { tone } : {}) });
+/** The {n, of} count as the zone title reads it. */
+const nOf = (n, of) => `${n} of ${of}`;
+
+function head(sl) {
+  // the project swatch: a hue-toned mark (the GUI draws the project's ■ in its hue); the name is ink
+  const cap = sl && sl.project !== null ? text('●', `hue-${sl.project}`) : text('◌', 'quiet');
+  return { type: 'Box', direction: 'row', children: [cap, text(sl && sl.name ? sl.name : 'paradigm')] };
+}
+
+/**
+ * Aegis L2: one item line. A FIXED type prefix (task / decision / lore) and the id come from the model; the
+ * repo-authored title follows QUOTED and dim, so a title can never pass for a status glyph, a kernel line or a
+ * card (any status mark, like the ▲ of a high task, is the model's own, in the prefix). Curly quotes inside the
+ * title are flattened so it cannot close its own quote.
+ */
+function line(kind, id, title, date = null) {
+  const q = String(title).replace(/[\u201c\u201d]/g, '"');
+  // the id and its date are separate words, so the GUI can truncate the id on one line and never break it mid-token
+  return { type: 'Box', direction: 'row', children: [text(kind, 'quiet'), text(id, 'quiet'), ...(date ? [text(date, 'quiet')] : []), text(`\u201c${q}\u201d`, 'quiet')] };
+}
+
+// a zone heading is a row: the zone's name (tone head, the label style) and its {n, of} count as quiet meta beside it
+function zone(title, meta, lines, empty) {
+  return { type: 'Box', direction: 'column', children: [{ type: 'Box', direction: 'row', children: [text(title, 'head'), text(meta, 'quiet')] }, ...(lines.length ? lines : [text(empty, 'quiet')])] };
+}
+
+/** The one quiet line of a project with no open tasks, decisions or lore. */
+export const EMPTY_LINE = 'nothing yet: no tasks, decisions or lore';
+
+/** The sheet (sidebar): the project swatch, then tasks, decisions and lore, each with its {n, of} count. */
+export function renderSheet(input, prefs = {}) {
+  void prefs; // the theme and motion change nothing here: no fill animates, every tone is a token
+  const sl = readSlice(input);
+  const base = { schemaVersion: 'display-block:v1', type: 'Box', title: 'Paradigm', direction: 'column' };
+  if (!sl || sl.state === 'unfocused') return { ...base, children: [head(null), text('focus a live session to see its project context', 'quiet')] };
+  if (sl.state === 'absent') return { ...base, children: [head(sl), text('no .paradigm in this repo', 'quiet')] };
+  const age = ageDays(sl.newest, sl.at);
+  const children = [head(sl)];
+  const t = sl.tasks;
+  // an empty project says so once (Mika 2026-10-23), not once per zone; each zone's own empty line shows only beside a zone with items
+  const nothing = !t.items.length && !sl.decisions.items.length && !sl.lore.items.length;
+  if (nothing) children.push(text(EMPTY_LINE, 'quiet'));
+  else if (sl.newest !== null && age !== null && age > STALE_DAYS) children.push(text(`stale · last entry ${sl.newest} (${age} days ago)`, 'warn'));
+  if (!nothing) children.push(
+    zone('tasks', `${nOf(t.items.length, t.of)} open${t.high ? ` · ${t.high} high` : ''}`, t.items.map((it) => line(`task${it.priority === 'high' ? ' ▲' : ''}`, it.id, it.title)), 'no open tasks'),
+    zone('decisions', nOf(sl.decisions.items.length, sl.decisions.of), sl.decisions.items.map((it) => line('decision', it.id, it.title, it.date)), 'no decisions'),
+    zone('lore', nOf(sl.lore.items.length, sl.lore.of), sl.lore.items.map((it) => line(`lore ${it.type}`, it.id, it.title)), 'no lore'),
+  );
+  // symbol chips: mono ink text (tone chip), never a hue
+  if (sl.symbols.length) children.push({ type: 'Box', direction: 'column', children: [{ type: 'Box', direction: 'row', children: [text('symbols', 'head'), text(String(sl.symbols.length), 'quiet')] }, { type: 'Box', direction: 'row', children: sl.symbols.map((s) => text(s, 'chip')) }] });
+  const sk = sl.skipped;
+  const notes = [sk.malformed ? `${sk.malformed} malformed` : '', sk.refused ? `${sk.refused} refused` : '', sk.secret ? `${sk.secret} secret` : '', sk.truncated ? 'truncated' : ''].filter(Boolean);
+  if (notes.length) children.push(text(`skipped · ${notes.join(' · ')}`, 'quiet'));
+  return { ...base, children };
+}
+
+export const VIEWS = Object.freeze({ 'paradigm-context.sheet': renderSheet });

package/gnomon-mods/workshop/README.md

@@ -0,0 +1,12 @@
+# workshop (first-party Gnomon mod)
+
+The Workshop view (spec §11.6): a sidebar strip with two zones.
+
+- **needs you**: one cap per pending card, labelled with the card's kind.
+- **working**: one cap per open session. A cap bobs only while its session streams (`turn.partial`) and stands still otherwise. With reduced motion it shows the word `working` instead.
+
+Each cap is a kit `Text` node: its `text` is the accessible form, and its `cap` is the closed shape `{shape, hue, filled, state, label}` (gnomon-contracts `checkCap`). The kernel's mod-block gate refuses any other cap field, and the GUI draws the hat from these five fields alone. Where the strip shows (a footer strip, a left or right column, or hidden) is the GUI Layout's choice; the manifest slot stays `sidebar`.
+
+Every attribute comes from kernel events that the host projects to the mod (`#mod-host` feed, granted by `log.read`). Nothing comes from model text. The hat shape shows the work type, a filled hat means Claude and an outlined hat means local, the hue shows the project, and violet is used only for a KNOT.
+
+Install it with `gnomon mod install packages/gnomon-mods/workshop`, then approve the card in the GUI. Its packageHash is pinned in the kernel's first-party list, so editing any file here needs a new pin.

package/gnomon-mods/workshop/fixtures/strip-reduced.golden.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": "display-block:v1",
+  "type": "Box",
+  "title": "Workshop",
+  "direction": "column",
+  "children": [
+    {
+      "type": "Box",
+      "title": "needs you 1",
+      "children": [
+        {
+          "type": "Text",
+          "text": "▲ permission",
+          "tone": "cap",
+          "cap": {
+            "shape": "tall",
+            "hue": 2,
+            "filled": true,
+            "state": "needs",
+            "label": "? permission"
+          }
+        }
+      ]
+    },
+    {
+      "type": "Box",
+      "title": "working 1 of 2",
+      "children": [
+        {
+          "type": "Text",
+          "text": "▲ builder filled working",
+          "tone": "hue-2",
+          "cap": {
+            "shape": "tall",
+            "hue": 2,
+            "filled": true,
+            "state": "working",
+            "label": "builder"
+          }
+        },
+        {
+          "type": "Text",
+          "text": "▲ builder outlined still",
+          "tone": "violet",
+          "cap": {
+            "shape": "tall",
+            "hue": 5,
+            "filled": false,
+            "state": "knot",
+            "label": "builder"
+          }
+        }
+      ]
+    }
+  ]
+}

package/gnomon-mods/workshop/fixtures/strip-reduced.json

@@ -0,0 +1,16 @@
+{
+  "input": {
+    "fixtureEvents": [
+      { "kind": "session.open", "payload": { "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA", "backend": "claude", "project": 2 } },
+      { "kind": "session.open", "payload": { "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZB", "backend": "local", "project": 5 } },
+      { "kind": "turn.partial", "payload": { "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA" } },
+      { "kind": "approval.request", "payload": { "cardId": "card:01HZZZZZZZZZZZZZZZZZZZZZZC", "kind": "permission", "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZA" } },
+      { "kind": "approval.request", "payload": { "cardId": "card:01HZZZZZZZZZZZZZZZZZZZZZZD", "kind": "plan", "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZB" } },
+      { "kind": "approval.decide", "payload": { "cardId": "card:01HZZZZZZZZZZZZZZZZZZZZZZD" } },
+      { "kind": "warpline.knot", "payload": { "hsid": "hsid:v1:01HZZZZZZZZZZZZZZZZZZZZZZB" } },
+      { "kind": "mod.paused", "payload": { "name": "hello", "reason": "user" } }
+    ]
+  },
+  "width": 40,
+  "prefs": { "motion": "reduced", "theme": "day" }
+}