@starci/hfs 4.0.9 → 4.1.0

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

@@ -0,0 +1,262 @@
+// graphql-sdl.mjs - the GraphQL tokenizer and the schema (SDL) reader of graphql-contract.mjs: tokens, a cursor over them, the
+// type, value and directive readers a document shares, and `parseSchema` over the SDL `starci app emit` writes. No dependency:
+// the runtime ships no GraphQL library.
+
+const PUNCTUATORS = new Set(['{', '}', '(', ')', '[', ']', ':', '!', '=', '$', '@', '|', '&']);
+
+/** The tokens of a GraphQL source: names, punctuators, `...`, strings and numbers; comments and commas are insignificant. */
+function commentEnd(source, index) { while (index < source.length && source[index] !== '\n') { index += 1; } return index; }
+function blockStringAt(source, index) { const end = source.indexOf('"""', index + 3); if (end === -1) { throw new SyntaxError('unterminated block string'); } return { token: { kind: 'string', value: source.slice(index + 3, end) }, next: end + 3 }; }
+function quotedStringAt(source, index) { let end = index + 1; while (end < source.length && source[end] !== '"') { end += source[end] === '\\' ? 2 : 1; } return { token: { kind: 'string', value: source.slice(index + 1, end) }, next: end + 1 }; }
+function nameAt(source, index) { const match = /^[_A-Za-z]\w*/.exec(source.slice(index)); return { token: { kind: 'name', value: match[0] }, next: index + match[0].length }; }
+function numberAt(source, index) { return /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(source.slice(index)); }
+export function tokenize(source) {
+  const tokens = [];
+  let index = 0;
+  while (index < source.length) {
+    const char = source[index];
+    if (char === '#') {
+      index = commentEnd(source, index);
+    } else if (/[\s,]/.test(char)) {
+      index += 1;
+    } else if (source.startsWith('...', index)) {
+      tokens.push({ kind: 'spread', value: '...' });
+      index += 3;
+    } else if (source.startsWith('"""', index)) {
+      const parsed = blockStringAt(source, index);
+      tokens.push(parsed.token);
+      index = parsed.next;
+    } else if (char === '"') {
+      const parsed = quotedStringAt(source, index);
+      tokens.push(parsed.token);
+      index = parsed.next;
+    } else if (PUNCTUATORS.has(char)) {
+      tokens.push({ kind: 'punct', value: char });
+      index += 1;
+    } else if (/[_A-Za-z]/.test(char)) {
+      const parsed = nameAt(source, index);
+      tokens.push(parsed.token);
+      index = parsed.next;
+    } else if (/[-0-9]/.test(char)) {
+      const match = numberAt(source, index);
+      if (!match) throw new SyntaxError(`unexpected character "${char}"`);
+      tokens.push({ kind: 'number', value: match[0] });
+      index += match[0].length;
+    } else {
+      throw new SyntaxError(`unexpected character "${char}"`);
+    }
+  }
+  return tokens;
+}
+
+/** A cursor over tokens with the expectations both parsers share. */
+export function cursorOf(tokens) {
+  let index = 0;
+  const cursor = {
+    peek: (offset = 0) => tokens[index + offset] ?? null,
+    next: () => {
+      const token = tokens[index];
+      if (token === undefined) throw new SyntaxError('unexpected end of document');
+      index += 1;
+      return token;
+    },
+    is: (value) => tokens[index]?.value === value && tokens[index]?.kind !== 'string',
+    done: () => index >= tokens.length,
+    take: (value) => {
+      if (!cursor.is(value)) return false;
+      index += 1;
+      return true;
+    },
+    expect: (value) => {
+      const token = cursor.next();
+      if (token.value !== value || token.kind === 'string') throw new SyntaxError(`expected "${value}", found "${token.value}"`);
+      return token;
+    },
+    name: () => {
+      const token = cursor.next();
+      if (token.kind !== 'name') throw new SyntaxError(`expected a name, found "${token.value}"`);
+      return token.value;
+    },
+  };
+  return cursor;
+}
+
+/** A type reference: `{ name, list, nonNull, item }`. */
+export function parseTypeRef(cursor) {
+  let type;
+  if (cursor.take('[')) {
+    const item = parseTypeRef(cursor);
+    cursor.expect(']');
+    type = { list: true, item, name: item.name, nonNull: false };
+  } else {
+    type = { list: false, name: cursor.name(), nonNull: false };
+  }
+  if (cursor.take('!')) type = { ...type, nonNull: true };
+  return type;
+}
+
+/** Skips one value of any shape (a default value, a directive argument). */
+export function skipValue(cursor) {
+  const token = cursor.next();
+  if (token.kind !== 'punct') return;
+  if (token.value === '$') return void cursor.name();
+  let close = null;
+  if (token.value === '{') close = '}';
+  else if (token.value === '[') close = ']';
+  if (close === null) return;
+  while (!cursor.take(close)) {
+    if (token.value === '{') {
+      cursor.name();
+      cursor.expect(':');
+    }
+    skipValue(cursor);
+  }
+}
+
+export function skipDirectives(cursor) {
+  while (cursor.take('@')) {
+    cursor.name();
+    if (cursor.take('(')) {
+      while (!cursor.take(')')) {
+        cursor.name();
+        cursor.expect(':');
+        skipValue(cursor);
+      }
+    }
+  }
+}
+
+function skipDescription(cursor) {
+  if (cursor.peek()?.kind === 'string') cursor.next();
+}
+
+/** Field or input-value definitions between braces. */
+function parseFieldDefinitions(cursor, withArguments) {
+  const fields = new Map();
+  cursor.expect('{');
+  while (!cursor.take('}')) {
+    skipDescription(cursor);
+    const name = cursor.name();
+    const args = new Map();
+    if (withArguments && cursor.take('(')) {
+      while (!cursor.take(')')) {
+        skipDescription(cursor);
+        const argName = cursor.name();
+        cursor.expect(':');
+        const type = parseTypeRef(cursor);
+        const hasDefault = cursor.take('=');
+        if (hasDefault) skipValue(cursor);
+        skipDirectives(cursor);
+        args.set(argName, { type, hasDefault });
+      }
+    }
+    cursor.expect(':');
+    const type = parseTypeRef(cursor);
+    const hasDefault = cursor.take('=');
+    if (hasDefault) skipValue(cursor);
+    skipDirectives(cursor);
+    fields.set(name, { type, args, hasDefault });
+  }
+  return fields;
+}
+
+// `schema { query: Q ... }` (or `extend schema`): the root operation type names.
+function readSchemaDefinition(cursor, keyword, roots) {
+  if (keyword === 'extend') cursor.name();
+  skipDirectives(cursor);
+  cursor.expect('{');
+  while (!cursor.take('}')) {
+    const operation = cursor.name();
+    cursor.expect(':');
+    roots[operation] = cursor.name();
+  }
+}
+
+// `directive @name(args) repeatable on A | B`: read and dropped.
+function skipDirectiveDefinition(cursor) {
+  cursor.expect('@');
+  cursor.name();
+  if (cursor.take('(')) parseArgumentList(cursor);
+  if (cursor.is('repeatable')) cursor.name();
+  cursor.name();
+  cursor.take('|');
+  cursor.name();
+  while (cursor.take('|')) cursor.name();
+}
+
+// The type readers by keyword: each returns [name, definition] for the types map.
+function readScalar(cursor) {
+  const name = cursor.name();
+  skipDirectives(cursor);
+  return [name, { kind: 'scalar' }];
+}
+
+function readEnum(cursor) {
+  const name = cursor.name();
+  skipDirectives(cursor);
+  const values = new Set();
+  cursor.expect('{');
+  while (!cursor.take('}')) {
+    skipDescription(cursor);
+    values.add(cursor.name());
+    skipDirectives(cursor);
+  }
+  return [name, { kind: 'enum', values }];
+}
+
+function readUnion(cursor) {
+  const name = cursor.name();
+  skipDirectives(cursor);
+  cursor.expect('=');
+  cursor.take('|');
+  const members = [cursor.name()];
+  while (cursor.take('|')) members.push(cursor.name());
+  return [name, { kind: 'union', members }];
+}
+
+function readObjectLike(cursor, keyword) {
+  const name = cursor.name();
+  if (cursor.is('implements')) {
+    cursor.name();
+    cursor.take('&');
+    cursor.name();
+    while (cursor.take('&')) cursor.name();
+  }
+  skipDirectives(cursor);
+  let kind = 'object';
+  if (keyword === 'input') kind = 'input';
+  else if (keyword === 'interface') kind = 'interface';
+  return [name, { kind, fields: parseFieldDefinitions(cursor, kind !== 'input') }];
+}
+
+const TYPE_READERS = new Map([['scalar', readScalar], ['enum', readEnum], ['union', readUnion], ['type', readObjectLike], ['interface', readObjectLike], ['input', readObjectLike]]);
+
+/** The types of an SDL source: Map(name -> { kind, fields? , values? , members? }), plus the root operation type names. */
+export function parseSchema(source) {
+  const cursor = cursorOf(tokenize(source));
+  const types = new Map();
+  const roots = { query: 'Query', mutation: 'Mutation', subscription: 'Subscription' };
+  while (!cursor.done()) {
+    skipDescription(cursor);
+    const keyword = cursor.name();
+    const readType = TYPE_READERS.get(keyword);
+    if (keyword === 'schema' || (keyword === 'extend' && cursor.is('schema'))) readSchemaDefinition(cursor, keyword, roots);
+    else if (keyword === 'directive') skipDirectiveDefinition(cursor);
+    else if (readType) {
+      const [name, definition] = readType(cursor, keyword);
+      types.set(name, definition);
+    } else throw new SyntaxError(`unexpected "${keyword}" in a schema`);
+  }
+  return { types, roots };
+}
+
+function parseArgumentList(cursor) {
+  while (!cursor.take(')')) {
+    skipDescription(cursor);
+    cursor.name();
+    cursor.expect(':');
+    parseTypeRef(cursor);
+    if (cursor.take('=')) skipValue(cursor);
+    skipDirectives(cursor);
+  }
+}

