@starci/hfs 4.0.8 → 4.0.10

package/runtime/scripts/lib/display-names.mjs

@@ -0,0 +1,259 @@
+// display-names.mjs — the names a person reads for a workflow, an operation and an op job.
+//
+// Owner request 2026-09-27: kernels, workflows and op workers need easy-to-understand names.
+// The ids stay the keys everywhere (workflow_id, op_id, job_id); these are labels only:
+//   workflow  workflows.display_name (starci kernel rename; derived at define-goal), else the goal slug in
+//             workflows.title, else the workflow id. Vietnamese, `<Product> · <what it does>`.
+//   operation modules/ops/_labels.yaml (vi/en), else the op id.
+//   op job    `<op label> · <what> · <workflow name>`: `what` is the job's target — an explicit
+//             enqueue --what, the work-graph node it covers, the Work record it owns, the slice
+//             its title names, its feature path, its cut — at most JOB_WHAT_MAX characters.
+// Every human-facing surface reads these helpers: the [Kernel]/[Op] Orca titles, starci kernel status,
+// the supervisor digest and progress report, Telegram notices and the harness UI.
+import fs from 'node:fs';
+import path from 'node:path';
+import { clipLine, squash } from './clip.mjs';
+import { ownerLanguage, translator } from './i18n.mjs';
+import { list } from './list.mjs';
+import { parseJson } from './json.mjs';
+import { readYamlFile } from './read-yaml.mjs';
+import { normRel, pathsOverlap } from './path-key.mjs';
+import { PRODUCT_NAME_SEGMENT } from './example-refs.mjs';
+
+export const WORKFLOW_NAME_MAX = 48;
+const DISPLAY_NAME_LIMIT = 80;
+export const JOB_WHAT_MAX = 40;
+const NAME_SEPARATOR = ' · ';
+
+const LABELS_FILE = new URL('../../modules/ops/_labels.yaml', import.meta.url);
+let labelsCache = null;
+/** {op: {vi, en}} from modules/ops/_labels.yaml; {} when the file is unreadable. */
+export function opLabelMap() {
+  if (labelsCache) return labelsCache;
+  labelsCache = Object.freeze({ ...(readYamlFile(LABELS_FILE)?.labels ?? {}) });
+  return labelsCache;
+}
+/** The human label of an op (a `op#instance` leg label reads as its op), else the op id itself. */
+export function opLabel(op, language = ownerLanguage()) {
+  const id = String(op ?? '').trim();
+  if (!id) return '';
+  const entry = opLabelMap()[id] ?? opLabelMap()[id.split('#')[0]];
+  const label = entry?.[language] ?? entry?.vi;
+  return typeof label === 'string' && label.trim() ? label.trim() : id;
+}
+
+/** One line, whitespace collapsed; '' for nothing. */
+/** `text` cut at a word boundary to at most `max` characters, ending in an ellipsis when cut. */
+function clipWords(text, max) {
+  const s = squash(text);
+  if (s.length <= max) return s;
+  const room = s.slice(0, max - 1);
+  const at = room.lastIndexOf(' ');
+  return `${(at >= max / 2 ? room.slice(0, at) : room).replace(/[\s,;:.·–—-]+$/, '')}…`;
+}
+
+/**
+ * A display name as the api stores it: one line, trimmed, 1..DISPLAY_NAME_LIMIT characters. Throws
+ * {code: 'rename-bad-title'} otherwise.
+ */
+export function normalizeDisplayName(name) {
+  const s = squash(name);
+  if (!s) throw Object.assign(new Error('the display name is empty'), { code: 'rename-bad-title' });
+  if (s.length > DISPLAY_NAME_LIMIT) throw Object.assign(new Error(`the display name is ${s.length} characters; at most ${DISPLAY_NAME_LIMIT}`), { code: 'rename-bad-title' });
+  return s;
+}
+
+/** A workflows row's name: display_name, else the goal slug (title), else the workflow id. */
+export function workflowDisplayName(row) {
+  if (!row) return null;
+  return squash(row.display_name) || squash(row.title) || row.workflow_id || null;
+}
+/** The name of one workflow of `db` (its id when the row is missing). */
+export function workflowNameOf(db, workflowId) {
+  if (!workflowId) return null;
+  try { return workflowDisplayName(db.prepare('SELECT * FROM workflows WHERE workflow_id=?').get(workflowId)) ?? workflowId; }
+  catch { return workflowId; }
+}
+/** workflow_id -> name for every workflow of `db` (`displayOnly` keeps only rows with a display_name). */
+export function workflowNames(db, { displayOnly = false } = {}) {
+  try {
+    const rows = db.prepare('SELECT * FROM workflows').all().filter((row) => !displayOnly || row.display_name);
+    return new Map(rows.map((row) => [row.workflow_id, displayOnly ? row.display_name : workflowDisplayName(row)]));
+  } catch { return new Map(); }
+}
+/** `Name (id)` for a line that must still carry the key, or the id alone when there is no other name. */
+export const nameWithId = (name, id) => (name && name !== id ? `${name} (${id})` : String(id ?? name ?? ''));
+
+/** The name of an attached file record ({name?, abs}): its declared name, else its basename, forward-slashed. */
+export const attachedNameOf = (file) => String(file.name ?? path.basename(String(file.abs ?? ''))).replace(/\\/g, '/');
+
+// ---------------------------------------------------------------------------------- workflow names
+const BRAND_CASE = { starci: 'StarCi' };
+const REPO_ROLE_SUFFIX = /[-_](backend|be|frontend|fe|api|server|web|app)$/i;
+/** The product's display word(s) from a project or repository name: `shop-be` -> `Shop`. */
+export function productName(raw) {
+  const base = squash(raw).replace(REPO_ROLE_SUFFIX, '');
+  if (!base) return '';
+  return base.split(/[-_\s]+/).filter(Boolean)
+    .map((w) => BRAND_CASE[w.toLowerCase()] ?? (w.length <= 3 && /^[a-z]+$/i.test(w) && w === w.toUpperCase() ? w : `${w[0].toUpperCase()}${w.slice(1)}`)).join(' ');
+}
+/** The first clause of the owner's goal text: up to the first sentence end, line break, colon or dash aside. */
+function firstClause(text) {
+  const s = String(text ?? '').split(/\r?\n/).map(squash).find(Boolean) ?? '';
+  const clause = s.split(/(?<=[.!?;:])\s|\s[—–-]\s|\s\(/)[0] ?? '';
+  return clause.replace(/[\s.!?;:,]+$/, '').trim();
+}
+/**
+ * A readable name for a new goal (define-goal): `<Product> · <first clause of the goal text>`, at
+ * most WORKFLOW_NAME_MAX characters; `fallback` (the goal slug) when the text yields nothing usable.
+ */
+export function deriveWorkflowDisplayName({ text, product = null, fallback = null, max = WORKFLOW_NAME_MAX } = {}) {
+  const prod = productName(product);
+  // The product leads the name already: a goal text that opens with it ("<product>: …") starts after it.
+  let body = squash(text);
+  if (prod && body.toLowerCase().startsWith(prod.toLowerCase())) body = body.slice(prod.length).replace(/^[\s:·,–—-]+/, '');
+  const clause = firstClause(body);
+  const head = prod ? `${prod}${NAME_SEPARATOR}` : '';
+  const room = max - head.length;
+  if (!clause || !/[\p{L}\p{N}]/u.test(clause) || room < 8) return fallback ? clipWords(fallback, max) : (prod || null);
+  return `${head}${clipWords(`${clause[0].toUpperCase()}${clause.slice(1)}`, room)}`;
+}
+
+// ------------------------------------------------------------------------------------ op job names
+const keyOf = (p) => normRel(p, { fold: true });
+// A path this broad names no target in particular (the whole Work tree, every feature).
+const BROAD = /^(\.starciwork|\.starciwork\/index\.yaml|\.starciwork\/features|\.starciwork\/features\/index\.yaml|src|apps|packages)?$/;
+const meets = pathsOverlap;
+
+/** The work-graph node the job covers most specifically (its longest owned path that meets the job's). */
+function coveredNode(nodes, paths) {
+  const keys = paths.map(keyOf).filter((k) => k && !BROAD.test(k));
+  let best = null, bestLen = -1;
+  for (const node of list(nodes)) {
+    for (const owned of list(node?.ownedPaths).map(keyOf).filter((k) => k && !BROAD.test(k))) {
+      if (keys.some((k) => meets(k, owned)) && owned.length > bestLen) { best = node; bestLen = owned.length; }
+    }
+  }
+  return best;
+}
+
+const titleCache = new Map();
+/** The `title:` of the Work record at `<repo>/<p>` (a record folder or its index.yaml), else null. */
+function recordTitle(repo, p) {
+  if (!repo || !p) return null;
+  const rel = String(p).replaceAll('\\', '/').replace(/\/+$/, '');
+  if (!rel.startsWith('.starciwork/') || BROAD.test(rel.toLowerCase())) return null;
+  const file = path.join(repo, rel.endsWith('.yaml') ? rel : `${rel}/index.yaml`);
+  if (!file.endsWith('index.yaml')) return null;
+  let mtime = null;
+  try { mtime = fs.statSync(file).mtimeMs; } catch { return null; }
+  const hit = titleCache.get(file);
+  if (hit && hit.mtime === mtime) return hit.title;
+  let title = null;
+  try {
+    const head = fs.readFileSync(file, 'utf8').slice(0, 4096);
+    const m = /^title:[ \t]*(.*)$/m.exec(head);
+    let value = m ? m[1] : '';
+    // A folded or literal block scalar (title: >-) continues on the indented lines right below it.
+    if (m && /^[>|][-+]?\s*$/.test(value)) {
+      const below = head.slice(m.index + m[0].length).split(/\r?\n/).slice(1);
+      const end = below.findIndex((l) => !/^\s+\S/.test(l));
+      value = (end < 0 ? below : below.slice(0, end)).join(' ');
+    }
+    title = squash(value.replace(/^(['"])(.*)\1$/, '$2')) || null;
+  } catch { title = null; }
+  if (titleCache.size > 2000) titleCache.clear();
+  titleCache.set(file, { mtime, title });
+  return title;
+}
+
+// Folder names that say what kind of record sits there, not which one.
+const FAMILY = new Set(['ui', 'fr', 'br', 'nfr', 'uat', 'sds', 'contract', 'data', 'journey', 'decision', 'scope', 'business', 'integration',
+  'impl', 'operations', 'evidence', 'e', 'assets', 'tools', 'src', 'apps', 'features', 'provision', 'shell', 'brand', 'lib', 'components', 'pages']);
+const words = (s) => s.replace(/[-_]+/g, ' ').trim();
+/** A short label from an owned path: `features/collab/ui/office` -> `collab / office`. */
+export function pathLabel(p) {
+  const segs = String(p ?? '').replaceAll('\\', '/').split('/').filter(Boolean).filter((s) => s !== '.starciwork');
+  const at = segs.indexOf('features');
+  if (at >= 0 && segs[at + 1]) {
+    const feature = segs[at + 1];
+    const rest = segs.slice(at + 2).filter((s) => !s.includes('.') && !FAMILY.has(s.toLowerCase()) && !PRODUCT_NAME_SEGMENT.test(s));
+    const leaf = rest.at(-1);
+    return leaf && leaf !== feature ? `${words(feature)} / ${words(leaf)}` : words(feature);
+  }
+  const plain = segs.filter((s) => !FAMILY.has(s.toLowerCase()) && !/^wf-/i.test(s));
+  const last = plain.at(-1);
+  return last ? words(last.replace(/\.[a-z0-9]+$/i, '')) : null;
+}
+
+/** A work-graph node's short label from its id: `login.sign-in` -> `login / sign in`. */
+export function nodeLabel(node) {
+  const id = String(node?.id ?? '');
+  const domain = String(node?.domain ?? '');
+  const leaf = domain && id.startsWith(`${domain}.`) ? id.slice(domain.length + 1) : id;
+  return domain && leaf && leaf !== domain ? `${words(domain)} / ${words(leaf.replaceAll('.', ' '))}` : words(id.replaceAll('.', ' '));
+}
+
+/**
+ * What an op job works on, for a human: at most JOB_WHAT_MAX characters, or null when nothing names it.
+ * `payload` is the job payload, `op` its op id, `nodes` the workflow's latest work-graph nodes, `repo`
+ * the ledger owner (to read Work record titles).
+ */
+export function jobWhat({ payload, op = null, nodes = null, repo = null, max = JOB_WHAT_MAX, language = ownerLanguage() } = {}) {
+  const p = payload ?? {};
+  const owned = list(p.owned_paths ?? p.ownedPaths).map((x) => (typeof x === 'string' ? x : x?.path)).filter(Boolean);
+  const records = list(p.records).filter((x) => typeof x === 'string');
+  const cut = p.cut && typeof p.cut === 'object' ? p.cut : null;
+  const title = squash(p.title);
+  const opId = String(op ?? p.opId ?? '');
+  const rest = opId && title.toLowerCase().startsWith(opId.toLowerCase()) ? title.slice(opId.length).replace(/^[\s:#·–—-]+/, '') : null;
+  const specific = [...owned, ...records].filter((x) => !BROAD.test(keyOf(x)));
+  // A title that already fits is the target's own name; a sentence-long one gives way to the short id.
+  const fits = (t) => (t && squash(t).length <= max ? t : null);
+  const node = coveredNode(nodes, owned);
+  const candidates = [
+    () => squash(p.displayWhat),
+    () => { for (const x of specific) { const t = fits(recordTitle(repo, x)); if (t) return t; } return null; },
+    () => fits(node?.title),
+    () => (node?.id ? nodeLabel(node) : null),
+    () => rest,
+    () => (specific[0] ? pathLabel(specific[0]) : null),
+    () => (rest === null && title && title !== opId ? firstClause(title) : null),
+    () => (cut?.id ? words(String(cut.id)) : null),
+  ];
+  let what = null;
+  for (const pick of candidates) { const v = squash(pick()); if (v) { what = v; break; } }
+  const tail = cut && Number(cut.total) > 1 && Number.isInteger(Number(cut.ordinal)) ? ` ${cut.ordinal}/${cut.total}` : '';
+  if (!what) return tail ? translator(language)('part{tail}', { tail }) : null;
+  return `${clipWords(what, Math.max(8, max - tail.length))}${tail}`;
+}
+
+/** `<op label> · <what> · <workflow name>`, skipping a missing part. */
+export function jobDisplayName({ op, what = null, workflowName = null, language = ownerLanguage() } = {}) {
+  return [opLabel(op, language), squash(what), squash(workflowName)].filter(Boolean).join(NAME_SEPARATOR);
+}
+
+/**
+ * The display name of one jobs row of `db`: reads its workflow's name and latest work-graph nodes unless
+ * given. `cache` (a Map) shares the workflow reads across many jobs.
+ */
+export function jobDisplayNameOf(db, job, { repo = null, workflowName = null, nodes = undefined, cache = null, language = ownerLanguage() } = {}) {
+  if (!job) return null;
+  const payload = typeof job.payload_json === 'string' ? parseJson(job.payload_json, {}) : (job.payload ?? {});
+  const op = job.op_id ?? job.opId ?? payload.opId ?? null;
+  const wf = job.workflow_id ?? job.workflowId ?? null;
+  const memo = cache ?? new Map();
+  const wfInfo = memo.get(wf) ?? (() => {
+    const info = { name: workflowNameOf(db, wf), nodes: null, repo: null };
+    // The ledger owner's root (to read Work record titles) when the caller names none: the workflow's first source root.
+    try { info.repo = parseJson(db.prepare('SELECT source_roots_json FROM workflows WHERE workflow_id=?').get(wf)?.source_roots_json)?.[0] ?? null; } catch { info.repo = null; }
+    try {
+      const row = db.prepare("SELECT graph_json FROM work_graph_versions WHERE workflow_id=? ORDER BY version DESC LIMIT 1").get(wf);
+      info.nodes = row ? parseJson(row.graph_json)?.nodes ?? null : null;
+    } catch { info.nodes = null; }
+    memo.set(wf, info);
+    return info;
+  })();
+  const what = jobWhat({ payload, op, nodes: nodes === undefined ? wfInfo.nodes : nodes, repo: repo ?? wfInfo.repo, language });
+  return jobDisplayName({ op, what, workflowName: workflowName ?? wfInfo.name, language });
+}

package/runtime/scripts/lib/dockerfile.mjs

@@ -0,0 +1,124 @@
+// dockerfile.mjs - a Dockerfile read by its own grammar (no regular-expression matching of instruction names inside the text):
+// 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;
+    }
+  }
+  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;
+  }
+}
+
+/** 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 (char === ';' || char === '|' || (char === '&' && body[i + 1] === '&')) {
+      if (char !== ';' && body[i + 1] === char) i += 1;
+      flush();
+    } else if (char === '\\' && body[i + 1] === '\n') {
+      i += 1;
+    } else {
+      current += char;
+    }
+  }
+  flush();
+  return commands;
+}
+
+/**
+ * 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).replace(/\r\n/g, '\n').split('\n');
+  const instructions = [];
+  const comments = [];
+  let escape = '\\';
+  let directives = true;
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    if (trimmed === '') { directives = false; continue; }
+    if (trimmed.startsWith('#')) {
+      const body = trimmed.slice(1).trim();
+      const directive = directives ? /^(syntax|escape|check)\s*=\s*(\S+)$/i.exec(body) : null;
+      if (directive) { if (directive[1].toLowerCase() === 'escape') escape = directive[2]; continue; }
+      directives = false;
+      comments.push({ text: body, line: i + 1 });
+      continue;
+    }
+    directives = false;
+    const start = i + 1;
+    let logical = trimmed;
+    while (logical.endsWith(escape) && i + 1 < lines.length) {
+      logical = logical.slice(0, -1).trimEnd();
+      i += 1;
+      while (i < lines.length && lines[i].trim().startsWith('#')) i += 1;
+      if (i >= lines.length) break;
+      logical = `${logical} ${lines[i].trim()}`;
+    }
+    const split = logical.search(/\s/);
+    const keyword = (split < 0 ? logical : logical.slice(0, split)).toUpperCase();
+    instructions.push({ keyword, text: split < 0 ? '' : logical.slice(split).trim(), line: start, stage: -1 });
+  }
+  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);
+  }
+  return { instructions, stages, comments, preamble };
+}

package/runtime/scripts/lib/env.mjs

@@ -0,0 +1,10 @@
+// env.mjs - the one place the runtime reads a named environment variable (smell S8-01/S8-02/S11-04; scripts/checks/check-env.mjs).
+// 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);

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

@@ -0,0 +1,103 @@
+// 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 nothing.
+
+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;
+}
+
+/** 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;
+}
+
+/** 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) {
+    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\``);
+      continue;
+    }
+    const type = fieldType(ts, member.type);
+    const written = type === null ? null : `${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;
+  }
+  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;
+    }
+    events.push({ className, name, version: version ?? 0, ...(compensates === undefined ? {} : { compensates }), payload: payloadOf(ts, sourceFile, parameter.typeName.text, problems, className) });
+  }
+  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().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`;
+}
+
+/** The snapshot's text with line endings folded, for comparing a committed file to a fresh one. */
+export const folded = (text) => text.replace(/\r\n/g, '\n');

package/runtime/scripts/lib/example-refs.mjs

@@ -0,0 +1,158 @@
+// example-refs.mjs — the ONE runtime source file that may spell a path into the runtime's own examples/
+// tree or a product name the runtime legitimately knows (R206, NO_EXAMPLE_COUPLING): every other source
+// file reaches these through the constants below, and scripts/checks/check-example-coupling.mjs exempts
+// this file's name only - a declared read, never a path allowlist. A constant belongs here only when the
+// runtime genuinely reads that tree or names that product at run time; a pointer that can be generic must
+// be generic in the file that holds it.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { validateAgainstSchema } from './json-schema.mjs';
+import { insidePath, samePath, slash } from './path-key.mjs';
+
+/** The runtime's example tree root. */
+export const EXAMPLES_ROOT = 'examples';
+
+/** Curated basic sample source; operational artifact writers remain external. */
+export const EXAMPLE_RUNTIMES_ROOT = `${EXAMPLES_ROOT}/.runtimes`;
+
+/** Every examples/<name>/hfs.json declaration of kind app, sorted by name. */
+export function discoverExampleApps(root) {
+  const directory = path.join(root, EXAMPLES_ROOT);
+  let entries;
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return []; }
+  return entries.filter((entry) => entry.isDirectory()).filter((entry) => {
+    try { return JSON.parse(fs.readFileSync(path.join(directory, entry.name, 'hfs.json'), 'utf8'))?.kind === 'app'; }
+    catch { return false; }
+  }).map((entry) => entry.name).sort();
+}
+
+/** The generic services-block template a starcistacks follow-up leg is pointed at (S11-02: one template
+ *  for every repository - the per-repository blocks it replaced are spec fixtures under
+ *  tests/fixtures/starcistacks-services/, never a run-time read). */
+export const STACK_DECLARATION_TEMPLATE = `${EXAMPLES_ROOT}/starcistacks-services/template.services.yaml`;
+
+/** The reference app declaration scripts/hfs/derived-fields.mjs samples for per-field slot ownership. */
+export const REFERENCE_APP_MANIFEST = `${EXAMPLES_ROOT}/ecommerce-app/hfs.json`;
+
+/** The example app whose installed tree an fe-kit peer link points at by default. */
+export const REFERENCE_EXAMPLE_APP = 'ecommerce-app';
+
+/** The grammar css families a product repository may declare (`[data-grammar-family="<id>"]`); the
+ *  runtime's own product maps to the core sheet. */
+export const GRAMMAR_FAMILIES = Object.freeze({ starci: 'core', nivo: 'nivo' });
+
+/** Display aliases of legacy workflow slugs that predate workflows.display_name (the progress report's
+ *  English fallback; the i18n catalog carries the owner's wording for each value). */
+export const WORKFLOW_ALIASES = Object.freeze({
+  'nivo-app-auth': 'AUTH (sign-in)', 'nivo-workspace-provision': 'WSPV (buy & provision workspace)',
+  'nivo-modules-agentos': 'Modules (AgentOS)', 'nivo-collab-group-chat': 'Collab (group chat)',
+  'starci-next-work-and-stacks': 'StarCi Next – work & stacks', 'starci-next-base-repos': 'StarCi Next – base repos',
+  'miamia-work-and-stacks': 'Mia Mia – work & stacks', 'miamia-base-repos': 'Mia Mia – base repos',
+});
+
+/** A feature-folder segment that is only the product's own name - no useful leaf (display-names pathLabel). */
+export const PRODUCT_NAME_SEGMENT = /^(nivo|starci|mia)[-\w]*$/i;
+
+/** The closed list of product names this runtime shipped against - the names R206
+ *  (check-example-coupling.mjs) refuses anywhere in runtime source outside this file (a retired
+ *  name is judged by RT_RETIRED_NAME_LIVE, R207, from modules/kernel/retired-paths.yaml). */
+export const PRODUCT_NAMES = Object.freeze(['mia-mia', 'miamia', 'nivo', 'starci-academy', 'ecommerce-app', 'shape-slot']);
+
+/** The catalog of stable pattern IDs pointing at actual executable example source. */
+export const EXAMPLE_CATALOG_FILE = `${EXAMPLES_ROOT}/index.yaml`;
+
+function referenceFile(root, relative, { directory = false, exact = false } = {}) {
+  if (typeof relative !== 'string' || !relative || relative.includes('\\') || relative.includes(':') || path.isAbsolute(relative)
+    || relative.split('/').some((part) => !part || part === '.' || part === '..')) throw new Error(`invalid example input: ${relative}`);
+  const file = path.resolve(root, relative);
+  if (!insidePath(root, file)) throw new Error(`example input is outside its declared root: ${relative}`);
+  let at = path.parse(file).root;
+  for (const segment of file.slice(at.length).split(path.sep).filter(Boolean)) {
+    at = path.join(at, segment);
+    if (fs.lstatSync(at).isSymbolicLink() || !samePath(fs.realpathSync.native(at), at)
+      || (exact && !fs.readdirSync(path.dirname(at)).includes(path.basename(at))))
+      throw new Error(`linked example input: ${relative}`);
+  }
+  if (!(directory ? fs.lstatSync(file).isDirectory() : fs.lstatSync(file).isFile())
+    || !insidePath(fs.realpathSync.native(root), fs.realpathSync.native(file)))
+    throw new Error(`example input is not a contained regular file: ${relative}`);
+  return file;
+}
+
+/** Read and validate complete source references. Duplicate IDs refuse before
+ * lookup; source, compiler and test pointers stay within one declared HFS app. */
+export function loadExampleCatalog(root, { file = EXAMPLE_CATALOG_FILE } = {}) {
+  const catalog = parseYaml(fs.readFileSync(referenceFile(root, file), 'utf8'));
+  const schema = parseYaml(fs.readFileSync(referenceFile(root, 'modules/schemas/code-example-catalog.schema.yaml'), 'utf8'));
+  const errors = validateAgainstSchema(catalog, schema);
+  if (errors.length) throw new Error(`invalid example catalog: ${errors.join('; ')}`);
+  const ids = new Set();
+  for (const row of catalog.examples) {
+    if (ids.has(row.id)) throw new Error(`duplicate example id: ${row.id}`);
+    ids.add(row.id);
+  }
+  for (const row of catalog.examples) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.path)) throw new Error(`invalid example app: ${row.path}`);
+    const app = path.join(root, EXAMPLES_ROOT, row.path);
+    const declaration = JSON.parse(fs.readFileSync(referenceFile(root, `${EXAMPLES_ROOT}/${row.path}/hfs.json`), 'utf8'));
+    if (declaration.kind !== 'app') throw new Error(`example has no HFS app declaration: ${row.id}`);
+    if (!row.files.includes(row.entrypoint) || !/\.tsx?$/.test(row.entrypoint)) throw new Error(`example entrypoint is not a listed source: ${row.id}`);
+    if (new Set(row.relatedRules).size !== row.relatedRules.length) throw new Error(`duplicate example relatedRules: ${row.id}`);
+    for (const key of ['files', 'projects', 'tests']) {
+      if (new Set(row[key]).size !== row[key].length) throw new Error(`duplicate example ${key}: ${row.id}`);
+      for (const relative of row[key]) {
+        if (relative.split('/').some((part) => ['node_modules', 'dist', '.next', '_derived', '.git'].includes(part)))
+          throw new Error(`derived or installed example input: ${relative}`);
+        referenceFile(app, relative);
+      }
+    }
+    if (row.files.some((relative) => !/\.(?:tsx?|json)$/.test(relative))) throw new Error(`unsupported example source: ${row.id}`);
+  }
+  return catalog;
+}
+
+/** Source, compiler and test inputs of selected stable IDs, relative to the runtime.
+ * A null selection requests the declared whole catalog; unknown IDs refuse. */
+export function exampleSourcePaths(root, ids = null, options = {}) {
+  const catalog = loadExampleCatalog(root, options), selected = new Set(ids ?? catalog.examples.map((row) => row.id));
+  const known = new Set(catalog.examples.map((row) => row.id));
+  for (const id of selected) if (!known.has(id)) throw new Error(`unknown example id: ${id}`);
+  return [...new Set(catalog.examples.filter((row) => selected.has(row.id))
+    .flatMap((row) => [...row.files, ...row.projects, ...row.tests].map((relative) => `${EXAMPLES_ROOT}/${row.path}/${relative}`)))];
+}
+
+/** Actual example apps' own Work trees in app-name order. Dependency/template
+ * trees are not app Work; an absent own tree contributes no checker input. */
+export function exampleWorkRoots(root) {
+  return discoverExampleApps(root).flatMap((app) => {
+    const relative = `${EXAMPLES_ROOT}/${app}/.starciwork/index.yaml`;
+    const directory = path.dirname(path.join(root, relative)), stat = fs.lstatSync(directory, { throwIfNoEntry: false });
+    if (!stat) return [];
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`invalid example Work directory: ${app}`);
+    return [path.dirname(referenceFile(root, relative))];
+  });
+}
+
+/** Per-call READ options for an actual HFS app's own Work tree. A real project
+ * uses the default external store; an example never falls back to that store.
+ * The fixture CAS is curated source, not a destination for operational writers. */
+export function exampleArtifactReadOptions(runtimeRoot, workRoot, { resolveRoot = workRoot } = {}) {
+  if (typeof runtimeRoot !== 'string' || typeof workRoot !== 'string') throw new TypeError('example artifact context needs runtime and Work paths');
+  const base = path.resolve(runtimeRoot), target = path.resolve(workRoot);
+  const relative = slash(path.relative(base, target)), parts = relative.split('/');
+  if (parts[0]?.toLowerCase() !== EXAMPLES_ROOT) return Object.freeze({});
+  const app = parts[1];
+  if (parts[0] !== EXAMPLES_ROOT || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(app ?? '')
+    || !discoverExampleApps(base).includes(app) || parts[2] !== '.starciwork')
+    throw new Error(`invalid example Work artifact context: ${relative}`);
+  referenceFile(base, `${EXAMPLES_ROOT}/${app}/hfs.json`, { exact: true });
+  referenceFile(base, `${EXAMPLES_ROOT}/${app}/.starciwork/index.yaml`, { exact: true });
+  referenceFile(base, relative, { directory: true, exact: true });
+  const resolution = path.resolve(resolveRoot), ownWork = path.join(base, EXAMPLES_ROOT, app, '.starciwork');
+  if (!insidePath(resolution, target, { includeSelf: true }) || !insidePath(ownWork, resolution, { includeSelf: true }))
+    throw new Error('selected example validation and resolution must share its own Work root');
+  referenceFile(base, slash(path.relative(base, resolution)), { directory: true, exact: true });
+  return Object.freeze({ root: path.join(base, EXAMPLE_RUNTIMES_ROOT, app, 'artifacts') });
+}