@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/lib/dockerfile.mjs

@@ -2,146 +2,163 @@
 // one statement per logical line (a trailing backslash continues it, comment lines inside a continuation are dropped), the
 // instruction keyword is the first word, the stages open at each FROM. Parser directives (`# syntax=`, `# escape=`) and
 // comments are kept apart from the instructions. Here-documents are not part of the subset the canon uses and are read as text.
-
 /** Split a shell-form or exec-form argument string into its words (quotes group a word and are removed). */
 export function words(text) {
-  const out = [];
-  let current = '';
-  let quote = null;
-  let started = false;
-  for (const char of text) {
-    if (quote) {
-      if (char === quote) quote = null;
-      else current += char;
-    } else if (char === '"' || char === "'") {
-      quote = char;
-      started = true;
-    } else if (char === ' ' || char === '\t' || char === '\n') {
-      if (started || current) out.push(current);
-      current = '';
-      started = false;
-    } else {
-      current += char;
+    const out = [];
+    let current = '';
+    let quote = null;
+    let started = false;
+    for (const char of text) {
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            else
+                current += char;
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+            started = true;
+        }
+        else if (char === ' ' || char === '\t' || char === '\n') {
+            if (started || current)
+                out.push(current);
+            current = '';
+            started = false;
+        }
+        else {
+            current += char;
+        }
     }
-  }
-  if (started || current) out.push(current);
-  return out;
+    if (started || current)
+        out.push(current);
+    return out;
 }
-
 /** The exec-form array of an instruction's argument text (`["node", "x.js"]`), or null when it is not a JSON array of strings. */
 export function execForm(text) {
-  const trimmed = text.trim();
-  if (!trimmed.startsWith('[')) return null;
-  try {
-    const value = JSON.parse(trimmed);
-    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : null;
-  } catch {
-    return null;
-  }
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('['))
+        return null;
+    try {
+        const value = JSON.parse(trimmed);
+        return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : null;
+    }
+    catch {
+        return null;
+    }
 }
