@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/edition-slots.d.mts

@@ -0,0 +1,37 @@
+import type { Parsed, RuleParams, Slot, SlotManifest, SlotPresence } from './manifest-shape.mjs';
+/** A row that may narrow itself to some editions (a rule, an enforcer, a backing service). */
+interface EditionScoped {
+    editions?: readonly string[] | undefined;
+}
+/** The presence of `slot` under edition lite for `profile`: `litePresence`, else the slot's own presence. */
+export declare function litePresenceOf(slot: Pick<Slot, 'litePresence' | 'presence'>, profile: string): SlotPresence;
+/** Whether `slot` exists under `edition` of `manifest` (default: the manifest's own editions). */
+export declare function slotInEdition(manifest: Pick<SlotManifest, 'editions'>, slot: Pick<Slot, 'editions'>, edition: string): boolean;
+/** The slot as `edition` sees it: lite overlays its data, presence and tracking; `tests` stays the slot's own (lite keeps the unit specs). */
+export declare function effectiveSlot(slot: Slot, profile: string, edition: string): Slot;
+/** The template group starci app sync renders `slot` from under `edition`: `liteManagedBy` (else `managedBy`) in lite, `managedBy` otherwise; undefined when unmanaged. */
+export declare function managedGroupOf(slot: Pick<Slot, 'managedBy' | 'liteManagedBy'>, edition: string): string | undefined;
+/** The declared edition and the vocabulary against which it is validated. */
+export declare function declarationEdition(manifest: Pick<SlotManifest, 'editions'>, declaration: Parsed): {
+    edition: string;
+    known: readonly string[];
+    valid: boolean;
+};
+/** Problems of an optional rule-catalog `editions` list, in the catalog schema's words. */
+export declare function ruleEditionProblems(rule: Parsed, label: string): string[];
+/** Whether a catalogued rule owner judges its finding under `edition`; uncatalogued codes always remain judged. */
+export declare function judgedInEdition(owner: EditionScoped | null | undefined, edition?: string): boolean;
+/** Whether the enforcer `kind:id` of the catalog `rules` runs under `edition`: every rule listing it is judged there, and the enforcer row's own `editions` (a rule with several enforcers where only one is full-only) agrees. A lint rule no rule lists runs everywhere. */
+export declare function enforcerJudgedInEdition(rules: ReadonlyArray<EditionScoped & {
+    enforcers: ReadonlyArray<EditionScoped & {
+        kind: string;
+        id: string;
+    }>;
+}>, kind: string, id: string, edition?: string): boolean;
+/**
+ * A frozen copy of one profile's parameters, with its lite overrides applied only in the lite edition. A lite key whose base
+ * value and override are both maps merges one level deep (lite.infraOwners restates only the specifiers whose owner changes);
+ * any other value replaces the base.
+ */
+export declare function editionRuleParams(params: RuleParams, edition: string): RuleParams;
+export {};

package/runtime/scripts/hfs/edition-slots.mjs

@@ -4,74 +4,77 @@
 // Its overlays exclude the e2e world, and every slot keeps its own `tests`.
 import { isPlainObject } from '../../engine/plain-object.mjs';
 import { EDITIONS } from './manifest-shape.mjs';
-
 /** The presence of `slot` under edition lite for `profile`: `litePresence`, else the slot's own presence. */
 export function litePresenceOf(slot, profile) {
-  const lp = slot.litePresence;
-  if (lp === undefined) return slot.presence;
-  return isPlainObject(lp) ? (lp[profile] ?? slot.presence) : lp;
+    const lp = slot.litePresence;
+    if (lp === undefined)
+        return slot.presence;
+    return isPlainObject(lp) ? (lp[profile] ?? slot.presence) : lp;
 }
-
 /** Whether `slot` exists under `edition` of `manifest` (default: the manifest's own editions). */
 export function slotInEdition(manifest, slot, edition) {
-  return (slot.editions ?? manifest.editions ?? EDITIONS).includes(edition);
+    return (slot.editions ?? manifest.editions ?? EDITIONS).includes(edition);
 }
-
 /** The slot as `edition` sees it: lite overlays its data, presence and tracking; `tests` stays the slot's own (lite keeps the unit specs). */
 export function effectiveSlot(slot, profile, edition) {
-  if (edition !== 'lite') return slot;
-  const { lite, litePresence, ...base } = slot;
-  const presence = litePresenceOf(slot, profile);
-  let tracked = slot.tracked;
-  if (presence === 'forbidden') tracked = 'external';
-  else if (tracked === 'external') tracked = 'tracked';
-  return { ...base, ...lite, presence, tracked };
+    if (edition !== 'lite')
+        return slot;
+    const { lite, litePresence, ...base } = slot;
+    const presence = litePresenceOf(slot, profile);
+    let tracked = slot.tracked;
+    if (presence === 'forbidden')
+        tracked = 'external';
+    else if (tracked === 'external')
+        tracked = 'tracked';
+    return { ...base, ...lite, presence, tracked };
 }