package/runtime/scripts/lib/i18n.mjs

@@ -11,6 +11,7 @@
 // A placeholder is `{name}`; the English and the Vietnamese of one entry carry exactly the same placeholders
 // (scripts/checks/check-i18n-catalog.mjs). An English source with no entry is returned as is: a missing translation degrades
 // to English, never to a blank.
+import { byCodeUnit } from './list.mjs';
 import { escapeRegExp } from './regex.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -19,7 +20,7 @@ import { parseYaml } from '../../engine/yaml.mjs';
 import { DEFAULT_OWNER_LANGUAGE, loadConfig } from '../../engine/config.mjs';
 
 export const CATALOG_DIR = 'modules/i18n/messages';
-export const PLACEHOLDER = /\{([A-Za-z_][\w]*)\}/g;
+export const PLACEHOLDER = /\{([A-Za-z_]\w*)\}/g;
 
 const cache = new Map();
 
@@ -54,7 +55,7 @@ export const resetCatalogCache = () => cache.clear();
 /** The names each `pattern` match captures (group 1) in `text`, in match order (`sort` sorts them). */
 export const captureNames = (text, pattern, { sort = false } = {}) => {
   const names = [...String(text).matchAll(pattern)].map((m) => m[1]);
-  return sort ? names.sort() : names;
+  return sort ? names.sort(byCodeUnit) : names;
 };
 
 /** The names of the placeholders of a message. */

