@starci/hfs 4.0.9 → 4.0.10

package/runtime/scripts/lib/clip.mjs

@@ -0,0 +1,19 @@
+// clip.mjs — shortening text for a message, a log line or a finding.
+
+/** `text` cut to at most `n` characters; a cut text ends in an ellipsis. */
+export const clip = (text, n) => { const s = String(text ?? ''); return s.length > n ? `${s.slice(0, n - 1)}…` : s; };
+
+/** `text` squashed to one line: whitespace runs collapsed, ends trimmed. */
+export const squash = (text) => String(text ?? '').replace(/\s+/g, ' ').trim();
+
+/** `text` on one line (whitespace runs collapsed, ends trimmed), cut to at most `n` characters. */
+export const clipLine = (text, n) => clip(squash(text), n);
+
+/** `text` on one line (whitespace runs collapsed, ends trimmed), cut to at most `n` characters — a plain cut, no ellipsis. */
+export const oneLine = (text, n = 380) => squash(text).slice(0, n);
+
+/** The last `n` lines of `text` (ends trimmed) joined with `join`, cut to at most `max` characters. */
+export const tailLines = (text, n = 30, { join = '\n', max = Infinity } = {}) => {
+  const tail = String(text ?? '').trim().split(/\r?\n/).slice(-n).join(join);
+  return Number.isFinite(max) ? tail.slice(0, max) : tail;
+};

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/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') });
+}

package/runtime/scripts/lib/fs-kind.mjs

@@ -2,9 +2,19 @@
 // A missing or unreadable path is false/null, never a throw; the stat syscall decides kind.
 import fs from 'node:fs';
 
-/** `p` names a file; false on any stat error (missing path, dangling link, EPERM). */
-export const isFile = (p) => { try { return fs.statSync(p).isFile(); } catch { return false; } };
-/** `p` names a directory; false on any stat error. */
-export const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+/** `p` names a file within `maxBytes`; false on any stat error. `followLinks: false` probes the entry itself. */
+export const isFile = (p, { followLinks = true, maxBytes = Infinity } = {}) => {
+  try {
+    const stat = followLinks ? fs.statSync(p) : fs.lstatSync(p);
+    return stat.isFile() && (followLinks || !stat.isSymbolicLink()) && stat.size <= maxBytes;
+  } catch { return false; }
+};
+/** `p` names a directory; false on any stat error. `followLinks: false` refuses linked entries. */
+export const isDir = (p, { followLinks = true } = {}) => {
+  try {
+    const stat = followLinks ? fs.statSync(p) : fs.lstatSync(p);
+    return stat.isDirectory() && (followLinks || !stat.isSymbolicLink());
+  } catch { return false; }
+};
 /** `p`'s canonical spelling via the filesystem (links resolved), or null when it cannot be read. */
 export const realpathOr = (p) => { try { return fs.realpathSync.native(p); } catch { return null; } };

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

