@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/lib/ts-analysis.mjs

@@ -1,37 +1,39 @@
 /** The expression under the wrappers selected by an AST check's contract. */
 export function unwrapExpression(ts, expression, { awaitExpressions = false, typeAssertions = true, nonNullExpressions = true, satisfiesExpressions = true } = {}) {
-  while (expression) {
-    const wrapper = ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
-      || (typeAssertions && ts.isTypeAssertionExpression(expression)) || (nonNullExpressions && ts.isNonNullExpression(expression))
-      || (satisfiesExpressions && (ts.isSatisfiesExpression?.(expression) ?? false))
-      || (awaitExpressions && ts.isAwaitExpression(expression));
-    if (!wrapper) break;
-    expression = expression.expression;
-  }
-  return expression;
+    let current = expression;
+    while (current) {
+        const wrapper = ts.isParenthesizedExpression(current) || ts.isAsExpression(current)
+            || (typeAssertions && ts.isTypeAssertionExpression(current)) || (nonNullExpressions && ts.isNonNullExpression(current))
+            || (satisfiesExpressions && (ts.isSatisfiesExpression?.(current) ?? false))
+            || (awaitExpressions && ts.isAwaitExpression(current));
+        if (!wrapper)
+            break;
+        current = current.expression;
+    }
+    return current;
 }
-
 /** Local name -> imported name and module; callers select their existing module key and literal policy. */
 export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiteralsOnly = false } = {}) {
-  const imports = new Map();
-  for (const statement of sourceFile.statements) {
-    if (!ts.isImportDeclaration(statement) || (stringLiteralsOnly && !ts.isStringLiteralLike(statement.moduleSpecifier))) continue;
-    const bindings = statement.importClause?.namedBindings;
-    if (!bindings || !ts.isNamedImports(bindings)) continue;
-    for (const binding of bindings.elements) imports.set(binding.name.text, { name: (binding.propertyName ?? binding.name).text, [moduleKey]: statement.moduleSpecifier.text });
-  }
-  return imports;
+    const imports = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || (stringLiteralsOnly && !ts.isStringLiteralLike(statement.moduleSpecifier)))
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const binding of bindings.elements)
+            imports.set(binding.name.text, { name: (binding.propertyName ?? binding.name).text, [moduleKey]: statement.moduleSpecifier.text });
+    }
+    return imports;
 }
-
 /** Catalog values unwrap parentheses, `as`, and `satisfies`, preserving assertions and non-null nodes. */
 export const unwrapCatalogExpression = (ts, node) => unwrapExpression(ts, node, { typeAssertions: false, nonNullExpressions: false });
-
 /** Bind this file in isolation: the compiler resolves lexical names, but imports and library files are never loaded. */
 export function lexicalChecker(ts, source) {
-  const options = { noLib: true, noResolve: true, allowJs: true };
-  const host = ts.createCompilerHost(options);
-  host.getSourceFile = (file) => file === source.fileName ? source : undefined;
-  host.fileExists = () => false;
-  host.readFile = () => undefined;
-  return ts.createProgram([source.fileName], options, host).getTypeChecker();
+    const options = { noLib: true, noResolve: true, allowJs: true };
+    const host = ts.createCompilerHost(options);
+    host.getSourceFile = (file) => file === source.fileName ? source : undefined;
+    host.fileExists = () => false;
+    host.readFile = () => undefined;
+    return ts.createProgram([source.fileName], options, host).getTypeChecker();
 }

package/runtime/scripts/lib/ts-ast.d.mts