package/runtime/scripts/lib/in-order.mjs

@@ -0,0 +1,71 @@
+// in-order.mjs — asynchronous work done strictly one after another, named by what it does. A sequential `await` in a
+// loop is often the point (ordered ledger writes, one Orca or git call at a time, a rate limit, stop at the first
+// failure or match); these helpers state that intent at the call site so no loop body carries an `await`. Each one
+// starts item n+1 only after item n has settled, lets the first rejection (or a synchronous throw of `fn`) stop the run
+// with later items never started, pulls a lazy iterable one item at a time, and closes it on an early stop, the way
+// `for (const x of xs) await fn(x)` does. All of them run on the one `walk` below: promise callbacks, not an async
+// recursion, so the stack and the memory stay flat however long the input is.
+// Provably independent work that needs no order, short-circuit or error contract may use `Promise.all` instead.
+
+/** Close `iterator` the way a `for...of` leaves it: `return()` when it has one. */
+const close = (iterator) => iterator.return?.();
+
+/**
+ * Drive `visit(item, index)` over `items` one at a time. `decide(outcome, item)` runs after each settled visit: a
+ * `{ value }` box ends the walk with that value, anything else goes on. Resolves with the box value, or `undefined` when
+ * the items ran out; rejects with the first rejection or throw, after closing the iterator.
+ */
+const walk = (items, visit, decide) => new Promise((resolve, reject) => {
+  const iterator = items[Symbol.iterator]();
+  let index = 0;
+  const fail = (error) => {
+    try { close(iterator); } catch { /* the failure being reported wins, as it does in a for...of */ }
+    reject(error);
+  };
+  const stop = (value) => {
+    try { close(iterator); } catch (error) { reject(error); return; }
+    resolve(value);
+  };
+  const advance = () => {
+    let step, pending;
+    try {
+      step = iterator.next();
+      if (step.done) { resolve(undefined); return; }
+      pending = visit(step.value, index++);
+    } catch (error) {
+      if (step === undefined || step.done) reject(error); else fail(error);
+      return;
+    }
+    Promise.resolve(pending).then((outcome) => {
+      let box;
+      try { box = decide(outcome, step.value); } catch (error) { fail(error); return; }
+      if (box) stop(box.value); else advance();
+    }, fail);
+  };
+  advance();
+});
+
+const never = () => undefined;
+
+/** `for (const x of items) await fn(x, index)`: resolves undefined once every item has run, one at a time. */
+export const eachInOrder = (items, fn) => walk(items, fn, never);
+
+/** The sequential map: `fn(x, index)` for each item in turn, resolving the results in item order. */
+export const mapInOrder = (items, fn) => {
+  const results = [];
+  return walk(items, fn, (outcome) => { results.push(outcome); }).then(() => results);
+};
+
+/** The first item whose `predicate(x, index)` resolves truthy (undefined when none); later items never run. */
+export const findInOrder = (items, predicate) => walk(items, predicate, (outcome, item) => (outcome ? { value: item } : undefined));
+
+/**
+ * `for (;;) await step(attempt)`: `step(attempt)` runs again, after the previous run settled, until it resolves
+ * something other than undefined; that value (null included) is the result. A poll or retry returns undefined to go
+ * on and its answer to stop. `attempt` counts from 0.
+ */
+export const repeatInOrder = (step) => walk(forever(), step, (outcome) => (outcome === undefined ? undefined : { value: outcome }));
+
+function* forever() {
+  for (let attempt = 0; ; attempt++) yield attempt;
+}

