@starci/hfs 4.0.7 → 4.0.9

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

@@ -0,0 +1,429 @@
+// graphql-contract.mjs - the GraphQL a back-end contract snapshot holds and the checks a front-end document must pass
+// against it. It reads the SDL `starci app emit` writes (`be/contracts/<service>/schema.graphql`: object, input, enum,
+// scalar, interface and union types, descriptions and directives) and the executable documents a front end keeps in
+// `.graphql` files (operations with variables, field arguments, object literals, inline fragments), with no dependency:
+// the runtime ships no GraphQL library, and an app's own install is not always resolvable from where hfs runs.
+//
+// What a document is checked for: every selected field exists on its parent type, every argument it passes is declared
+// and every required argument (or required input field of an object literal) is given, an object literal names only
+// declared input fields, a variable passed to an argument has the argument's named type, a leaf field selects nothing
+// and an object field selects something, and every declared variable is used. Validation stops at the first failure of
+// each field path, so a broken document reads as a short list of named problems.
+
+const PUNCTUATORS = new Set(['{', '}', '(', ')', '[', ']', ':', '!', '=', '$', '@', '|', '&']);
+const BUILT_IN_SCALARS = new Set(['String', 'Int', 'Float', 'Boolean', 'ID']);
+
+/** The tokens of a GraphQL source: names, punctuators, `...`, strings and numbers; comments and commas are insignificant. */
+export function tokenize(source) {
+  const tokens = [];
+  let index = 0;
+  while (index < source.length) {
+    const char = source[index];
+    if (char === '#') {
+      while (index < source.length && source[index] !== '\n') index += 1;
+    } else if (/[\s,]/.test(char)) {
+      index += 1;
+    } else if (source.startsWith('...', index)) {
+      tokens.push({ kind: 'spread', value: '...' });
+      index += 3;
+    } else if (source.startsWith('"""', index)) {
+      const end = source.indexOf('"""', index + 3);
+      if (end === -1) throw new SyntaxError('unterminated block string');
+      tokens.push({ kind: 'string', value: source.slice(index + 3, end) });
+      index = end + 3;
+    } else if (char === '"') {
+      let end = index + 1;
+      while (end < source.length && source[end] !== '"') end += source[end] === '\\' ? 2 : 1;
+      tokens.push({ kind: 'string', value: source.slice(index + 1, end) });
+      index = end + 1;
+    } else if (PUNCTUATORS.has(char)) {
+      tokens.push({ kind: 'punct', value: char });
+      index += 1;
+    } else if (/[_A-Za-z]/.test(char)) {
+      const match = /^[_A-Za-z][_0-9A-Za-z]*/.exec(source.slice(index));
+      tokens.push({ kind: 'name', value: match[0] });
+      index += match[0].length;
+    } else if (/[-0-9]/.test(char)) {
+      const match = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(source.slice(index));
+      if (!match) throw new SyntaxError(`unexpected character "${char}"`);
+      tokens.push({ kind: 'number', value: match[0] });
+      index += match[0].length;
+    } else {
+      throw new SyntaxError(`unexpected character "${char}"`);
+    }
+  }
+  return tokens;
+}
+
+/** A cursor over tokens with the expectations both parsers share. */
+function cursorOf(tokens) {
+  let index = 0;
+  const cursor = {
+    peek: (offset = 0) => tokens[index + offset] ?? null,
+    next: () => {
+      const token = tokens[index];
+      if (token === undefined) throw new SyntaxError('unexpected end of document');
+      index += 1;
+      return token;
+    },
+    is: (value) => tokens[index]?.value === value && tokens[index]?.kind !== 'string',
+    done: () => index >= tokens.length,
+    take: (value) => {
+      if (!cursor.is(value)) return false;
+      index += 1;
+      return true;
+    },
+    expect: (value) => {
+      const token = cursor.next();
+      if (token.value !== value || token.kind === 'string') throw new SyntaxError(`expected "${value}", found "${token.value}"`);
+      return token;
+    },
+    name: () => {
+      const token = cursor.next();
+      if (token.kind !== 'name') throw new SyntaxError(`expected a name, found "${token.value}"`);
+      return token.value;
+    },
+  };
+  return cursor;
+}
+
+/** A type reference: `{ name, list, nonNull, item }`. */
+function parseTypeRef(cursor) {
+  let type;
+  if (cursor.take('[')) {
+    const item = parseTypeRef(cursor);
+    cursor.expect(']');
+    type = { list: true, item, name: item.name, nonNull: false };
+  } else {
+    type = { list: false, name: cursor.name(), nonNull: false };
+  }
+  if (cursor.take('!')) type = { ...type, nonNull: true };
+  return type;
+}
+
+/** Skips one value of any shape (a default value, a directive argument). */
+function skipValue(cursor) {
+  const token = cursor.next();
+  if (token.kind !== 'punct') return;
+  if (token.value === '$') return void cursor.name();
+  const close = token.value === '{' ? '}' : token.value === '[' ? ']' : null;
+  if (close === null) return;
+  while (!cursor.take(close)) {
+    if (token.value === '{') {
+      cursor.name();
+      cursor.expect(':');
+    }
+    skipValue(cursor);
+  }
+}
+
+function skipDirectives(cursor) {
+  while (cursor.take('@')) {
+    cursor.name();
+    if (cursor.take('(')) {
+      while (!cursor.take(')')) {
+        cursor.name();
+        cursor.expect(':');
+        skipValue(cursor);
+      }
+    }
+  }
+}
+
+function skipDescription(cursor) {
+  if (cursor.peek()?.kind === 'string') cursor.next();
+}
+
+/** Field or input-value definitions between braces. */
+function parseFieldDefinitions(cursor, withArguments) {
+  const fields = new Map();
+  cursor.expect('{');
+  while (!cursor.take('}')) {
+    skipDescription(cursor);
+    const name = cursor.name();
+    const args = new Map();
+    if (withArguments && cursor.take('(')) {
+      while (!cursor.take(')')) {
+        skipDescription(cursor);
+        const argName = cursor.name();
+        cursor.expect(':');
+        const type = parseTypeRef(cursor);
+        const hasDefault = cursor.take('=');
+        if (hasDefault) skipValue(cursor);
+        skipDirectives(cursor);
+        args.set(argName, { type, hasDefault });
+      }
+    }
+    cursor.expect(':');
+    const type = parseTypeRef(cursor);
+    const hasDefault = cursor.take('=');
+    if (hasDefault) skipValue(cursor);
+    skipDirectives(cursor);
+    fields.set(name, { type, args, hasDefault });
+  }
+  return fields;
+}
+
+/** The types of an SDL source: Map(name -> { kind, fields? , values? , members? }), plus the root operation type names. */
+export function parseSchema(source) {
+  const cursor = cursorOf(tokenize(source));
+  const types = new Map();
+  const roots = { query: 'Query', mutation: 'Mutation', subscription: 'Subscription' };
+  while (!cursor.done()) {
+    skipDescription(cursor);
+    const keyword = cursor.name();
+    if (keyword === 'schema' || (keyword === 'extend' && cursor.is('schema'))) {
+      if (keyword === 'extend') cursor.name();
+      skipDirectives(cursor);
+      cursor.expect('{');
+      while (!cursor.take('}')) {
+        const operation = cursor.name();
+        cursor.expect(':');
+        roots[operation] = cursor.name();
+      }
+    } else if (keyword === 'directive') {
+      cursor.expect('@');
+      cursor.name();
+      if (cursor.take('(')) parseArgumentList(cursor);
+      if (cursor.is('repeatable')) cursor.name();
+      cursor.name();
+      cursor.take('|');
+      cursor.name();
+      while (cursor.take('|')) cursor.name();
+    } else if (keyword === 'scalar') {
+      const name = cursor.name();
+      skipDirectives(cursor);
+      types.set(name, { kind: 'scalar' });
+    } else if (keyword === 'enum') {
+      const name = cursor.name();
+      skipDirectives(cursor);
+      const values = new Set();
+      cursor.expect('{');
+      while (!cursor.take('}')) {
+        skipDescription(cursor);
+        values.add(cursor.name());
+        skipDirectives(cursor);
+      }
+      types.set(name, { kind: 'enum', values });
+    } else if (keyword === 'union') {
+      const name = cursor.name();
+      skipDirectives(cursor);
+      cursor.expect('=');
+      cursor.take('|');
+      const members = [cursor.name()];
+      while (cursor.take('|')) members.push(cursor.name());
+      types.set(name, { kind: 'union', members });
+    } else if (keyword === 'type' || keyword === 'interface' || keyword === 'input') {
+      const name = cursor.name();
+      if (cursor.is('implements')) {
+        cursor.name();
+        cursor.take('&');
+        cursor.name();
+        while (cursor.take('&')) cursor.name();
+      }
+      skipDirectives(cursor);
+      const kind = keyword === 'input' ? 'input' : keyword === 'interface' ? 'interface' : 'object';
+      types.set(name, { kind, fields: parseFieldDefinitions(cursor, kind !== 'input') });
+    } else {
+      throw new SyntaxError(`unexpected "${keyword}" in a schema`);
+    }
+  }
+  return { types, roots };
+}
+
+function parseArgumentList(cursor) {
+  while (!cursor.take(')')) {
+    skipDescription(cursor);
+    cursor.name();
+    cursor.expect(':');
+    parseTypeRef(cursor);
+    if (cursor.take('=')) skipValue(cursor);
+    skipDirectives(cursor);
+  }
+}
+
+/** A value of a document: `{ kind: 'variable', name }`, `{ kind: 'object', fields: Map }`, `{ kind: 'list', items }` or a scalar. */
+function parseValue(cursor) {
+  if (cursor.take('$')) return { kind: 'variable', name: cursor.name() };
+  if (cursor.take('{')) {
+    const fields = new Map();
+    while (!cursor.take('}')) {
+      const name = cursor.name();
+      cursor.expect(':');
+      fields.set(name, parseValue(cursor));
+    }
+    return { kind: 'object', fields };
+  }
+  if (cursor.take('[')) {
+    const items = [];
+    while (!cursor.take(']')) items.push(parseValue(cursor));
+    return { kind: 'list', items };
+  }
+  const token = cursor.next();
+  return { kind: token.kind === 'name' ? 'literal-name' : 'literal', value: token.value };
+}
+
+/** A selection set: [{ kind: 'field', name, alias, args: Map, selections } | { kind: 'inline', on, selections } | { kind: 'spread', name }]. */
+function parseSelectionSet(cursor) {
+  const selections = [];
+  cursor.expect('{');
+  while (!cursor.take('}')) {
+    if (cursor.peek()?.kind === 'spread') {
+      cursor.next();
+      if (cursor.is('on')) {
+        cursor.name();
+        const on = cursor.name();
+        skipDirectives(cursor);
+        selections.push({ kind: 'inline', on, selections: parseSelectionSet(cursor) });
+      } else if (cursor.is('{') || cursor.is('@')) {
+        skipDirectives(cursor);
+        selections.push({ kind: 'inline', on: null, selections: parseSelectionSet(cursor) });
+      } else {
+        selections.push({ kind: 'spread', name: cursor.name() });
+        skipDirectives(cursor);
+      }
+      continue;
+    }
+    let name = cursor.name();
+    let alias = null;
+    if (cursor.take(':')) {
+      alias = name;
+      name = cursor.name();
+    }
+    const args = new Map();
+    if (cursor.take('(')) {
+      while (!cursor.take(')')) {
+        const argName = cursor.name();
+        cursor.expect(':');
+        args.set(argName, parseValue(cursor));
+      }
+    }
+    skipDirectives(cursor);
+    const subSelections = cursor.is('{') ? parseSelectionSet(cursor) : null;
+    selections.push({ kind: 'field', name, alias, args, selections: subSelections });
+  }
+  return selections;
+}
+
+/** The operations and fragments of an executable document. */
+export function parseDocument(source) {
+  const cursor = cursorOf(tokenize(source));
+  const operations = [];
+  const fragments = new Map();
+  while (!cursor.done()) {
+    if (cursor.is('{')) {
+      operations.push({ operation: 'query', name: null, variables: new Map(), selections: parseSelectionSet(cursor) });
+      continue;
+    }
+    const keyword = cursor.name();
+    if (keyword === 'fragment') {
+      const name = cursor.name();
+      if (!cursor.take('on')) throw new SyntaxError(`fragment ${name} names no type condition`);
+      const on = cursor.name();
+      skipDirectives(cursor);
+      fragments.set(name, { on, selections: parseSelectionSet(cursor) });
+      continue;
+    }
+    if (keyword !== 'query' && keyword !== 'mutation' && keyword !== 'subscription') throw new SyntaxError(`unexpected "${keyword}" in a document`);
+    const name = cursor.peek()?.kind === 'name' ? cursor.name() : null;
+    const variables = new Map();
+    if (cursor.take('(')) {
+      while (!cursor.take(')')) {
+        cursor.expect('$');
+        const variable = cursor.name();
+        cursor.expect(':');
+        const type = parseTypeRef(cursor);
+        if (cursor.take('=')) skipValue(cursor);
+        skipDirectives(cursor);
+        variables.set(variable, type);
+      }
+    }
+    skipDirectives(cursor);
+    operations.push({ operation: keyword, name, variables, selections: parseSelectionSet(cursor) });
+  }
+  return { operations, fragments };
+}
+
+const typeText = (type) => (type.list ? `[${typeText(type.item)}]` : type.name) + (type.nonNull ? '!' : '');
+
+/** The problems of one value against the input type it is passed as. */
+function valueProblems(schema, value, type, where, operation, used) {
+  if (value.kind === 'variable') {
+    used.add(value.name);
+    const declared = operation.variables.get(value.name);
+    if (declared === undefined) return [`${where} uses $${value.name}, which the operation does not declare`];
+    return declared.name === type.name ? [] : [`${where} takes ${typeText(type)}, but $${value.name} is ${typeText(declared)}`];
+  }
+  if (type.list && value.kind === 'list') return value.items.flatMap((item, i) => valueProblems(schema, item, type.item, `${where}[${i}]`, operation, used));
+  const named = schema.types.get(type.name);
+  if (value.kind === 'object') {
+    if (named?.kind !== 'input') return [`${where} is an object, but ${type.name} is not an input type`];
+    const problems = [];
+    for (const [field, inner] of value.fields) {
+      const declared = named.fields.get(field);
+      if (declared === undefined) problems.push(`${where} names ${field}, which the input ${type.name} does not declare (it declares ${[...named.fields.keys()].join(', ') || 'nothing'})`);
+      else problems.push(...valueProblems(schema, inner, declared.type, `${where}.${field}`, operation, used));
+    }
+    for (const [field, declared] of named.fields) {
+      if (declared.type.nonNull && !declared.hasDefault && !value.fields.has(field)) problems.push(`${where} omits ${field}, which the input ${type.name} requires`);
+    }
+    return problems;
+  }
+  return [];
+}
+
+/** The problems of one selection set against its parent type. */
+function selectionProblems(schema, document, parentName, selections, path, operation, used, visiting = new Set()) {
+  const parent = schema.types.get(parentName);
+  const problems = [];
+  for (const selection of selections) {
+    if (selection.kind === 'spread') {
+      const fragment = document.fragments.get(selection.name);
+      if (fragment === undefined) problems.push(`${path} spreads ...${selection.name}, which the document does not define`);
+      else if (!visiting.has(selection.name)) problems.push(...selectionProblems(schema, document, fragment.on, fragment.selections, path, operation, used, new Set([...visiting, selection.name])));
+      continue;
+    }
+    if (selection.kind === 'inline') {
+      problems.push(...selectionProblems(schema, document, selection.on ?? parentName, selection.selections, path, operation, used, visiting));
+      continue;
+    }
+    if (selection.name === '__typename') continue;
+    const where = `${path}.${selection.name}`;
+    const field = parent?.fields?.get(selection.name);
+    if (field === undefined) {
+      const known = parent?.fields ? [...parent.fields.keys()].join(', ') : 'nothing';
+      problems.push(`${where} is not a field of ${parentName} (it has ${known})`);
+      continue;
+    }
+    for (const [arg, value] of selection.args) {
+      const declared = field.args.get(arg);
+      if (declared === undefined) problems.push(`${where} passes ${arg}, which ${parentName}.${selection.name} does not take (it takes ${[...field.args.keys()].join(', ') || 'no argument'})`);
+      else problems.push(...valueProblems(schema, value, declared.type, `${where}(${arg})`, operation, used));
+    }
+    for (const [arg, declared] of field.args) {
+      if (declared.type.nonNull && !declared.hasDefault && !selection.args.has(arg)) problems.push(`${where} omits ${arg}, which ${parentName}.${selection.name} requires`);
+    }
+    const target = schema.types.get(field.type.name);
+    const leaf = BUILT_IN_SCALARS.has(field.type.name) || target?.kind === 'scalar' || target?.kind === 'enum';
+    if (leaf && selection.selections !== null) problems.push(`${where} is a ${field.type.name}, which selects no fields`);
+    else if (!leaf && selection.selections === null) problems.push(`${where} is a ${field.type.name}, which needs a selection of its fields`);
+    else if (!leaf) problems.push(...selectionProblems(schema, document, field.type.name, selection.selections, where, operation, used, visiting));
+  }
+  return problems;
+}
+
+/** The root fields an operation selects (no aliases followed into fragments). */
+export const rootFieldsOf = (operation) => operation.selections.filter((selection) => selection.kind === 'field').map((selection) => selection.name);
+
+/** The problems of one operation of a document against one parsed schema; empty when it is valid. */
+export function operationProblems(schema, document, operation) {
+  const rootName = schema.roots[operation.operation];
+  if (!schema.types.has(rootName)) return [`the contract has no ${operation.operation} type`];
+  const used = new Set();
+  const label = operation.name ?? `anonymous ${operation.operation}`;
+  const problems = selectionProblems(schema, document, rootName, operation.selections, label, operation, used);
+  for (const variable of operation.variables.keys()) {
+    if (!used.has(variable)) problems.push(`${label} declares $${variable}, which no argument uses`);
+  }
+  return problems;
+}