@@ -0,0 +1,36 @@
+import type { Expression, Node, SourceFile, VariableDeclaration } from 'typescript';
+/** The TypeScript compiler module a caller resolved (see package-at.mjs loadTypescript). */
+export type TypeScript = typeof import('typescript');
+/** Whether the single-bit `flag` (a ts.NodeFlags member) is set in `flags`: the bit read as arithmetic, no bitwise operator in the condition. */
+export declare const hasFlag: (flags: number, flag: number) => boolean;
+/** Whether any bit of `mask` (a ts flag or an OR of flags) is set in `flags` (absent flags read as none): an explicit comparison of the masked value. */
+export declare const hasAnyFlag: (flags: number | undefined, mask: number) => boolean;
+/** Whether the variable `declaration` belongs to a `const` list: the TypeScript node-flag test, an explicit comparison of the masked flags. */
+export declare const isConstVariable: (ts: TypeScript, declaration: VariableDeclaration) => boolean;
+/** Text of a string-literal-like node or an enabled identifier/numeric name; null for other expressions. */
+export declare function nameText(ts: TypeScript, node: Node | undefined | null, { identifiers, numbers }?: {
+    identifiers?: boolean;
+    numbers?: boolean;
+}): string | null;
+/** A statically selected property name, including string-literal element access; null for computed selections. */
+export declare function accessName(ts: TypeScript, node: Node): string | null;
+/** The text of a string-literal-like `node` (a string literal or a no-substitution template), or null. */
+export declare const literalText: (ts: TypeScript, node: Node | undefined | null) => string | null;
+/** The 1-based {line, column} of `node` in `sourceFile`. */
+export declare const sourceLocation: (sourceFile: SourceFile, node: Node) => {
+    line: number;
+    column: number;
+};
+/**
+ * The `.text` of `key`'s property initializer in `text` (parsed as `file`): a property assignment
+ * inside an object literal, or — `declaration: true` — a class property declaration. `kind` is
+ * 'string' (a string-literal-like initializer) or 'identifier'. The last match wins; null when none.
+ */
+export declare function propertyText(ts: TypeScript, text: string, { file, key, declaration, kind }?: {
+    file?: string;
+    key?: string;
+    declaration?: boolean;
+    kind?: 'string' | 'identifier';
+}): string | null;
+/** Initializers of every identifier-named variable, grouped in traversal order across the source's scopes. */
+export declare function variableInitializerGroups(ts: TypeScript, source: SourceFile): Map<string, Expression[]>;

package/runtime/scripts/lib/ts-ast.mjs

@@ -1,69 +1,63 @@
-// ts-ast.mjs — the small reads the hfs checks share over TypeScript's own AST: a node's name or
-// literal text, a node's 1-based position, a named property's initializer text. `ts` is the caller's
-// already-resolved compiler (see package-at.mjs loadTypescript); nothing here resolves a package.
-
 /** Whether the single-bit `flag` (a ts.NodeFlags member) is set in `flags`: the bit read as arithmetic, no bitwise operator in the condition. */
 export const hasFlag = (flags, flag) => Math.floor(flags / flag) % 2 === 1;
-
 /** Whether any bit of `mask` (a ts flag or an OR of flags) is set in `flags` (absent flags read as none): an explicit comparison of the masked value. */
 export const hasAnyFlag = (flags, mask) => ((flags ?? 0) & mask) !== 0;
-
 /** Whether the variable `declaration` belongs to a `const` list: the TypeScript node-flag test, an explicit comparison of the masked flags. */
 export const isConstVariable = (ts, declaration) => (ts.getCombinedNodeFlags(declaration.parent) & ts.NodeFlags.Const) !== 0;
-
 /** Text of a string-literal-like node or an enabled identifier/numeric name; null for other expressions. */
 export function nameText(ts, node, { identifiers = true, numbers = false } = {}) {
-  if (!node) return null;
-  if (ts.isStringLiteralLike(node) || (identifiers && ts.isIdentifier(node)) || (numbers && ts.isNumericLiteral(node))) return node.text;
-  return null;
+    if (!node)
+        return null;
+    if (ts.isStringLiteralLike(node) || (identifiers && ts.isIdentifier(node)) || (numbers && ts.isNumericLiteral(node)))
+        return node.text;
+    return null;
 }
-
 /** A statically selected property name, including string-literal element access; null for computed selections. */
 export function accessName(ts, node) {
-  if (ts.isPropertyAccessExpression(node)) return node.name.text;
-  return ts.isElementAccessExpression(node) ? literalText(ts, node.argumentExpression) : null;
+    if (ts.isPropertyAccessExpression(node))
+        return node.name.text;
+    return ts.isElementAccessExpression(node) ? literalText(ts, node.argumentExpression) : null;
 }
