@starci/hfs 4.7.32 → 4.7.33

package/runtime/scripts/lib/cli-arg.mjs

@@ -0,0 +1,120 @@
+// cli-arg.mjs — the `--name value` and `--flag` readers of the thin CLI entries (the scripts/api call files run as
+// commands, scripts/agent/send.mjs). Pure.
+import { textLine } from './escape.mjs';
+
+/** The value after `--<name>` in argv, else `fallback`. */
+export const arg = (argv, name, fallback = null) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 ? argv[i + 1] : fallback;
+};
+
+/** True when argv holds `--<name>`. */
+export const flag = (argv, name) => argv.includes(`--${name}`);
+
+/** The token after the literal `token` in argv, else `fallback` (absent or last). */
+export const valueAfter = (argv, token, fallback = null) => {
+  const i = argv.indexOf(token);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : fallback;
+};
+
+/**
+ * The `--name value` / boolean-flag scan the multi-option CLIs share: `spec` maps each accepted token to a setter
+ * `(opts, take)` where `take()` consumes the next token as the value (a missing one reports
+ * `<token> needs a value` through `fail`); boolean flags are setters that never call `take`. An unrecognized
+ * token reports `unrecognized argument: <token>` through `fail` (its return is ignored, so a non-throwing `fail`
+ * keeps scanning). Returns `opts`.
+ */
+export function parseOpts(argv, spec, fail) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    const set = spec[token];
+    if (!set) { fail(`unrecognized argument: ${token}`); continue; }
+    const take = () => {
+      i += 1;
+      if (argv[i] === undefined) fail(`${token} needs a value`);
+      return argv[i];
+    };
+    set(opts, take);
+  }
+  return opts;
+}
+
+/**
+ * The `--<name> value` pairs of `names` read from argv: every other token, a missing value and a `--`-led value throw
+ * an error suffixed with `usage`.
+ */
+export const valueFlags = (argv, names, usage) => {
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (names.includes(arg)) {
+      if (argv[i + 1] === undefined || argv[i + 1].startsWith('--')) throw new Error(`${arg} needs a value; ${usage}`);
+      opts[arg.slice(2)] = argv[++i];
+    } else throw new Error(`unknown argument ${arg}; ${usage}`);
+  }
+  return opts;
+};
+
+/** A parseOpts `fail` that throws `Error(message)`. */
+export const argThrow = (message) => { throw new Error(message); };
+
+/** Throw `Error('--<name> is required')` for the first of `names` `args` lacks a value for. */
+export const needArgs = (args, names) => {
+  for (const name of names) if (!args[name]) throw new Error(`--${name} is required`);
+};
+
+/** Setter entries the `.starciwork`-record CLIs share: `--work <dir> --record <id> --cwd <dir>`. */
+export const workRecordSpec = {
+  '--work': (o, take) => { o.work = take(); },
+  '--record': (o, take) => { o.record = take(); },
+  '--cwd': (o, take) => { o.cwd = take(); },
+};
+
+/** `--work --record --cwd` for the example-record CLIs; throws on an unknown token or a missing value. */
+export function parseExampleArgs(argv) {
+  const args = parseOpts(argv, workRecordSpec, argThrow);
+  needArgs(args, ['work', 'record', 'cwd']);
+  return args;
+}
+
+/** Setter entries the record-scoped op CLIs share: `--op`, `--records` (csv, accumulated), `--state`, `--json`, `--help`/`-h` (calls `help`). */
+const opRecordSpec = (help) => ({
+  '--op': (o, take) => { o.op = take(); },
+  '--records': (o, take) => { o.records = [...(o.records ?? []), ...take().split(',')]; },
+  '--state': (o, take) => { o.state = take(); },
+  '--json': (o) => { o.json = true; },
+  '--help': () => help(), '-h': () => help(),
+});
+
+/** The final value of an accumulated `--records` list: trimmed, blanks dropped, deduplicated. */
+const recordsList = (args) => [...new Set((args.records ?? []).map((s) => s.trim()).filter(Boolean))];
+
+/**
+ * The `usage` + `parseArgs` pair the record-scoped op CLIs share: `usage` prints `usageText` to stderr and exits
+ * with the code; `parseArgs` scans the opRecordSpec options plus the CLI's own `spec` setters and resolves
+ * `records` to its deduplicated list (recordsList).
+ */
+export function opCli(usageText, spec) {
+  const usage = (code) => { console.error(usageText); process.exit(code); };
+  const parseArgs = (argv) => {
+    const a = parseOpts(argv, { ...opRecordSpec(() => usage(0)), ...spec }, () => usage(2));
+    a.records = recordsList(a);
+    return a;
+  };
+  return { usage, parseArgs };
+}
+
+/**
+ * The prelude the multi-verb lesson CLIs share (scripts/machine/lessons.mjs, scripts/supervisor/lesson-actions.mjs):
+ * `verb` is argv[0]; `value(n)` the token after `--n` (null when absent); `csv(v)` a trimmed non-empty list;
+ * `print(result, human)` logs the JSON record under `--json`, else the human text: one string is one line, an array
+ * holds one element per line; control characters inside a line (CR, LF, escape sequences) print as \uXXXX.
+ */
+export function verbCli(argv = process.argv.slice(2)) {
+  const value = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] ?? null : null; };
+  const csv = (v) => String(v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  const asJson = argv.includes('--json');
+  const print = (r, human) => console.log(asJson ? JSON.stringify(r) : [human].flat().map((line) => textLine(line)).join('\n'));
+  return { argv, verb: argv[0], value, csv, asJson, print };
+}