package/runtime/scripts/lib/language.mjs

@@ -50,13 +50,13 @@ export const DECLARED_VIETNAMESE_FIELDS = Object.freeze({
   'modules/ops/_labels.yaml': Object.freeze({ flowFields: Object.freeze(['vi']) }),
   'modules/goal/archetypes.yaml': Object.freeze({
     fields: Object.freeze([
-      'buildIntent', 'canonIntent', 'e2eIntent', 'uatIntent', 'proofNegation', 'integrationIntent', 'integrationNegation', 'brandIntent',
+      'buildIntent', 'canonIntent', 'e2eIntent', 'uatIntent', 'proofNegation', 'proofStateCue', 'integrationIntent', 'brandIntent',
       'phrases', 'requires', 'excludes', 'backend', 'frontend', 'package',
     ]),
   }),
   'modules/goal/source-phrases.yaml': Object.freeze({
     fields: Object.freeze([
-      'prefer', 'avoid', 'negation', 'refused', 'accept', 'golden',
+      'prefer', 'avoid', 'only', 'negation', 'refused', 'accept', 'golden',
       'missingPaths', 'grantTooNarrow', 'toolTimeout', 'testGap', 'checkerUnavailable',
       'supervisorVerbs', 'ownerWord', 'orWord', 'beyondAuthority', 'ownerOnly', 'workerDied', 'contractConflict', 'decision',
       'product', 'grammar', 'knowledge', 'sourceLabel', 'internalVocabulary', 'actor', 'success',
@@ -124,7 +124,7 @@ export function documentLanguageHits(rel, text) {
     if (declared.fields?.includes(keys[hit.line - 1])) return false;
     if (!declared.flowFields) return true;
     // an inline flow map: drop the declared fields' values and judge what is left of the line
-    const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(`\\b${field}\\s*:\\s*(?:"(?:[^"\\\\]|\\\\.)*"|'(?:[^'\\\\]|\\\\.)*'|[^,}]*)`, 'g'), ''), lines[hit.line - 1]);
+    const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(String.raw`\b${field}\s*:\s*(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^,}]*)`, 'g'), ''), lines[hit.line - 1]);
     return hasSecondLanguage(rest);
   });
 }