-
 /** The template group starci app sync renders `slot` from under `edition`: `liteManagedBy` (else `managedBy`) in lite, `managedBy` otherwise; undefined when unmanaged. */
 export function managedGroupOf(slot, edition) {
-  return edition === 'lite' ? (slot.liteManagedBy ?? slot.managedBy) : slot.managedBy;
+    return edition === 'lite' ? (slot.liteManagedBy ?? slot.managedBy) : slot.managedBy;
 }
-
 /** The declared edition and the vocabulary against which it is validated. */
 export function declarationEdition(manifest, declaration) {
-  const edition = declaration.edition === undefined ? 'full' : declaration.edition;
-  const known = manifest.editions ?? EDITIONS;
-  return { edition, known, valid: known.includes(edition) };
+    const edition = declaration.edition === undefined ? 'full' : declaration.edition;
+    const known = manifest.editions ?? EDITIONS;
+    return { edition, known, valid: known.includes(edition) };
 }
-
 /** Problems of an optional rule-catalog `editions` list, in the catalog schema's words. */
 export function ruleEditionProblems(rule, label) {
-  if (rule.editions === undefined) return [];
-  const bad = [];
-  if (!Array.isArray(rule.editions) || !rule.editions.length) return [`${label}.editions must be a non-empty list`];
-  for (const value of rule.editions) if (!EDITIONS.includes(value)) bad.push(`${label}.editions has ${JSON.stringify(value)}, not one of ${EDITIONS.join(', ')}`);
-  if (new Set(rule.editions).size !== rule.editions.length) bad.push(`${label}.editions repeats a value`);
-  return bad;
+    if (rule.editions === undefined)
+        return [];
+    const bad = [];
+    if (!Array.isArray(rule.editions) || !rule.editions.length)
+        return [`${label}.editions must be a non-empty list`];
+    for (const value of rule.editions)
+        if (!EDITIONS.includes(value))
+            bad.push(`${label}.editions has ${JSON.stringify(value)}, not one of ${EDITIONS.join(', ')}`);
+    if (new Set(rule.editions).size !== rule.editions.length)
+        bad.push(`${label}.editions repeats a value`);
+    return bad;
 }
-
 /** Whether a catalogued rule owner judges its finding under `edition`; uncatalogued codes always remain judged. */
 export function judgedInEdition(owner, edition = 'full') {
-  return !owner?.editions || owner.editions.includes(edition);
+    return !owner?.editions || owner.editions.includes(edition);
 }
-
 /** Whether the enforcer `kind:id` of the catalog `rules` runs under `edition`: every rule listing it is judged there, and the enforcer row's own `editions` (a rule with several enforcers where only one is full-only) agrees. A lint rule no rule lists runs everywhere. */
 export function enforcerJudgedInEdition(rules, kind, id, edition = 'full') {
-  const owners = rules.filter((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id));
-  return owners.every((rule) => judgedInEdition(rule, edition) && rule.enforcers.filter((enforcer) => enforcer.kind === kind && enforcer.id === id).every((enforcer) => judgedInEdition(enforcer, edition)));
+    const owners = rules.filter((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id));
+    return owners.every((rule) => judgedInEdition(rule, edition) && rule.enforcers.filter((enforcer) => enforcer.kind === kind && enforcer.id === id).every((enforcer) => judgedInEdition(enforcer, edition)));
 }
-
 /**
  * A frozen copy of one profile's parameters, with its lite overrides applied only in the lite edition. A lite key whose base
  * value and override are both maps merges one level deep (lite.infraOwners restates only the specifiers whose owner changes);
  * any other value replaces the base.
  */
 export function editionRuleParams(params, edition) {
-  const { lite, ...base } = params;
-  const merged = edition === 'lite' && lite ? { ...base } : base;
-  if (edition === 'lite' && lite) {
-    for (const [key, value] of Object.entries(lite)) merged[key] = isPlainObject(value) && isPlainObject(base[key]) ? { ...base[key], ...value } : value;
-  }
-  const deepFreeze = (value) => { if (value && typeof value === 'object') { Object.values(value).forEach(deepFreeze); } return Object.freeze(value); };
-  return deepFreeze(structuredClone(merged));
+    const { lite, ...base } = params;
+    const merged = edition === 'lite' && lite ? { ...base } : base;
+    if (edition === 'lite' && lite) {
+        for (const [key, value] of Object.entries(lite))
+            merged[key] = isPlainObject(value) && isPlainObject(base[key]) ? { ...base[key], ...value } : value;
+    }
+    const deepFreeze = (value) => { if (value && typeof value === 'object') {
+        Object.values(value).forEach(deepFreeze);
+    } return Object.freeze(value); };
+    return deepFreeze(structuredClone(merged));
 }