package/runtime/scripts/lib/i18n.mjs

@@ -0,0 +1,86 @@
+// i18n.mjs - the ONE mechanism for text the owner must read in Vietnamese. Runtime source, comments and messages are English;
+// a message the owner reads (a Telegram notice, a why line, a progress report) is written once in English at its call site and
+// translated through a DECLARED catalog keyed from that English source: modules/i18n/messages/<area>.yaml, a list of
+// `{en, vi}` entries. Each area belongs to a scope: `runtime` for Node callers or `ui` for the generated browser catalog.
+// The `vi` field is declared in scripts/lib/language.mjs, so it is the only Vietnamese source. There is no per-module
+// `TEXT.vi` table and no second catalog mechanism.
+//
+//   const tr = translator(config.language);      // 'vi' translates, anything else returns the English source
+//   tr('Workflow {id} needs your decision', { id })
+//
+// A placeholder is `{name}`; the English and the Vietnamese of one entry carry exactly the same placeholders
+// (scripts/checks/check-i18n-catalog.mjs). An English source with no entry is returned as is: a missing translation degrades
+// to English, never to a blank.
+import { escapeRegExp } from './regex.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { DEFAULT_OWNER_LANGUAGE, loadConfig } from '../../engine/config.mjs';
+
+export const CATALOG_DIR = 'modules/i18n/messages';
+export const PLACEHOLDER = /\{([A-Za-z_][\w]*)\}/g;
+
+const cache = new Map();
+
+/** The catalog files of a runtime root: repository-relative paths, sorted. */
+export function catalogFiles(root = skillRoot) {
+  const dir = path.join(root, ...CATALOG_DIR.split('/'));
+  try { return fs.readdirSync(dir).filter((name) => /\.ya?ml$/.test(name)).sort().map((name) => `${CATALOG_DIR}/${name}`); } catch { return []; }
+}
+
+/** Every entry in one catalog scope: `[{ en, vi, area, scope, file }]`. */
+export function catalogEntries(root = skillRoot, { scope = 'runtime' } = {}) {
+  return catalogFiles(root).flatMap((rel) => {
+    const doc = parseYaml(fs.readFileSync(path.join(root, ...rel.split('/')), 'utf8'));
+    const documentScope = typeof doc?.scope === 'string' ? doc.scope : 'runtime';
+    if (documentScope !== scope) return [];
+    return (Array.isArray(doc?.messages) ? doc.messages : []).map((entry) => ({
+      en: entry?.en, vi: entry?.vi, area: doc?.area, scope: documentScope, file: rel,
+    }));
+  });
+}
+
+/** One scoped catalog as a Map from the English source to the Vietnamese text (cached per root and scope). */
+export function loadCatalog(root = skillRoot, { scope = 'runtime' } = {}) {
+  const key = `${root}\0${scope}`;
+  if (!cache.has(key)) cache.set(key, new Map(catalogEntries(root, { scope }).filter((e) => typeof e.en === 'string' && typeof e.vi === 'string').map((e) => [e.en, e.vi])));
+  return cache.get(key);
+}
+
+/** Forget the cached catalogs (a spec that rewrites a catalog file). */
+export const resetCatalogCache = () => cache.clear();
+
+/** The names each `pattern` match captures (group 1) in `text`, in match order (`sort` sorts them). */
+export const captureNames = (text, pattern, { sort = false } = {}) => {
+  const names = [...String(text).matchAll(pattern)].map((m) => m[1]);
+  return sort ? names.sort() : names;
+};
+
+/** The names of the placeholders of a message. */
+export const placeholdersOf = (text) => captureNames(text, PLACEHOLDER, { sort: true });
+
+/** `text` with each `{name}` replaced by vars[name] (an unknown name is left as written). */
+export const fill = (text, vars = {}) => String(text).replace(PLACEHOLDER, (whole, name) => (Object.hasOwn(vars, name) ? String(vars[name]) : whole));
+
+/** The message `en` in `language` (`vi` translates through the catalog; any other language is the English source). */
+export function translate(en, vars = {}, { language = DEFAULT_OWNER_LANGUAGE, root = skillRoot, scope = 'runtime' } = {}) {
+  const vi = language === 'vi' ? loadCatalog(root, { scope }).get(en) : undefined;
+  return fill(vi ?? en, vars);
+}
+
+/** The owner's language (config.yaml `language`); `fallback` when there is no readable config (DEFAULT_OWNER_LANGUAGE of engine/config.mjs). */
+export function ownerLanguage(fallback = DEFAULT_OWNER_LANGUAGE) {
+  try { return loadConfig()?.language ?? fallback; } catch { return fallback; }
+}
+
+/** A translator bound to one language: `tr(en, vars)`. */
+export const translator = (language = DEFAULT_OWNER_LANGUAGE, { root = skillRoot, scope = 'runtime' } = {}) =>
+  (en, vars = {}) => translate(en, vars, { language, root, scope });
+
+/**
+ * A pattern source matching `en` in the owner's language or in English: each language's rendering of the English source,
+ * escaped, with the placeholder `slot` (a placeholder name of `en`) replaced by `slotPattern`. Never hardcodes a spelling.
+ */
+export const translatedPattern = (en, slot, slotPattern, languages = ['en', 'vi']) =>
+  `(?:${languages.map((language) => escapeRegExp(translate(en, { [slot]: '@@' }, { language })).replace('@@', slotPattern)).join('|')})`;