-
 /** The commands of a shell-form RUN body: the text split at `&&`, `||`, `;` and `|` outside quotes, each as its words. */
 export function shellCommands(body) {
-  const commands = [];
-  let current = '';
-  let quote = null;
-  const flush = () => {
-    const parts = words(current);
-    if (parts.length) commands.push(parts);
-    current = '';
-  };
-  for (let i = 0; i < body.length; i += 1) {
-    const char = body[i];
-    if (quote) {
-      current += char;
-      if (char === quote) quote = null;
-    } else if (char === '"' || char === "'") {
-      quote = char;
-      current += char;
-    } else if (isCommandSeparator(body, i, char)) {
-      i += commandSeparatorAdvance(body, i, char);
-      flush();
-    } else if (char === '\\' && body[i + 1] === '\n') {
-      i += 1;
-    } else {
-      current += char;
+    const commands = [];
+    let current = '';
+    let quote = null;
+    const flush = () => {
+        const parts = words(current);
+        if (parts.length)
+            commands.push(parts);
+        current = '';
+    };
+    for (let i = 0; i < body.length; i += 1) {
+        const char = body.charAt(i);
+        if (quote) {
+            current += char;
+            if (char === quote)
+                quote = null;
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+            current += char;
+        }
+        else if (isCommandSeparator(body, i, char)) {
+            i += commandSeparatorAdvance(body, i, char);
+            flush();
+        }
+        else if (char === '\\' && body[i + 1] === '\n') {
+            i += 1;
+        }
+        else {
+            current += char;
+        }
     }
-  }
-  flush();
-  return commands;
+    flush();
+    return commands;
 }
-
 const isCommandSeparator = (body, index, char) => char === ';' || char === '|' || (char === '&' && body[index + 1] === '&');
 const commandSeparatorAdvance = (body, index, char) => char !== ';' && body[index + 1] === char ? 1 : 0;
-
 /**
  * Parse a Dockerfile: { instructions: [{ keyword, text, line, stage }], stages: [{ index, name, image, line, instructions }],
  * comments: [{ text, line }], preamble: [instruction before the first FROM (ARG)] }. `keyword` is upper-case; `text` is the
  * argument text of the logical line; `stage` is the index of the stage the instruction belongs to (-1 before the first FROM).
  */
 export function parseDockerfile(source) {
-  const lines = String(source).replaceAll('\r\n', '\n').split('\n');
-  const { instructions, comments } = parseInstructions(lines);
-  const stages = [];
-  const preamble = [];
-  for (const instruction of instructions) {
-    if (instruction.keyword === 'FROM') {
-      const parts = words(instruction.text).filter((part) => !part.startsWith('--'));
-      const asAt = parts.findIndex((part, index) => index > 0 && part.toUpperCase() === 'AS');
-      stages.push({ index: stages.length, name: asAt > 0 ? parts[asAt + 1] ?? null : null, image: parts[0] ?? '', line: instruction.line, instructions: [] });
+    const lines = String(source).replaceAll('\r\n', '\n').split('\n');
+    const { instructions, comments } = parseInstructions(lines);
+    const stages = [];
+    const preamble = [];
+    for (const instruction of instructions) {
+        if (instruction.keyword === 'FROM') {
+            const parts = words(instruction.text).filter((part) => !part.startsWith('--'));
+            const asAt = parts.findIndex((part, index) => index > 0 && part.toUpperCase() === 'AS');
+            stages.push({ index: stages.length, name: asAt > 0 ? parts[asAt + 1] ?? null : null, image: parts[0] ?? '', line: instruction.line, instructions: [] });
+        }
+        instruction.stage = stages.length - 1;
+        if (stages.length)
+            stages.at(-1).instructions.push(instruction);
+        else
+            preamble.push(instruction);
     }
-    instruction.stage = stages.length - 1;
-    if (stages.length) stages.at(-1).instructions.push(instruction);
-    else preamble.push(instruction);
-  }
-  return { instructions, stages, comments, preamble };
+    return { instructions, stages, comments, preamble };
 }
-
 function parseInstructions(lines) {
-  const instructions = [];
-  const comments = [];
-  const state = { escape: '\\', directives: true };
-  let i = 0;
-  while (i < lines.length) {
-    const parsed = parseInstructionLine(lines, i, state);
-    if (parsed.comment) comments.push(parsed.comment);
-    if (parsed.instruction) instructions.push(parsed.instruction);
-    i = parsed.nextLine + 1;
-  }
-  return { instructions, comments };
+    const instructions = [];
+    const comments = [];
+    const state = { escape: '\\', directives: true };
+    let i = 0;
+    while (i < lines.length) {
+        const parsed = parseInstructionLine(lines, i, state);
+        if (parsed.comment)
+            comments.push(parsed.comment);
+        if (parsed.instruction)
+            instructions.push(parsed.instruction);
+        i = parsed.nextLine + 1;
+    }
+    return { instructions, comments };
 }
-
 function parseInstructionLine(lines, index, state) {
-  const trimmed = lines[index].trim();
-  if (trimmed === '') { state.directives = false; return { nextLine: index }; }
-  if (trimmed.startsWith('#')) return parseCommentLine(trimmed, index, state);
-  state.directives = false;
-  const { logical, nextLine } = logicalInstructionOf(lines, index, state.escape);
-  const split = logical.search(/\s/);
-  const keyword = (split < 0 ? logical : logical.slice(0, split)).toUpperCase();
-  return { nextLine, instruction: { keyword, text: split < 0 ? '' : logical.slice(split).trim(), line: index + 1, stage: -1 } };
+    const trimmed = lines[index].trim();
+    if (trimmed === '') {
+        state.directives = false;
+        return { nextLine: index };
+    }
+    if (trimmed.startsWith('#'))
+        return parseCommentLine(trimmed, index, state);
+    state.directives = false;
+    const { logical, nextLine } = logicalInstructionOf(lines, index, state.escape);
+    const split = logical.search(/\s/);
+    const keyword = (split < 0 ? logical : logical.slice(0, split)).toUpperCase();
+    return { nextLine, instruction: { keyword, text: split < 0 ? '' : logical.slice(split).trim(), line: index + 1, stage: -1 } };
 }
-
 function parseCommentLine(trimmed, index, state) {
-  const body = trimmed.slice(1).trim();
-  const directive = state.directives ? /^(syntax|escape|check)\s*=\s*(\S+)$/i.exec(body) : null;
-  if (directive) {
-    if (directive[1].toLowerCase() === 'escape') state.escape = directive[2];
-    return { nextLine: index };
-  }
-  state.directives = false;
-  return { nextLine: index, comment: { text: body, line: index + 1 } };
+    const body = trimmed.slice(1).trim();
+    const directive = state.directives ? /^(syntax|escape|check)\s*=\s*(\S+)$/i.exec(body) : null;
+    if (directive) {
+        if (directive[1].toLowerCase() === 'escape')
+            state.escape = directive[2];
+        return { nextLine: index };
+    }
+    state.directives = false;
+    return { nextLine: index, comment: { text: body, line: index + 1 } };
 }
-
 function logicalInstructionOf(lines, index, escape) {
-  let logical = lines[index].trim();
-  let nextLine = index;
-  while (logical.endsWith(escape) && nextLine + 1 < lines.length) {
-    logical = logical.slice(0, -1).trimEnd();
-    nextLine += 1;
-    while (nextLine < lines.length && lines[nextLine].trim().startsWith('#')) nextLine += 1;
-    if (nextLine >= lines.length) break;
-    logical = `${logical} ${lines[nextLine].trim()}`;
-  }
-  return { logical, nextLine };
+    let logical = lines[index].trim();
+    let nextLine = index;
+    while (logical.endsWith(escape) && nextLine + 1 < lines.length) {
+        logical = logical.slice(0, -1).trimEnd();
+        nextLine += 1;
+        while (nextLine < lines.length && lines[nextLine].trim().startsWith('#'))
+            nextLine += 1;
+        if (nextLine >= lines.length)
+            break;
+        logical = `${logical} ${lines[nextLine].trim()}`;
+    }
+    return { logical, nextLine };
 }

package/runtime/scripts/lib/dom-tree.d.mts

@@ -0,0 +1,7 @@
+/** The ancestors of `el`, nearest first, stopping below the '#root' sentinel. */
+export interface DomElement {
+    tag: string;
+    attrs: Record<string, string>;
+    parent: DomElement | null;
+}
+export declare const ancestorsOf: (el: DomElement) => DomElement[];

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

@@ -1,4 +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; };
+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/env.d.mts

@@ -0,0 +1,12 @@
+/** The value of the environment variable `name` in `env` (default: the process environment), or undefined. */
+export declare const readEnv: (name: string, env?: NodeJS.ProcessEnv) => string | undefined;
+/** True when `env` (default: the process environment) belongs to a spec run (`node --test` marks its children with NODE_TEST_CONTEXT). */
+export declare const isSpecRun: (env?: NodeJS.ProcessEnv) => boolean;
+/**
+ * The environment for a child that is itself a test runner: `env` without the mark of an enclosing spec run. A `node --test` that inherits NODE_TEST_CONTEXT believes it is a
+ * subtest of that run: it reports to its parent and exits 0 whatever its tests did, so a verb that runs specs as a child (the package clean-test, the scaffold e2e, the release cut)
+ * would pass red specs from inside a test process. The runner marks the spec files it starts itself, so isSpecRun stays true inside them.
+ */
+export declare function withoutTestRunner(env?: NodeJS.ProcessEnv): {
+    [key: string]: string | undefined;
+};

package/runtime/scripts/lib/env.mjs

@@ -2,20 +2,17 @@
 // modules/schemas/env.yaml catalogues every variable with its purpose and kind. Production code reads a variable here
 // (readEnv) or takes an injected `env` parameter; it never reads `process.env.NAME` itself. The test runner is observed
 // in exactly one place, isSpecRun: code that must not touch the host's real state during a spec asks it.
-
 /** The value of the environment variable `name` in `env` (default: the process environment), or undefined. */
 export const readEnv = (name, env = process.env) => env[name];
-
 /** True when `env` (default: the process environment) belongs to a spec run (`node --test` marks its children with NODE_TEST_CONTEXT). */
 export const isSpecRun = (env = process.env) => Boolean(env.NODE_TEST_CONTEXT);
-
 /**
  * The environment for a child that is itself a test runner: `env` without the mark of an enclosing spec run. A `node --test` that inherits NODE_TEST_CONTEXT believes it is a
  * subtest of that run: it reports to its parent and exits 0 whatever its tests did, so a verb that runs specs as a child (the package clean-test, the scaffold e2e, the release cut)
  * would pass red specs from inside a test process. The runner marks the spec files it starts itself, so isSpecRun stays true inside them.
  */
 export function withoutTestRunner(env = process.env) {
-  const rest = { ...env };
-  delete rest.NODE_TEST_CONTEXT;
-  return rest;
+    const rest = { ...env };
+    delete rest.NODE_TEST_CONTEXT;
+    return rest;
 }

package/runtime/scripts/lib/escape.d.mts

@@ -0,0 +1,6 @@
+/** `s` with &, < and > entity-escaped. */
+export declare const escapeHtml: (s?: unknown) => string;
+/** `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 declare const logLine: (value: unknown) => string;
+/** `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 declare const textLine: (text?: unknown) => string;

package/runtime/scripts/lib/escape.mjs

@@ -1,16 +1,12 @@
 // 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;
+    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-contract.d.mts

@@ -0,0 +1,21 @@
+import type { TypeScript } from './ts-ast.mjs';
+/** One event class of a service: its wire name, version, the event it compensates (if any) and its payload fields. */
+export interface EventClassRecord {
+    className: string;
+    name: string;
+    version: number;
+    compensates?: string;
+    payload: Record<string, string>;
+}
+/**
+ * The event classes of one source text: `{ events: [{ className, name, version, compensates, payload }], problems: [text] }`. A class is an event
+ * when it declares `static readonly eventName`; `version` is required, `create(payload: <Interface>)` names the payload.
+ */
+export declare function readEventClasses(ts: TypeScript, text: string, file?: string): {
+    events: EventClassRecord[];
+    problems: string[];
+};
+/** The text of the snapshot of a service from its event classes: 2-space JSON, sorted keys, one final newline. */
+export declare function snapshotText(service: string, events: readonly EventClassRecord[]): string;
+/** The snapshot's text with line endings folded, for comparing a committed file to a fresh one. */
+export declare const folded: (text: string) => string;

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

@@ -1,107 +1,102 @@
-// event-contract.mjs - the async contract between the services of one product (R166 HFS_EVENT_CONTRACT).
-// The one source of the contract is the typed event classes of a service, `be/src/modules/events/<service>/<event>.event.ts`:
-//   export interface OrderPlacedPayload { readonly orderId: string; readonly totalMinorUnits: number }
-//   export class OrderPlacedEvent extends BaseEvent {
-//     static readonly eventName = "order.placed"; static readonly version = 1
-//     static readonly compensates = "order.placed"            // only an event that reports the failure of a step
-//     static create(payload: OrderPlacedPayload): OrderPlacedEvent { ... }
-//   }
-// `starci app emit` writes `be/contracts/<service>/events.json` from them (name, version, compensates, and the payload fields of the
-// interface `create` takes); `starci app check` compares the committed file with the same reader. Nothing is executed: both walk the TypeScript
-// syntax tree. The functions take the `ts` module the caller loaded (the repository's own, else the runtime's); this file imports only the code-unit comparator.
 import { byCodeUnit } from './list.mjs';
-
 const EVENT_CONTRACT_SCHEMA = 'starci/event-contract@1';
 const FIELD_TYPE = /^(?:string|number|boolean|string\[\]|number\[\])\??$/;
-
 const hasStatic = (ts, member) => member.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword) === true;