package/runtime/scripts/hfs/example-secrets.d.mts

@@ -0,0 +1,18 @@
+import { type AppIdentity } from './secret-bootstrap-crypto.mjs';
+import type { SecretSops } from './secret-sops.mjs';
+/** The sops seam placeholders are sealed through: only `seal` is needed. */
+type SealingSops = Pick<SecretSops, 'seal'>;
+/** Generate genuine sealed members; the fresh private identity is confined to os.tmpdir and removed before return. */
+export declare function materializeExample(repoRoot: string, { createIdentity, sops }?: {
+    createIdentity?: () => AppIdentity;
+    sops?: SealingSops | undefined;
+}): Promise<{
+    members: string[];
+}>;
+/** Await callback(tempExamplePath, lintBaseRef), return its result, and remove the os.tmpdir-based copy even on failure. */
+export declare function withMaterializedExample<T>(repoRoot: string, exampleRelativePath: string, callback: (app: string, lintBaseRef: string | null) => T | Promise<T>, { materialize, linkDependencies, preserveCoverage, }?: {
+    materialize?: (app: string) => unknown;
+    linkDependencies?: boolean;
+    preserveCoverage?: boolean;
+}): Promise<T>;
+export {};

package/runtime/scripts/hfs/example-secrets.mjs

@@ -19,47 +19,47 @@ import { withoutGitLocalEnv } from '../lib/git.mjs';
 import { resolveRealTool } from '../api/process/resolve-real-tool.mjs';
 import { generateAppIdentity } from './secret-bootstrap-crypto.mjs';
 import { declaredSealedMembers, materializeDeclaredPlaceholders } from './sealed-members.mjs';
-
 const SKIPPED = new Set(['.git', '.claude', '.secrets', '.aws', '.codex', '.agents', 'node_modules', '.next', '.turbo', 'dist', 'coverage']);