-
 /** The text of a string-literal-like `node` (a string literal or a no-substitution template), or null. */
 export const literalText = (ts, node) => (node && ts.isStringLiteralLike(node) ? node.text : null);
-
 /** The 1-based {line, column} of `node` in `sourceFile`. */
 export const sourceLocation = (sourceFile, node) => {
-  const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
-  return { line: position.line + 1, column: position.character + 1 };
+    const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    return { line: position.line + 1, column: position.character + 1 };
 };
-
 /**
  * The `.text` of `key`'s property initializer in `text` (parsed as `file`): a property assignment
  * inside an object literal, or — `declaration: true` — a class property declaration. `kind` is
  * 'string' (a string-literal-like initializer) or 'identifier'. The last match wins; null when none.
  */
 export function propertyText(ts, text, { file = 'source.ts', key, declaration = false, kind = 'string' } = {}) {
-  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-  let value = null;
-  const visit = (node) => {
-    const isProp = declaration ? ts.isPropertyDeclaration(node) : ts.isPropertyAssignment(node);
-    if (isProp && node.name && ts.isIdentifier(node.name) && node.name.text === key && node.initializer) {
-      const ok = kind === 'identifier' ? ts.isIdentifier(node.initializer) : ts.isStringLiteralLike(node.initializer);
-      if (ok) value = node.initializer.text;
-    }
-    ts.forEachChild(node, visit);
-  };
-  visit(source);
-  return value;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    let value = null;
+    const visit = (node) => {
+        const prop = declaration
+            ? (ts.isPropertyDeclaration(node) ? node : undefined)
+            : (ts.isPropertyAssignment(node) ? node : undefined);
+        if (prop?.name && ts.isIdentifier(prop.name) && prop.name.text === key && prop.initializer) {
+            const initializer = prop.initializer;
+            if (kind === 'identifier' ? ts.isIdentifier(initializer) : ts.isStringLiteralLike(initializer))
+                value = initializer.text;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return value;
 }
-
 /** Initializers of every identifier-named variable, grouped in traversal order across the source's scopes. */
 export function variableInitializerGroups(ts, source) {
-  const groups = new Map();
-  const collect = (node) => {
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
-      const initializers = groups.get(node.name.text) ?? [];
-      initializers.push(node.initializer);
-      groups.set(node.name.text, initializers);
-    }
-    ts.forEachChild(node, collect);
-  };
-  collect(source);
-  return groups;
+    const groups = new Map();
+    const collect = (node) => {
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+            const initializers = groups.get(node.name.text) ?? [];
+            initializers.push(node.initializer);
+            groups.set(node.name.text, initializers);
+        }
+        ts.forEachChild(node, collect);
+    };
+    collect(source);
+    return groups;
 }

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

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+/** Whether `target` is `root` itself or inside it (filesystem paths, either separator). `includeSelf: false` excludes `target === root`. */
+export declare function isInside(root: string, target: string, { includeSelf }?: {
+    includeSelf?: boolean;
+}): boolean;
+/** The options of walkFiles. */
+export interface WalkOptions {
+    filter?: (name: string, full: string) => boolean;
+    sorted?: boolean;
+    exclude?: (name: string, full: string, entry: fs.Dirent) => boolean;
+    maxDepth?: number;
+    ignoreReadErrors?: boolean;
+}
+/**
+ * Every entry under `dir` that is not a directory, depth-first; `filter` sees the entry name and full
+ * path. `sorted` sorts each directory's entries by name (default: readdir order). `exclude`
+ * applies to files and directories before descent; `maxDepth` counts from the starting dir.
+ */
+export declare function walkFiles(dir: string, { filter, sorted, exclude, maxDepth, ignoreReadErrors }?: WalkOptions): string[];

package/runtime/scripts/lib/walk.mjs

@@ -1,39 +1,45 @@
 // walk.mjs - filesystem walking helpers: isInside (containment) and walkFiles (depth-first file listing).
 import fs from 'node:fs';
 import path from 'node:path';