-
 /** The literal of a `static readonly <name> = <literal>` member: `{ text }` for a string, `{ number }` for an integer, or null. */
 function staticLiteral(ts, member) {
-  if (!ts.isPropertyDeclaration(member) || !hasStatic(ts, member) || !ts.isIdentifier(member.name) || member.initializer === undefined) return null;
-  let value = member.initializer;
-  while (ts.isAsExpression(value) || ts.isParenthesizedExpression(value)) value = value.expression;
-  if (ts.isStringLiteralLike(value)) return { name: member.name.text, text: value.text };
-  if (ts.isNumericLiteral(value) && Number.isInteger(Number(value.text))) return { name: member.name.text, number: Number(value.text) };
-  return null;
+    if (!ts.isPropertyDeclaration(member) || !hasStatic(ts, member) || !ts.isIdentifier(member.name) || member.initializer === undefined)
+        return null;
+    let value = member.initializer;
+    while (ts.isAsExpression(value) || ts.isParenthesizedExpression(value))
+        value = value.expression;
+    if (ts.isStringLiteralLike(value))
+        return { name: member.name.text, text: value.text };
+    if (ts.isNumericLiteral(value) && Number.isInteger(Number(value.text)))
+        return { name: member.name.text, number: Number(value.text) };
+    return null;
 }