-const PATH_RULE = String.raw`\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc(?:\.yaml)?$`;
-
+const PATH_RULE = String.raw `\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc(?:\.yaml)?$`;
 function writePublicRecipient(repoRoot, recipient) {
-  fs.writeFileSync(path.join(repoRoot, '.sops.yaml'), stringifyYaml({
-    creation_rules: [{ path_regex: PATH_RULE, age: recipient }],
-  }));
-  const stacks = path.join(repoRoot, '.starcistacks');
-  for (const entry of fs.readdirSync(stacks, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const file = path.join(stacks, entry.name, 'backup.recipient');
-    if (fs.existsSync(file)) fs.writeFileSync(file, `${recipient}\n`);
-  }
+    fs.writeFileSync(path.join(repoRoot, '.sops.yaml'), stringifyYaml({
+        creation_rules: [{ path_regex: PATH_RULE, age: recipient }],
+    }));
+    const stacks = path.join(repoRoot, '.starcistacks');
+    for (const entry of fs.readdirSync(stacks, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const file = path.join(stacks, entry.name, 'backup.recipient');
+        if (fs.existsSync(file))
+            fs.writeFileSync(file, `${recipient}\n`);
+    }
 }
-
 /** Generate genuine sealed members; the fresh private identity is confined to os.tmpdir and removed before return. */
 export async function materializeExample(repoRoot, { createIdentity = generateAppIdentity, sops } = {}) {
-  const declared = declaredSealedMembers(repoRoot);
-  if (!declared.length) return { members: [] };
-  if (declared.some(({ env, slug }) => fs.existsSync(memberFile(path.join(repoRoot, '.starcistacks', env, 'secrets'), slug))))
-    throw new Error('example materialization requires a disposable copy without existing sealed members');
-  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-example-age-'));
-  try {
-    const selected = createIdentity();
+    const declared = declaredSealedMembers(repoRoot);
+    if (!declared.length)
+        return { members: [] };
+    if (declared.some(({ env, slug }) => fs.existsSync(memberFile(path.join(repoRoot, '.starcistacks', env, 'secrets'), slug))))
+        throw new Error('example materialization requires a disposable copy without existing sealed members');
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-example-age-'));
     try {
-      fs.writeFileSync(path.join(directory, 'identity.txt'), selected.identity, { mode: 0o600, flag: 'wx' });
-    } finally {
-      selected.identity.fill(0);
+        const selected = createIdentity();
+        try {
+            fs.writeFileSync(path.join(directory, 'identity.txt'), selected.identity, { mode: 0o600, flag: 'wx' });
+        }
+        finally {
+            selected.identity.fill(0);
+        }
+        writePublicRecipient(repoRoot, selected.recipient);
+        return materializeDeclaredPlaceholders(repoRoot, { recipient: selected.recipient, sops });
+    }
+    finally {
+        safeRemove(directory, { hold: () => null });
     }
-    writePublicRecipient(repoRoot, selected.recipient);
-    return materializeDeclaredPlaceholders(repoRoot, { recipient: selected.recipient, sops });
-  } finally {
-    safeRemove(directory, { hold: () => null });
-  }
 }
-
 const COMMITTER = { 'user.name': 'starci', 'user.email': 'l4@starci.invalid' };
 const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
 const ok = (r) => !r.error && r.status === 0 && Boolean(String(r.stdout ?? '').trim());
-
 /**
  * The lint base the copy's size-growth ratchet measures against: the source app's subtree at the source repository's
  * lint baseline (STARCI_BASE_REF, then origin/main, then main),
@@ -68,149 +68,168 @@ const ok = (r) => !r.error && r.status === 0 && Boolean(String(r.stdout ?? '').t
  * Returns the synthetic base commit sha, or null when the source sits in no repository. Missing repository baselines fail explicitly.
  */
 function sealedLintBase(repoRoot, source, env) {
-  const query = { cwd: source, env };
-  const top = revParseQuery(['--show-toplevel'], query);
-  if (!ok(top)) return null;
-  const common = revParseQuery(['--git-common-dir'], query);
-  if (!ok(common)) return null;
-  const candidates = [...(env.STARCI_BASE_REF ? [env.STARCI_BASE_REF] : []), 'origin/main', 'main'];
-  let baseSha = null;
-  for (const ref of candidates) {
-    baseSha = mergeBase(source, 'HEAD', ref);
-    if (baseSha) break;
-  }
-  if (!baseSha) throw new Error('sealed lint baseline unavailable: set STARCI_BASE_REF to a source commit sharing history with HEAD, or fetch origin/main or main');
-  const relative = path.relative(top.stdout.trim(), path.resolve(source)).split(path.sep).join('/');
-  const tree = revParseQuery(['--verify', '--quiet', relative && !relative.startsWith('..') ? `${baseSha}:${relative}` : `${baseSha}^{tree}`], query);
-  const baseTree = ok(tree) ? tree.stdout.trim() : EMPTY_TREE;
-  const info = path.join(repoRoot, '.git', 'objects', 'info');
-  fs.mkdirSync(info, { recursive: true });
-  fs.appendFileSync(path.join(info, 'alternates'), `${path.resolve(source, common.stdout.trim()).split(path.sep).join('/')}/objects\n`);
-  const base = commitTree([baseTree, '-m', 'sealed lint base'], { cwd: repoRoot, env, config: COMMITTER });
-  if (!ok(base)) throw new Error('could not commit the lint base of the isolated example git tree');
-  return base.stdout.trim();
+    const query = { cwd: source, env };
+    const top = revParseQuery(['--show-toplevel'], query);
+    if (!ok(top))
+        return null;
+    const common = revParseQuery(['--git-common-dir'], query);
+    if (!ok(common))
+        return null;
+    const candidates = [...(env.STARCI_BASE_REF ? [env.STARCI_BASE_REF] : []), 'origin/main', 'main'];
+    let baseSha = null;
+    for (const ref of candidates) {
+        baseSha = mergeBase(source, 'HEAD', ref);
+        if (baseSha)
+            break;
+    }
+    if (!baseSha)
+        throw new Error('sealed lint baseline unavailable: set STARCI_BASE_REF to a source commit sharing history with HEAD, or fetch origin/main or main');
+    const relative = path.relative(top.stdout.trim(), path.resolve(source)).split(path.sep).join('/');
+    const tree = revParseQuery(['--verify', '--quiet', relative && !relative.startsWith('..') ? `${baseSha}:${relative}` : `${baseSha}^{tree}`], query);
+    const baseTree = ok(tree) ? tree.stdout.trim() : EMPTY_TREE;
+    const info = path.join(repoRoot, '.git', 'objects', 'info');
+    fs.mkdirSync(info, { recursive: true });
+    fs.appendFileSync(path.join(info, 'alternates'), `${path.resolve(source, common.stdout.trim()).split(path.sep).join('/')}/objects\n`);
+    const base = commitTree([baseTree, '-m', 'sealed lint base'], { cwd: repoRoot, env, config: COMMITTER });
+    if (!ok(base))
+        throw new Error('could not commit the lint base of the isolated example git tree');
+    return base.stdout.trim();
 }
-
 function trackExample(repoRoot, source) {
-  const env = withoutGitLocalEnv(process.env);
-  if (!initGit(repoRoot, { env }).ok) throw new Error('could not initialize the isolated example git tree');
-  // The linked node_modules (linkExampleDependencies: a junction on Windows, a symlink elsewhere) is the install, never a tracked entry: git treats a
-  // symlink as a file, which the app's `node_modules/` (directory) ignore line does not match, so on Linux `git add -A` tracked it (HFS_TRACKED_MUST_BE_IGNORED,
-  // HFS_ROOT_ENTRY_FORBIDDEN in every examples.yml lint since the link). The copy's own exclude file ignores it in any form.
-  fs.appendFileSync(path.join(repoRoot, '.git', 'info', 'exclude'), ['', '# the linked install of the example (example-secrets.mjs)', 'node_modules', ''].join('\n'));
-  const staged = addGit(['-A', '--', '.'], { cwd: repoRoot, env });
-  if (staged.error || staged.status !== 0) throw new Error('could not stage the isolated example git tree');
-  // The isolated tree is committed (and based on the source's lint baseline) so the size-growth ratchet reads a real
-  // recorded size instead of failing "baseline unavailable" in every sealed lint, as it did on a historyless tree.
-  const base = sealedLintBase(repoRoot, source, env);
-  const tree = writeTree([], { cwd: repoRoot, env });
-  if (!ok(tree)) throw new Error('could not write the isolated example git tree');
-  const committed = commitTree([tree.stdout.trim(), ...(base ? ['-p', base] : []), '-m', 'sealed snapshot'], { cwd: repoRoot, env, config: COMMITTER });
-  if (!ok(committed)) throw new Error('could not commit the isolated example git tree');
-  const moved = updateRef(repoRoot, 'HEAD', committed.stdout.trim());
-  if (!moved.ok) throw new Error('could not point the isolated example git tree at its snapshot commit');
-  return base;
+    const env = withoutGitLocalEnv(process.env);
+    if (!initGit(repoRoot, { env }).ok)
+        throw new Error('could not initialize the isolated example git tree');
+    // The linked node_modules (linkExampleDependencies: a junction on Windows, a symlink elsewhere) is the install, never a tracked entry: git treats a
+    // symlink as a file, which the app's `node_modules/` (directory) ignore line does not match, so on Linux `git add -A` tracked it (HFS_TRACKED_MUST_BE_IGNORED,
+    // HFS_ROOT_ENTRY_FORBIDDEN in every examples.yml lint since the link). The copy's own exclude file ignores it in any form.
+    fs.appendFileSync(path.join(repoRoot, '.git', 'info', 'exclude'), ['', '# the linked install of the example (example-secrets.mjs)', 'node_modules', ''].join('\n'));
+    const staged = addGit(['-A', '--', '.'], { cwd: repoRoot, env });
+    if (staged.error || staged.status !== 0)
+        throw new Error('could not stage the isolated example git tree');
+    // The isolated tree is committed (and based on the source's lint baseline) so the size-growth ratchet reads a real
+    // recorded size instead of failing "baseline unavailable" in every sealed lint, as it did on a historyless tree.
+    const base = sealedLintBase(repoRoot, source, env);
+    const tree = writeTree([], { cwd: repoRoot, env });
+    if (!ok(tree))
+        throw new Error('could not write the isolated example git tree');
+    const committed = commitTree([tree.stdout.trim(), ...(base ? ['-p', base] : []), '-m', 'sealed snapshot'], { cwd: repoRoot, env, config: COMMITTER });
+    if (!ok(committed))
+        throw new Error('could not commit the isolated example git tree');
+    const moved = updateRef(repoRoot, 'HEAD', committed.stdout.trim());
+    if (!moved.ok)
+        throw new Error('could not point the isolated example git tree at its snapshot commit');
+    return base;
 }
-
 function safeExampleSource(source, { preserveCoverage = false } = {}) {
-  const name = path.basename(source);
-  const stat = fs.lstatSync(source);
-  if (stat.isSymbolicLink()) return false;
-  if (SKIPPED.has(name) && !(preserveCoverage && name === 'coverage')) return false;
-  if (/\.enc(?:\.yaml)?$/u.test(name) || /\.(?:agekey|pem|key)$/iu.test(name)) return false;
-  if (['secret.env', 'secrets.env', 'keys.txt'].includes(name)) return false;
-  if (name === '.env.example' || name.endsWith('.env.example')) return true;
-  if (name === '.env' || name.startsWith('.env.') || name.endsWith('.env')) return false;
-  if (stat.isDirectory()) return true;
-  const parts = source.split(path.sep);
-  return !parts.includes('secrets') || ['.gitignore', 'README.md'].includes(name);
+    const name = path.basename(source);
+    const stat = fs.lstatSync(source);
+    if (stat.isSymbolicLink())
+        return false;
+    if (SKIPPED.has(name) && !(preserveCoverage && name === 'coverage'))
+        return false;
+    if (/\.enc(?:\.yaml)?$/u.test(name) || /\.(?:agekey|pem|key)$/iu.test(name))
+        return false;
+    if (['secret.env', 'secrets.env', 'keys.txt'].includes(name))
+        return false;
+    if (name === '.env.example' || name.endsWith('.env.example'))
+        return true;
+    if (name === '.env' || name.startsWith('.env.') || name.endsWith('.env'))
+        return false;
+    if (stat.isDirectory())
+        return true;
+    const parts = source.split(path.sep);
+    return !parts.includes('secrets') || ['.gitignore', 'README.md'].includes(name);
 }
-
 function pruneEmptyDirectories(directory) {
-  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-    if (entry.isDirectory()) pruneEmptyDirectories(path.join(directory, entry.name));
-  }
-  if (!fs.readdirSync(directory).length) fs.rmdirSync(directory);
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        if (entry.isDirectory())
+            pruneEmptyDirectories(path.join(directory, entry.name));
+    }
+    if (!fs.readdirSync(directory).length)
+        fs.rmdirSync(directory);
 }