package/runtime/scripts/lib/css-rules.mjs

@@ -0,0 +1,220 @@
+// css-rules.mjs - a flat reading of a stylesheet: every style rule with its resolved selector, its `@apply` utilities and its
+// declarations, nesting (`&`) and wrapping at-rules (@layer, @media, @supports) resolved. Pure: text in, rules out.
+// The reader of the vendor CSS (scripts/work/ui/vendor-heroui.mjs) and of Grammar's own CSS (scripts/lib/grammar-vendor-parity.mjs).
+
+import { byCodeUnit } from './list.mjs';
+
+const SKIPPED_AT_RULES = new Set(['keyframes', 'property', 'font-face', 'counter-style', 'page', 'theme', 'utility', 'custom-variant', 'variant', 'source', 'plugin', 'config']);
+
+/** The text without `/* ... *\/` comments. */
+export const stripCssComments = (text) => String(text).replaceAll(/\/\*[\s\S]*?\*\//g, '');
+
+/** Split `text` at top-level `separator` characters (outside parentheses, brackets and quotes). */
+export function splitTopLevel(text, separator) {
+  const parts = [];
+  let depth = 0;
+  let quote = '';
+  let start = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (quote) {
+      if (char === '\\') index += 1;
+      else if (char === quote) quote = '';
+    } else if (char === '"' || char === "'") quote = char;
+    else if (char === '(' || char === '[') depth += 1;
+    else if (char === ')' || char === ']') depth -= 1;
+    else if (char === separator && depth === 0) {
+      parts.push(text.slice(start, index));
+      start = index + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts.map((part) => part.trim()).filter(Boolean);
+}
+
+/** The matching `}` of the `{` at `open`, or the text length. */
+function blockEnd(text, open) {
+  let depth = 0;
+  let quote = '';
+  for (let index = open; index < text.length; index += 1) {
+    const char = text[index];
+    if (quote) {
+      if (char === '\\') index += 1;
+      else if (char === quote) quote = '';
+    } else if (char === '"' || char === "'") quote = char;
+    else if (char === '{') depth += 1;
+    else if (char === '}') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return text.length;
+}
+
+/** One block body as its declarations (statements) and its child blocks (prelude + body). */
+function members(body) {
+  const statements = [];
+  const blocks = [];
+  let cursor = 0;
+  let statementStart = 0;
+  while (cursor < body.length) {
+    const char = body[cursor];
+    if (char === ';') {
+      statements.push(body.slice(statementStart, cursor).trim());
+      statementStart = cursor + 1;
+    } else if (char === '{') {
+      const end = blockEnd(body, cursor);
+      blocks.push({ prelude: body.slice(statementStart, cursor).trim(), body: body.slice(cursor + 1, end) });
+      cursor = end;
+      statementStart = end + 1;
+    } else if (char === '"' || char === "'") {
+      let next = cursor + 1;
+      while (next < body.length && body[next] !== char) next += body[next] === '\\' ? 2 : 1;
+      cursor = next;
+    }
+    cursor += 1;
+  }
+  const tail = body.slice(statementStart).trim();
+  if (tail) statements.push(tail);
+  return { statements: statements.filter(Boolean), blocks };
+}
+
+/** Resolve a nested selector list against its parent selector list (`&` is the parent; no `&` means a descendant). */
+function resolveSelectors(parents, prelude) {
+  const own = splitTopLevel(prelude, ',');
+  if (!parents.length) return own;
+  return parents.flatMap((parent) => own.map((selector) => (selector.includes('&') ? selector.replaceAll('&', parent) : `${parent} ${selector}`)));
+}
+
+function ruleFromStatements(selectors, wraps, statements) {
+  const apply = [];
+  const declarations = [];
+  for (const statement of statements) {
+    if (statement.startsWith('@apply ')) apply.push(...statement.slice(7).split(/\s+/).filter(Boolean));
+    else {
+      const colon = statement.indexOf(':');
+      if (colon > 0 && !statement.startsWith('@')) declarations.push({ property: statement.slice(0, colon).trim(), value: statement.slice(colon + 1).trim().replaceAll(/\s+/g, ' ') });
+    }
+  }
+  return { selectors, wraps, apply, declarations };
+}
+
+function collect(body, parents, wraps, out) {
+  const { statements, blocks } = members(body);
+  if (parents.length && (statements.length > 0)) out.push(ruleFromStatements(parents, wraps, statements));
+  for (const block of blocks) {
+    if (block.prelude.startsWith('@')) {
+      const name = /^@([\w-]+)/.exec(block.prelude)?.[1] ?? '';
+      if (SKIPPED_AT_RULES.has(name)) continue;
+      collect(block.body, parents, [...wraps, block.prelude.replaceAll(/\s+/g, ' ')], out);
+    } else collect(block.body, resolveSelectors(parents, block.prelude), wraps, out);
+  }
+}
+
+/**
+ * Every style rule of `text`: `{selectors, wraps, apply, declarations}`. `selectors` are fully resolved, `wraps` the at-rule preludes
+ * (`@media (forced-colors: active)`, `@layer x`) the rule sits in, `apply` the `@apply` utilities and `declarations` the plain properties.
+ */
+export function cssRules(text) {
+  const out = [];
+  collect(stripCssComments(text), [], [], out);
+  return out;
+}
+
+/** The subject compound of a selector: the part after the last combinator, outside brackets and parentheses. */
+export function subjectCompound(selector) {
+  let depth = 0;
+  let cut = 0;
+  for (const [index, char] of [...selector].entries()) {
+    if (char === '(' || char === '[') depth += 1;
+    else if (char === ')' || char === ']') depth -= 1;
+    else if (depth === 0 && (char === ' ' || char === '>' || char === '+' || char === '~')) cut = index + 1;
+  }
+  return selector.slice(cut).trim();
+}
+
+/** The selector split into the text outside `[...]` and the bodies inside them. */
+function bracketParts(selector) {
+  const outside = [];
+  const bodies = [];
+  let open = -1;
+  for (const [index, char] of [...selector].entries()) {
+    if (char === '[' && open < 0) open = index;
+    else if (char === ']' && open >= 0) {
+      bodies.push(selector.slice(open + 1, index));
+      open = -1;
+    } else if (open < 0) outside.push(char);
+  }
+  return { outside: outside.join(''), bodies };
+}
+
+/** The `.class` names a selector mentions, outside attribute brackets. */
+export function selectorClasses(selector) {
+  return [...bracketParts(selector).outside.matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)].map((match) => match[1]);
+}
+
+/** The `[data-...]` attribute names a selector mentions. */
+export function selectorAttributes(selector) {
+  return bracketParts(selector).bodies.map((raw) => {
+    const body = raw.trim();
+    const equals = body.indexOf('=');
+    const name = (equals < 0 ? body : body.slice(0, equals)).replace(/[~|^$*]$/, '').trim();
+    const value = equals < 0 ? null : body.slice(equals + 1).trim().replaceAll(/^["']|["']$/g, '');
+    return { name, value };
+  });
+}
+
+const FAMILY_BY_PROPERTY = [
+  [/^padding/, 'padding'],
+  [/^margin/, 'margin'],
+  [/^border-(?:top-|bottom-|start-|end-)*(?:start-|end-)*radius$|^border-radius$/, 'radius'],
+  [/^background/, 'background'],
+  [/^color$/, 'color'],
+  [/^(?:border|outline)/, 'border'],
+  [/^box-shadow$/, 'shadow'],
+  [/^(?:min-|max-)?(?:block-size|height)$/, 'block-size'],
+  [/^(?:min-|max-)?(?:inline-size|width)$/, 'inline-size'],
+  [/^(?:font|line-height|letter-spacing|text-transform)/, 'font'],
+  [/^(?:row-|column-)?gap$/, 'gap'],
+  [/^opacity$/, 'opacity'],
+];
+
+/** The paint family a CSS property belongs to (`padding-inline` is `padding`), or the property itself. */
+export function propertyFamily(property) {
+  const name = String(property).trim().toLowerCase();
+  if (name.startsWith('--')) return null;
+  return FAMILY_BY_PROPERTY.find(([pattern]) => pattern.test(name))?.[1] ?? name;
+}
+
+const TEXT_SIZES = /^(?:xs|sm|base|lg|xl|[2-9]xl|\[.*\])$/;
+const TEXT_FLOW = /^(?:left|center|right|start|end|justify|wrap|nowrap|balance|pretty|ellipsis|clip)$/;
+const UTILITY_FAMILIES = [
+  [/^(?:p|px|py|ps|pe|pt|pb|pl|pr)-/, ['padding']],
+  [/^-?(?:m|mx|my|ms|me|mt|mb|ml|mr)-/, ['margin']],
+  [/^rounded/, ['radius']],
+  [/^bg-/, ['background']],
+  [/^(?:min-h|max-h|h)-/, ['block-size']],
+  [/^(?:min-w|max-w|w)-/, ['inline-size']],
+  [/^size-/, ['block-size', 'inline-size']],
+  [/^(?:gap|gap-x|gap-y)-/, ['gap']],
+  [/^(?:border|ring|outline)(?:-|$)/, ['border']],
+  [/^(?:shadow)(?:-|$)/, ['shadow']],
+  [/^(?:font|leading|tracking)-/, ['font']],
+  [/^opacity-/, ['opacity']],
+];
+
+/** The paint families one `@apply` utility sets (`ps-7` is `padding`, `text-muted` is `color`); an unrecognised utility sets none. */
+export function utilityFamilies(utility) {
+  const bare = String(utility).replace(/^(?:[^\s:]+:)+/, '').replace(/^!/, '').replace(/!$/, '');
+  if (bare.startsWith('text-')) {
+    const rest = bare.slice(5);
+    if (TEXT_SIZES.test(rest)) return ['font'];
+    return TEXT_FLOW.test(rest) ? [] : ['color'];
+  }
+  return UTILITY_FAMILIES.find(([pattern]) => pattern.test(bare))?.[1] ?? [];
+}
+
+/** The paint families a rule sets, from its `@apply` utilities and its declarations. */
+export function ruleFamilies(rule) {
+  return [...new Set([...rule.apply.flatMap(utilityFamilies), ...rule.declarations.map((entry) => propertyFamily(entry.property)).filter(Boolean)])].sort(byCodeUnit);
+}

package/runtime/scripts/lib/dom-tree.mjs

@@ -0,0 +1,4 @@
+// dom-tree.mjs — walks over the draw checkers' parsed-DOM element shape ({tag, attrs, parent}).
+
+/** The ancestors of `el`, nearest first, stopping below the '#root' sentinel. */
+export const ancestorsOf = (el) => { const out = []; for (let p = el.parent; p && p.tag !== '#root'; p = p.parent) { out.push(p); } return out; };

package/runtime/scripts/lib/escape.mjs

@@ -0,0 +1,16 @@
+// escape.mjs — the escapes for text embedded in another syntax: HTML entities for markup (Telegram HTML, report blocks), one-line JSON for logs.
+
+/** `s` with &, < and > entity-escaped. */
+export const escapeHtml = (s) => String(s ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+
+/** `c` (one character) with a C0 control character or U+2028/2029 written as \uXXXX. */
+const visibleChar = (c) => {
+  const n = c.codePointAt(0);
+  return n < 0x20 || n === 0x2028 || n === 0x2029 ? String.raw`\u${n.toString(16).padStart(4, '0')}` : c;
+};
+
+/** `value` as JSON on ONE log line: CR, LF, every other C0 control character and U+2028/2029 written as \uXXXX (JSON.stringify already does so for C0 inside strings, so well-formed data prints byte-identically). */
+export const logLine = (value) => Array.from(String(JSON.stringify(value)), visibleChar).join('');
+
+/** `text` as ONE plain line: CR, LF and every other control character except the tab written as \uXXXX; ordinary text, quotes and backslashes print unchanged. */
+export const textLine = (text) => Array.from(String(text ?? ''), (c) => (c === '\t' ? c : visibleChar(c))).join('');

package/runtime/scripts/lib/event-items.mjs

@@ -0,0 +1,22 @@
+// event-items.mjs - the open items of an owed/resolved event pair, replayed from a workflow ledger (read only).
+
+/**
+ * The workflow's open items of an owed/resolved event pair (grammar proposals, asset slots): replay the kinds in seq
+ * order — a `resolvedKind` row deletes the item `keyOf` names, an `owedKind` row sets `item(payload,row)`; a row
+ * whose key is falsy is skipped. Returns the open items in first-seen order, [] when the table cannot be read.
+ */
+export function openEventItems(db,workflowId,{owedKind,resolvedKind,keyOf,item}){
+  let rows=[];
+  try{rows=db.prepare('SELECT kind,payload_json,created_at FROM events WHERE workflow_id=? AND kind IN (?,?) ORDER BY seq').all(workflowId,owedKind,resolvedKind);}
+  catch{return[];}
+  const open=new Map();
+  for(const row of rows){
+    let p={};
+    try{p=JSON.parse(row.payload_json??'{}')??{};}catch{p={};}
+    const key=keyOf(p);
+    if(!key)continue;
+    if(row.kind===resolvedKind){open.delete(key);continue;}
+    open.set(key,item(p,row));
+  }
+  return[...open.values()];
+}

package/runtime/scripts/lib/failure-code-template-errors.mjs

@@ -0,0 +1,161 @@
+// Canonical platform templates can own shared application failures as well as runtime findings.
+// A catalog entry stays current only when production code instantiates its genuine DomainError enum member.
+import path from 'node:path';
+
+const CODE = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/;
+const exported = (t, node) => node.modifiers?.some((modifier) => modifier.kind === t.SyntaxKind.ExportKeyword);
+const textName = (t, node) => node && (t.isIdentifier(node) || t.isStringLiteralLike(node)) ? node.text : null;
+
+/** An import path resolves inside the virtual backend source tree declared by the pattern files. */
+function sourceTarget(specifier, owner, sources) {
+  let target = null;
+  if (specifier.startsWith('@modules/')) target = `src/modules/${specifier.slice('@modules/'.length)}`;
+  else if (specifier.startsWith('.')) target = path.posix.normalize(path.posix.join(path.posix.dirname(owner), specifier));
+  if (target === null) return null;
+  return [target, `${target}.ts`, `${target}/index.ts`].find((candidate) => sources.has(candidate)) ?? null;
+}
+
+/** Index module bindings and explicit exports without importing or running a template. */
+function moduleInfo(t, name, entry) {
+  const source = t.createSourceFile(name, entry.text, t.ScriptTarget.Latest, true, t.ScriptKind.TS);
+  const info = { name, file: entry.file, source, imports: new Map(), namespaces: new Map(), locals: new Map(), exports: new Map(), shadows: new Set() };
+  for (const statement of source.statements) {
+    if (t.isImportDeclaration(statement)) indexImport(t, info, statement);
+    if (t.isExportDeclaration(statement)) indexExport(t, info, statement);
+    if ((t.isEnumDeclaration(statement) || t.isClassDeclaration(statement)) && statement.name) {
+      const key = statement.name.text;
+      info.locals.set(key, statement);
+      if (exported(t, statement)) info.exports.set(key, { local: key });
+    }
+  }
+  const visit = (node) => {
+    const binding = scopedBinding(t, node);
+    if (binding) info.shadows.add(binding);
+    t.forEachChild(node, visit);
+  };
+  visit(source);
+  return info;
+}
+
+/** A nested declaration makes a text-only binding ambiguous; it cannot supply catalog evidence. */
+function scopedBinding(t, node) {
+  const named = t.isVariableDeclaration(node) || t.isParameter(node) || t.isBindingElement(node)
+    || t.isClassDeclaration(node) || t.isEnumDeclaration(node) || t.isFunctionDeclaration(node);
+  if (!named || !node.name || !t.isIdentifier(node.name)) return null;
+  let scope = node.parent;
+  while (scope && !t.isSourceFile(scope)) {
+    if (t.isBlock(scope) || t.isFunctionLike(scope)) return node.name.text;
+    scope = scope.parent;
+  }
+  return null;
+}
+
+function indexImport(t, info, statement) {
+  const bindings = statement.importClause?.namedBindings;
+  if (!bindings || !t.isStringLiteralLike(statement.moduleSpecifier)) return;
+  const specifier = statement.moduleSpecifier.text;
+  if (t.isNamespaceImport(bindings)) info.namespaces.set(bindings.name.text, specifier);
+  else for (const binding of bindings.elements) info.imports.set(binding.name.text, { name: (binding.propertyName ?? binding.name).text, specifier });
+}
+
+function indexExport(t, info, statement) {
+  const clause = statement.exportClause;
+  if (!clause || !t.isNamedExports(clause)) return;
+  const specifier = statement.moduleSpecifier && t.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
+  for (const binding of clause.elements) {
+    const name = (binding.propertyName ?? binding.name).text;
+    info.exports.set(binding.name.text, specifier ? { name, specifier } : { local: name });
+  }
+}
+
+/** Only a declared binding or a named import/export can establish an error family or enum identity. */
+function localValue(info, name, modules, seen = new Set()) {
+  const identity = `${info.name}:${name}`;
+  if (seen.has(identity) || info.shadows.has(name)) return null;
+  const visited = new Set(seen).add(identity);
+  if (info.locals.has(name)) return { info, declaration: info.locals.get(name) };
+  const binding = info.imports.get(name);
+  return binding ? importedValue(info, binding, modules, visited) : null;
+}
+
+function importedValue(info, binding, modules, seen) {
+  const target = sourceTarget(binding.specifier, info.name, modules);
+  const owner = target && modules.get(target);
+  const identity = owner && `export:${owner.name}:${binding.name}`;
+  if (!owner || seen.has(identity)) return null;
+  const visited = new Set(seen).add(identity);
+  const exposed = owner?.exports.get(binding.name);
+  if (!exposed) return null;
+  return exposed.local ? localValue(owner, exposed.local, modules, visited) : importedValue(owner, exposed, modules, visited);
+}
+
+const accessParts = (t, expression) => {
+  if (t.isPropertyAccessExpression(expression) || t.isQualifiedName(expression)) {
+    return { base: expression.expression ?? expression.left, member: (expression.name ?? expression.right).text };
+  }
+  if (t.isElementAccessExpression(expression) && t.isStringLiteralLike(expression.argumentExpression)) return { base: expression.expression, member: expression.argumentExpression.text };
+  return null;
+};
+
+function expressionValue(t, info, expression, modules) {
+  if (t.isIdentifier(expression)) return localValue(info, expression.text, modules);
+  const access = accessParts(t, expression);
+  const specifier = access && t.isIdentifier(access.base) && !info.shadows.has(access.base.text) && info.namespaces.get(access.base.text);
+  return specifier ? importedValue(info, { specifier, name: access.member }, modules, new Set()) : null;
+}
+
+/** DomainError is the canonical imported base, not an identically named local class. */
+function domainBase(t, info, expression) {
+  if (!t.isIdentifier(expression)) return false;
+  const binding = info.imports.get(expression.text);
+  return !info.shadows.has(expression.text) && binding?.name === 'DomainError' && binding.specifier === '@modules/platform/errors';
+}
+
+/** The generic enum on the real DomainError base owns the family's permitted codes. */
+function errorEnum(t, value, modules) {
+  const node = value?.declaration;
+  if (!node || !t.isClassDeclaration(node) || node.members.some(t.isConstructorDeclaration)) return null;
+  const clause = node.heritageClauses?.find((item) => item.token === t.SyntaxKind.ExtendsKeyword);
+  const base = clause?.types[0];
+  const argument = base?.typeArguments?.[0];
+  if (!base || !domainBase(t, value.info, base.expression) || base.typeArguments?.length !== 1 || !argument || !t.isTypeReferenceNode(argument)) return null;
+  const enumeration = expressionValue(t, value.info, argument.typeName, modules);
+  return enumeration && t.isEnumDeclaration(enumeration.declaration) ? enumeration : null;
+}
+
+/** A static code field survives only when no later spread or dynamic key can replace it. */
+function codeField(t, expression) {
+  if (!expression || !t.isObjectLiteralExpression(expression)) return null;
+  let code = null;
+  for (const property of expression.properties) {
+    if (t.isSpreadAssignment(property) || textName(t, property.name) === null) code = null;
+    else if (textName(t, property.name) === 'code') code = t.isPropertyAssignment(property) ? property.initializer : null;
+  }
+  return code;
+}
+
+/** Constructor and code expression must resolve to the same declared enum, including through public barrels. */
+function constructedCode(t, info, node, modules) {
+  const family = errorEnum(t, expressionValue(t, info, node.expression, modules), modules);
+  const field = codeField(t, node.arguments?.[0]);
+  const access = field && accessParts(t, field);
+  const enumeration = access && expressionValue(t, info, access.base, modules);
+  if (!family || !enumeration || enumeration.declaration !== family.declaration) return null;
+  const member = family.declaration.members.find((item) => textName(t, item.name) === access.member);
+  return member?.initializer && t.isStringLiteralLike(member.initializer) && CODE.test(member.initializer.text) ? member.initializer.text : null;
+}
+
+/** Actual typed error constructions in declared production platform templates, with their source locations. */
+export function templateErrorCodes(t, sources) {
+  const modules = new Map([...sources].map(([name, entry]) => [name, moduleInfo(t, name, entry)]));
+  const emitted = new Map();
+  for (const info of modules.values()) {
+    const visit = (node) => {
+      const code = t.isNewExpression(node) && constructedCode(t, info, node, modules);
+      if (code) emitted.set(code, { code, file: info.file, line: info.source.getLineAndCharacterOfPosition(node.getStart(info.source)).line + 1 });
+      t.forEachChild(node, visit);
+    };
+    visit(info.source);
+  }
+  return [...emitted.values()];
+}

package/runtime/scripts/lib/git-dir.mjs

@@ -0,0 +1,120 @@
+// git-dir.mjs — a checkout's git directory and the git processes that may hold it, read without running git: the pure
+// half of the stale `.git/index.lock` recovery (scripts/api/git/index-lock.mjs indexLock removes the lock;
+// scripts/machine/lock-recovery.mjs reads the process table, records the removal and runs the command guard's pre-flight).
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathKey } from './path-key.mjs';
+
+/** git.exe and its helpers (git-remote-https.exe, git-lfs.exe, ...). */
+const GIT_IMAGE = /^git(?:-[\w.-]+)?(?:\.exe)?$/i;
+/** Whether a process image name is git or one of its helpers. */
+export const isGitImage = (name) => GIT_IMAGE.test(String(name ?? ''));
+/** `file`'s lstat, or null when it cannot be read. */
+export const lockStat = (file) => { try { return fs.lstatSync(file); } catch { return null; } };
+
+const GITDIR_LINE = new RegExp([
+  '^gitdir:',
+  String.raw`\s*(.+)$`,
+].join(''), 'm');
+
+/** The git dir of the checkout at `repo`: `.git` itself, or the `gitdir:` a worktree's `.git` file names. Null when none. */
+export function gitDirOf(repo) {
+  const dotGit = path.join(path.resolve(repo), '.git');
+  let st;
+  try { st = fs.lstatSync(dotGit); } catch { return null; }
+  if (st.isDirectory()) return dotGit;
+  if (!st.isFile()) return null;
+  try {
+    const m = GITDIR_LINE.exec(fs.readFileSync(dotGit, 'utf8'));
+    return m ? path.resolve(path.dirname(dotGit), m[1].trim()) : null;
+  } catch { return null; }
+}
+
+/** The checkout `start` is in: the nearest directory at or above it holding `.git`, or null. */
+export function checkoutOf(start) {
+  for (let dir = path.resolve(String(start ?? '.')); ; dir = path.dirname(dir)) {
+    if (lockStat(path.join(dir, '.git'))) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+const FULL_SHA = /^[0-9a-f]{40}$/;
+
+function looseHeadRef(gitDir, common, ref, commonOnly) {
+  for (const dir of commonOnly ? [common] : [gitDir, common]) {
+    try {
+      const loose = fs.readFileSync(path.join(dir, ref), 'utf8').trim();
+      if (FULL_SHA.test(loose)) return loose;
+    } catch { /* packed */ }
+  }
+  return null;
+}
+
+function packedHeadRef(common, ref) {
+  for (const line of fs.readFileSync(path.join(common, 'packed-refs'), 'utf8').split('\n')) {
+    const [sha, name] = line.trim().split(' ');
+    if (name === ref && FULL_SHA.test(sha)) return sha;
+  }
+  return null;
+}
+
+const HEADS_REF_LINE = new RegExp([
+  String.raw`^ref:\s*(refs\/heads\/\S+)`,
+  '$',
+].join(''));
+const ANY_REF_LINE = new RegExp([
+  String.raw`^ref:\s*(.+)`,
+  '$',
+].join(''));
+/**
+ * The commit the HEAD of the checkout at `root` names, read from .git with no spawn; null when it cannot be told that
+ * way (not a top level, reftable, an unreadable ref) and the read then runs live. `headsOnly` accepts only
+ * refs/heads/* symbolic refs; a loose ref reads from the common dir, as git does for a linked worktree — plus the git
+ * dir itself first unless `commonOnly`.
+ */
+export function headShaOf(root, { headsOnly = false, commonOnly = false } = {}) {
+  try {
+    let gitDir = path.join(root, '.git');
+    if (fs.statSync(gitDir).isFile()) {
+      const pointer = GITDIR_LINE.exec(fs.readFileSync(gitDir, 'utf8'))?.[1];
+      if (!pointer) return null;
+      gitDir = path.resolve(root, pointer.trim());
+    }
+    const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
+    if (FULL_SHA.test(head)) return head;
+    const ref = headsOnly ? HEADS_REF_LINE.exec(head)?.[1] : ANY_REF_LINE.exec(head)?.[1]?.trim();
+    if (!ref) return null;
+    let common = gitDir;
+    try { common = path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim()); } catch { /* not a linked worktree */ }
+    const loose = looseHeadRef(gitDir, common, ref, commonOnly);
+    if (loose) return loose;
+    return packedHeadRef(common, ref);
+  } catch { /* no git metadata */ }
+  return null;
+}
+
+/** Command-line words, double quotes grouping (Windows command lines quote paths with spaces). */
+const words = (line) => [...String(line ?? '').matchAll(/"([^"]*)"|(\S+)/g)].map((m) => m[1] ?? m[2]);
+
+/** The repositories a git command line names by -C, --git-dir or --work-tree (as given, unresolved). */
+function reposNamed(commandLine) {
+  const w = words(commandLine), out = [];
+  for (let i = 0; i < w.length; i += 1) {
+    if (w[i] === '-C' || w[i] === '--git-dir' || w[i] === '--work-tree') { if (w[i + 1]) { out.push(w[i + 1]); } i += 1; continue; }
+    const m = /^--(?:git-dir|work-tree)=(.+)$/.exec(w[i]);
+    if (m) out.push(m[1]);
+  }
+  return out;
+}
+
+/**
+ * Whether one git process may hold `repo`'s index: 'this' (it names the repo or a path inside it), 'other'
+ * (every repository it names is elsewhere) or 'unknown' (it names none; its cwd may be this repo).
+ */
+export function processOnRepo(proc, repo) {
+  const named = reposNamed(proc?.commandLine);
+  if (!named.length) return 'unknown';
+  const key = pathKey(path.resolve(repo));
+  const hit = named.some((p) => { const k = pathKey(path.resolve(p)); return k === key || k.startsWith(`${key}/`) || key.startsWith(`${k}/`); });
+  return hit ? 'this' : 'other';
+}