-
 /** The text of a type node when it is one of the wire field types (`string`, `number`, `boolean`, `string[]`, `number[]`), else null. */
 function fieldType(ts, node) {
-  if (node.kind === ts.SyntaxKind.StringKeyword) return 'string';
-  if (node.kind === ts.SyntaxKind.NumberKeyword) return 'number';
-  if (node.kind === ts.SyntaxKind.BooleanKeyword) return 'boolean';
-  if (ts.isArrayTypeNode(node)) {
-    const element = fieldType(ts, node.elementType);
-    return element === 'string' || element === 'number' ? `${element}[]` : null;
-  }
-  return null;
+    if (node.kind === ts.SyntaxKind.StringKeyword)
+        return 'string';
+    if (node.kind === ts.SyntaxKind.NumberKeyword)
+        return 'number';
+    if (node.kind === ts.SyntaxKind.BooleanKeyword)
+        return 'boolean';
+    if (ts.isArrayTypeNode(node)) {
+        const element = fieldType(ts, node.elementType);
+        return element === 'string' || element === 'number' ? `${element}[]` : null;
+    }
+    return null;
 }
-
 function appendPayloadMember(ts, member, typeName, problems, where, payload) {
-  if (!ts.isPropertySignature(member) || !ts.isIdentifier(member.name) || member.type === undefined) {
-    problems.push(`${where}: the payload ${typeName} holds a member that is not \`name: type\``);
-    return;
-  }
-  const type = fieldType(ts, member.type);
-  let written = null;
-  if (type !== null) written = `${type}${member.questionToken ? '?' : ''}`;
-  if (written === null || !FIELD_TYPE.test(written)) problems.push(`${where}: payload field ${member.name.text} must be string, number, boolean, string[] or number[]`);
-  else payload[member.name.text] = written;
+    if (!ts.isPropertySignature(member) || !ts.isIdentifier(member.name) || member.type === undefined) {
+        problems.push(`${where}: the payload ${typeName} holds a member that is not \`name: type\``);
+        return;
+    }
+    const type = fieldType(ts, member.type);
+    let written = null;
+    if (type !== null)
+        written = `${type}${member.questionToken ? '?' : ''}`;
+    if (written === null || !FIELD_TYPE.test(written))
+        problems.push(`${where}: payload field ${member.name.text} must be string, number, boolean, string[] or number[]`);
+    else
+        payload[member.name.text] = written;
 }