-
 /** Await callback(tempExamplePath, lintBaseRef), return its result, and remove the os.tmpdir-based copy even on failure. */
-export async function withMaterializedExample(repoRoot, exampleRelativePath, callback, { materialize = materializeExample, linkDependencies = false, preserveCoverage = false } = {}) {
-  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-example-'));
-  const source = path.resolve(repoRoot, exampleRelativePath);
-  const app = path.join(directory, 'examples', path.basename(source));
-  try {
-    fs.writeFileSync(path.join(directory, 'hfs.json'), JSON.stringify({ kind: 'runtime' }));
-    fs.cpSync(source, app, {
-      recursive: true,
-      filter: (file) => safeExampleSource(file, { preserveCoverage }),
-    });
-    pruneEmptyDirectories(app);
-    if (linkDependencies) linkExampleDependencies(source, app);
-    await materialize(app);
-    const lintBaseRef = trackExample(app, source);
-    return await callback(app, lintBaseRef);
-  } finally {
-    safeRemove(directory, { hold: () => null });
-  }
+export async function withMaterializedExample(repoRoot, exampleRelativePath, callback, { materialize = materializeExample, linkDependencies = false, preserveCoverage = false, } = {}) {
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-example-'));
+    const source = path.resolve(repoRoot, exampleRelativePath);
+    const app = path.join(directory, 'examples', path.basename(source));
+    try {
+        fs.writeFileSync(path.join(directory, 'hfs.json'), JSON.stringify({ kind: 'runtime' }));
+        fs.cpSync(source, app, {
+            recursive: true,
+            filter: (file) => safeExampleSource(file, { preserveCoverage }),
+        });
+        pruneEmptyDirectories(app);
+        if (linkDependencies)
+            linkExampleDependencies(source, app);
+        await materialize(app);
+        const lintBaseRef = trackExample(app, source);
+        return await callback(app, lintBaseRef);
+    }
+    finally {
+        safeRemove(directory, { hold: () => null });
+    }
 }
-
 // Runtime example command execution shares the same isolated materialization as the source check.
 function linkExampleDependencies(source, target) {
-  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
-    const from = path.join(source, entry.name);
-    const to = path.join(target, entry.name);
-    if (entry.name === 'node_modules') {
-      fs.mkdirSync(target, { recursive: true });
-      fs.symlinkSync(from, to, process.platform === 'win32' ? 'junction' : 'dir');
-    } else if (entry.isDirectory() && safeExampleSource(from)) {
-      linkExampleDependencies(from, to);
+    for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+        const from = path.join(source, entry.name);
+        const to = path.join(target, entry.name);
+        if (entry.name === 'node_modules') {
+            fs.mkdirSync(target, { recursive: true });
+            fs.symlinkSync(from, to, process.platform === 'win32' ? 'junction' : 'dir');
+        }
+        else if (entry.isDirectory() && safeExampleSource(from)) {
+            linkExampleDependencies(from, to);
+        }
     }
-  }
 }
