@starci/hfs 4.7.32 → 4.7.34

package/runtime/scripts/lib/grammar-vendor-parity.mjs

@@ -0,0 +1,377 @@
+// grammar-vendor-parity.mjs - GRAMMAR_VENDOR_PARITY: a Grammar component that wraps HeroUI keeps HeroUI's anatomy and defaults.
+//
+// Grammar is a wrapper of HeroUI. The vendor reference (knowledge/vendor/heroui/<dir>.yaml, measured from the installed @heroui packages by
+// scripts/work/ui/vendor-heroui.mjs) states what HeroUI draws; the wrapper manifest (knowledge/vendor/heroui/wrappers.yaml) states what each
+// Grammar file wraps, which parts it hands to its caller (`delegates`) and which vendor slots it restyles on purpose (`overrides`, empty by
+// default, pinned by an owner ruling: scripts/checks/check-grammar-vendor-parity.mjs). This library is pure: the caller hands the parsed
+// reference, the parsed manifest, the Grammar sources and stylesheets.
+//
+// Two layers. The UNIVERSAL layer binds every Grammar built on HeroUI: use the HeroUI component for each role (no hand-rolled menu, list
+// box, dialog or switch: `role`), keep its anatomy and parts (`anatomy`, `undeclared`). The PER-GRAMMAR layer is what a Grammar declares in the
+// manifest (`grammars: [{id, paths, vendor: {name: heroui, parity}}]`, never inferred from its code): `strict` keeps HeroUI's default CSS and
+// arrangement (`slot`, `style`, `default`, `stale`; the pinned overrides are the only deviations), `custom` may re-skin and re-arrange
+// (tokens, radius, padding, colour, where the indicator sits, separators, icon size) and is judged by the universal layer only.
+// Grammar StarCi is strict.
+//
+// A finding is red when
+//   anatomy    a wrapper renders a part the vendor does not have, omits a part the vendor requires, or omits the vendor's embedded
+//              divider (`Separator`) while it renders a `Section`;
+//   undeclared a Grammar file wraps a HeroUI component its manifest row does not declare (or the row names a file that is gone);
+//   slot       Grammar CSS targets a vendor class or `data-slot` no override declares;
+//   style      (rows with `styleParity: true`) Grammar CSS restyles a paint family (padding, radius, colour, size, ...) of a vendor part
+//              through a class or `data-grammar-*` stamp that wrapper puts on that part, and no override declares it (accessibility
+//              media - forced colors, the touch target floor - is not judged);
+//   default    a wrapper passes a vendor part a prop value other than the vendor default (the dot indicator in place of the check);
+//   role       a Grammar file hand-rolls an ARIA role HeroUI already has a component for (unless a pinned `role` override declares it);
+//   grammar    a Grammar file belongs to no declared Grammar, or a declaration is malformed;
+//   stale      an override nothing needs any more.
+// A StarCi canon decision that is not drift (the glyph size of the icon rule) is declared as a `canon` override: justified, pinned, and it
+// permits nothing. Family skins (`offset-pop`, `heritage`) are brand directions that re-skin HeroUI on purpose and are not judged; the
+// base look (`common`, `core`) is.
+import { createHash } from 'node:crypto';
+import { cssRules, ruleFamilies, selectorAttributes, selectorClasses, subjectCompound } from './css-rules.mjs';
+import { byCodeUnit } from './list.mjs';
+
+export const CODE = 'GRAMMAR_VENDOR_PARITY';
+export const WRAPPERS_SCHEMA = 'starci/vendor-heroui-wrappers@1';
+
+/** The sha256 of a pinned file's text, line endings normalised. */
+export const manifestDigest = (text) => createHash('sha256').update(String(text ?? '').replaceAll('\r\n', '\n')).digest('hex');
+
+const finding = (rule, file, line, message) => ({ code: CODE, rule, file, line, message: `${rule}: ${message}` });
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+
+// ---------------------------------------------------------------------------
+// Reading JSX without a parser: the opening tags of the aliases a file imports from @heroui/react.
+// ---------------------------------------------------------------------------
+
+/** The index after the quoted string that starts at `start`. */
+function skipQuoted(text, start) {
+  const quote = text[start];
+  let index = start + 1;
+  while (index < text.length && text[index] !== quote) index += text[index] === '\\' ? 2 : 1;
+  return index + 1;
+}
+
+/** The index after the template literal that starts at `start`, `${...}` substitutions included. */
+function skipTemplate(text, start) {
+  let index = start + 1;
+  while (index < text.length && text[index] !== '`') {
+    if (text[index] === '\\') index += 2;
+    else if (text[index] === '$' && text[index + 1] === '{') index = skipBraces(text, index + 1);
+    else index += 1;
+  }
+  return index + 1;
+}
+
+/** The index after the balanced `{...}` that starts at `start`. */
+function skipBraces(text, start) {
+  let depth = 0;
+  let index = start;
+  while (index < text.length) {
+    const char = text[index];
+    if (char === '"' || char === "'") index = skipQuoted(text, index);
+    else if (char === '`') index = skipTemplate(text, index);
+    else {
+      if (char === '{') depth += 1;
+      if (char === '}') depth -= 1;
+      index += 1;
+      if (depth === 0 && char === '}') return index;
+    }
+  }
+  return index;
+}
+
+/** The index after the value (a string, a template or a braced expression) that starts at `start`. */
+function skipValue(text, start) {
+  const char = text[start];
+  if (char === '"' || char === "'") return skipQuoted(text, start);
+  if (char === '`') return skipTemplate(text, start);
+  return char === '{' ? skipBraces(text, start) : start + 1;
+}
+
+/** Attributes of the opening tag whose name ended at `from`: `{name, raw}` (a spread is named `...`). */
+function readAttributes(text, from) {
+  const attrs = [];
+  let index = from;
+  while (index < text.length) {
+    while (/\s/.test(text[index] ?? '')) index += 1;
+    if (text[index] === '>' || text.startsWith('/>', index)) break;
+    if (text[index] === '{') {
+      const end = skipBraces(text, index);
+      attrs.push({ name: '...', raw: text.slice(index + 1, end - 1) });
+      index = end;
+      continue;
+    }
+    const name = /^[\w:-]+/.exec(text.slice(index, index + 80))?.[0];
+    if (!name) break;
+    index += name.length;
+    if (text[index] !== '=') {
+      attrs.push({ name, raw: 'true' });
+      continue;
+    }
+    index += 1;
+    const end = skipValue(text, index);
+    const raw = text.slice(index, end);
+    attrs.push({ name, raw: raw.startsWith('{') ? raw.slice(1, -1) : raw });
+    index = end;
+  }
+  return attrs;
+}
+
+/** The opening tags of the given import aliases: `{alias, part, attrs, line}` (`part` is `Root` for the bare alias). */
+export function heroTags(text, aliases) {
+  if (!aliases.length) return [];
+  const pattern = new RegExp(String.raw`<(${aliases.join('|')})(?:\.(\w+))?(?=[\s/>])`, 'g');
+  return [...text.matchAll(pattern)].map((match) => ({
+    alias: match[1],
+    part: match[2] ?? 'Root',
+    attrs: readAttributes(text, match.index + match[0].length),
+    line: lineOf(text, match.index),
+  }));
+}
+
+/** The string literals of an expression, without their quotes. */
+const stringLiterals = (raw) => (String(raw).match(/"[^"\n]*"|'[^'\n]*'|`[^`$]*`/g) ?? []).map((literal) => literal.slice(1, -1));
+
+/** The class tokens an element carries: the literals of its className, with a bare constant resolved one level in the file. */
+function classTokens(text, attrs) {
+  const raw = attrs.find((attr) => attr.name === 'className')?.raw;
+  if (raw === undefined) return [];
+  const names = String(raw).match(/\b[A-Za-z_]\w*\b/g) ?? [];
+  const resolved = names.flatMap((name) => {
+    const declaration = new RegExp(String.raw`\bconst\s+${name}\s*=\s*([^\n]*(?:\n[^\n;]*)?)`).exec(text);
+    return declaration ? stringLiterals(declaration[1]) : [];
+  });
+  return [...stringLiterals(raw), ...resolved].flatMap((value) => value.split(/\s+/)).filter(Boolean);
+}
+
+// ---------------------------------------------------------------------------
+// The judgment.
+// ---------------------------------------------------------------------------
+
+/** Accessibility adaptations of the user's input or display (forced colours, contrast, the touch target floor) are not restyles of the vendor look. */
+const ACCESSIBILITY_MEDIA = /forced-colors|prefers-contrast|pointer:\s*coarse/;
+const OVERRIDE_KINDS = ['slot', 'style', 'default', 'role', 'canon'];
+const PARITY_MODES = ['strict', 'custom'];
+/** The ARIA roles HeroUI has a component for: a Grammar file that writes one by hand has hand-rolled that component. */
+const HEROUI_ROLES = new Set(['menu', 'menuitem', 'menuitemradio', 'menuitemcheckbox', 'listbox', 'option', 'combobox', 'dialog', 'alertdialog', 'tablist', 'tab', 'tabpanel', 'switch', 'slider', 'checkbox', 'radio', 'radiogroup']);
+const overrideKey = (kind, target) => `${kind}:${target}`;
+
+/** The vendor imports of a source: alias -> vendor component name. */
+export function importAliases(text) {
+  const aliases = new Map();
+  for (const match of text.matchAll(/import\s*\{([^}]*)\}\s*from\s*["']@heroui\/react["']/g)) {
+    for (const entry of match[1].split(',').map((part) => part.trim()).filter(Boolean)) {
+      const found = /^(?!type\s)(\w+)(?:\s+as\s+(\w+))?$/.exec(entry);
+      if (found) aliases.set(found[2] ?? found[1], found[1]);
+    }
+  }
+  return aliases;
+}
+
+/**
+ * The declared overrides as a ledger: `allowed(kind, target)` answers and remembers the use, so an override nothing needs is found stale.
+ * A `canon` override records a StarCi canon decision that is not vendor drift (the glyph size of the icon rule) for the owner; it permits nothing.
+ */
+function declaredOverrides(wrappers) {
+  const declared = new Map();
+  const used = new Set();
+  const problems = [];
+  for (const row of wrappers) {
+    for (const entry of row.overrides ?? []) {
+      if (OVERRIDE_KINDS.includes(entry?.kind) && entry.target && entry.reason) declared.set(overrideKey(entry.kind, entry.target), row.file);
+      else problems.push(finding('override', row.file, 0, `an override names its kind (${OVERRIDE_KINDS.join(', ')}), its target and its reason`));
+    }
+  }
+  const allowed = (kind, target) => {
+    const key = overrideKey(kind, target);
+    used.add(key);
+    return declared.has(key);
+  };
+  const stale = () => [...declared]
+    .filter(([key]) => !key.startsWith('canon:') && !used.has(key))
+    .map(([key, file]) => finding('stale', file, 0, `the override ${key} is declared but nothing needs it: remove it`));
+  return { allowed, stale, problems };
+}
+
+/** The Grammar a file belongs to (the longest declared path prefix), or undefined. */
+const grammarOf = (file, grammars) => grammars
+  .flatMap((grammar) => (grammar.paths ?? []).filter((prefix) => file.startsWith(prefix)).map((prefix) => ({ grammar, length: prefix.length })))
+  .sort((a, b) => b.length - a.length)[0]?.grammar;
+
+/** The malformed Grammar declarations and the files that belong to no declared Grammar. */
+function grammarFindings(grammars, files) {
+  const found = grammars
+    .filter((grammar) => !grammar.id || !Array.isArray(grammar.paths) || grammar.vendor?.name !== 'heroui' || !PARITY_MODES.includes(grammar.vendor?.parity))
+    .map((grammar) => finding('grammar', 'knowledge/vendor/heroui/wrappers.yaml', 0, `the Grammar ${grammar.id ?? '?'} declares an id, its paths and vendor: {name: heroui, parity: ${PARITY_MODES.join(' | ')}}`));
+  return [...found, ...files.filter((file) => grammarOf(file, grammars) === undefined).map((file) => finding('grammar', file, 0, 'belongs to no declared Grammar: declare it in the grammars of the wrapper manifest'))];
+}
+
+/** The ARIA roles a file writes by hand in JSX (comments excluded) that HeroUI has a component for. */
+function roleFindings({ file, text, allowed }) {
+  const code = text.replaceAll(/\/\*[\s\S]*?\*\//g, (comment) => comment.replaceAll(/[^\n]/g, ' ')).replaceAll(/\/\/[^\n]*/g, '');
+  const roles = [...code.matchAll(/\srole=["']([a-z]+)["']/g)].map((match) => match[1]).filter((role) => HEROUI_ROLES.has(role));
+  return [...new Set(roles)].filter((role) => !allowed('role', `${file}:${role}`)).map((role) => finding('role', file, 0, `hand-rolls role="${role}", which HeroUI has a component for: use it (override target role:${file}:${role})`));
+}
+
+/** The part findings of one wrapped component: parts that are not the vendor's, required parts left out, the divider between sections. */
+function anatomyFindings({ file, name, reference, mine, row, tags, aliases }) {
+  const found = [];
+  for (const tag of mine) {
+    if (tag.part !== 'Root' && !reference.anatomy.parts.includes(tag.part)) {
+      found.push(finding('anatomy', file, tag.line, `<${tag.alias}.${tag.part}> is not a part of HeroUI ${name} (parts: ${reference.anatomy.parts.join(', ') || 'none'})`));
+    }
+  }
+  const delegates = new Set(row.delegates?.[name] ?? []);
+  const rendered = new Set(mine.map((tag) => tag.part));
+  for (const part of reference.anatomy.required.filter((candidate) => !rendered.has(candidate) && !delegates.has(candidate))) {
+    found.push(finding('anatomy', file, 1, `omits ${name}.${part}, which HeroUI ${name} requires (render it, or declare it under delegates when the caller supplies it)`));
+  }
+  if (!rendered.has('Section')) return found;
+  for (const embed of reference.anatomy.embeds.filter((entry) => entry.slot === 'separator')) {
+    const separatorAliases = new Set([...aliases].filter(([, exported]) => exported === embed.component).map(([local]) => local));
+    if (!tags.some((tag) => separatorAliases.has(tag.alias))) {
+      found.push(finding('anatomy', file, 1, `renders ${name}.Section without HeroUI's ${embed.component} between sections (HeroUI styles its separator inside the menu)`));
+    }
+  }
+  return found;
+}
+
+/** The default findings: a prop of a part given a value of its closed set other than the vendor default. */
+function defaultFindings({ file, name, reference, mine, allowed }) {
+  const found = [];
+  for (const tag of mine) {
+    const part = reference.parts[tag.part];
+    for (const attr of part ? tag.attrs : []) {
+      const closedSet = part.values?.[attr.name];
+      const fallback = part.defaults?.[attr.name];
+      if (!closedSet || fallback === undefined) continue;
+      const odd = stringLiterals(attr.raw).filter((value) => closedSet.includes(value) && value !== fallback);
+      const target = [name, tag.part, attr.name].join('.');
+      if (odd.length && !allowed('default', target)) {
+        found.push(finding('default', file, tag.line, `${name}.${tag.part} ${attr.name}=${odd.map((value) => JSON.stringify(value)).join('|')} replaces the vendor default "${fallback}" (override target default:${target})`));
+      }
+    }
+  }
+  return found;
+}
+
+function wrapperFindings({ file, text, row, references, byName, allowed, strict }) {
+  const aliases = importAliases(text);
+  const components = [...new Set([...aliases.values()].filter((name) => byName.has(name)))].sort(byCodeUnit);
+  if (!row) return components.length ? [finding('undeclared', file, 1, `wraps ${components.join(', ')} but the wrapper manifest has no row for it`)] : [];
+  const found = [];
+  const declared = [...(row.wraps ?? [])].sort(byCodeUnit);
+  if (components.join(',') !== declared.join(',')) found.push(finding('undeclared', file, 1, `wraps ${components.join(', ') || 'nothing'} but its manifest row declares ${declared.join(', ') || 'nothing'}`));
+  const tags = heroTags(text, [...aliases.keys()]);
+  for (const name of components) {
+    const reference = references[byName.get(name)];
+    const locals = new Set([...aliases].filter(([, exported]) => exported === name).map(([local]) => local));
+    const mine = tags.filter((tag) => locals.has(tag.alias));
+    found.push(...anatomyFindings({ file, name, reference, mine, row, tags, aliases }), ...(strict ? defaultFindings({ file, name, reference, mine, allowed }) : []));
+  }
+  return found;
+}
+
+/** The stamps (class tokens and `data-grammar-*` names) each wrapped vendor part carries: stamp -> [{name, part, dir, file}]. */
+function stampsOf(sources, rows, byName, references, strictOf) {
+  const stamps = new Map();
+  const add = (key, entry) => stamps.set(key, [...(stamps.get(key) ?? []), entry]);
+  for (const { file, text } of sources.filter((source) => rows.get(source.file)?.styleParity && strictOf(source.file))) {
+    const aliases = importAliases(text);
+    for (const tag of heroTags(text, [...aliases.keys()])) {
+      const name = aliases.get(tag.alias);
+      const dir = byName.get(name);
+      if (dir === undefined || !references[dir].parts[tag.part]) continue;
+      const entry = { name, part: tag.part, dir, file };
+      classTokens(text, tag.attrs).forEach((token) => add(`.${token}`, entry));
+      tag.attrs.filter((attr) => attr.name.startsWith('data-grammar-')).forEach((attr) => add(`[${attr.name}]`, entry));
+    }
+  }
+  return stamps;
+}
+
+/** The vendor classes and data-slots Grammar CSS targets, as slot findings. */
+function slotFindings({ file, selector, vendor, allowed }) {
+  const found = [];
+  for (const cls of selectorClasses(selector).filter((candidate) => vendor.classes.has(candidate) && !allowed('slot', `.${candidate}`))) {
+    found.push(finding('slot', file, 0, `${selector} targets the vendor class .${cls} (override target slot:.${cls})`));
+  }
+  for (const attribute of selectorAttributes(selector)) {
+    if (attribute.name === 'data-slot' && vendor.slots.has(attribute.value) && !allowed('slot', attribute.value)) {
+      found.push(finding('slot', file, 0, `${selector} targets the vendor data-slot "${attribute.value}" (override target slot:${attribute.value})`));
+    }
+  }
+  return found;
+}
+
+/** The paint families Grammar CSS repaints on a vendor part through a stamp of the subject compound, as style findings. */
+function styleFindings({ file, selector, families, stamps, references, allowed }) {
+  const found = [];
+  const subject = subjectCompound(selector);
+  const tokens = [...selectorClasses(subject).map((cls) => `.${cls}`), ...selectorAttributes(subject).map((attribute) => `[${attribute.name}]`)];
+  for (const token of tokens) {
+    for (const entry of stamps.get(token) ?? []) {
+      const paints = references[entry.dir].parts[entry.part].paints;
+      for (const family of families.filter((candidate) => paints.includes(candidate))) {
+        const target = `${entry.name}.${entry.part}:${family}`;
+        if (!allowed('style', target)) found.push(finding('style', file, 0, `${selector} restyles ${family} of HeroUI ${entry.name}.${entry.part}, which the vendor decides (stamp ${token} on ${entry.file}; override target style:${target})`));
+      }
+    }
+  }
+  return found;
+}
+
+function cssFindings({ styles, references, stamps, allowed, strictOf }) {
+  const vendor = {
+    classes: new Set(Object.values(references).flatMap((reference) => reference.css.classes)),
+    slots: new Set(Object.values(references).flatMap((reference) => reference.css.dataSlots)),
+  };
+  const found = [];
+  for (const { file, text } of styles.filter((sheet) => strictOf(sheet.file))) {
+    for (const rule of cssRules(text)) {
+      const families = rule.wraps.some((wrap) => ACCESSIBILITY_MEDIA.test(wrap)) ? [] : ruleFamilies(rule);
+      for (const selector of rule.selectors) {
+        found.push(...slotFindings({ file, selector, vendor, allowed }), ...(families.length ? styleFindings({ file, selector, families, stamps, references, allowed }) : []));
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Every GRAMMAR_VENDOR_PARITY finding.
+ *   references  { <dir>: parsed vendor reference }
+ *   manifest    the parsed wrapper manifest ({schema, wrappers: [{file, wraps, delegates, styleParity, overrides}]})
+ *   sources     [{file, text}] Grammar .ts/.tsx (stories excluded), file relative to packages/grammar/src
+ *   styles      [{file, text}] every Grammar .css; a sheet is judged only when its Grammar declares `parity: strict`
+ */
+export function parityFindings({ references, manifest, sources, styles }) {
+  if (manifest?.schema !== WRAPPERS_SCHEMA) return [finding('manifest', 'knowledge/vendor/heroui/wrappers.yaml', 0, `schema must be ${WRAPPERS_SCHEMA}`)];
+  const wrappers = Array.isArray(manifest.wrappers) ? manifest.wrappers : [];
+  const byName = new Map(Object.entries(references).map(([dir, reference]) => [reference.component, dir]));
+  const rows = new Map(wrappers.map((row) => [row.file, row]));
+  const known = new Set(sources.map((source) => source.file));
+  const { allowed, stale, problems } = declaredOverrides(wrappers);
+  const grammars = Array.isArray(manifest.grammars) ? manifest.grammars : [];
+  const strictOf = (file) => grammarOf(file, grammars)?.vendor?.parity === 'strict';
+  return [
+    ...grammarFindings(grammars, [...sources, ...styles].map((source) => source.file)),
+    ...wrappers.filter((row) => !known.has(row.file)).map((row) => finding('undeclared', row.file, 0, 'the manifest names a file that does not exist')),
+    ...problems,
+    ...sources.flatMap(({ file, text }) => [
+      ...wrapperFindings({ file, text, row: rows.get(file), references, byName, allowed, strict: strictOf(file) }),
+      ...roleFindings({ file, text, allowed }),
+    ]),
+    ...cssFindings({ styles, references, stamps: stampsOf(sources, rows, byName, references, strictOf), allowed, strictOf }),
+    ...stale(),
+  ];
+}
+
+/** Pin findings: the manifest differs from the digest the latest owner ruling that pins it records. */
+export function pinFindings({ file, text, pinned }) {
+  if (pinned === undefined) return [finding('pin', file, 0, 'no owner ruling pins this manifest: an owner ruling records its sha256')];
+  const digest = manifestDigest(text);
+  return digest === pinned ? [] : [finding('pin', file, 0, `its digest ${digest.slice(0, 12)} is not the one the owner pinned (${String(pinned).slice(0, 12)}): only an owner ruling may add an override or change a row`)];
+}

package/runtime/scripts/lib/guard-command.mjs

@@ -0,0 +1,24 @@
+// guard-command.mjs — the one spelling of the hook command that registers a StarCi guard verb with an agent host.
+//
+// A host chooses the shell that runs a hook. The linked runtime supplies the absolute CLI path shared by launch trust
+// and preflight. Hook deadlines belong to the guard process; shell termination does not bound native children on Windows.
+import process from 'node:process';
+import path from 'node:path';
+import { readRuntimeRecord } from './runtime-location.mjs';
+
+const GUARD_COMMAND_END = /starci(?:\.mjs|\.cmd)?"? guard command$/;
+const quotedPath = (file) => `"${String(file).replaceAll('\\', '/')}"`;
+
+/** The command guard hook for the linked runtime; a missing or stale runtime record refuses registration. */
+export function toolGuardCommand({ home, nodePath = process.execPath, cliPath = null } = {}) {
+  if (!cliPath) {
+    const skipped = [];
+    const installed = readRuntimeRecord({ home, skipped });
+    if (!installed) throw new Error(skipped.join('; ') || 'no linked runtime; run starci runtime link');
+    cliPath = path.join(installed.root, 'packages', 'cli', 'bin', 'starci.mjs');
+  }
+  return `${quotedPath(nodePath)} ${quotedPath(cliPath)} guard command`;
+}
+
+/** Recognize the direct Node hook and launcher spellings so trust preparation replaces an older registered guard. */
+export const isGuardCommand = (command) => GUARD_COMMAND_END.test(String(command ?? ''));

package/runtime/scripts/lib/hook-limits.mjs

@@ -0,0 +1,5 @@
+import fs from 'node:fs';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+/** The shared hook lifetime and input limits, read from their protected contract. */
+export const HOOK_INPUT_LIMITS = Object.freeze(parseYaml(fs.readFileSync(new URL('../../modules/kernel/hook-input.yaml', import.meta.url), 'utf8')));

package/runtime/scripts/lib/interrupt-cleanup.mjs

@@ -0,0 +1,38 @@
+// interrupt-cleanup.mjs - the one owner of "what a long verb leaves behind when it is interrupted". A verb that creates something outside its own return path (a lock, a temp file,
+// a container) registers the undo with `onInterrupt(undo)`; the undo runs when the process receives SIGINT, SIGTERM, SIGBREAK or SIGHUP (then the process exits with 128 + the signal number)
+// and when the process exits while the registration is still open, and never twice. The returned disposer removes the registration once the verb released the thing itself.
+// The process handlers are installed with the first registration and removed with the last. The registry takes the process as a seam (`proc`: on, off, exit).
+const SIGNALS = Object.freeze({ SIGHUP: 1, SIGINT: 2, SIGTERM: 15, SIGBREAK: 21 });
+
+/** A registry of undo functions bound to `proc`. */
+function createInterruptRegistry({ proc = process } = {}) {
+  const undos = new Set();
+  const handlers = new Map();
+
+  const runAll = () => {
+    for (const undo of [...undos].reverse()) {
+      undos.delete(undo);
+      try { undo(); } catch { /* one failing undo never stops the others */ }
+    }
+  };
+  const uninstall = () => {
+    for (const [event, handler] of handlers) proc.off(event, handler);
+    handlers.clear();
+  };
+  const install = () => {
+    if (handlers.size) return;
+    for (const [signal, number] of Object.entries(SIGNALS)) handlers.set(signal, () => { runAll(); uninstall(); proc.exit(128 + number); });
+    handlers.set('exit', runAll);
+    for (const [event, handler] of handlers) proc.on(event, handler);
+  };
+
+  /** Register `undo`; returns the disposer that removes it (and the process handlers when it was the last). */
+  const onInterrupt = (undo) => {
+    undos.add(undo);
+    install();
+    return () => { undos.delete(undo); if (!undos.size) uninstall(); };
+  };
+  return { onInterrupt, pending: () => undos.size };
+}
+
+export const { onInterrupt } = createInterruptRegistry();

package/runtime/scripts/lib/js-lex.mjs

@@ -0,0 +1,200 @@
+// js-lex.mjs - reads a JavaScript, TypeScript or stylesheet source as three layers: its code, its comments and its string contents.
+// A scanner that looks for a spelling in text (a bypass marker, a command in a string) needs to know which layer the spelling is in: a marker
+// quoted inside a string or a template literal is data, a marker at the start of a comment is a directive, a marker in code is a call.
+// One pass, no dependency, no AST: strings (single, double, template with nested `${}`), line and block comments and regular expression
+// literals are told apart by the previous significant character; a `)` that closes an `if`, `while`, `for` or `with` head is followed by a
+// statement, so a `/` after it opens a regular expression. A line ends at \n, \r, U+2028 and U+2029, as in JavaScript. A quote with no closing
+// quote on its line is not a string (an apostrophe in JSX text or prose), so it cannot swallow a comment behind it.
+const REGEX_AFTER = new Set(['', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '<', '>', '~', '^']);
+const REGEX_KEYWORDS = new Set(['return', 'typeof', 'case', 'delete', 'void', 'throw', 'in', 'of', 'else', 'yield', 'await']);
+const HEAD_KEYWORDS = new Set(['if', 'while', 'for', 'with']);
+const LINE_SEPARATOR = String.fromCodePoint(0x2028);
+const PARAGRAPH_SEPARATOR = String.fromCodePoint(0x2029);
+const LINE_BREAKS = new Set(['\n', '\r', LINE_SEPARATOR, PARAGRAPH_SEPARATOR]);
+const LINE_SPLIT = new RegExp(String.raw`\r\n|[\n\r${LINE_SEPARATOR}${PARAGRAPH_SEPARATOR}]`);
+const isBreak = (char) => LINE_BREAKS.has(char);
+
+/** What `kind` of source this is: `css` has block comments only, `scss` and `less` add line comments, anything else is script. */
+export const langOf = (file) => {
+  if (file.endsWith('.css')) return 'css';
+  if (/\.(?:scss|less)$/.test(file)) return 'scss';
+  return 'script';
+};
+
+const NOT_A_BREAK = new RegExp(String.raw`[^\n\r${LINE_SEPARATOR}${PARAGRAPH_SEPARATOR}]`, 'g');
+const blank = (text) => text.replace(NOT_A_BREAK, ' ');
+
+/** The index right after the last non-blank character before `end` (a scan back over blanks only, so a long source stays linear). */
+function contentEnd(code, end) {
+  let stop = end;
+  while (stop > 0 && /\s/.test(code[stop - 1])) stop -= 1;
+  return stop;
+}
+
+/** The word that ends at `end` of `code` (letters, digits, `$`, `_`). */
+function wordBefore(code, end) {
+  let start = end;
+  while (start > 0 && /[\w$]/.test(code[start - 1])) start -= 1;
+  return code.slice(start, end);
+}
+
+class Reader {
+  constructor(text, lang) {
+    this.text = text;
+    this.lang = lang;
+    this.at = 0;
+    this.line = 1;
+    this.code = '';
+    this.comments = [];
+    this.strings = [];
+    this.lastSignificant = '';
+    this.heads = [];
+    this.headClosed = false;
+  }
+
+  /** Consumes `count` characters as non-code (blanked in `code`). */
+  skip(count) {
+    const piece = this.text.slice(this.at, this.at + count);
+    this.code += blank(piece);
+    this.advanceLines(piece);
+    this.at += count;
+  }
+
+  advanceLines(piece) {
+    for (let index = 0; index < piece.length; index += 1) {
+      if (piece[index] === '\r' && piece[index + 1] === '\n') continue;
+      if (isBreak(piece[index])) this.line += 1;
+    }
+  }
+
+  /** Consumes one code character. */
+  take() {
+    const char = this.text[this.at];
+    this.code += char;
+    if (isBreak(char)) { if (!(char === '\r' && this.text[this.at + 1] === '\n')) this.line += 1; } else if (!/\s/.test(char)) this.trackParens(char);
+    this.at += 1;
+  }
+
+  /** Remembers which parenthesis closes the head of an if, while, for or with: a statement, and so possibly a regular expression, follows it. */
+  trackParens(char) {
+    this.headClosed = false;
+    if (char === '(') this.heads.push(HEAD_KEYWORDS.has(wordBefore(this.code, contentEnd(this.code, this.code.length - 1))));
+    else if (char === ')') this.headClosed = this.heads.pop() === true;
+    this.lastSignificant = char;
+  }
+
+  regexAllowed() {
+    if (this.lastSignificant === ')') return this.headClosed;
+    if (!REGEX_AFTER.has(this.lastSignificant)) return REGEX_KEYWORDS.has(wordBefore(this.code, contentEnd(this.code, this.code.length)));
+    return true;
+  }
+
+  lineEnd(from) {
+    let end = from;
+    while (end < this.text.length && !isBreak(this.text[end])) end += 1;
+    return end;
+  }
+
+  lineComment() {
+    const stop = this.lineEnd(this.at);
+    this.comments.push({ line: this.line, text: this.text.slice(this.at + 2, stop), first: true, last: true, block: false });
+    this.skip(stop - this.at);
+  }
+
+  blockComment() {
+    const close = this.text.indexOf('*/', this.at + 2);
+    const stop = close < 0 ? this.text.length : close + 2;
+    const body = this.text.slice(this.at + 2, close < 0 ? stop : close);
+    const pieces = body.split(LINE_SPLIT);
+    pieces.forEach((piece, index) => this.comments.push({ line: this.line + index, text: piece, first: index === 0, last: index === pieces.length - 1, block: true }));
+    this.skip(stop - this.at);
+  }
+
+  quoted(quote) {
+    let end = this.at + 1;
+    while (end < this.text.length && this.text[end] !== quote && !isBreak(this.text[end])) end += this.text[end] === '\\' ? 2 : 1;
+    if (this.text[end] !== quote) { this.take(); return; }
+    this.strings.push({ line: this.line, at: this.at + 1, text: this.text.slice(this.at + 1, end) });
+    this.skip(end + 1 - this.at);
+    this.lastSignificant = quote;
+  }
+
+  regex() {
+    let end = this.at + 1;
+    let inClass = false;
+    while (end < this.text.length && !isBreak(this.text[end])) {
+      const char = this.text[end];
+      if (char === '\\') end += 1;
+      else if (char === '[') inClass = true;
+      else if (char === ']') inClass = false;
+      else if (char === '/' && !inClass) break;
+      end += 1;
+    }
+    if (this.text[end] !== '/') { this.take(); return; }
+    end += 1;
+    while (/[a-z]/i.test(this.text[end] ?? '')) end += 1;
+    this.skip(end - this.at);
+    this.lastSignificant = '/';
+  }
+
+  /** A template literal: the text pieces are strings, each `${ ... }` is code again. */
+  template() {
+    this.skip(1);
+    let piece = '';
+    let from = this.at;
+    const flush = () => { this.strings.push({ line: this.line, at: from, text: piece }); piece = ''; };
+    while (this.at < this.text.length && this.text[this.at] !== '`') {
+      if (this.text[this.at] === '\\') { piece += this.text.slice(this.at, this.at + 2); this.skip(2); continue; }
+      if (this.text[this.at] === '$' && this.text[this.at + 1] === '{') {
+        flush();
+        this.skip(2);
+        this.expression();
+        from = this.at;
+        continue;
+      }
+      piece += this.text[this.at];
+      this.skip(1);
+    }
+    flush();
+    if (this.text[this.at] === '`') this.skip(1);
+    this.lastSignificant = '`';
+  }
+
+  /** Code up to the `}` that closes the current `${`. */
+  expression() {
+    let depth = 0;
+    while (this.at < this.text.length) {
+      const char = this.text[this.at];
+      if (char === '}' && depth === 0) { this.skip(1); return; }
+      if (char === '{') depth += 1;
+      else if (char === '}') depth -= 1;
+      this.step();
+    }
+  }
+
+  step() {
+    const char = this.text[this.at];
+    const next = this.text[this.at + 1];
+    if (char === '/' && next === '*') this.blockComment();
+    else if (char === '/' && next === '/' && this.lang !== 'css') this.lineComment();
+    else if (char === '"' || char === "'") this.quoted(char);
+    else if (char === '`' && this.lang === 'script') this.template();
+    else if (char === '/' && this.lang === 'script' && this.regexAllowed()) this.regex();
+    else this.take();
+  }
+
+  run() {
+    while (this.at < this.text.length) this.step();
+    return { code: this.code, comments: this.comments, strings: this.strings };
+  }
+}
+
+/**
+ * `text` as { code, comments, strings }. `code` is the source with every comment, string and regular expression blanked (same length, same
+ * lines); `comments` are { line, text, first, last } per physical line of each comment (the text without its opener; `first` and `last`
+ * mark the ends of a block comment); `strings` are { line, at, text } per string or template piece, the content without its quotes and its offset.
+ */
+export const lexSource = (text, lang = 'script') => new Reader(String(text ?? ''), lang).run();
+
+/** `text` as its physical lines (a line ends at \n, \r\n, \r, U+2028 and U+2029). */
+export const splitLines = (text) => String(text ?? '').split(LINE_SPLIT);

package/runtime/scripts/lib/json-formats.mjs

@@ -26,7 +26,6 @@ export const JSON_FORMATS = Object.freeze([
   { id: 'package-scripts-fragment', tool: 'npm (scripts rendered into package.json)', match: (rel) => /^packages\/hfs\/templates\/app\/package-scripts[^/]*\/[^/]+\.json$/.test(rel) },
   { id: 'async-event-contract', tool: 'starci app emit', match: (rel) => /(^|\/)be\/contracts\/[^/]+\/events(\.pin)?\.json$/.test(rel) },
   { id: 'operation-contract', tool: 'starci app emit', match: (rel) => /(^|\/)be\/contracts\/[^/]+\/openapi\.json$/.test(rel) },
-  { id: 'model-scorecard-snapshot', tool: 'scripts/agent/benchmark-snapshot.mjs', match: (rel) => /^benchmark\/snapshots\/[^/]+\.json$/.test(rel) },
 ]);
 
 /** The declared format that fixes `rel`, or null: the file is authored JSON the check must refuse. */