-
 /** The payload fields of the interface or type literal named `typeName` in the file: `{ <field>: <type> }`, optional fields with a `?`. */
 function payloadOf(ts, sourceFile, typeName, problems, where) {
-  let members = null;
-  for (const statement of sourceFile.statements) {
-    if (ts.isInterfaceDeclaration(statement) && statement.name.text === typeName) members = statement.members;
-    if (ts.isTypeAliasDeclaration(statement) && statement.name.text === typeName && ts.isTypeLiteralNode(statement.type)) members = statement.type.members;
-  }
-  if (members === null) {
-    problems.push(`${where}: the payload type ${typeName} is not an interface or type literal of the file`);
-    return {};
-  }
-  const payload = {};
-  for (const member of members) appendPayloadMember(ts, member, typeName, problems, where, payload);
-  return payload;
+    let members = null;
+    for (const statement of sourceFile.statements) {
+        if (ts.isInterfaceDeclaration(statement) && statement.name.text === typeName)
+            members = statement.members;
+        if (ts.isTypeAliasDeclaration(statement) && statement.name.text === typeName && ts.isTypeLiteralNode(statement.type))
+            members = statement.type.members;
+    }
+    if (members === null) {
+        problems.push(`${where}: the payload type ${typeName} is not an interface or type literal of the file`);
+        return {};
+    }
+    const payload = {};
+    for (const member of members)
+        appendPayloadMember(ts, member, typeName, problems, where, payload);
+    return payload;
 }