-
 function commandLaunch(command, args) {
-  const npm = /^(npm|npx)(?:\.cmd)?$/iu.exec(command);
-  if (process.platform !== 'win32' || !npm) return { file: command, args };
-  const entry = npm[1].toLowerCase() + '-cli.js';
-  const resolved = resolveRealTool(npm[1]);
-  const npmExecPath = readEnv('npm_execpath');
-  const candidates = [
-    npmExecPath && path.join(path.dirname(npmExecPath), entry),
-    resolved && path.join(path.dirname(resolved), 'node_modules', 'npm', 'bin', entry),
-    path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', entry),
-  ];
-  const cli = candidates.find((file) => file && fs.existsSync(file));
-  if (!cli) throw new Error('the example runner could not locate the installed npm CLI entry point');
-  return { file: process.execPath, args: [cli, ...args] };
+    const npm = /^(npm|npx)(?:\.cmd)?$/iu.exec(command);
+    if (process.platform !== 'win32' || !npm)
+        return { file: command, args };
+    const entry = npm[1].toLowerCase() + '-cli.js';
+    const resolved = resolveRealTool(npm[1]);
+    const npmExecPath = readEnv('npm_execpath');
+    const candidates = [
+        npmExecPath && path.join(path.dirname(npmExecPath), entry),
+        resolved && path.join(path.dirname(resolved), 'node_modules', 'npm', 'bin', entry),
+        path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', entry),
+    ];
+    const cli = candidates.find((file) => file && fs.existsSync(file));
+    if (!cli)
+        throw new Error('the example runner could not locate the installed npm CLI entry point');
+    return { file: process.execPath, args: [cli, ...args] };
 }