package/runtime/scripts/lib/is-main.mjs

@@ -0,0 +1,13 @@
+// is-main.mjs - is this module the process entry point (`node file.mjs`, not an import)? Compared by real path.
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+/** The real path of a file, or its resolved path when it cannot be read (a missing file is never the entry module). */
+const realPathOf = (file) => { try { return fs.realpathSync.native(path.resolve(file)); } catch { return path.resolve(file); } };
+/**
+ * True when the module at `metaUrl` is the process entry point. Both sides are compared as REAL paths: Node gives a module
+ * its symlink-resolved URL, while argv[1] keeps the path it was started with, so an entry reached through a node_modules
+ * junction or symlink (a lane worktree, an npx shim) would otherwise look like an import and silently do nothing.
+ */
+export const isMain = (metaUrl, argv = process.argv) => Boolean(argv[1]) && realPathOf(argv[1]) === realPathOf(fileURLToPath(metaUrl));

package/runtime/scripts/lib/json.mjs

@@ -1,7 +1,7 @@
 // json.mjs — the ledger's forgiving JSON read. Every one of these rows may hold text a peer wrote or a
 // truncated payload, so a malformed column is the caller's fallback, never a throw. The parse of the
 // literal 'null' is kept as null (callers that want {} instead write `parseJsonOr`).