-
 /**
  * The event classes of one source text: `{ events: [{ className, name, version, compensates, payload }], problems: [text] }`. A class is an event
  * when it declares `static readonly eventName`; `version` is required, `create(payload: <Interface>)` names the payload.
  */
 export function readEventClasses(ts, text, file = 'event.ts') {
-  const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-  const events = [];
-  const problems = [];
-  for (const statement of sourceFile.statements) {
-    if (!ts.isClassDeclaration(statement) || statement.name === undefined) continue;
-    const literals = statement.members.map((member) => staticLiteral(ts, member)).filter((literal) => literal !== null);
-    const name = literals.find((literal) => literal.name === 'eventName')?.text;
-    if (name === undefined) continue;
-    const className = statement.name.text;
-    const version = literals.find((literal) => literal.name === 'version')?.number;
-    const compensates = literals.find((literal) => literal.name === 'compensates')?.text;
-    if (version === undefined || version < 1) problems.push(`${className} needs \`static readonly version\` as a positive integer`);
-    const create = statement.members.find((member) => ts.isMethodDeclaration(member) && hasStatic(ts, member) && ts.isIdentifier(member.name) && member.name.text === 'create');
-    const parameter = create?.parameters[0]?.type;
-    if (parameter === undefined || !ts.isTypeReferenceNode(parameter) || !ts.isIdentifier(parameter.typeName)) {
-      problems.push(`${className} needs \`static create(payload: <Interface>)\` naming its payload interface`);
-      continue;
+    const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const events = [];
+    const problems = [];
+    for (const statement of sourceFile.statements) {
+        if (!ts.isClassDeclaration(statement) || statement.name === undefined)
+            continue;
+        const literals = statement.members.map((member) => staticLiteral(ts, member)).filter((literal) => literal !== null);
+        const name = literals.find((literal) => literal.name === 'eventName')?.text;
+        if (name === undefined)
+            continue;
+        const className = statement.name.text;
+        const version = literals.find((literal) => literal.name === 'version')?.number;
+        const compensates = literals.find((literal) => literal.name === 'compensates')?.text;
+        if (version === undefined || version < 1)
+            problems.push(`${className} needs \`static readonly version\` as a positive integer`);
+        const create = statement.members.find((member) => ts.isMethodDeclaration(member) && hasStatic(ts, member) && ts.isIdentifier(member.name) && member.name.text === 'create');
+        const parameter = create?.parameters[0]?.type;
+        if (parameter === undefined || !ts.isTypeReferenceNode(parameter) || !ts.isIdentifier(parameter.typeName)) {
+            problems.push(`${className} needs \`static create(payload: <Interface>)\` naming its payload interface`);
+            continue;
+        }
+        events.push({ className, name, version: version ?? 0, ...(compensates === undefined ? {} : { compensates }), payload: payloadOf(ts, sourceFile, parameter.typeName.text, problems, className) });
     }
-    events.push({ className, name, version: version ?? 0, ...(compensates === undefined ? {} : { compensates }), payload: payloadOf(ts, sourceFile, parameter.typeName.text, problems, className) });
-  }
-  return { events, problems };
+    return { events, problems };
 }
-
 /** The sorted object: keys in code-point order, recursively (what the snapshot prints). */
 const sorted = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.keys(value).sort(byCodeUnit).map((key) => [key, sorted(value[key])])) : value);
-
 /** The text of the snapshot of a service from its event classes: 2-space JSON, sorted keys, one final newline. */
 export function snapshotText(service, events) {
-  const table = Object.fromEntries(events.map(({ name, version, compensates, payload }) => [name, { version, payload, ...(compensates === undefined ? {} : { compensates }) }]));
-  return `${JSON.stringify(sorted({ schema: EVENT_CONTRACT_SCHEMA, service, events: table }), null, 2)}\n`;
+    const table = Object.fromEntries(events.map(({ name, version, compensates, payload }) => [name, { version, payload, ...(compensates === undefined ? {} : { compensates }) }]));
+    return `${JSON.stringify(sorted({ schema: EVENT_CONTRACT_SCHEMA, service, events: table }), null, 2)}\n`;
 }
-
 /** The snapshot's text with line endings folded, for comparing a committed file to a fresh one. */
 export const folded = (text) => text.replaceAll('\r\n', '\n');

package/runtime/scripts/lib/event-items.d.mts

@@ -0,0 +1,20 @@
+import type { SqliteDb } from './sqlite.mjs';
+/** The payload of a workflow event, parsed from its ledger column (an open record: each event kind carries its own fields). */
+export type EventPayload = Record<string, unknown>;
+/** The columns of an event row this replay reads. */
+export interface EventRow {
+    kind: string;
+    payload_json: string | null;
+    created_at: string;
+}
+/**
+ * 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 declare function openEventItems<Item>(db: SqliteDb, workflowId: unknown, { owedKind, resolvedKind, keyOf, item }: {
+    owedKind: string;
+    resolvedKind: string;
+    keyOf: (payload: EventPayload) => unknown;
+    item: (payload: EventPayload, row: EventRow) => Item;
+}): Item[];