package/runtime/scripts/lib/list.mjs

@@ -4,7 +4,11 @@
 export const list = (v) => (Array.isArray(v) ? v : []);
 
 /** `v` as an array: itself when already one, [] for null/undefined, else [v]. */
-export const asList = (v) => (Array.isArray(v) ? v : v == null ? [] : [v]);
+export const asList = (v) => {
+  if (Array.isArray(v)) return v;
+  if (v == null) return [];
+  return [v];
+};
 
 /** The object entries of `v` (a non-array reads as []). */
 export const objectList = (v) => (Array.isArray(v) ? v : []).filter((item) => item && typeof item === 'object');
@@ -18,3 +22,6 @@ export const splitList = (v, { sep = ',', dedupe = false } = {}) => {
   const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);
   return dedupe ? [...new Set(items)] : items;
 };
+
+// The comparator of a bare `sort()` (UTF-16 code-unit order) is owned by the engine, which cannot import scripts/lib.
+export { byCodeUnit } from '../../engine/by-code-unit.mjs';

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

@@ -6,6 +6,17 @@ const WIN = process.platform === 'win32';
 
 /** `p` with every backslash turned into a forward slash; null and undefined read as ''. */
 export const slash = (p) => String(p ?? '').replaceAll('\\', '/');
+/** `text` without its trailing '/' run (a loop: a trailing-run pattern backtracks super-linearly). */
+export const trimTrailingSlashes = (text) => {
+  for (let end = text.length; ; end -= 1) if (end === 0 || text[end - 1] !== '/') return text.slice(0, end);
+};
+// A trailing '*' run with the one '/' before it (the glob suffix of 'dir/**'); text without a trailing '*' is unchanged.
+const stripTrailingStars = (text) => {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === '*') end -= 1;
+  if (end === text.length) return text;
+  return text.slice(0, end > 0 && text[end - 1] === '/' ? end - 1 : end);
+};
 /** A relative path in git's spelling: forward slashes, no leading './'. */
 export const posixPath = (p) => slash(p).replace(/^\.\//, '');
 /** Whether posix `file` is `prefix` itself or under it (`file === prefix || file` starts with `prefix/`). */
@@ -19,7 +30,7 @@ export const samePath = (a, b) => foldCase(a) === foldCase(b);
  * `fold: true` folds case on every platform (a comparison against a lowercase-stored root needs it).
  */
 export const pathKey = (p, { fold = WIN } = {}) => {
-  const key = slash(path.resolve(p)).replace(/\/+$/, '');
+  const key = trimTrailingSlashes(slash(path.resolve(p)));
   return fold ? key.toLowerCase() : key;
 };
 /** `a` is `b` or under it, or the reverse: two path spellings whose trees touch. */
@@ -36,37 +47,59 @@ export const normPath = (p, { trim = false, collapse = false, dot = false, glob
   s = slash(s);
   if (collapse) s = s.replace(/\/{2,}/g, '/');
   if (dot) s = s.replace(/^\.\//, '');
-  if (glob === 'star') s = s.replace(/\/?\*+$/, '');
+  if (glob === 'star') s = stripTrailingStars(s);
   else if (glob === 'double') s = s.replace(/\/\*\*$/, '');
-  s = s.replace(/\/+$/, '');
+  s = trimTrailingSlashes(s);
   return fold ? s.toLowerCase() : s;
 };
 /** A work-relative path in one spelling: forward slashes, no leading ./, no trailing slash. */
-export const normWork = (p) => String(p ?? '').trim().replaceAll('\\', '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+export const normWork = (p) => trimTrailingSlashes(String(p ?? '').trim().replaceAll('\\', '/').replace(/^\.\/+/, ''));
 
 /** `p` resolved and dereferenced (realpath where the path exists) — the canonical spelling of a checkout dir. */
 export const realPath = (p) => {
   const resolved = path.resolve(p);
   try { return fs.realpathSync.native(resolved); } catch { return resolved; }
 };
+/** `p` with its nearest existing ancestor dereferenced and the not-yet-created rest appended: a root's canonical spelling before it exists. */
+export const canonicalPath = (p) => {
+  const rest = [];
+  for (let at = path.resolve(p); ; at = path.dirname(at)) {
+    try { return path.join(fs.realpathSync.native(at), ...rest); } catch { /* not created yet */ }
+    if (path.dirname(at) === at) return path.resolve(p);
+    rest.unshift(path.basename(at));
+  }
+};
 /** `p` resolved and case-folded where the filesystem ignores case — the Map key of an absolute path. */
 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);
+};
+/**
+ * `candidate` (absolute, or relative to `base`) resolved and dereferenced, required to sit under `base` (or be it):
+ * the boundary check for a path an operator, an agent or another process hands in. `base` is canonicalised once and the
+ * candidate is judged below it, so `..` segments and links leading out are refused; returns the canonical path, or throws
+ * a PATH_OUTSIDE_BASE refusal (`label` names the argument in the message).
+ */
+export const containedPath = (base, candidate, { label = 'path' } = {}) => {
+  const root = canonicalPath(base);
+  const resolved = canonicalPath(path.resolve(root, String(candidate ?? '')));
+  const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+  if (!insidePath(root, resolved, { includeSelf: true }) || (resolved !== root && !resolved.startsWith(prefix))) throw Object.assign(new Error(`${label} ${String(candidate)} is outside ${root} [PATH_OUTSIDE_BASE]`), { code: 'PATH_OUTSIDE_BASE' });
+  return resolved;
 };
 /**
  * A path-ish value (a string or a {path} entry) in relative compare form: trimmed, forward slashes,
  * no trailing '/**' glob or slashes, no leading './'; `fold` lowercases for a case-insensitive key.
  */
 export const normRel = (p, { fold = false } = {}) => {
-  const s = String(typeof p === 'string' ? p : p?.path ?? '').trim().replace(/\\/g, '/').replace(/\/\*\*$/, '').replace(/\/+$/, '').replace(/^\.\//, '');
+  const s = trimTrailingSlashes(String(typeof p === 'string' ? p : p?.path ?? '').trim().replaceAll('\\', '/').replace(/\/\*\*$/, '')).replace(/^\.\//, '');
   return fold ? s.toLowerCase() : s;
 };
 /** Whether `file` equals or sits under one of `prefixes` (posix spellings; `dot` counts a '.' prefix as covering all). */

package/runtime/scripts/lib/pid-alive.mjs

@@ -0,0 +1,7 @@
+// pid-alive.mjs - whether a process id names a live process: the one probe the host locks, the file claim and the machine store share.
+
+/** True while `pid` names a live process (EPERM counts as alive). */
+export const pidAlive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) { return false; }
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
+};

package/runtime/scripts/lib/regex.mjs

@@ -1,4 +1,4 @@
 // regex.mjs - building a RegExp from text.
 
 /** `text` with every regular-expression metacharacter escaped, so it matches itself literally. */
-export const escapeRegExp = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+export const escapeRegExp = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);

package/runtime/scripts/lib/same-text.mjs

@@ -2,4 +2,4 @@
 // carry CRLF): the one comparison the database rules use for a committed file against its base or against a regenerated one.
 
 /** True when both texts exist and are equal once CRLF is folded to LF and trailing whitespace at the end is dropped. */
-export const sameText = (a, b) => a !== null && b !== null && a.replace(/\r\n/g, '\n').trimEnd() === b.replace(/\r\n/g, '\n').trimEnd();
+export const sameText = (a, b) => a !== null && b !== null && a.replaceAll('\r\n', '\n').trimEnd() === b.replaceAll('\r\n', '\n').trimEnd();

package/runtime/scripts/lib/secret-patterns.mjs

@@ -15,7 +15,7 @@ export const FORBIDDEN_FILES = [
 export const SECRET_PATTERNS = [
   { name: 'private-key-block', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
   { name: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/ },
-  { name: 'github-token', re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{50,}\b/ },
+  { name: 'github-token', re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_\w{50,}\b/ },
   { name: 'anthropic-key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}/ },
   { name: 'openai-key', re: /\bsk-(?:proj-)?[A-Za-z0-9]{32,}\b/ },
   { name: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/ },
@@ -28,7 +28,11 @@ export const SECRET_PATTERNS = [
   // candidate; only this heuristic takes the exemption, never a provider-shaped token above.
   // A spec file's keyword-assigned values are test inputs (a spec's sign-in
   // form password and a mocked accessToken once refused a push): the heuristic skips spec files too.
-  { name: 'assigned-secret', re: /\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|client[_-]?secret)\b\s*[:=]\s*['"](?!env\([A-Z_][A-Z0-9_]*\)['"])([^'"\s$<{]{12,})['"]/i, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+  { name: 'assigned-secret', re: new RegExp([
+    String.raw`\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|client[_-]?secret)`,
+    String.raw`\b\s*[:=]\s*['"](?!env\([A-Z_][A-Z0-9_]*\)['"])([^'"\s$<{]{12,})`,
+    `['"]`,
+  ].join(''), 'i'), placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
     skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$/ },
 ];
 

package/runtime/scripts/lib/sleep-sync.mjs

@@ -3,8 +3,8 @@
 /**
  * Test seam: STARCI_SLEEP_SCALE (a number >= 0, default 1) multiplies every wait. A spec that drives a real
  * dispatch/boot against a fake host sets it small so the card's settle/attestation windows (seconds of pure
- * waiting, counted logically by their callers, not by the wall clock) cost milliseconds and the run no longer
- * depends on machine load. Unset in production.
+ * waiting, counted logically by their callers, not by the wall clock) cost milliseconds and the run does not
+ * depend on machine load. Unset in production.
  */
 import { readEnv } from './env.mjs';
 const scaleOf = () => {