-import fs from 'node:fs';
+import { readParsedFile } from './read-text.mjs';
 
 /** `text` as JSON, or `fallback` when it does not parse. */
 export const parseJson = (text, fallback = null) => {
@@ -17,6 +17,16 @@ export const parseJsonOr = (text, fallback = {}) => parseJson(text) ?? fallback;
 export const withPayload = (row, fallback = {}) => (row ? { ...row, payload: parseJsonOr(row.payload_json, fallback) } : row);
 
 /** `file` read and parsed as JSON, or `fallback` when the file is missing, unreadable or malformed. */
-export const readJsonFile = (file, fallback = null) => {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+export const readJsonFile = (file, fallback = null) => readParsedFile(file, JSON.parse, fallback);
+
+/** `stdout` as JSON: the trimmed text, else its first-{-to-last-} span; null when neither parses. */
+export const jsonFromStdout = (stdout) => {
+  const text = String(stdout ?? '').trim();
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { /* fall through */ }
+  const first = text.indexOf('{'), last = text.lastIndexOf('}');
+  if (first >= 0 && last > first) {
+    try { return JSON.parse(text.slice(first, last + 1)); } catch { /* not json */ }
+  }
+  return null;
 };

package/runtime/scripts/lib/language.mjs

@@ -1,6 +1,6 @@
 // language.mjs - the one home of "is this text English?" for source, comments, tests and docs (HFS_LANGUAGE_NOT_ENGLISH,
 // BE_SOURCE_FORM, FE_SOURCE_FORM). Shared by the architecture machine (docs) and by both lint canons (each ships a byte
-// copy in its runtime/ bundle, kept by packages/hfs/scripts/sync-runtime.mjs).
+// copy in its runtime/ bundle, kept by scripts/hfs/sync-runtime.mjs).
 //
 // Detection is structural on characters, never a word list: the letters Vietnamese adds to the Latin alphabet (a-breve, a-circumflex,
 // d-stroke, e-circumflex, o-circumflex, o-horn, u-horn) and every vowel carrying a tone mark. Text is folded to NFC first, so a
@@ -26,7 +26,7 @@ export function secondLanguageHits(text) {
 
 /**
  * The Vietnamese fields of one failure-code entry: the operator text the owner mandated for the failure-code catalog
- * (scripts/checks/failure-codes.mjs types the entry with exactly these). causes_vi is the list companion of the three scalar fields.
+ * (scripts/checks/check-failure-codes.mjs types the entry with exactly these). causes_vi is the list companion of the three scalar fields.
  */
 export const FAILURE_CODE_VIETNAMESE_FIELDS = Object.freeze(['title_vi', 'meaning_vi', 'nextStep_vi', 'causes_vi']);
 
@@ -39,6 +39,8 @@ export const FAILURE_CODE_VIETNAMESE_FIELDS = Object.freeze(['title_vi', 'meanin
  *  - modules/ops/_labels.yaml: the op-label catalogue, one `{ vi, en }` pair per op (the `vi` field is the localized label).
  *  - modules/goal/archetypes.yaml: the Vietnamese phrase lexicons matched against owner input (the signal phrase sets, and the
  *    phrase lists of the archetype recognisers).
+ *  - modules/goal/source-phrases.yaml: the Vietnamese phrase lists runtime source matchers read through
+ *    scripts/lib/source-phrases.mjs (owner replies, report wording, product copy) - each leaf list under `phrases`.
  * An op manifest (modules/ops/ops/<id>.yaml, the starci/op@1 documents check-op-manifest types) is declared by
  * OP_MANIFEST_VIETNAMESE_FIELDS: its text objects are {en, vi} (modules/schemas/op.schema.yaml $defs text), and `vi` is the
  * owner's reading of the same rule.
@@ -52,13 +54,30 @@ export const DECLARED_VIETNAMESE_FIELDS = Object.freeze({
       'phrases', 'requires', 'excludes', 'backend', 'frontend', 'package',
     ]),
   }),
+  'modules/goal/source-phrases.yaml': Object.freeze({
+    fields: Object.freeze([
+      'prefer', 'avoid', 'negation', 'refused', 'accept', 'golden',
+      'missingPaths', 'grantTooNarrow', 'toolTimeout', 'testGap', 'checkerUnavailable',
+      'supervisorVerbs', 'ownerWord', 'orWord', 'beyondAuthority', 'ownerOnly', 'workerDied', 'contractConflict', 'decision',
+      'product', 'grammar', 'knowledge', 'sourceLabel', 'internalVocabulary', 'actor', 'success',
+      'wizard', 'form', 'dashboard', 'gap', 'anatomy', 'otpLabel',
+    ]),
+  }),
 });
 
+/**
+ * The Vietnamese catalog of owner-visible messages (scripts/lib/i18n.mjs): modules/i18n/messages/<area>.yaml, a list of
+ * `{en, vi}` entries keyed from the English source. The `vi` field (block or inline flow) is the declared Vietnamese.
+ */
+const I18N_CATALOG_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']), flowFields: Object.freeze(['vi']) });
+const I18N_CATALOG_DIR = 'modules/i18n/messages/';
+
 /** The `vi` field of an op manifest's text objects (modules/schemas/op.schema.yaml $defs text). */
-export const OP_MANIFEST_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']) });
+const OP_MANIFEST_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']) });
 const OP_MANIFEST_DIR = 'modules/ops/ops/';
 /** The declared Vietnamese fields of `rel`: its own entry, or the op-manifest text field for a manifest of modules/ops/ops. */
 export const declaredVietnameseFieldsOf = (rel) => DECLARED_VIETNAMESE_FIELDS[rel]
+  ?? (rel.startsWith(I18N_CATALOG_DIR) && !rel.slice(I18N_CATALOG_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? I18N_CATALOG_VIETNAMESE_FIELDS : null)
   ?? (rel.startsWith(OP_MANIFEST_DIR) && !rel.slice(OP_MANIFEST_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? OP_MANIFEST_VIETNAMESE_FIELDS : null);
 
 /**
@@ -66,7 +85,7 @@ export const declaredVietnameseFieldsOf = (rel) => DECLARED_VIETNAMESE_FIELDS[re
  * fixture reproduces a real localized string a parser or formatter must accept. Placement is the whole marker - there is no
  * comment pragma and no path pattern. The slots are declared in knowledge/hfs/slots.yaml.
  */
-export const LOCALIZED_TEXT_SLOTS = Object.freeze([
+const LOCALIZED_TEXT_SLOTS = Object.freeze([
   'be.domain.messages', 'be.feature.messages', 'be.tests.fixtures.i18n',
   'fe.modules.i18n', 'fe.package.i18n',
 ]);
@@ -78,7 +97,7 @@ export const isLocalizedDataFile = (rel, slot) => LOCALIZED_TEXT_SLOTS.includes(
  * The key each line of a YAML text belongs to: a `key:` line owns itself, and every deeper-indented line after it (a list item,
  * a folded block, a wrapped scalar) belongs to the same key. A line at or above the key's indent that is not a key belongs to none.
  */
-export function yamlKeyOfEachLine(text) {
+function yamlKeyOfEachLine(text) {
   let key = null;
   let keyIndent = -1;
   return String(text).split(/\r?\n/).map((raw) => {
@@ -105,13 +124,13 @@ export function documentLanguageHits(rel, text) {
     if (declared.fields?.includes(keys[hit.line - 1])) return false;
     if (!declared.flowFields) return true;
     // an inline flow map: drop the declared fields' values and judge what is left of the line
-    const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(`\\b${field}\\s*:\\s*[^,}]*`, 'g'), ''), lines[hit.line - 1]);
+    const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(`\\b${field}\\s*:\\s*(?:"(?:[^"\\\\]|\\\\.)*"|'(?:[^'\\\\]|\\\\.)*'|[^,}]*)`, 'g'), ''), lines[hit.line - 1]);
     return hasSecondLanguage(rest);
   });
 }
 
 /** The file extensions of a prose document (Markdown and YAML). */
-export const DOCUMENT_EXTENSIONS = Object.freeze(['.md', '.yaml', '.yml']);
+const DOCUMENT_EXTENSIONS = Object.freeze(['.md', '.yaml', '.yml']);
 
 /** Whether `rel` is a document a language check reads. */
 export const isDocument = (rel) => DOCUMENT_EXTENSIONS.includes(path.posix.extname(rel));

package/runtime/scripts/lib/list.mjs

@@ -0,0 +1,20 @@
+// list.mjs — the array-or-empty coercion half the scripts re-declared by hand.
+// `v` when it already is an array, else []. Scalars are NOT wrapped: a caller that wants
+// `[v]` for a lone value writes its own coercion (see contract-version's list).
+export const list = (v) => (Array.isArray(v) ? v : []);
+
+/** `v` as an array: itself when already one, [] for null/undefined, else [v]. */
+export const asList = (v) => (Array.isArray(v) ? v : v == null ? [] : [v]);
+
+/** The object entries of `v` (a non-array reads as []). */
+export const objectList = (v) => (Array.isArray(v) ? v : []).filter((item) => item && typeof item === 'object');
+
+/** Every entry of `v` a non-empty string (`blank: false` also rejects all-whitespace entries). */
+export const stringList = (v, { blank = true } = {}) =>
+  Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0 && (blank || s.trim().length > 0));
+
+/** The items of a `sep`-separated list: trimmed, empties dropped; `dedupe` keeps first occurrences only. */
+export const splitList = (v, { sep = ',', dedupe = false } = {}) => {
+  const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);
+  return dedupe ? [...new Set(items)] : items;
+};