@starci/hfs 4.7.31 → 4.7.33

package/runtime/scripts/lib/loosening-state.mjs

@@ -0,0 +1,223 @@
+// loosening-state.mjs - the state-based loosening check: does the tree, as it stands, hold a gate weaker than the canon says? (owner decision
+// 2026-10-24, owner ruling loosening-state-check.) The history of the tree is never read: a deleted file, a re-pointed row or reworded text
+// cannot be a loosening, and a loosening that stands cannot be hidden by when it was written. The check is red on
+//   bypass          an inline disable, a type-check escape, a Sonar or coverage ignore, a skipped or focused test, a failure swallowed in a script,
+//                   a hook or a workflow, a warning budget, a pass-with-no-tests flag, a hook skipped (scripts/lib/bypass-markers.mjs);
+//   list-extra      an entry of an ignore or exclude list (codecov, sonar, jest, eslint, stylelint, tsconfig, a *ignore file) that the canon does not
+//                   derive and the design-truths manifest does not allow FOR THAT FILE;
+//   threshold       a coverage target below 100, a threshold above 0, a gate limit looser than the manifest's;
+//   setting         a switch that relaxes a gate (`require_ci_to_pass: false`, `informational: true`, `passWithNoTests`, `requireCi: false`) that the
+//                   manifest does not allow;
+//   rule-off        an ESLint or stylelint rule turned off or down in a config;
+//   strictness      a tsconfig strictness option turned off, or skipLibCheck (and the like) turned on outside the file the manifest allows;
+//   budget          a numeric budget of the slot manifests raised, lowered or gone against the manifest's pins; budget-override: an app or example
+//                   config (hfs.json, an ESLint config) that states a budget itself; scope-override: a jest config that narrows what runs;
+//   exception-file  an allowlist, approval, waiver, suppression or baseline file that the manifest does not list, or one with more entries than it allows;
+//   pin             a file the owner pinned (the manifest, the fixtures of this checker, the vendored YAML) whose digest differs from the pin;
+//   fixture-misuse  code other than a package spec that imports the fixtures of this checker.
+// Every legitimate exception lives in knowledge/hfs/design-truths.yaml, each with the cite of its owner ruling. The manifest itself is pinned by the
+// digest the latest owner ruling records (pins): a lane that edits it turns the check red until the owner records a ruling. The library is pure: the
+// caller hands the tracked files, a reader, the canon's derivations and the pins.
+import { bypassFileKind, bypassesIn } from './bypass-markers.mjs';
+import { LIST, configKindOf, configRecords, coreOf, exceptionEntries, isAnyDepth, isExceptionFile, maybeTsconfig } from './loosening-config.mjs';
+import { braceVariants, globExpression } from './glob.mjs';
+import { byCodeUnit, list as asArray } from './list.mjs';
+import { budgetRecords } from './loosening-budgets.mjs';
+import { manifestDigest as truthsDigest } from './grammar-vendor-parity.mjs';
+
+export { truthsDigest };
+
+const TRUTHS_SCHEMA = 'starci/design-truths@1';
+const MANIFEST = 'knowledge/hfs/design-truths.yaml';
+
+const LISTS = new Set(Object.values(LIST));
+const RELAXING = Object.freeze({ require_ci_to_pass: 'false', informational: 'true', passWithNoTests: 'true', requireCi: 'false', if_ci_failed: 'success', status: 'off', 'sonar.qualitygate.wait': 'false', 'yaml-alias': 'true' });
+
+const hasRuling = (cite) => cite !== null && typeof cite === 'object' && typeof cite.ruling === 'string' && cite.ruling.length > 0;
+/** The file globs an allowance names: one string or a list of them. */
+function globsOf(value) {
+  const globs = [];
+  for (const glob of [value].flat()) if (typeof glob === 'string') globs.push(glob);
+  return globs;
+}
+const matchesFile = (globs, file) => globs.some((glob) => braceVariants(glob).some((variant) => globExpression(variant).test(file)));
+
+function readListAllow(truth, allow, out) {
+  if (!LISTS.has(allow.list)) out.problems.push(`truth ${truth.id}: unknown list ${allow.list}`);
+  if (allow.derivedBy !== undefined) out.derivations.add(allow.derivedBy);
+  const entries = asArray(allow.entries);
+  if (entries.length > 0 && globsOf(allow.file).length === 0) out.problems.push(`truth ${truth.id}: an allowance of list entries names the file it holds for`);
+  if (entries.length > 0) out.literal.push({ list: allow.list, files: globsOf(allow.file), entries });
+}
+
+function readAllow(truth, allow, out) {
+  if (allow.list !== undefined) readListAllow(truth, allow, out);
+  else if (allow.setting !== undefined) out.settings.push({ key: allow.setting, value: String(allow.value) });
+  else if (allow.compilerOption !== undefined) out.options.push({ key: allow.compilerOption, value: String(allow.value), files: asArray(allow.files) });
+  else if (allow.exceptionFile !== undefined) out.exceptionFiles.set(allow.exceptionFile, Number(allow.maxEntries ?? 0));
+  else out.problems.push(`truth ${truth.id}: an allow names no list, setting, compilerOption or exceptionFile`);
+}
+
+/**
+ * The manifest `doc` as the sets the check reads, plus `problems`: the shapes a malformed manifest breaks (a truth, a group, a budget pin or the gate
+ * limits without an id, an owner-ruling cite, a sentence or an allowance is a problem, so an exception can never be anonymous or lane-authored).
+ */
+export function readTruths(doc) {
+  const out = {
+    problems: [], ids: [], fixtureFiles: asArray(doc?.fixtureFiles), vendored: new Set(asArray(doc?.vendored).map((entry) => entry.path)),
+    groups: [], literal: [], derivations: new Set(), settings: [], options: [], exceptionFiles: new Map(), limits: doc?.gateLimits ?? null,
+    budgets: asArray(doc?.budgets),
+  };
+  if (doc?.schema !== TRUTHS_SCHEMA) out.problems.push(`schema must be ${TRUTHS_SCHEMA}`);
+  if (out.limits && !hasRuling(out.limits.cite)) out.problems.push('gateLimits: an owner-ruling cite is required');
+  for (const group of asArray(doc?.outsideTheGates)) {
+    if (!group.id || !hasRuling(group.cite)) out.problems.push(`outsideTheGates ${group.id ?? '?'}: id and an owner-ruling cite are required`);
+    out.groups.push({ cores: new Set(asArray(group.entries).map(coreOf)), anyDepth: group.anyDepth === true });
+  }
+  for (const pin of out.budgets) if (!pin.file || !hasRuling(pin.cite)) out.problems.push(`budgets ${pin.file ?? '?'}: file and an owner-ruling cite are required`);
+  for (const truth of asArray(doc?.truths)) {
+    if (!truth.id || !hasRuling(truth.cite) || !truth.says || asArray(truth.allows).length === 0) out.problems.push(`truth ${truth.id ?? '?'}: id, an owner-ruling cite, says and allows are required`);
+    out.ids.push(truth.id);
+    for (const allow of asArray(truth.allows)) readAllow(truth, allow, out);
+  }
+  return out;
+}
+
+/** Whether the tree check reads `file`: every tracked file, but the fixtures of this checker (pinned by digest) and the vendored dependency copy (pinned too). */
+export const inScope = (file, truths) => !truths.vendored.has(file) && !truths.fixtureFiles.includes(file);
+
+/** Whether any reading of the check applies to `file`: only those files are read at all. */
+const extensionless = (file) => !file.slice(file.lastIndexOf('/') + 1).includes('.');
+const isJudged = (file, truths) => Boolean(bypassFileKind(file) || configKindOf(file) || maybeTsconfig(file) || extensionless(file) || isExceptionFile(file) || truths.limits?.file === file
+  || truths.budgets.some((pin) => pin.file === file));
+
+const finding = (kind, file, line, detail) => ({ id: `${kind}:${file}:${detail}`, kind, file, line, detail });
+
+/** Whether the manifest lists `item` of `list` for `file`: a jest pattern by its exact text, any other entry by its path core. */
+function listedFor(truths, file, list, item) {
+  return truths.literal.some((allow) => allow.list === list && matchesFile(allow.files, file)
+    && allow.entries.some((entry) => (list === LIST.jest ? entry === item : coreOf(entry) === coreOf(item) && isAnyDepth(entry) === isAnyDepth(item))));
+}
+
+/** Whether `item` names only what no gate reads (build output, generated records, sealed custody), rooted unless its group is the same at any depth. */
+const outsideTheGates = (truths, item, list) => list !== LIST.jest && list !== LIST.issues && truths.groups.some((group) => group.cores.has(coreOf(item)) && (group.anyDepth || !isAnyDepth(item)));
+
+function listFindings(file, records, truths, canon) {
+  const derived = new Map();
+  const derivedFor = (list) => {
+    if (!derived.has(list)) {
+      const from = canon.derive?.(file, list) ?? null;
+      derived.set(list, from && truths.derivations.has(from.by) ? new Set(from.items.map((item) => (list === LIST.jest ? item : coreOf(item)))) : new Set());
+    }
+    return derived.get(list);
+  };
+  const allowed = (entry) => derivedFor(entry.list).has(entry.list === LIST.jest ? entry.item : coreOf(entry.item)) || outsideTheGates(truths, entry.item, entry.list) || listedFor(truths, file, entry.list, entry.item);
+  return records.filter((entry) => !allowed(entry)).map((entry) => finding('list-extra', file, entry.line, `${entry.key}: ${entry.item}`));
+}
+
+function numberFindings(file, numbers) {
+  return numbers.flatMap((entry) => {
+    const loose = entry.key === 'threshold' ? entry.value > 0 : entry.value < 100;
+    return loose ? [finding('threshold', file, entry.line, `${entry.key} ${entry.value}`)] : [];
+  });
+}
+
+const normalised = (value) => ({ yes: 'true', on: 'true', no: 'false', off: 'off' }[String(value).toLowerCase()] ?? String(value).toLowerCase());
+
+function settingFindings(file, settings, truths) {
+  return settings.map((entry) => ({ ...entry, value: normalised(entry.value) }))
+    .filter((entry) => entry.value === RELAXING[entry.key] || (entry.key === 'if_ci_failed' && entry.value !== 'error'))
+    .filter((entry) => !truths.settings.some((allow) => allow.key === entry.key && allow.value === entry.value))
+    .map((entry) => finding('setting', file, entry.line, `${entry.key}: ${entry.value}`));
+}
+
+/** A strictness record is a finding unless the manifest allows that option at that value in that very file (the canon base tsconfig for skipLibCheck). */
+function strictnessFindings(file, strictness, truths) {
+  return strictness.filter((entry) => !truths.options.some((allow) => allow.key === entry.key && allow.value === entry.value && allow.files.includes(file)))
+    .map((entry) => finding('strictness', file, entry.line, `${entry.key}: ${entry.value}`));
+}
+
+function configFindings(file, kind, text, truths, canon, withLists) {
+  const records = configRecords(kind, text, file);
+  return [
+    ...(withLists ? listFindings(file, records.lists, truths, canon) : []),
+    ...numberFindings(file, records.numbers),
+    ...settingFindings(file, records.settings, truths),
+    ...records.rulesOff.map((entry) => finding('rule-off', file, entry.line, entry.rule)),
+    ...strictnessFindings(file, records.strictness, truths),
+    ...records.budgets.map((entry) => finding('budget-override', file, entry.line, `${entry.key}: a budget is the canon's, never stated by a config`)),
+    ...records.scope.map((entry) => finding('scope-override', file, entry.line, `${entry.key}: the canon config states no scope of what runs`)),
+  ];
+}
+
+/** The gate limits of the file the manifest names (the Sonar gate): a floor lowered or a ceiling raised against the manifest's numbers. */
+function limitFindings(file, text, limits) {
+  const found = [];
+  text.split(/\r?\n/).forEach((raw, index) => {
+    const match = /^\s*(?:-\s+)?([A-Za-z]\w*)\s*:\s*(-?\d+(?:\.\d+)?)\s*(?:#.*)?$/.exec(raw);
+    if (!match) return;
+    const value = Number(match[2]);
+    const floor = limits.floors?.[match[1]];
+    const ceiling = limits.ceilings?.[match[1]];
+    if ((floor !== undefined && value < floor) || (ceiling !== undefined && value > ceiling)) found.push(finding('threshold', file, index + 1, `${match[1]} ${value}`));
+  });
+  return found;
+}
+
+function exceptionFileFindings(file, text, truths) {
+  if (!truths.exceptionFiles.has(file)) return [finding('exception-file', file, 1, 'an exception, approval, allowlist or baseline file the design-truths manifest does not list')];
+  const held = exceptionEntries(file, text);
+  const allowed = truths.exceptionFiles.get(file);
+  return held > allowed ? [finding('exception-file', file, 1, `${held} entries, the manifest allows ${allowed}`)] : [];
+}
+
+const FIXTURE_IMPORT = /fixtures\/loosening\//;
+const PACKAGE_SPEC = /^packages\/hfs\/src\/[\w.-]+\.spec\.mjs$/;
+
+/** The findings of one file. */
+function fileFindings(file, text, truths, canon, withLists) {
+  const found = bypassesIn(file, text).map((hit) => finding('bypass', file, hit.line, hit.label));
+  const kind = configKindOf(file, text);
+  if (kind) found.push(...configFindings(file, kind, text, truths, canon, withLists));
+  if (isExceptionFile(file)) found.push(...exceptionFileFindings(file, text, truths));
+  if (truths.limits?.file === file) found.push(...limitFindings(file, text, truths.limits));
+  for (const pin of truths.budgets.filter((entry) => entry.file === file)) found.push(...budgetRecords(text, pin).map((detail) => finding('budget', file, 1, detail)));
+  if (bypassFileKind(file, text) === 'code' && !PACKAGE_SPEC.test(file) && FIXTURE_IMPORT.test(text)) found.push(finding('fixture-misuse', file, 1, 'only a package spec of packages/hfs/src may import the fixtures of the loosening check'));
+  return found;
+}
+
+/** The pinned files whose digest differs from the pin, and the declared fixtures and vendored copies the pins do not cover. */
+function pinFindings(truths, pins, read) {
+  const declared = [MANIFEST, ...truths.fixtureFiles, ...truths.vendored];
+  const found = declared.filter((file) => !Object.hasOwn(pins, file)).map((file) => finding('pin', file, 1, 'no owner ruling pins this file: record its digest in an owner ruling'));
+  for (const [file, digest] of Object.entries(pins)) {
+    const text = read(file);
+    if (typeof text !== 'string') found.push(finding('pin', file, 1, 'a pinned file is missing'));
+    else if (truthsDigest(text) !== digest) found.push(finding('pin', file, 1, `its digest ${truthsDigest(text).slice(0, 12)} is not the one the owner pinned (${String(digest).slice(0, 12)}): only an owner ruling may change it`));
+  }
+  return found;
+}
+
+/**
+ * Every loosening of the tree: [{id, kind, file, line, detail}] sorted, plus the manifest's own problems as `truths` findings.
+ *   files   the tracked files (repository-relative, forward slashes);
+ *   read    (file) -> text, or null when it cannot be read;
+ *   truths  the manifest document (readTruths shapes it);
+ *   canon   { derive(file, list) -> { by, items } | null }: what the canon derives for a list of a file, allowed only when the manifest names `by`;
+ *   lists   false leaves the ignore and exclude lists out (the app gate: an app's rendered files are held to their render by the managed-file drift);
+ *   pins    { path: sha256 } the latest owner ruling records; undefined skips the pin check (the app gate).
+ */
+export function stateFindings({ files, read, truths: doc, canon = {}, lists = true, pins }) {
+  const truths = readTruths(doc);
+  const found = truths.problems.map((problem) => finding('truths', MANIFEST, 1, problem));
+  if (pins !== undefined) found.push(...pinFindings(truths, pins, read));
+  for (const file of files) {
+    if (!inScope(file, truths) || !isJudged(file, truths)) continue;
+    const text = read(file);
+    if (typeof text === 'string') found.push(...fileFindings(file, text, truths, canon, lists));
+  }
+  return found.sort((a, b) => byCodeUnit(a.id, b.id) || a.line - b.line);
+}
+
+/** One finding as the self-check and the app gate print it. */
+export const findingLine = (entry) => `${entry.kind} ${entry.file}:${entry.line} ${entry.detail}`;

package/runtime/scripts/lib/menu-parts.mjs

@@ -0,0 +1,11 @@
+// The parts the Kernel menu and the Supervisor menu share: a template filled from an item's subject, the escape option every
+// item carries, and the plain words of a starci call a seat table is read by.
+
+/** `template` with each `{key}` replaced by the subject's value; a key the subject does not know stays as written. */
+export const fillTemplate = (template, subject) => String(template ?? '').replace(/\{(\w+)\}/g, (match, key) => (subject[key] == null ? match : String(subject[key])));
+
+/** The escape option of a menu catalog (`escape: {choice, effect}`): no step, a reason as its text. */
+export const escapeOptionOf = (escape, extra = {}) => ({ choice: escape.choice, ...extra, steps: [], effect: escape.effect, text: 'reason', escape: true });
+
+/** The first `count` words of an argument list that are not options. */
+export const plainWords = (args, count) => args.filter((value) => !String(value).startsWith('-')).slice(0, count).map(String);

package/runtime/scripts/lib/normalize.mjs

@@ -0,0 +1,25 @@
+// normalize.mjs — text in compare form for matching (phrase hits, repeated questions).
+
+const SENTENCE_TRAILING_CHAR = /[\s.?!:;,]/;
+
+/** `text` without its trailing run of characters that `chars` (a one-character pattern) matches; a loop, not a trailing-run regex. */
+export const trimTrailingChars = (text, chars) => {
+  for (let end = text.length; ; end -= 1) if (end === 0 || !chars.test(text[end - 1])) return text.slice(0, end);
+};
+
+/** `text` without the run of `ch` (one character) at each end; loops, not an anchored-run regex. */
+export const trimEdgeChar = (text, ch) => {
+  let start = 0, end = text.length;
+  while (start < end && text[start] === ch) start += 1;
+  while (end > start && text[end - 1] === ch) end -= 1;
+  return text.slice(start, end);
+};
+
+/**
+ * `s` normalized for a literal compare: Unicode `form`-normalized, lowercased, whitespace runs to a
+ * single space, ends trimmed; `punct: true` also drops trailing sentence punctuation.
+ */
+export const normalizeText = (s, { form = 'NFC', punct = false } = {}) => {
+  const out = String(s ?? '').normalize(form).toLowerCase().replace(/\s+/g, ' ').trim();
+  return punct ? trimTrailingChars(out, SENTENCE_TRAILING_CHAR) : out;
+};

package/runtime/scripts/lib/op-gate.mjs

@@ -0,0 +1,15 @@
+// op-gate.mjs — one section of the runtime's knowledge/op-gate.yaml (testWorld, unitKit, ...):
+// {required, forbidden, outage, ...} as authored. An absent section reads as {}.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+/** The `section` object of knowledge/op-gate.yaml under `runtime`, {} when the doc omits it. Throws when the file is unreadable. */
+const opGateSection = (runtime, section) =>
+  (parseYaml(fs.readFileSync(path.join(runtime, 'knowledge', 'op-gate.yaml'), 'utf8'))?.[section]) ?? {};
+
+/** The {required, forbidden, outage} rule lists of a gate `section` (absent lists read as []). */
+export const opGateRules = (runtime, section) => {
+  const rules = opGateSection(runtime, section);
+  return { required: rules.required ?? [], forbidden: rules.forbidden ?? [], outage: rules.outage ?? [] };
+};

package/runtime/scripts/lib/redact.mjs

@@ -0,0 +1,208 @@
+// redact.mjs — the ONE redaction module (docs/ledger-db.md). Every blob put of text bytes
+// (report attachments, check stdout/stderr/output, terminal transcripts, CLI sessions) and every log write
+// passes through here first; the harness UI server reuses it. A blob whose bytes went through redactText is
+// stamped blobs.redaction = REDACTION_VERSION; bytes that cannot be filtered (images, video, archives) are
+// stamped 'binary'.
+//
+// It blanks: provider tokens and JWTs (secret-patterns.mjs, the push scan's list), auth headers, URL query
+// secrets, URL credentials (scheme://user:pass@host), PEM private-key blocks (the whole block), KEY=value /
+// KEY: value pairs whose key names a secret (FOO_API_KEY=..., password: ...), and the declared secrets of a
+// product repo's .starcistacks (their env-style names as keys, and their values wherever they appear).
+// Keys and surrounding words stay, so a redacted transcript still reads.
+import fs from 'node:fs';
+import path from 'node:path';
+import { FORBIDDEN_FILES, SECRET_PATTERNS } from './secret-patterns.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { altOf } from './source-phrases.mjs';
+import { trimEdgeChar } from './normalize.mjs';
+import { redactResolvedSecrets } from '../../engine/secrets.mjs';
+
+const REDACTION_VERSION = 'v1';
+export const MARK = '[redacted]';
+
+const withGlobal = (re) => new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
+const PATTERNS = SECRET_PATTERNS.filter((rule) => rule.name !== 'private-key-block').map((rule) => ({ ...rule, g: withGlobal(rule.re) }));
+// Words that make an env-style key a secret, matched per `_`-separated segment of the name (FOO_API_KEY,
+// KEYCLOAK_ADMIN_PASSWORD, GH_TOKEN, MINIO_SECRET_KEY, DATABASE_URL is not; TESTS_PASSED is not).
+const SECRET_SEGMENTS = new Set(['PASSWORD', 'PASSWD', 'PWD', 'PASS', 'SECRET', 'SECRETS', 'TOKEN', 'APIKEY', 'KEY', 'CREDENTIAL', 'CREDENTIALS', 'COOKIE', 'OTP', 'DSN', 'PAT']);
+const isSecretEnvName = (name) => String(name).replace(/^export\s+/, '').replace(/_FILE$/, '').split('_').some((seg) => SECRET_SEGMENTS.has(seg));
+const PEM_BLOCK = /-----BEGIN ((?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?)-----[\s\S]*?(?:-----END \1-----|$)/g;
+const RULES = [
+  { name: 'url-credentials', re: /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:@/"'<>]+):([^\s@/"'<>]+)@/gi, to: (m, scheme, user) => `${scheme}${user}:${MARK}@` },
+  { name: 'auth-header', re: /\b(Bearer|Basic|Token)(\s+)[A-Z0-9._~+/=-]{8,}/gi, to: (m, a, b) => `${a}${b}${MARK}` },
+  { name: 'url-secret', re: /([?&#](?:access_token|refresh_token|id_token|token|key|api_key|apikey|secret|code|password|otp|sig|signature)=)([^&#\s"']+)/gi, to: (m, a) => `${a}${MARK}` },
+  { name: 'otp', re: new RegExp(String.raw`\b(otp|one[-_ ]?time[-_ ]?(?:code|password|pin)|verification[-_ ]?code|2fa[-_ ]?code|${altOf('redact.otpLabel')})(\s*[:=]?\s*["']?)(\d{4,8})\b`, 'giu'), to: (m, a, b) => `${a}${b}${MARK}` },
+  // ENV_STYLE_KEY=value / ENV_STYLE_KEY: value (shell exports, dotenv, compose, CLI echo).
+  { name: 'env-secret', re: /\b((?:export\s+)?[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*)(\s*[:=]\s*["']?)((?!\[redacted)[^\s"'`]{3,})/g,
+    to: (m, a, b, c) => (isSecretEnvName(a) && !c.startsWith('/run/secrets/') && !c.startsWith('$') ? `${a}${b}${MARK}` : m) },
+  { name: 'keyed-secret', re: new RegExp([
+    String.raw`\b(password|passwd|pwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|auth[_-]?token|session[_-]?token|private[_-]?key|otp|pin[_-]?code|cookie|set-cookie)`,
+    String.raw`(["']?\s*[:=]\s*["']?)((?!\[redacted)[^\s"',;&}]{3,})`,
+  ].join(''), 'gi'), to: (m, a, b) => `${a}${b}${MARK}` },
+];
+
+/** Keys whose value is a secret whatever it looks like; the key stays, the value goes. */
+export const SECRET_KEY = new RegExp([
+  '^(?:password|passwd|pwd|pass|secret|otp|pin|pincode|pin_code|credential|credentials|authorization|cookie|cookies|set-cookie|private[_-]?key|client[_-]?secret|api[_-]?key|apikey|[a-z_-]*token|[a-z_-]*secret)',
+  '$',
+].join(''), 'i');
+
+// ------------------------------------------------------------------------------ declared stack secrets
+// A product repo's .starcistacks/<stack>/stack.yaml `secrets:` block names each secret and the runtime file
+// that holds its value. Values are refreshed from their declared inputs; values never leave the filter.
+const STACK_DIRS = ['.starcistacks'];
+const secretValues = new Set();
+const secretNames = new Set();
+const envName = (name) => trimEdgeChar(String(name).replace(/[^A-Za-z0-9]+/g, '_'), '_').toUpperCase();
+const readSafe = (file) => { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } };
+const listSafe = (dir) => { try { return fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; } };
+
+function learnStackDirectory(root, stackDir, entry) {
+  const dir = path.join(root, stackDir, entry.name);
+  const text = readSafe(path.join(dir, 'stack.yaml'));
+  let doc = null;
+  try { doc = text ? parseYaml(text) : null; } catch { doc = null; }
+  const secrets = doc?.secrets && typeof doc.secrets === 'object' ? doc.secrets : {};
+  for (const [name, spec] of Object.entries(secrets)) {
+    secretNames.add(envName(name));
+    if (typeof spec?.file === 'string') addSecretValue(readSafe(path.resolve(dir, spec.file)));
+  }
+  // Plaintext runtime copies of the secrets (git-ignored): their values are secrets too.
+  for (const file of listSafe(path.join(dir, 'runtime', 'files'))) if (file.isFile()) addSecretValue(readSafe(path.join(dir, 'runtime', 'files', file.name)));
+}
+
+/** A value this process must never write out (a secret it resolved itself). Values under 6 chars are ignored. */
+function addSecretValue(value) {
+  const v = typeof value === 'string' ? value.trim() : '';
+  if (v.length >= 6 && !v.startsWith('[redacted')) secretValues.add(v);
+}
+
+/** Learn the declared secrets of every .starcistacks stack under `repoRoot` (idempotent). */
+export function learnStackSecrets(repoRoot) {
+  if (typeof repoRoot !== 'string' || !repoRoot) return;
+  const root = path.resolve(repoRoot);
+  for (const stackDir of STACK_DIRS) {
+    for (const entry of listSafe(path.join(root, stackDir))) {
+      if (!entry.isDirectory()) continue;
+      learnStackDirectory(root, stackDir, entry);
+    }
+  }
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+let namesRe = null, namesSize = -1;
+const declaredNameRule = () => {
+  if (namesSize !== secretNames.size) {
+    namesSize = secretNames.size;
+    namesRe = secretNames.size ? new RegExp(`\\b((?:${[...secretNames].map(escapeRe).join('|')})(?:_FILE)?)(\\s*[:=]\\s*["']?)((?!\\[redacted)[^\\s"'\`]{3,})`, 'g') : null;
+  }
+  return namesRe;
+};
+
+// --------------------------------------------------------------------------------------------- text
+const PEM_RULE = 'private-key-block';
+
+/** `text` with `re` replaced by `to`, `hits` counting each replacement that changed the match under the rule's name. */
+function replaceCounting(text, re, name, to, hits) {
+  re.lastIndex = 0;
+  return text.replace(re, (...args) => {
+    const out = to(...args);
+    if (out !== args[0]) hits.set(name, (hits.get(name) ?? 0) + 1);
+    return out;
+  });
+}
+
+const patternTo = (rule) => (match, value) => {
+  if (rule.name === 'assigned-secret') return rule.placeholder?.test(value ?? '') ? match : match.replace(value, MARK);
+  return `[redacted:${rule.name}]`;
+};
+
+function redactPatterns(text, hits, assignments) {
+  for (const rule of PATTERNS) {
+    if ((rule.name === 'assigned-secret') !== assignments) continue;
+    text = replaceCounting(text, rule.g, rule.name, patternTo(rule), hits);
+  }
+  return text;
+}
+
+/**
+ * `text` with every secret value blanked, and what blanked it: {text, hits: Map(rule name -> replacements that changed the text)}. A rule
+ * that meets only a placeholder ([redacted...]) counts nothing, so a text redacted before reports no hit. `repoRoots` (optional) are product
+ * repos whose .starcistacks declarations are learned first.
+ */
+export function redactTracked(text, { repoRoots = [] } = {}) {
+  const hits = new Map();
+  if (typeof text !== 'string' || !text) return { text, hits };
+  for (const root of repoRoots) learnStackSecrets(root);
+  const resolved = redactResolvedSecrets(text);
+  if (resolved !== text) hits.set('resolved-secret', 1);
+  let out = replaceCounting(resolved, PEM_BLOCK, PEM_RULE, (m, kind) => `[redacted:pem ${kind}]`, hits);
+  for (const value of secretValues) if (out.includes(value)) { hits.set('stack-secret', (hits.get('stack-secret') ?? 0) + 1); out = out.split(value).join('[redacted:stack-secret]'); }
+  out = redactPatterns(out, hits, false);
+  const declared = declaredNameRule();
+  if (declared) out = replaceCounting(out, declared, 'declared-secret-name', (m, a, b) => `${a}${b}${MARK}`, hits);
+  for (const rule of RULES) out = replaceCounting(out, rule.re, rule.name, rule.to, hits);
+  // Specific contexts keep their classifications; the widened assignment heuristic handles the remaining values.
+  out = redactPatterns(out, hits, true);
+  return { text: out, hits };
+}
+
+/** `text` with every secret value blanked. */
+export function redactText(text, options = {}) { return redactTracked(text, options).text; }
+
+/** The rules that still find a secret in `text` after redaction ran: [{rule, count}], never the matched text. */
+export function survivingSecrets(text, options = {}) { return [...redactTracked(text, options).hits].map(([rule, count]) => ({ rule, count })); }
+
+/** A path that is a secret by being one (an env file, a key file, .secrets/): blanked, its rule named. */
+export function redactPath(p) {
+  if (typeof p !== 'string') return p;
+  const slashed = p.replaceAll('\\', '/');
+  const rule = FORBIDDEN_FILES.find((r) => r.test(slashed));
+  return rule ? `[redacted:${rule.name}]` : redactText(p);
+}
+
+/** A deep copy of `value` with secret-named keys blanked and every string redacted. */
+export function redactData(value, key = null, depth = 0) {
+  if (depth > 8) return '[depth]';
+  if (key && SECRET_KEY.test(key) && value != null && typeof value !== 'object' && typeof value !== 'boolean') return MARK;
+  if (typeof value === 'string') return /(?:path|ref|file)$/i.test(key ?? '') ? redactPath(value) : redactText(value);
+  if (Array.isArray(value)) return value.map((v) => redactData(v, null, depth + 1));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactData(v, k, depth + 1)]));
+  return value;
+}
+
+// -------------------------------------------------------------------------------------------- bytes
+const TEXT_MEDIA = new RegExp([
+  String.raw`^text\/`,
+  String.raw`|[/+](?:json|xml|yaml|x-yaml|javascript|x-ndjson|x-diff|x-patch|csv|sql|x-sh)\b`,
+  String.raw`|^application\/(?:json|xml|yaml|javascript|x-ndjson|x-diff|x-patch|sql)$`,
+].join(''), 'i');
+
+/** True for media types whose bytes are text the filter can read. */
+export const isTextMedia = (mediaType) => TEXT_MEDIA.test(String(mediaType ?? ''));
+
+/** The supported text encoding selected by a byte-order mark. */
+export function textEncodingOf(bytes) {
+  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) return 'utf-16le';
+  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) return 'utf-16be';
+  if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return 'utf-8-bom';
+  return 'utf-8';
+}
+
+/** Decode supported text without accepting malformed bytes as sanitized evidence. */
+export function decodeText(bytes) {
+  const encoding = textEncodingOf(bytes);
+  return new TextDecoder(encoding === 'utf-8-bom' ? 'utf-8' : encoding, { fatal: true }).decode(bytes);
+}
+
+/**
+ * Bytes ready for a blob put: text bytes redacted ({redaction:'v1'}), anything else untouched
+ * ({redaction:'binary'}). The blob sha is then taken over the returned bytes.
+ */
+export function redactBytes(bytes, mediaType, { repoRoots = [] } = {}) {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  if (!isTextMedia(mediaType)) return { bytes: buf, redaction: 'binary' };
+  const text = decodeText(buf);
+  const clean = redactText(text, { repoRoots });
+  return { bytes: Buffer.from(clean, 'utf8'), redaction: REDACTION_VERSION };
+}

package/runtime/scripts/lib/runtime-location.mjs

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** The usable runtime linked for `home`, or null with a diagnostic in `skipped` for a stale or unreadable record. */
+export function readRuntimeRecord({ home = os.homedir(), exists = existsSync, read = readFileSync, skipped = [] } = {}) {
+  const record = path.join(home, '.starci', 'runtime.json');
+  if (!exists(record)) return null;
+  let candidate;
+  try { candidate = JSON.parse(read(record, 'utf8'))?.root; }
+  catch {
+    skipped.push(`${record} is not valid JSON`);
+    return null;
+  }
+  if (typeof candidate === 'string' && candidate) {
+    const root = path.resolve(candidate);
+    if (exists(path.join(root, 'scripts', 'cli', 'main.mjs'))) return { root, source: record };
+  }
+  skipped.push(`${record} points at ${JSON.stringify(candidate ?? null)}, which has no scripts/cli/main.mjs (stale record)`);
+  return null;
+}

package/runtime/scripts/lib/runtime-package-inventory.mjs

@@ -0,0 +1,21 @@
+// The root archive's names equal npm's selection from tracked inputs and verified generated copies.
+import { byCodeUnit } from './list.mjs';
+
+const relativeFile = (file) => typeof file === 'string' && file.length > 0 && !/^[a-z]:/i.test(file) && !file.includes('\0') && !file.includes('\\') && !file.split('/').some((part) => !part || part === '.' || part === '..');
+
+/** Exact selected-set proof; source-byte equality remains owned by verifyPackedDependencies. */
+export function runtimePackageInventory({ files, tracked, generated = [], selected }) {
+  if (!Array.isArray(tracked) || !tracked.length || !tracked.every(relativeFile)) return { unrun: 'the tracked file inventory of the root is unavailable or malformed' };
+  if (!Array.isArray(selected) || !selected.length || !selected.every(relativeFile) || new Set(selected).size !== selected.length) return { unrun: 'npm did not return a complete, unique tracked-projection inventory' };
+  if (!Array.isArray(generated) || !generated.every(relativeFile)) return { unrun: 'the verified generated file inventory is malformed' };
+  const trackedSet = new Set(tracked), generatedSet = new Set(generated), selectedSet = new Set(selected);
+  const unknown = selected.filter((file) => !trackedSet.has(file) && !generatedSet.has(file));
+  if (unknown.length) return { unrun: `npm selected files outside the tracked projection: ${unknown.slice(0, 5).join(', ')}` };
+  const packed = [...files.keys()];
+  const foreign = packed.filter((file) => !file.startsWith('package/') || !selectedSet.has(file.slice('package/'.length))).sort(byCodeUnit);
+  if (foreign.length) return { red: `root archive carries ${foreign.length} file(s) outside npm's tracked-only selection (ignored build output or scratch): ${foreign.slice(0, 5).join(', ')}` };
+  const missing = selected.filter((file) => !files.has(`package/${file}`)).sort(byCodeUnit);
+  if (missing.length) return { red: `root archive omits ${missing.length} file(s) from npm's tracked-only selection: ${missing.slice(0, 5).join(', ')}` };
+  const generatedCount = selected.filter((file) => !trackedSet.has(file) && generatedSet.has(file)).length;
+  return { tracked: selected.length - generatedCount, generated: generatedCount };
+}

package/runtime/scripts/lib/runtime-package-manifests.mjs

@@ -0,0 +1,84 @@
+// Manifests the root archive ships name files by path; a path that does not ship breaks the installed runtime.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { asList, byCodeUnit } from './list.mjs';
+import { EXAMPLES_ROOT } from './example-refs.mjs';
+
+const KNOWLEDGE_SOURCE = 'starci/knowledge-source@1';
+const strings = (value) => asList(value).filter((item) => typeof item === 'string' && item.length > 0);
+const entries = (value) => asList(value).filter((item) => item && typeof item === 'object');
+const joined = (directory, file) => path.posix.normalize(path.posix.join(directory, file));
+
+/** The example catalog: each example's files/entrypoint/projects/tests are relative to that example's own directory. */
+const exampleReferences = (doc) => entries(doc?.examples).flatMap((example) => {
+  const base = path.posix.join(EXAMPLES_ROOT, String(example.path ?? ''));
+  return [...strings(example.files), ...strings(example.entrypoint), ...strings(example.projects), ...strings(example.tests)]
+    .map((file) => ({ from: String(example.id ?? '?'), target: joined(base, file) }));
+});
+
+/** The schema catalog: schemas[].file and every moduleLocalDocumentKinds[].files entry are relative to the package root. */
+const schemaReferences = (doc) => [
+  ...entries(doc?.schemas).flatMap((schema) => strings(schema.file).map((file) => ({ from: String(schema.id ?? '?'), target: joined('.', file) }))),
+  ...entries(doc?.moduleLocalDocumentKinds).flatMap((kind) => strings(kind.files).map((file) => ({ from: String(kind.id ?? '?'), target: joined('.', file) }))),
+];
+
+/** The path-bearing keys of a grammar family entry. */
+const FAMILY_PATH_KEYS = ['authority', 'packageSnapshot', 'reusableStyle', 'productComposition', 'index'];
+
+/** A knowledge-source index: branches[].path, topics[].path and the family files, relative to the index's own directory. */
+const knowledgeReferences = (directory) => (doc) => [
+  ...entries(doc?.branches).flatMap((branch) => strings(branch.path).map((file) => ({ from: String(branch.id ?? '?'), target: joined(directory, file) }))),
+  ...entries(doc?.topics).flatMap((topic) => strings(topic.path).map((file) => ({ from: String(topic.title ?? '?'), target: joined(directory, file) }))),
+  ...entries(doc?.families).flatMap((family) => FAMILY_PATH_KEYS.flatMap((key) => strings(family[key]).map((file) => ({ from: `${family.id ?? '?'}.${key}`, target: joined(directory, file) })))),
+];
+
+/** Manifests the package must ship; their absence from the selection is red, never a skip. */
+export const REQUIRED_MANIFESTS = Object.freeze([`${EXAMPLES_ROOT}/index.yaml`, 'modules/schemas/index.yaml', 'knowledge/index.yaml']);
+
+const KNOWLEDGE_INDEX = /^knowledge\/(?:.+\/)?index\.yaml$/;
+
+/** The reader of one manifest file: the two catalogs have their own, every knowledge index reads its own directory. */
+const readerOf = (file) => {
+  if (file === REQUIRED_MANIFESTS[0]) return exampleReferences;
+  if (file === REQUIRED_MANIFESTS[1]) return schemaReferences;
+  return knowledgeReferences(path.posix.dirname(file));
+};
+
+/** The manifests to read: the required set plus every selected knowledge index. */
+const manifestFiles = (selected) => [...new Set([...REQUIRED_MANIFESTS, ...selected.filter((name) => KNOWLEDGE_INDEX.test(name))])].sort(byCodeUnit);
+
+/** {references} of one manifest, {skip} for an index of another schema, {unrun} or {red} when it cannot be trusted. */
+function readManifest(file, readFile) {
+  let doc;
+  try { doc = parseYaml(readFile(file)); } catch { return { unrun: `${file} is unreadable or not valid YAML` }; }
+  if (doc?.schema !== KNOWLEDGE_SOURCE && !REQUIRED_MANIFESTS.includes(file)) return { skip: true };
+  const references = readerOf(file)(doc);
+  if (!references.length) return { red: `${file} yields no file references; its reference keys changed or it lists nothing, so nothing in it would be checked` };
+  return { references };
+}
+
+/**
+ * Pre-pack admission: every path a shipped manifest names must be in the archive selection. Manifests are the required
+ * set plus every selected knowledge index stamped starci/knowledge-source@1, so a new index is covered unlisted.
+ * Returns {unrun} when a manifest cannot be read, {red} naming the first unresolved paths, else {manifests, references, counts}.
+ */
+export function manifestAdmission({ root, selected, readFile = (file) => fs.readFileSync(path.join(root, file), 'utf8') }) {
+  const shipped = new Set(selected);
+  const missing = REQUIRED_MANIFESTS.filter((file) => !shipped.has(file));
+  if (missing.length) return { red: `the archive does not ship required manifest(s): ${missing.join(', ')}` };
+  const gaps = [];
+  const counts = {};
+  for (const file of manifestFiles(selected)) {
+    const read = readManifest(file, readFile);
+    if (read.unrun || read.red) return read;
+    if (read.skip) continue;
+    counts[file] = read.references.length;
+    for (const { from, target } of read.references) if (target.startsWith('../') || !shipped.has(target)) gaps.push(`${file} (${from}) -> ${target}`);
+  }
+  if (gaps.length) {
+    const sorted = [...new Set(gaps)].sort(byCodeUnit);
+    return { red: `${sorted.length} shipped manifest reference(s) do not resolve in the archive: ${sorted.slice(0, 5).join('; ')}` };
+  }
+  return { manifests: Object.keys(counts).length, references: Object.values(counts).reduce((sum, count) => sum + count, 0), counts };
+}