yichus 0.2.0 → 0.3.0

package/dist/studio-page/what-happens-record.js

@@ -0,0 +1,217 @@
+// The what-happens record (schema what-happens-1, marks yichus-marks-3 plus
+// the outcome leaf), built from the engine's own output. web/what-happens.js
+// draws this record and nothing else; every element names the engine field
+// it was copied or derived from (`from`). scripts/what-happens-examples.mjs
+// records one per program.
+//
+// The record joins, by computed id:
+//   api_organize lens=structure (with requirements)   scenarios[], claims
+//   api_access_check                                  report.findings[]
+//   another what-happens record of the same program   its red leaves (base)
+// The author's words are copied as labels onto the ids they name and never
+// decide anything: colour comes only from a claim's verdict or a check's
+// witness, and structure only from the engine's trees.
+
+import { MARKS_VERSION } from './system-map-record.js';
+
+export const SCHEMA = 'what-happens-1';
+
+export const VOCABULARY = {
+  version: MARKS_VERSION,
+  added: ['outcome'],
+  marks: {
+    entryHead: 'arrowhead where a request comes in; the rack above the tree has one per described entry, then one dashed line counting the entries no scenario describes, which opens to draw each of them struck  <- entries[], ghosts[]',
+    guard: 'red diamond: the declared sign-in or role check, the first branch of every entry that has one; its failure stem ends in a refusal  <- tree node with from.kind=guard',
+    fork: 'three prongs: a branch the code takes on the request, the caller, a value read from a table, or a call result; the arm each line takes is written where it leaves  <- tree nodes',
+    station: 'ring on a line: an effect on that path, its verb and table beside it; filled = it writes  <- arms[].effects, entry.effects',
+    modelRing: 'violet ring: the path reaches the model  <- effects[resource=model]',
+    netRing: 'orange ring: the path reaches the network  <- effects[resource=net]',
+    outcome: 'the end of a path: a cap with what the request gets back (a constructor, or a refusal with its status and code); red when a claim fails there or a check reports a witness that ends there, green when every obligation that failed there at the base is checked here and holds, hollow and dashed (unchecked) when a claim there is inconclusive or an obligation that failed at the base is no longer checked, grey otherwise  <- leaves',
+    unchecked: 'a hollow dashed cap and a ? tick: the engine cannot say whether the claim holds on this path (a step it could not open, a table it could not name, an answer it could not decide), or what failed here at the base is not checked here; never counted as holding  <- claims[verdict=inconclusive], leaves[].gaps, diff.unresolved',
+    struck: 'a struck ghost: something checked and found absent (an entry nobody described, a write a claim says a path must not make, "no base compared" when no earlier version was compared)  <- ghosts[], claims holding with not',
+    bundle: 'a cable with a count: a subtree too large for this view; opening it draws that part with a breadcrumb  <- derived from the tree',
+    compared: 'a line under the rack, always there: "compared with <base> · N fixed · M still failing", or "no base compared", struck  <- diff',
+    hull: 'a shaded box on the line: a step that is not the handler\'s own work, folded (a wrapper\'s guard or short-circuit, the platform\'s declared check or the transaction it runs the plan in, work beside the wrapper, a wrapper\'s work after the handler); it keeps what the step answers instead of running the handler, one row per arm that skips the handler, read as a side stub (the arm, its struck writes, what the request gets, ticks), then "continue" (a transaction: "runs"), and its effects; opening it draws the step\'s own tree; drawn inline, the same hull is a light band behind the step and its exits, with its role and where it comes from above its test, so either way it reads as not the handler\'s own work  <- tree nodes[concern.role], entries[].steps',
+  },
+  rule: 'every entry, branch, arm, effect and outcome the engine computes is drawn, a folded step\'s inside its box and an undescribed entry behind the rack\'s one line; the author\'s words appear only on ids the engine computed, in italic, with the code name beside them.',
+  concerns: 'where each branch and effect comes from in value flow (concern.layer, effects[].layer): core = the handler\'s own work, a function it hands its wrapper or its body when it has none; cross = the wrapper its route shape names, shared with other entries; beside = the handler\'s code outside the wrapper call; platform = the route\'s declared authority, or the transaction the platform runs a plan in (its arms that give up or cannot confirm skip the handler\'s work). Roles come from which arms reach the handler, never from names.',
+};
+
+const bare = id => String(id).split('::').pop();
+const claimKey = (entry, c) => `${entry}\u0000${c.at}\u0000${c.parsed}`;
+
+export function walk(tree, f, path = []) {
+  if (!tree) return;
+  f(tree, path);
+  if (tree.kind === 'node') for (const arm of tree.arms) { f(arm, path); walk(arm.next, f, [...path, arm]); }
+}
+export const leavesOf = tree => { const out = []; walk(tree, t => { if (t.kind === 'leaf') out.push(t); }); return out; };
+// A leaf's effects are the entry's leading effects and those of each arm on
+// its path; the record keeps them once, on the arms, and these rebuild them.
+export function pathEffects(entry) {
+  const out = new Map();
+  const go = (t, acc) => {
+    if (!t) return;
+    if (t.kind === 'leaf') { out.set(t.id, acc); return; }
+    for (const a of t.arms) go(a.next, [...acc, ...a.effects]);
+  };
+  go(entry.tree, entry.effects || []);
+  return out;
+}
+export const allEffects = entry => { const out = [...(entry.effects || [])]; walk(entry.tree, t => { if (!t.kind) out.push(...t.effects); }); return out; };
+
+// The access check's findings that report a violation at an effect: the
+// leaves whose path runs that effect, at that definition, on that table.
+// A finding with a path condition (pathCondition.unlessHeld: the guards the
+// write sits under no branch on) is witnessed only on the paths where none
+// of those guards was tested and held: a path through a guard's True arm is
+// the guarded case, even when the write ran before the test.
+function heldOn(tree, guards) {
+  const out = new Set();
+  const go = (t, held) => {
+    if (!t) return;
+    if (t.kind === 'leaf') { if (held) out.add(t.id); return; }
+    const isGuard = t.from?.kind === 'call' && guards.includes(bare(t.from.callee));
+    for (const a of t.arms) go(a.next, held || (isGuard && a.arm === 'True'));
+  };
+  go(tree, false);
+  return out;
+}
+function witnessesOf(access, entries) {
+  if (!access) return [];
+  const findings = (access.report?.findings || []).filter(f => f.status === 'violated');
+  return findings.map((f, i) => {
+    const site = `${f.package}::${f.binding}`;
+    const guards = f.pathCondition?.unlessHeld || [];
+    const leaves = entries.flatMap(e => {
+      const held = heldOn(e.tree, guards);
+      return leavesOf(e.tree).filter(l => !held.has(l.id) && l.effects.some(x => x.site === site && bare(x.primitive) === f.operation && x.tables.includes(f.resource)));
+    }).map(l => l.id);
+    return { id: `witness:${i + 1}`, check: 'access', resource: f.resource, site, operation: f.operation, kind: f.kind, detail: f.detail, leaves,
+      ...(guards.length ? { unlessHeld: guards } : {}),
+      from: guards.length ? 'api_access_check report.findings[status=violated], on paths where pathCondition.unlessHeld did not hold' : 'api_access_check report.findings[status=violated]' };
+  });
+}
+
+/**
+ * engine: { structure, access? }  structure = api_organize lens=structure
+ * output (with requirements), access = api_access_check output.
+ * base: the record of the program before a change, for the diff marks.
+ */
+export function buildWhatHappens(engine, { program, base = null, baseLabel = 'base' } = {}) {
+  for (const [k, v] of Object.entries(engine)) if (v && !v.ok) throw new Error(`${k}: ${v.error}`);
+  const st = engine.structure;
+  const claims = st.claims || { scenarios: [], undescribed: (st.scenarios || []).map(s => s.entry) };
+  const byEntry = new Map(claims.scenarios.filter(s => s.status === 'matched').map(s => [s.entry, s]));
+  const routes = new Map((st.entries || []).map(e => [e.entry, e]));
+  const entries = st.scenarios.map(s => {
+    const meta = routes.get(s.entry) || {};
+    const sc = byEntry.get(s.entry);
+    const names = new Map((sc?.names || []).filter(n => n.status === 'named').map(n => [n.id, n.words]));
+    // copy the tree, putting the author's words on the ids they name
+    const copy = t => {
+      if (!t) return null;
+      if (t.kind === 'leaf') return { ...t, words: names.get(t.id) || null, claims: [], witnesses: [], status: 'grey' };
+      return { ...t, words: names.get(t.id) || null, arms: t.arms.map(a => ({ ...a, words: names.get(a.id) || null, next: copy(a.next) })) };
+    };
+    return {
+      entry: s.entry, handler: s.handler, label: s.entry.replace(/^route:/, ''),
+      authority: meta.authority || null, transport: meta.transport || null,
+      title: sc?.title || null, described: !!sc,
+      effects: s.effects, tree: copy(s.tree), leafCount: Number(s.leafCount), truncated: s.truncated, unsupported: s.unsupported || null,
+      wrapper: s.wrapper || null, steps: s.steps || [],
+      from: 'structure.scenarios[]',
+    };
+  });
+  const entryOf = new Map(entries.map(e => [e.entry, e]));
+  const leafById = new Map(entries.flatMap(e => leavesOf(e.tree).map(l => [l.id, l])));
+
+  // claims onto the leaves they are about
+  const checked = [], notes = [], refused = [], mismatches = [];
+  for (const sc of claims.scenarios) {
+    if (sc.status !== 'matched') { mismatches.push({ entry: sc.entry, title: sc.title || null, reason: sc.reason, from: 'structure.claims.scenarios[status=mismatch]' }); continue; }
+    for (const n of sc.names) if (n.status !== 'named') refused.push({ entry: sc.entry, id: n.id, words: n.words, reason: n.reason, from: 'structure.claims.scenarios[].names[status=refused]' });
+    for (const x of sc.expect) {
+      if (x.verdict === 'not-a-claim') { notes.push({ entry: sc.entry, at: x.at, text: x.claim, from: 'structure.claims.scenarios[].expect[verdict=not-a-claim]' }); continue; }
+      if (x.verdict === 'refused') { refused.push({ entry: sc.entry, id: x.at, words: x.claim, reason: x.reason, from: 'structure.claims.scenarios[].expect[verdict=refused]' }); continue; }
+      const open = new Map((x.inconclusive || []).map(o => [o.leaf, o.reasons]));
+      const c = { id: `claim:${checked.length + 1}`, entry: sc.entry, at: x.at, claim: x.claim, parsed: x.parsed, property: x.property, verdict: x.verdict, leaves: x.leaves, failing: x.failing,
+        inconclusive: x.inconclusive || [], from: 'structure.claims.scenarios[].expect[]' };
+      checked.push(c);
+      for (const id of x.leaves) {
+        const l = leafById.get(id);
+        if (!l) continue;
+        const verdict = x.failing.includes(id) ? 'fails' : open.has(id) ? 'inconclusive' : 'holds';
+        l.claims.push({ id: c.id, at: x.at, parsed: x.parsed, property: x.property, verdict, ...(verdict === 'inconclusive' ? { reasons: open.get(id) } : {}) });
+      }
+    }
+  }
+  const witnesses = witnessesOf(engine.access, entries);
+  // the base record keeps its leaves' effects on its arms
+  const basePaths = base ? new Map(base.entries.flatMap(e => [...pathEffects(e)])) : null;
+  for (const w of witnesses) for (const id of w.leaves) leafById.get(id)?.witnesses.push(w.id);
+  for (const l of leafById.values()) {
+    if (l.claims.some(c => c.verdict === 'fails') || l.witnesses.length) l.status = 'red';
+    else if (l.claims.some(c => c.verdict === 'inconclusive')) l.status = 'unchecked';
+  }
+
+  // the diff: a leaf red at the base is fixed only when every obligation
+  // that failed there (a claim, by entry, at and parsed claim; an access
+  // witness, by the check running here and naming no witness on the leaf)
+  // is checked here and holds; the base's red
+  // leaf travels with it, drawn faded beside it. An obligation that is gone
+  // or inconclusive here leaves the leaf unchecked, never green.
+  let diff = null;
+  if (base) {
+    const baseRed = new Map(base.entries.flatMap(e => leavesOf(e.tree).filter(l => l.status === 'red').map(l => [l.id, { entry: e.entry, leaf: l }])));
+    const baseWitness = new Map((base.witnesses || []).map(w => [w.id, w]));
+    const fixed = [], still = [], gone = [], unresolved = [];
+    for (const [id, { entry, leaf: bl }] of baseRed) {
+      const here = leafById.get(id);
+      if (!here) { gone.push(id); continue; }
+      if (here.status === 'red') { still.push(id); continue; }
+      const reasons = [
+        ...bl.claims.filter(c => c.verdict === 'fails').flatMap(c => {
+          const now = here.claims.find(h => claimKey(entry, h) === claimKey(entry, c));
+          if (!now) return [`the claim ${c.parsed} at ${c.at} failed here at the base and is not checked here`];
+          return now.verdict === 'holds' ? [] : [`the claim ${c.parsed} at ${c.at} failed here at the base and is inconclusive here`];
+        }),
+        ...(bl.witnesses.length && !engine.access ? [`the access check reported a witness here at the base and did not run here`] : []),
+      ];
+      const baseClaims = bl.claims, baseWitnesses = bl.witnesses.map(w => baseWitness.get(w)).filter(Boolean);
+      here.base = { outcome: bl.outcome, effects: bl.effects || basePaths.get(id) || [], claims: baseClaims, witnesses: baseWitnesses };
+      if (reasons.length) { here.status = 'unchecked'; unresolved.push({ id, reasons }); continue; }
+      here.status = 'green';
+      fixed.push(id);
+    }
+    diff = { base: baseLabel, fixed, stillRed: still, goneAtHead: gone, unresolved,
+      from: 'derived: base leaves[status=red] matched by id; each failed claim matched by entry, at and parsed claim; a witness is gone when the access check ran here and reports none on the leaf' };
+  }
+
+  const ghosts = entries.filter(e => !e.described).map(e => ({ entry: e.entry, from: 'structure.claims.undescribed[]' }));
+  // a leaf's effects are kept once, on the arms of its path (pathEffects)
+  for (const l of leafById.values()) delete l.effects;
+  return {
+    schema: SCHEMA, marks: MARKS_VERSION, vocabulary: VOCABULARY, program,
+    entries, ghosts, claims: checked, witnesses, notes, refused, mismatches, diff,
+    counts: { entries: entries.length, described: entries.length - ghosts.length, leaves: leafById.size,
+      steps: entries.reduce((n, e) => n + e.steps.length, 0), wrapped: entries.filter(e => e.wrapper && e.wrapper.wraps).length,
+      red: [...leafById.values()].filter(l => l.status === 'red').length, green: [...leafById.values()].filter(l => l.status === 'green').length,
+      unchecked: [...leafById.values()].filter(l => l.status === 'unchecked').length },
+    evidence: { tools: ['api_organize:structure', ...(engine.access ? ['api_access_check'] : [])], derived: ['diff: base red leaves matched by id, their failed obligations by identity'] },
+  };
+}
+
+// Small helpers the renderer and tests share.
+export const isWriteOp = op => !['read', 'runs', 'effect', 'random', 'trace', 'capture', 'init', 'mint id'].includes(op) && op !== 'call model' && op !== 'fetch article';
+export function stationLabel(e) {
+  const verb = e.op === 'mint id' ? 'mint' : e.op;
+  if (e.tables.length) return `${verb} · ${e.tables.join(', ')}`;
+  if (e.resource === 'model' || e.resource === 'net') return verb;
+  return `${verb} · ${bare(e.primitive)}`;
+}
+export function outcomeLabel(o) {
+  if (o.status && !o.constructors.length) return o.shown;
+  const head = o.constructors.length ? o.constructors.join(' | ') : (o.value ? `the ${o.value}` : o.shown);
+  return head;
+}