-
 /** Whether `target` is `root` itself or inside it (filesystem paths, either separator). `includeSelf: false` excludes `target === root`. */
 export function isInside(root, target, { includeSelf = true } = {}) {
-  const relative = path.relative(root, target);
-  if (relative === '') return includeSelf;
-  return !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative);
+    const relative = path.relative(root, target);
+    if (relative === '')
+        return includeSelf;
+    return !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative);
 }
 /**
  * Every entry under `dir` that is not a directory, depth-first; `filter` sees the entry name and full
  * path. `sorted` sorts each directory's entries by name (default: readdir order). `exclude`
  * applies to files and directories before descent; `maxDepth` counts from the starting dir.
  */
-export function walkFiles(dir, {filter = () => true, sorted = false, exclude = () => false,
-  maxDepth = Infinity, ignoreReadErrors = false} = {}) {
-  const out = [];
-  const visit = (current, depth) => {
-    if (depth > maxDepth) return;
-    let entries;
-    try { entries = fs.readdirSync(current, {withFileTypes: true}); }
-    catch (error) {
-      if (ignoreReadErrors) {
-        return;
-      }
-      throw error;
-    }
-    if (sorted) entries = entries.sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-      const full = path.join(current, entry.name);
-      if (exclude(entry.name, full, entry)) continue;
-      if (entry.isDirectory()) visit(full, depth + 1);
-      else if (filter(entry.name, full)) out.push(full);
-    }
-  };
-  visit(dir, 0);
-  return out;
+export function walkFiles(dir, { filter = () => true, sorted = false, exclude = () => false, maxDepth = Infinity, ignoreReadErrors = false } = {}) {
+    const out = [];
+    const visit = (current, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch (error) {
+            if (ignoreReadErrors) {
+                return;
+            }
+            throw error;
+        }
+        if (sorted)
+            entries = entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (exclude(entry.name, full, entry))
+                continue;
+            if (entry.isDirectory())
+                visit(full, depth + 1);
+            else if (filter(entry.name, full))
+                out.push(full);
+        }
+    };
+    visit(dir, 0);
+    return out;
 }

package/runtime/scripts/lib/work-edition.d.mts

@@ -0,0 +1,10 @@
+/** Unrendered Work seeds in this runtime's app skeletons are templates, not product records. */
+export declare function isWorkTemplatePath(file: string): boolean;
+/** Whether the app owning this Work root declares lite. Missing declarations retain the full reader contract. */
+export declare function isLiteWorkRoot(workRoot: string | null | undefined): boolean;
+/** Whether a reader may open `file`: external files are unaffected; lite Work paths keep workspace.yaml and brand/**. */
+export declare function workPathAllowed(workRoot: string | null | undefined, file: string, { dir }?: {
+    dir?: boolean;
+}): boolean;
+/** Every forbidden entry directly below a lite Work root, including empty directories. Never read their contents. */
+export declare function liteWorkForbiddenPaths(workRoot: string): string[];

package/runtime/scripts/lib/work-edition.mjs

@@ -4,37 +4,45 @@ import path from 'node:path';
 import { isLiteProductPath } from './starciwork-boundary.mjs';
 import { foldCase } from './path-key.mjs';
 import { WORK_DIR_NAME } from './roots.mjs';
-
 const appTemplatesRoot = path.resolve(import.meta.dirname, '..', '..', 'packages', 'hfs', 'templates', 'app');
-
 /** Unrendered Work seeds in this runtime's app skeletons are templates, not product records. */
 export function isWorkTemplatePath(file) {
-  const [skeleton, work] = foldCase(path.relative(appTemplatesRoot, path.resolve(file))).replaceAll('\\', '/').split('/');
-  return (skeleton === 'skeleton' || skeleton === 'skeleton-lite') && work === WORK_DIR_NAME;
+    const [skeleton, work] = foldCase(path.relative(appTemplatesRoot, path.resolve(file))).replaceAll('\\', '/').split('/');
+    return (skeleton === 'skeleton' || skeleton === 'skeleton-lite') && work === WORK_DIR_NAME;
 }