@@ -0,0 +1,52 @@
+// json-schema.mjs - a minimal draft-2020-12 JSON schema walker over the keywords the runtime's yaml schemas use.
+import {isPlainObject} from '../../engine/plain-object.mjs';
+
+// A minimal draft-2020-12 walker over the keywords op.schema.yaml uses. ajv is
+// a devDependency; the runtime has no npm dependencies, so the walker is here.
+export function validateAgainstSchema(value, schema) {
+  const errors = [];
+  const resolve = (ref) => String(ref).replace(/^#\//, '').split('/')
+    .reduce((node, key) => node?.[key.replaceAll('~1', '/').replaceAll('~0', '~')], schema);
+  const typeOk = (node, type) => {
+    if (Array.isArray(type)) return type.some((t) => typeOk(node, t));
+    if (type === 'object') return isPlainObject(node);
+    if (type === 'array') return Array.isArray(node);
+    if (type === 'integer') return Number.isInteger(node);
+    if (type === 'null') return node === null;
+    return typeof node === type;
+  };
+  const walk = (node, shape, at) => {
+    if (!isPlainObject(shape)) return;
+    if (shape.$ref) { walk(node, resolve(shape.$ref), at); return; }
+    if (shape.type !== undefined && !typeOk(node, shape.type)) {
+      errors.push(`${at}: expected ${Array.isArray(shape.type) ? shape.type.join('|') : shape.type}`);
+      return;
+    }
+    if (Object.hasOwn(shape, 'const') && node !== shape.const) errors.push(`${at}: must be ${JSON.stringify(shape.const)}`);
+    if (Array.isArray(shape.enum) && !shape.enum.includes(node)) errors.push(`${at}: ${JSON.stringify(node)} is outside [${shape.enum.join(', ')}]`);
+    if (typeof node === 'string') {
+      if (shape.minLength !== undefined && node.length < shape.minLength) errors.push(`${at}: empty or too short`);
+      if (shape.pattern && !new RegExp(shape.pattern, 'u').test(node)) errors.push(`${at}: ${JSON.stringify(node)} does not match ${shape.pattern}`);
+    }
+    if (typeof node === 'number') {
+      if (shape.minimum !== undefined && node < shape.minimum) errors.push(`${at}: below minimum ${shape.minimum}`);
+      if (shape.maximum !== undefined && node > shape.maximum) errors.push(`${at}: above maximum ${shape.maximum}`);
+    }
+    if (Array.isArray(node)) {
+      if (shape.minItems !== undefined && node.length < shape.minItems) errors.push(`${at}: needs at least ${shape.minItems} item(s)`);
+      if (shape.items) node.forEach((item, i) => walk(item, shape.items, `${at}[${i}]`));
+      return;
+    }
+    if (!isPlainObject(node)) return;
+    if (shape.minProperties !== undefined && Object.keys(node).length < shape.minProperties) errors.push(`${at}: needs at least ${shape.minProperties} entr(y|ies)`);
+    for (const key of shape.required ?? []) if (!Object.hasOwn(node, key)) errors.push(`${at}: missing ${key}`);
+    for (const [key, child] of Object.entries(node)) {
+      const where = at === '$' ? `$.${key}` : `${at}.${key}`;
+      if (Object.hasOwn(shape.properties ?? {}, key)) walk(child, shape.properties[key], where);
+      else if (shape.additionalProperties === false) errors.push(`${where}: unknown key`);
+      else if (isPlainObject(shape.additionalProperties)) walk(child, shape.additionalProperties, where);
+    }
+  };
+  walk(value, schema, '$');
+  return errors;
+}

package/runtime/scripts/lib/mutation-fence.mjs

@@ -0,0 +1,15 @@
+// mutation-fence.mjs — ephemeral admission carried through awaited work, never a state store.
+import { AsyncLocalStorage } from 'node:async_hooks';
+const scope = new AsyncLocalStorage();
+
+/** Run one admitted call; the checker is synchronous and reads its existing durable owners again. */
+export const withMutationFence = (check, authority, fn) => scope.run({ check, authority, checking: false }, fn);
+/** Recheck after the actual transaction lock or immediately before a native effect. */
+export function assertMutationFence(boundary) {
+  const current = scope.getStore();
+  if (!current || current.checking) return;
+  current.checking = true;
+  try { current.check(boundary); } finally { current.checking = false; }
+}
+/** Identity stamped by existing write owners, never accepted from a command argument. */
+export const mutationAuthority = () => scope.getStore()?.authority ?? null;

package/runtime/scripts/lib/path-key.mjs

@@ -54,12 +54,12 @@ export const resolvedKey = (p) => foldCase(path.resolve(p));
 /** Whether `a` and `b` resolve to the same path (always case-folded, so differently-cased spellings count). */
 export const sameResolvedPath = (a, b) => pathKey(a, { fold: true }) === pathKey(b, { fold: true });
 /**
- * Whether `file` sits strictly under `root`. `key` normalizes both sides first (e.g. the registry's
- * realpath-folded treeKey) when the callers' spellings need it.
+ * Whether `file` sits under `root`; `includeSelf` also admits the root itself. `key` normalizes
+ * both sides first (e.g. the registry's realpath-folded treeKey) when their spellings need it.
  */
-export const insidePath = (root, file, { key = (p) => p } = {}) => {
+export const insidePath = (root, file, { key = (p) => p, includeSelf = false } = {}) => {
   const rel = path.relative(key(root), key(file));
-  return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
+  return (includeSelf || Boolean(rel)) && !rel.startsWith('..') && !path.isAbsolute(rel);
 };
 /**
  * A path-ish value (a string or a {path} entry) in relative compare form: trimmed, forward slashes,

package/runtime/scripts/lib/process-identity.mjs

@@ -0,0 +1,6 @@
+// Pure identity shape and receipt schema shared by the process API and its domain consumers.
+export const OWNED_PROCESS_SCHEMA = 'starci/owned-process@1';
+
+/** A complete Windows process identity: positive PID, native birth and absolute executable; presence grants no launch authority. */
+export const validProcessIdentity = (value) => Number.isInteger(value?.pid) && value.pid > 0
+  && /^[1-9]\d{15,19}$/.test(String(value?.birth ?? '')) && typeof value?.exe === 'string' && /^(?:[a-z]:[\\/]|\\\\)/i.test(value.exe);

package/runtime/scripts/lib/read-yaml.mjs

@@ -0,0 +1,18 @@
+// yaml.mjs — the forgiving YAML read: a module file a peer wrote, a missing agent card or a truncated
+// template is the caller's fallback, never a throw (the JSON twin is ./json.mjs readJsonFile).
+import { parseYaml } from '../../engine/yaml.mjs';
+import { readParsedFile } from './read-text.mjs';
+
+/** `file` read and parsed as YAML, or `fallback` when it is missing, unreadable or malformed. */
+export const readYamlFile = (file, fallback = null) => readParsedFile(file, parseYaml, fallback);
+
+/** `file` (YAML) overlaid on `defaults`: each declared key whose doc value is a positive finite number. */
+export const yamlNumberSettings = (file, defaults) => {
+  const doc = readYamlFile(file) ?? {};
+  const out = { ...defaults };
+  for (const key of Object.keys(defaults)) {
+    const n = Number(doc[key]);
+    if (Number.isFinite(n) && n > 0) out[key] = n;
+  }
+  return out;
+};