-
 // The copy's own lint base replaces any STARCI_BASE_REF of the caller, which names a ref of the source repository, not of the copy.
 function commandEnvironment(lintBaseRef) {
-  const env = withoutGitLocalEnv(process.env);
-  const out = Object.fromEntries(Object.entries(env).filter(([name]) => !/^SOPS_AGE_KEY(?:_FILE)?$/iu.test(name)));
-  if (lintBaseRef) out.STARCI_BASE_REF = lintBaseRef;
-  return out;
+    const env = withoutGitLocalEnv(process.env);
+    const out = Object.fromEntries(Object.entries(env).filter(([name]) => !/^SOPS_AGE_KEY(?:_FILE)?$/iu.test(name)));
+    if (lintBaseRef)
+        out.STARCI_BASE_REF = lintBaseRef;
+    return out;
 }
-
 /** Run an installed app command in a sealed temporary copy, returning its exit code and preserving report artifacts. */
-async function runMaterializedCommand(repoRoot, command, args = [], { run = runProgram } = {}) {
-  return withMaterializedExample(repoRoot, '.', (app, lintBaseRef) => {
-    const launch = commandLaunch(command, args);
-    const result = run(launch.file, launch.args, { cwd: app, env: commandEnvironment(lintBaseRef), stdio: 'inherit', windowsHide: true });
-    const reports = path.join(app, 'reports');
-    if (fs.existsSync(reports)) fs.cpSync(reports, path.join(repoRoot, 'reports'), { recursive: true });
-    if (result.error) throw new Error('the example check command could not start');
-    return result.status ?? 1;
-  }, { linkDependencies: true, preserveCoverage: true });
+async function runMaterializedCommand(repoRoot, command, args = [], { run = runProgram, } = {}) {
+    return withMaterializedExample(repoRoot, '.', (app, lintBaseRef) => {
+        const launch = commandLaunch(command, args);
+        const result = run(launch.file, launch.args, { cwd: app, env: commandEnvironment(lintBaseRef), stdio: 'inherit', windowsHide: true });
+        const reports = path.join(app, 'reports');
+        if (fs.existsSync(reports))
+            fs.cpSync(reports, path.join(repoRoot, 'reports'), { recursive: true });
+        if (result.error)
+            throw new Error('the example check command could not start');
+        return result.status ?? 1;
+    }, { linkDependencies: true, preserveCoverage: true });
 }
-
 async function main(argv) {
-  if (argv[0] === '--run' && argv[1] && argv[2] === '--' && argv[3])
-    return runMaterializedCommand(path.resolve(argv[1]), argv[3], argv.slice(4));
-  if (argv.length !== 1) throw new Error('usage: example-secrets.mjs <disposable-copy> | --run <example> -- <command> [args]');
-  const result = await materializeExample(path.resolve(argv[0]));
-  process.stdout.write(`example sealed members generated: ${result.members.length}\n`);
-  return 0;
+    if (argv[0] === '--run' && argv[1] && argv[2] === '--' && argv[3])
+        return runMaterializedCommand(path.resolve(argv[1]), argv[3], argv.slice(4));
+    if (argv.length !== 1)
+        throw new Error('usage: example-secrets.mjs <disposable-copy> | --run <example> -- <command> [args]');
+    const result = await materializeExample(path.resolve(argv[0]));
+    process.stdout.write(`example sealed members generated: ${result.members.length}\n`);
+    return 0;
 }
-
-if (isMain(import.meta.url)) process.exitCode = await main(process.argv.slice(2));
+if (isMain(import.meta.url))
+    process.exitCode = await main(process.argv.slice(2));

package/runtime/scripts/hfs/gate-threshold.d.mts

@@ -0,0 +1,20 @@
+export declare const GATE_ERROR_LIMIT = 20;
+/** The limit in force: policy/quality.yaml `gate.errorLimit`, handed in by the harness CLI as STARCI_GATE_ERROR_LIMIT, else 20. */
+export declare function gateErrorLimit(env?: NodeJS.ProcessEnv): number;
+export declare const GATE_THRESHOLD_RULING = "owner ruling gate-threshold-20 2026-10-30: app check and lint pass under 20 error findings with no plaintext secret, boot proof or migration finding";
+/** The codes that block at any count: plaintext secrets, the boot proof, the migrations. */
+export declare const HARD_BLOCKERS: ReadonlySet<string>;
+/**
+ * The verdict over the error findings (each with `code`): { pass, count, hard, line }. `pass` is true when no hard blocker is
+ * among them and there are fewer than GATE_ERROR_LIMIT; `line` says which, for the report.
+ */
+/** The gate's verdict over a run's error findings. */
+export interface GateVerdict {
+    pass: boolean;
+    count: number;
+    hard: string[];
+    line: string | null;
+}
+export declare function gateVerdict(errors: readonly {
+    code: string | null;
+}[], limit?: number): GateVerdict;

package/runtime/scripts/hfs/gate-threshold.mjs

@@ -0,0 +1,28 @@
+// gate-threshold.mjs - the verdict of `starci app check` and `starci app lint` (owner ruling gate-threshold-20, 2026-10-30): green
+// while fewer than GATE_ERROR_LIMIT error findings remain and none of them is a hard blocker, so a release is not held back finding
+// by finding (5, 4, 3, ...) by the last few structural nits. A plaintext secret, a failed boot proof and a broken migration block at
+// any count. Every finding is still printed; only the exit code changes. Typecheck, build and the tests are not judged here.
+export const GATE_ERROR_LIMIT = 20;
+/** The limit in force: policy/quality.yaml `gate.errorLimit`, handed in by the harness CLI as STARCI_GATE_ERROR_LIMIT, else 20. */
+export function gateErrorLimit(env = process.env) {
+    const value = Number(env.STARCI_GATE_ERROR_LIMIT);
+    return Number.isInteger(value) && value > 0 ? value : GATE_ERROR_LIMIT;
+}
+export const GATE_THRESHOLD_RULING = 'owner ruling gate-threshold-20 2026-10-30: app check and lint pass under 20 error findings with no plaintext secret, boot proof or migration finding';
+/** The codes that block at any count: plaintext secrets, the boot proof, the migrations. */
+export const HARD_BLOCKERS = Object.freeze(new Set([
+    'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'RT_SECRET_TRACKED',
+    'STACKS_SECRET_ENV_LITERAL', 'APP_SECRET_IN_CI', 'BE_LOG_SECRET',
+    'BE_APP_BOOT_PROOF_MISSING',
+    'DB_MIGRATION_SHAPE', 'DB_MIGRATION_DESTRUCTIVE', 'LITE_DB_MIGRATION', 'BE_MIGRATION_REVERSIBLE',
+]));
+export function gateVerdict(errors, limit = gateErrorLimit()) {
+    const hard = [...new Set(errors.map((finding) => finding.code).filter((code) => code !== null && HARD_BLOCKERS.has(code)))].sort();
+    const count = errors.length;
+    const pass = hard.length === 0 && count < limit;
+    const line = count === 0 ? null
+        : hard.length > 0 ? `gate: red, ${hard.join(', ')} block${hard.length === 1 ? 's' : ''} at any count (${count} error finding(s))`
+            : pass ? `gate: green under the threshold, ${count} error finding(s) < ${limit} and no hard blocker (owner ruling gate-threshold-20); they stay listed above`
+                : `gate: red, ${count} error finding(s), the threshold is fewer than ${limit}`;
+    return { pass, count, hard, line };
+}