-
 /** Whether the app owning this Work root declares lite. Missing declarations retain the full reader contract. */
 export function isLiteWorkRoot(workRoot) {
-  if (!workRoot) return false;
-  try {
-    const declaration = JSON.parse(fs.readFileSync(path.join(path.dirname(path.resolve(workRoot)), 'hfs.json'), 'utf8'));
-    return declaration?.kind === 'app' && declaration?.edition === 'lite';
-  } catch { return false; }
+    if (!workRoot)
+        return false;
+    try {
+        // reason: hfs.json is parsed from disk; only `kind` and `edition` are read.
+        const declaration = JSON.parse(fs.readFileSync(path.join(path.dirname(path.resolve(workRoot)), 'hfs.json'), 'utf8'));
+        return declaration?.kind === 'app' && declaration?.edition === 'lite';
+    }
+    catch {
+        return false;
+    }
 }
-
 /** Whether a reader may open `file`: external files are unaffected; lite Work paths keep workspace.yaml and brand/**. */
 export function workPathAllowed(workRoot, file, { dir = false } = {}) {
-  if (!isLiteWorkRoot(workRoot)) return true;
-  const rel = path.relative(path.resolve(workRoot), path.resolve(file)).replaceAll('\\', '/');
-  if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) return true;
-  return !rel || isLiteProductPath(rel, { dir });
+    if (!isLiteWorkRoot(workRoot))
+        return true;
+    const rel = path.relative(path.resolve(workRoot), path.resolve(file)).replaceAll('\\', '/');
+    if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel))
+        return true;
+    return !rel || isLiteProductPath(rel, { dir });
 }
-
 /** Every forbidden entry directly below a lite Work root, including empty directories. Never read their contents. */
 export function liteWorkForbiddenPaths(workRoot) {
-  if (!isLiteWorkRoot(workRoot)) return [];
-  let entries;
-  try { entries = fs.readdirSync(workRoot, { withFileTypes: true }); } catch { return []; }
-  return entries.filter(entry => !isLiteProductPath(entry.name, { dir: entry.isDirectory() }))
-    .map(entry => path.join(workRoot, entry.name));
+    if (!isLiteWorkRoot(workRoot))
+        return [];
+    let entries;
+    try {
+        entries = fs.readdirSync(workRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter(entry => !isLiteProductPath(entry.name, { dir: entry.isDirectory() }))
+        .map(entry => path.join(workRoot, entry.name));
 }

package/runtime/scripts/lib/workflow-events.d.mts

@@ -0,0 +1,2 @@
+/** Convert shorthand workflow events into an options map; mappings retain their values. */
+export declare function workflowEventOptions<T>(on: string | readonly string[] | T, eventName?: (event: string) => string): Record<string, null> | T;

package/runtime/scripts/lib/workflow-events.mjs

@@ -1,8 +1,9 @@
 // GitHub workflow `on` supports a scalar event, an event list or an options map.
-
 /** Convert shorthand workflow events into an options map; mappings retain their values. */
 export function workflowEventOptions(on, eventName = (event) => event) {
-  if (typeof on === 'string') return { [on]: null };
-  if (Array.isArray(on)) return Object.fromEntries(on.map((event) => [eventName(event), null]));
-  return on;
+    if (typeof on === 'string')
+        return { [on]: null };
+    if (Array.isArray(on))
+        return Object.fromEntries(on.map((event) => [eventName(event), null]));
+    return on;
 }

package/runtime/scripts/lib/worktree-exclude.d.mts

@@ -0,0 +1,16 @@
+/** The worktrees directory, relative to the product repository root (posix). */
+export declare const WORKTREES_REL = ".starciwork/worktrees";
+/** Glob patterns an ESLint/tsc-style ignore list takes. */
+export declare const WORKTREES_IGNORE_GLOBS: readonly string[];
+/**
+ * True when `rel` (a path relative to a repository root, either slash) is the worktrees directory or inside it.
+ * With `root`, `rel` may be absolute: it is made relative to root first.
+ */
+export declare function isWorktreesPath(rel: unknown, { root }?: {
+    root?: string | null;
+}): boolean;
+/**
+ * True when `abs` is a worktrees dir (or inside one) BELOW the scan root `root`. Always relative to the root a walker
+ * started from: a walker whose root is itself a runtime tree (<repo>/.starciwork/worktrees/<name>) must still walk it.
+ */
+export declare const underWorktrees: (root: unknown, abs: unknown) => boolean;

package/runtime/scripts/lib/worktree-exclude.mjs

@@ -9,25 +9,23 @@
 // skips it with isWorktreesPath / WORKTREES_IGNORE_GLOBS, or it would lint and hash every sibling worktree.
 import path from 'node:path';
 import { posixPath } from './path-key.mjs';
-
 /** The worktrees directory, relative to the product repository root (posix). */
 export const WORKTREES_REL = '.starciwork/worktrees';
 /** Glob patterns an ESLint/tsc-style ignore list takes. */
 export const WORKTREES_IGNORE_GLOBS = Object.freeze([`${WORKTREES_REL}/**`, `**/${WORKTREES_REL}/**`]);
-
 const posix = posixPath;
-
 /**
  * True when `rel` (a path relative to a repository root, either slash) is the worktrees directory or inside it.
  * With `root`, `rel` may be absolute: it is made relative to root first.
  */
 export function isWorktreesPath(rel, { root = null } = {}) {
-  let p = posix(rel);
-  if (root && path.isAbsolute(String(rel))) p = posix(path.relative(root, String(rel)));
-  while (p.endsWith('/')) p = p.slice(0, -1);
-  return p === WORKTREES_REL || p.startsWith(`${WORKTREES_REL}/`) || p.includes(`/${WORKTREES_REL}/`) || p.endsWith(`/${WORKTREES_REL}`);
+    let p = posix(rel);
+    if (root && path.isAbsolute(String(rel)))
+        p = posix(path.relative(root, String(rel)));
+    while (p.endsWith('/'))
+        p = p.slice(0, -1);
+    return p === WORKTREES_REL || p.startsWith(`${WORKTREES_REL}/`) || p.includes(`/${WORKTREES_REL}/`) || p.endsWith(`/${WORKTREES_REL}`);
 }
-
 /**
  * True when `abs` is a worktrees dir (or inside one) BELOW the scan root `root`. Always relative to the root a walker
  * started from: a walker whose root is itself a runtime tree (<repo>/.starciwork/worktrees/<name>) must still walk it.

package/runtime/scripts/lib/yaml-cached.d.mts

@@ -0,0 +1,2 @@
+/** The parsed document of `text`: parsed on the first ask for this text, a structured copy afterwards. Throws what parseYaml throws, every time. */
+export declare function parseYamlCached(text: string): any;

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

@@ -4,11 +4,11 @@
 // bytes do not change between those asks, so the parse (the dominant cost of a load) is keyed by the text itself; each caller gets its own copy of the
 // parsed document, so nothing a caller does to it reaches the next one. A changed file is a different text and parses again.
 import { parseYaml } from '../../engine/yaml.mjs';
-
 const parsed = new Map();
-
 /** The parsed document of `text`: parsed on the first ask for this text, a structured copy afterwards. Throws what parseYaml throws, every time. */
+// reason: the parsed YAML document is an unvalidated input boundary; each caller narrows what it reads.
 export function parseYamlCached(text) {
-  if (!parsed.has(text)) parsed.set(text, parseYaml(text));
-  return structuredClone(parsed.get(text));
+    if (!parsed.has(text))
+        parsed.set(text, parseYaml(text));
+    return structuredClone(parsed.get(text));
 }

package/runtime/scripts/machine/artifact-hold.d.mts

@@ -0,0 +1,26 @@
+/** An enrolled ledger: its sqlite file and the repository that owns it. */
+interface RegisteredRepo {
+    ledger: string;
+    repo: string;
+}
+/** What artifactHoldOf answers when a removal touches a held file. */
+export interface ArtifactHold {
+    ledger: string;
+    repo: string | null;
+    paths: string[];
+    count: number | null;
+    error?: string;
+}
+interface HoldOptions {
+    env?: NodeJS.ProcessEnv;
+    repos?: RegisteredRepo[] | null;
+}
+/**
+ * Null when removing `target` touches no held file; else {ledger, repo, paths, count}.
+ * Held: a registered ledger file at or under `target`. An unreadable registry holds every path in or
+ * holding the projects root of the host-state directory (fail closed).
+ */
+export declare function artifactHoldOf(target: string, { env, repos }?: HoldOptions): ArtifactHold | null;
+/** artifactHoldOf as one refusal line, or null. */
+export declare const artifactHoldReason: (target: string, options?: HoldOptions) => string | null;
+export {};

package/runtime/scripts/machine/artifact-hold.mjs

@@ -11,42 +11,41 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { localProjectsRoot, machineFileFor, readMachine } from '../../engine/db/machine.mjs';
 import { pathKey, sameOrUnder } from '../lib/path-key.mjs';
-
 const REGISTRY_TTL_MS = 30000;
 const norm = pathKey;
 let cache = { file: null, at: 0, repos: [] };
-
 /** The repositories whose ledgers the registry enrols: [{repo, ledger}], cached briefly per registry file; null when the registry cannot be read. */
 function registeredRepos({ env = process.env, now = Date.now() } = {}) {
-  const file = machineFileFor(env);
-  if (cache.file === file && now - cache.at < REGISTRY_TTL_MS) return cache.repos;
-  const repos = fs.existsSync(file) ? readMachine((m) => m.listLedgers().map((l) => ({ ledger: l.file, repo: l.repoRoot })), null, { file, env }) : [];
-  cache = { file, at: now, repos };
-  return repos;
+    const file = machineFileFor(env);
+    if (cache.file === file && now - cache.at < REGISTRY_TTL_MS)
+        return cache.repos;
+    const repos = fs.existsSync(file) ? readMachine((m) => m.listLedgers().map((l) => ({ ledger: l.file, repo: l.repoRoot })), null, { file, env }) : [];
+    cache = { file, at: now, repos };
+    return repos;
 }
-
 /**
  * Null when removing `target` touches no held file; else {ledger, repo, paths, count}.
  * Held: a registered ledger file at or under `target`. An unreadable registry holds every path in or
  * holding the projects root of the host-state directory (fail closed).
  */
 export function artifactHoldOf(target, { env = process.env, repos = registeredRepos({ env }) } = {}) {
-  const t = norm(target);
-  if (repos === null) {
-    const projects = norm(localProjectsRoot(env));
-    return sameOrUnder(t, projects) || sameOrUnder(projects, t) ? { ledger: machineFileFor(env), repo: null, paths: [], count: null, error: 'the machine registry cannot be read' } : null;
-  }
-  for (const { ledger, repo } of repos) {
-    // The typed logs (scripts/kernel/typed-logs.mjs: the ledger's logs table) are append-only history: never swept.
-    if (ledger && sameOrUnder(norm(ledger), t) && fs.existsSync(ledger)) return { ledger, repo, paths: [path.basename(ledger)], count: 1 };
-  }
-  return null;
+    const t = norm(target);
+    if (repos === null) {
+        const projects = norm(localProjectsRoot(env));
+        return sameOrUnder(t, projects) || sameOrUnder(projects, t) ? { ledger: machineFileFor(env), repo: null, paths: [], count: null, error: 'the machine registry cannot be read' } : null;
+    }
+    for (const { ledger, repo } of repos) {
+        // The typed logs (scripts/kernel/typed-logs.mjs: the ledger's logs table) are append-only history: never swept.
+        if (ledger && sameOrUnder(norm(ledger), t) && fs.existsSync(ledger))
+            return { ledger, repo, paths: [path.basename(ledger)], count: 1 };
+    }
+    return null;
 }
-
 /** artifactHoldOf as one refusal line, or null. */
 export const artifactHoldReason = (target, options) => {
-  const hold = artifactHoldOf(target, options);
-  if (!hold) return null;
-  return hold.error ? `${hold.error} (${hold.ledger})`
-    : `${hold.count} ledger file(s) of ${hold.ledger} (${hold.paths.join(', ')})`;
+    const hold = artifactHoldOf(target, options);
+    if (!hold)
+        return null;
+    return hold.error ? `${hold.error} (${hold.ledger})`
+        : `${hold.count} ledger file(s) of ${hold.ledger} (${hold.paths.join(', ')})`;
 };