@starci/hfs 4.3.0 → 4.4.1

package/runtime/scripts/hfs/rules/release-provenance.mjs

@@ -0,0 +1,211 @@
+// R271: a product release keeps its v<semver> tag, root package version, image tags and database deployment ref together.
+// Ordinary untagged development trees have no release version to compare. Workflow checks still run there in both editions.
+// YAML is parsed, so comments and unrelated jobs cannot supply a guard. Shell guards are deliberately a small, explicit form;
+// opaque helper scripts and computed image metadata cannot prove provenance in this static check.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { isPlainObject } from '../../../engine/plain-object.mjs';
+import { revParseQuery } from '../../api/git/rev-parse-query.mjs';
+import { tag } from '../../api/git/tag.mjs';
+import { gitOutputOf, withoutGitLocalEnv } from '../../lib/git.mjs';
+import { found, readJson, readText } from './read.mjs';
+
+export const HFS_RELEASE_TAG_MISMATCH = 'HFS_RELEASE_TAG_MISMATCH';
+export const HFS_DB_DEPLOY_UNGUARDED = 'HFS_DB_DEPLOY_UNGUARDED';
+const SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const WORKFLOW = /^\.github\/workflows\/(images|db-deploy)\.ya?ml$/;
+const TAG = 1;
+const VERSION_PREFIX = 2;
+const RELEASE_REF = TAG | VERSION_PREFIX;
+
+function gitTags(repoRoot, env) {
+  const options = { cwd: repoRoot, env: withoutGitLocalEnv(env), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, maxBuffer: 64 * 1024, windowsHide: true };
+  try {
+    // A nested example belongs to its own product, never to an ancestor runtime's tags.
+    const top = gitOutputOf(revParseQuery(['--show-toplevel'], options)).trim();
+    if (path.relative(fs.realpathSync(top), fs.realpathSync(repoRoot)) !== '') return [];
+    const tags = gitOutputOf(tag(['--points-at', 'HEAD'], options)).trim().split(/\r?\n/).filter((value) => value.startsWith('v'));
+    if (env.GITHUB_ACTIONS === 'true' && env.GITHUB_REF?.startsWith('refs/tags/v')) tags.push(env.GITHUB_REF.slice('refs/tags/'.length));
+    return [...new Set(tags)];
+  } catch { return []; }
+}
+
+function tagFindings(repoRoot, version, env) {
+  return gitTags(repoRoot, env).filter((tag) => !SEMVER.test(tag.slice(1)) || tag.slice(1) !== version)
+    .map((tag) => found(HFS_RELEASE_TAG_MISMATCH, 'package.json', 'the release tag at HEAD must be v<semver> and equal the root package.json version; align the version before cutting the release', { tag, version: typeof version === 'string' ? version : null }));
+}
+
+// Split only outside strings/function calls; arbitrary expressions remain unproved atoms.
+function splitBoolean(expression, operator) {
+  const parts = [];
+  let start = 0, depth = 0, quote = '';
+  for (let i = 0; i < expression.length; i += 1) {
+    const char = expression[i];
+    if (quote) { if (char === quote) quote = ''; continue; }
+    if (char === "'" || char === '"') { quote = char; continue; }
+    if (char === '(') depth += 1;
+    if (char === ')') depth -= 1;
+    if (depth === 0 && expression.slice(i, i + 2) === operator) { parts.push(expression.slice(start, i)); start = i + 2; i += 1; }
+  }
+  parts.push(expression.slice(start));
+  return parts;
+}
+
+function enclosingParentheses(text) {
+  let depth = 0, quote = '';
+  for (let i = 0; i < text.length - 1; i += 1) {
+    const char = text[i];
+    if (quote) { if (char === quote) quote = ''; continue; }
+    if (char === "'" || char === '"') { quote = char; continue; }
+    if (char === '(') depth += 1;
+    if (char === ')' && --depth === 0) return false;
+  }
+  return true;
+}
+
+function unwrap(expression) {
+  let text = expression.trim();
+  while (text.startsWith('(') && text.endsWith(')') && enclosingParentheses(text)) text = text.slice(1, -1).trim();
+  return text;
+}
+
+function workflowExpression(value) {
+  const text = value.trim();
+  return text.startsWith('${{') && text.endsWith('}}') ? text.slice(3, -2).trim() : text;
+}
+
+function refProof(value) {
+  if (typeof value !== 'string') return 0;
+  const expression = unwrap(workflowExpression(value));
+  const alternatives = splitBoolean(expression, '||');
+  if (alternatives.length > 1) return alternatives.map(refProof).reduce((a, b) => a & b);
+  const conjuncts = splitBoolean(expression, '&&');
+  if (conjuncts.length > 1) return conjuncts.map(refProof).reduce((a, b) => a | b, 0);
+  if (/^startsWith\(\s*github\.ref\s*,\s*(['"])refs\/tags\/v\1\s*\)$/.test(expression)) return RELEASE_REF;
+  const exact = /^github\.ref\s*==\s*(['"])refs\/tags\/v([^'"\s]+)\1$/.exec(expression);
+  if (exact && SEMVER.test(exact[2])) return RELEASE_REF;
+  if (/^(?:github\.ref_type\s*==\s*(['"])tag\1|(['"])tag\2\s*==\s*github\.ref_type)$/.test(expression)) return TAG;
+  if (/^startsWith\(\s*github\.ref_name\s*,\s*(['"])v\1\s*\)$/.test(expression)) return VERSION_PREFIX;
+  return 0;
+}
+
+function tagOnlyTrigger(workflow) {
+  const events = workflow.on;
+  if (!events || typeof events !== 'object' || Array.isArray(events) || Object.keys(events).join() !== 'push') return false;
+  const push = events.push;
+  if (!push || typeof push !== 'object' || push.branches || push['branches-ignore'] || push['tags-ignore']) return false;
+  const tags = Array.isArray(push.tags) ? push.tags : [];
+  const included = tags.filter((tag) => typeof tag === 'string' && !tag.startsWith('!'));
+  return included.length > 0 && included.every((tag) => tag.startsWith('v'));
+}
+
+function shellTagGuard(step) {
+  if (step.if !== undefined || step['continue-on-error'] || typeof step.run !== 'string') return false;
+  const command = step.run.trim().replace(/^set -[a-z]+(?:\s+pipefail)?\s*\n/, '').trim();
+  // The whole guard step must reject a non-release ref; a nested, commented or later guard is insufficient.
+  return /^\[\[\s*["']?\$(?:GITHUB_REF|\{GITHUB_REF\})["']?\s*==\s*refs\/tags\/v\*\s*\]\]\s*\|\|\s*exit\s+[1-9]\d*\s*;?$/.test(command)
+    || /^case\s+["']?\$(?:GITHUB_REF|\{GITHUB_REF\})["']?\s+in\s+refs\/tags\/v\*\)\s*;;\s*\*\)\s*exit\s+[1-9]\d*\s*;;\s*esac\s*;?$/.test(command);
+}
+
+function checkoutPreservesRef(job) {
+  return (job.steps ?? []).filter((step) => /^actions\/checkout@/.test(step.uses ?? '')).every((step) => {
+    const ref = step.with?.ref;
+    return ref === undefined || /^\$\{\{\s*github\.(?:ref|ref_name|sha)\s*\}\}$/.test(String(ref));
+  });
+}
+
+function setupStep(step) {
+  return /^(?:actions\/checkout|actions\/setup-node)@/.test(step.uses ?? '')
+    || (typeof step.run === 'string' && /^npm ci --ignore-scripts\s*$/.test(step.run.trim()));
+}
+
+function unguardedDeployStep(step, shellGuarded, guarded) {
+  // Checkout, Node setup and script-disabled npm install may precede the guard. Opaque commands may deploy.
+  // A later always()/failure() step can run despite the rejecting shell guard's failure.
+  const shellConstrained = shellGuarded && !/\b(?:always|failure|cancelled)\s*\(/.test(String(step.if ?? ''));
+  return (step.run || step.uses) && !setupStep(step) && !guarded && !shellConstrained && refProof(step.if) !== RELEASE_REF;
+}
+
+function dbJobConstrained(job, guarded) {
+  let shellGuarded = false;
+  let constrained = !job.uses || guarded;
+  for (const step of job.steps ?? []) {
+    if (shellTagGuard(step)) { shellGuarded = true; continue; }
+    if (unguardedDeployStep(step, shellGuarded, guarded)) constrained = false;
+  }
+  if (!job.uses && !(job.steps ?? []).some((step) => step.run || step.uses)) constrained = false;
+  return constrained;
+}
+
+function dbFindings(file, workflow) {
+  const jobs = Object.entries(workflow.jobs ?? {});
+  if (!jobs.length) return [found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} has no verifiable database deploy job; require a release tag before migration`)];
+  const findings = [];
+  for (const [name, job] of jobs) {
+    if (!job || typeof job !== 'object') continue;
+    const guarded = tagOnlyTrigger(workflow) || refProof(job.if) === RELEASE_REF;
+    const constrained = dbJobConstrained(job, guarded);
+    if (!constrained || !checkoutPreservesRef(job)) findings.push(found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} job ${name} can deploy a non-release ref; require refs/tags/v at the job or before any deploy command, and check out that ref`, { job: name }));
+  }
+  return findings;
+}
+
+function validJob(job) {
+  return isPlainObject(job) && (job.steps === undefined || (Array.isArray(job.steps) && job.steps.every(isPlainObject)));
+}
+
+function validWorkflow(workflow) {
+  return isPlainObject(workflow) && isPlainObject(workflow.jobs) && Object.values(workflow.jobs).every(validJob);
+}
+
+function imageTagIsRelease(value, version) {
+  if (typeof value !== 'string') return false;
+  const tags = value.split(/[\n,]+/).map((tag) => tag.trim()).filter(Boolean);
+  return tags.length > 0 && tags.every((tag) => {
+    const ref = tag.replace(/\$\{\{\s*github\.ref_name\s*\}\}/g, '<release-ref>');
+    if (ref.endsWith(':<release-ref>')) return true;
+    return SEMVER.test(String(version)) && ref.endsWith(`:v${version}`);
+  });
+}
+
+function imageFindings(file, workflow, version) {
+  const findings = [];
+  let builds = 0;
+  for (const [name, job] of Object.entries(workflow.jobs ?? {})) {
+    for (const step of job?.steps ?? []) {
+      if (!/^docker\/build-push-action@/.test(step.uses ?? '')) continue;
+      builds += 1;
+      const guarded = tagOnlyTrigger(workflow) || refProof(job.if) === RELEASE_REF || refProof(step.if) === RELEASE_REF;
+      if (!guarded || !checkoutPreservesRef(job) || !imageTagIsRelease(step.with?.tags, version)) findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} must build the checked-out release ref and tag every image with v<package.json version> or github.ref_name under a release-tag guard`, { job: name }));
+    }
+  }
+  if (!builds) findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} has no verifiable release image tags; declare docker/build-push-action tags from the release ref`));
+  return findings;
+}
+
+function productRoot(repo, isRoot) {
+  return isRoot !== false && !['be', 'fe', 'runtime'].includes(repo.profile)
+    && (!repo.kind || repo.kind === 'app') && ['lite', 'full'].includes(repo.edition ?? 'full');
+}
+
+/** Synchronous product-root provenance findings; root and workflows are judged in lite and full, never a side or runtime. */
+export function releaseProvenanceFindings({ repoRoot, files = [], repo = {}, isRoot, inScope = () => true, env = process.env } = {}) {
+  if (!productRoot(repo, isRoot)) return [];
+  const version = readJson(repoRoot, 'package.json')?.version;
+  const packageInScope = files.includes('package.json') && inScope('package.json');
+  const findings = packageInScope ? tagFindings(repoRoot, version, env) : [];
+  for (const file of files) {
+    const match = WORKFLOW.exec(file);
+    if (!match || (!inScope(file) && !packageInScope)) continue;
+    const code = match[1] === 'images' ? HFS_RELEASE_TAG_MISMATCH : HFS_DB_DEPLOY_UNGUARDED;
+    let workflow;
+    try { workflow = parseYaml(readText(repoRoot, file) ?? ''); } catch { /* unreadable YAML cannot prove a release */ }
+    if (!validWorkflow(workflow)) {
+      findings.push(found(code, file, `${file} cannot be parsed as a workflow; restore its release tag checks`));
+      continue;
+    }
+    findings.push(...(match[1] === 'images' ? imageFindings(file, workflow, version) : dbFindings(file, workflow)));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/saga-delivery.mjs

@@ -0,0 +1,66 @@
+// Trace the delivery parameter into command constructor arguments, rather than arbitrary reads.
+import { accessName, isConstVariable } from '../../lib/ts-ast.mjs';
+import { sourceValue } from './database-queue-sources.mjs';
+
+function unwrap(ts, node) {
+  const value = sourceValue(ts, node);
+  return value && ts.isNonNullExpression(value) ? unwrap(ts, value.expression) : value;
+}
+
+function resolve(ts, node, aliases, seen = new Set()) {
+  const value = unwrap(ts, node);
+  if (!value || !ts.isIdentifier(value) || !aliases.has(value.text) || seen.has(value.text)) return value;
+  return resolve(ts, aliases.get(value.text), aliases, new Set(seen).add(value.text));
+}
+
+function carriesKey(ts, node, delivery, aliases, seen = new Set()) {
+  const value = resolve(ts, node, aliases);
+  if (!value || seen.has(value)) return false;
+  const next = new Set(seen).add(value);
+  if (accessName(ts, value) === 'eventId') {
+    const receiver = resolve(ts, value.expression, aliases);
+    return ts.isIdentifier(receiver) && receiver.text === delivery;
+  }
+  if (ts.isObjectLiteralExpression(value)) return value.properties.some((property) => carriesKey(ts, property, delivery, aliases, next));
+  if (ts.isPropertyAssignment(value)) return carriesKey(ts, value.initializer, delivery, aliases, next);
+  if (ts.isShorthandPropertyAssignment(value)) return carriesKey(ts, value.name, delivery, aliases, next);
+  if (ts.isArrayLiteralExpression(value)) return value.elements.some((element) => carriesKey(ts, element, delivery, aliases, next));
+  return false;
+}
+
+function localAliases(ts, method) {
+  const aliases = new Map();
+  for (const statement of method.body?.statements ?? []) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.initializer && isConstVariable(ts, declaration)) aliases.set(declaration.name.text, declaration.initializer);
+    }
+  }
+  return aliases;
+}
+
+function methodForwards(ts, method) {
+  const parameter = method.parameters[0]?.name;
+  if (!parameter || !ts.isIdentifier(parameter)) return false;
+  const aliases = localAliases(ts, method);
+  const commands = [];
+  const visit = (node) => {
+    // A read in a nested function does not forward the handler's delivery.
+    if (ts.isFunctionLike(node)) return;
+    if (ts.isCallExpression(node) && accessName(ts, node.expression) === 'execute') commands.push(resolve(ts, node.arguments[0], aliases));
+    ts.forEachChild(node, visit);
+  };
+  if (method.body) visit(method.body);
+  return commands.length > 0 && commands.every((command) => command && ts.isNewExpression(command)
+    && (command.arguments ?? []).some((argument) => carriesKey(ts, argument, parameter.text, aliases)));
+}
+
+export function forwardsDeliveryKey(ts, source) {
+  const handlers = [];
+  const visit = (node) => {
+    if (ts.isMethodDeclaration(node) && node.name.getText(source) === 'handle') handlers.push(node);
+    else ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return handlers.length > 0 && handlers.every((method) => methodForwards(ts, method));
+}

package/runtime/scripts/hfs/rules/saga.mjs

@@ -20,6 +20,7 @@ import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { found, readJson, readText } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
+import { forwardsDeliveryKey } from './saga-delivery.mjs';
 
 const SAGA_STEP_COMPENSATION = 'BE_SAGA_STEP_COMPENSATION';
 const SAGA_STATE_VERSIONED = 'BE_SAGA_STATE_VERSIONED';
@@ -81,17 +82,6 @@ function statesVersion(ts, sourceFile) {
   return versioned;
 }
 
-/** Whether a source text reads `.eventId` of something (the id of the delivery travels on). */
-function readsEventId(ts, sourceFile) {
-  let read = false;
-  const visit = (node) => {
-    if (ts.isPropertyAccessExpression(node) && node.name.text === 'eventId') read = true;
-    ts.forEachChild(node, visit);
-  };
-  visit(sourceFile);
-  return read;
-}
-
 /** The sagas of the app: every folder of the saga kind (`be/src/features/saga/<saga>/`). */
 const featuresOf = (files) => [...new Set(files.map((file) => SAGA_FILE.exec(file)?.[1]).filter((feature) => feature !== undefined))].sort(byCodeUnit);
 
@@ -186,7 +176,7 @@ function consumerFindings(ts, repoRoot, feature, files) {
   const findings = [];
   for (const file of filesForFeature(files, CONSUMER, feature)) {
     const text = readText(repoRoot, file);
-    if (text !== null && !readsEventId(ts, parse(ts, text))) findings.push(found(SAGA_CONSUMER_DEDUPE, file, `${file} is a consumer of the saga ${feature} but never passes the id of the delivery on (\`message.eventId\`); the saga takes every event through the inbox, so the consumer hands the id to its command.`, { feature }));
+    if (text !== null && !forwardsDeliveryKey(ts, parse(ts, text))) findings.push(found(SAGA_CONSUMER_DEDUPE, file, `${file} is a consumer of the saga ${feature} but does not pass the delivery id (\`message.eventId\`) to every dispatched command; the saga takes every event through the inbox, so the consumer hands the id to its command.`, { feature }));
   }
   return findings;
 }
@@ -214,7 +204,7 @@ function compensationE2eFindings(compensationPaths, specs) {
 }
 
 /** Findings of R169 to R173 over the tracked paths `files` of the app at `repoRoot`. */
-export function sagaFindings({ repoRoot, files }) {
+export function sagaFindings({ repoRoot, files, repo }) {
   const features = featuresOf(files);
   if (features.length === 0) return [];
   const ts = typescriptFor(repoRoot);
@@ -223,7 +213,6 @@ export function sagaFindings({ repoRoot, files }) {
   for (const contract of files.filter((file) => CONTRACT.test(file))) {
     for (const [name, event] of Object.entries(readJson(repoRoot, contract)?.events ?? {})) events.set(name, { contract, ...event });
   }
-  const specs = files.filter((file) => E2E_SPEC.test(file)).map((file) => ({ file, text: readText(repoRoot, file) ?? '' })).filter(({ text }) => USE_TEST_WORLD.test(text));
   const findings = [];
   const compensationPaths = [];
   for (const feature of features) {
@@ -231,7 +220,10 @@ export function sagaFindings({ repoRoot, files }) {
     findings.push(...result.findings);
     compensationPaths.push(...result.compensationPaths);
   }
-  // R173
-  findings.push(...compensationE2eFindings(compensationPaths, specs));
+  // R173 is the full-edition test-world proof; lite keeps R169-R172 and proves its scenarios through R284.
+  if (repo?.edition !== 'lite') {
+    const specs = files.filter((file) => E2E_SPEC.test(file)).map((file) => ({ file, text: readText(repoRoot, file) ?? '' })).filter(({ text }) => USE_TEST_WORLD.test(text));
+    findings.push(...compensationE2eFindings(compensationPaths, specs));
+  }
   return findings;
 }

package/runtime/scripts/hfs/rules/script-hygiene.mjs

@@ -0,0 +1,151 @@
+// R252: inspect executable source for plaintext loads, tracing and service-role custody.
+// Only source is read. Secret files and sealed envelopes are excluded before any read,
+// and findings carry a path and a fixed explanation, never source text or values.
+import { found, readJson, readText } from './read.mjs';
+
+const PLAINTEXT_LOAD = 'HFS_SCRIPT_PLAINTEXT_LOAD';
+const XTRACE = 'HFS_SCRIPT_XTRACE';
+const SERVICE_ROLE = 'HFS_SERVICE_ROLE_SCOPE';
+const SUPABASE_OWNER = 'be.integrations.supabase';
+const SECRET_FILE = /(?:^|\/)(?:secrets?\.env(?:\.[^/]*)?|\.env(?:\.[^/]*)?|\.nivo-lite(?:\/|$))|\.enc$/iu;
+const EXCLUDED_TREE = /(?:^|\/)(?:node_modules|\.git|\.claude|\.secrets|secrets|tests?|__tests__|docs|coverage|dist|build)(?:\/|$)/u;
+const TEST_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/u;
+const SOURCE = /\.(?:[cm]?[jt]sx?|sh|bash|zsh|ksh|ps1|psm1|bat|cmd|py|rb|pl)$/iu;
+const WORKFLOW = /(?:^|\/)\.?(?:github\/)?workflows\/[^/]+\.ya?ml$/u;
+const DELIVERY = /(?:^|\/)(?:deploy|scripts|bin)\//u;
+const DOCKER = /(?:^|\/)(?:Dockerfile(?:\.[^/]*)?|(?:docker-)?compose(?:[.-][^/]*)?\.ya?ml)$/iu;
+const SECRET_REFERENCE = /(?:^|[\s/\\'"`(=])(?:secrets?\.env(?:\.[\w.-]+)?|\.env(?:\.[\w.-]+)?|\.nivo-lite(?:[/\\][\w./\\-]*)?)(?=$|[\s/\\'"`),;])/iu;
+const EXAMPLE_REFERENCE = /(?:secrets?\.env|\.env)\.(?:example|sample|template)(?=$|[^\w.-])/giu;
+const LOAD = /(?:^|[\s;&|('"`])(?:source|cat|tac|less|more|head|tail|grep|egrep|fgrep|awk|gawk|sed|base64|Get-Content|gc|Import-DotEnv|env-cmd|load_dotenv|loadEnvFile|readFile(?:Sync)?|readTextFile(?:Sync)?|ReadAllText|ReadAllLines|dotenv\s*\.\s*(?:config|parse))\b|\b(?:File|IO)\s*\.\s*(?:read|readlines)\b|\.\s*read_(?:text|bytes)\s*\(|(?:^|[\s;&|])\.[\t ]+|(?<!<)<(?!<)/iu;
+const READ_CALL = /\b(?:readFile(?:Sync)?|readTextFile(?:Sync)?|ReadAllText|ReadAllLines|load_dotenv|loadEnvFile|dotenv\s*\.\s*(?:config|parse))\s*\(/giu;
+const TRACE_COMMAND = /(?:^|[\s;&|('"`]|#!)(?:set|\/?(?:[\w.-]+\/)*(?:bash|sh|dash|zsh|ksh))\s+/giu;
+const SHELL_OPTIONS = /\bSHELLOPTS\s*=\s*['"]?([^\s;'"]*)/giu;
+const SERVICE_ROLE_NAME = /(?:^|[^a-z0-9])(?:[a-z0-9]+[_-])*service[_-]?role(?:[_-][a-z0-9]+)*(?=$|[^a-z0-9])/iu;
+
+/** Retain executable strings, including remote shell commands, but discard comment-only lines. */
+function executableText(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//gu, '').split(/\r?\n/u)
+    .filter((line) => !/^\s*(?:#(?!!)|\/\/)/u.test(line)).join('\n')
+    .replace(/(?:\\|`)\r?\n/gu, ' ');
+}
+
+const hasSecretReference = (text) => SECRET_REFERENCE.test(text.replace(EXAMPLE_REFERENCE, 'example-file'));
+
+function callArguments(text, from) {
+  let depth = 1;
+  let quote = '';
+  for (let at = from; at < Math.min(text.length, from + 1024); at += 1) {
+    const character = text[at];
+    if (character === '\\') { at += 1; continue; }
+    if (quote) { if (character === quote) quote = ''; continue; }
+    if (['\'', '"', '`'].includes(character)) { quote = character; continue; }
+    if (character === '(') depth += 1;
+    if (character === ')' && --depth === 0) return text.slice(from, at);
+  }
+  return '';
+}
+
+/** A helper may assign a path first and source/read the variable on the next line. */
+function secretAliases(lines) {
+  const aliases = [];
+  for (const line of lines) {
+    const equals = line.indexOf('=');
+    if (equals < 0 || !hasSecretReference(line.slice(equals + 1))) continue;
+    const name = line.slice(0, equals).trim().replace(/^(?:export|const|let|var)\s+/iu, '').replace(/^\$/u, '');
+    if (/^[a-z_]\w*$/iu.test(name)) aliases.push(new RegExp(String.raw`\b${name}\b`, 'u'));
+  }
+  return aliases;
+}
+
+/** JS, .NET and dotenv readers can put their filename on a later line of the call. */
+function multilineLoad(text, secretReference) {
+  for (const match of text.matchAll(READ_CALL)) {
+    const args = callArguments(text, match.index + match[0].length);
+    if (secretReference(args)) return true;
+  }
+  return false;
+}
+
+function pythonLoad(text) {
+  // Python's default open mode is reading; explicit write/append modes are not loads.
+  for (const match of text.matchAll(/\bopen\s*\(/gu)) {
+    const args = callArguments(text, match.index + match[0].length).split(',').map((value) => value.trim());
+    const filename = /^(['"])([^'"\r\n]+)\1$/u.exec(args[0]);
+    const mode = /^(['"])([^'"]*)\1$/u.exec(args[1] ?? '');
+    if (filename && (!args[1] || mode && /^[rU]/u.test(mode[2])) && hasSecretReference(filename[2])) return true;
+  }
+  return false;
+}
+
+function plaintextLoad(text) {
+  const lines = text.split(/\r?\n/u);
+  const aliases = secretAliases(lines);
+  const secretReference = (value) => hasSecretReference(value) || aliases.some((alias) => alias.test(value));
+  return lines.some((line) => LOAD.test(line) && secretReference(line)) || multilineLoad(text, secretReference) || pythonLoad(text);
+}
+
+function tracingOptions(source) {
+  let previous = '';
+  for (const [token] of source.matchAll(/[^\s;'"})`]+/gu)) {
+    if (!token.startsWith('-')) {
+      if (!previous || !/^[\w-]+$/u.test(token)) return false;
+      if (/^-o$/iu.test(previous) && /^xtrace$/iu.test(token)) return true;
+      previous = '';
+      continue;
+    }
+    if (!/^--?[\w-]+$/u.test(token)) return false;
+    if (/^-[a-z]+$/iu.test(token) && token.toLowerCase().includes('x')) return true;
+    previous = token;
+  }
+  return false;
+}
+
+/** Parse shell options individually so repeated flags cannot create regex backtracking. */
+function enablesTracing(text) {
+  if (/--reveal\b/iu.test(text)) return true;
+  for (const match of text.matchAll(SHELL_OPTIONS)) {
+    if (/\bxtrace\b/iu.test(match[1])) return true;
+  }
+  for (const match of text.matchAll(TRACE_COMMAND)) {
+    const from = match.index + match[0].length;
+    const newline = text.indexOf('\n', from);
+    if (tracingOptions(text.slice(from, newline < 0 ? text.length : newline))) return true;
+  }
+  return false;
+}
+
+function integrationOwns(file, resolver) {
+  if (!file.startsWith('be/src/modules/integrations/supabase/')) return false;
+  return !resolver?.ownerOf || resolver.ownerOf(file)?.slot === SUPABASE_OWNER;
+}
+
+function isSource(file) {
+  if (SECRET_FILE.test(file) || EXCLUDED_TREE.test(file) || TEST_FILE.test(file)) return false;
+  return SOURCE.test(file) || WORKFLOW.test(file) || DOCKER.test(file)
+    || file.endsWith('/package.json') || file === 'package.json'
+    || (DELIVERY.test(file) && !/\.[a-z0-9]+$/iu.test(file));
+}
+
+function sourceText(repoRoot, file) {
+  if (file === 'package.json' || file.endsWith('/package.json')) {
+    const scripts = readJson(repoRoot, file)?.scripts;
+    return scripts && typeof scripts === 'object' ? Object.values(scripts).filter((value) => typeof value === 'string').join('\n') : null;
+  }
+  return readText(repoRoot, file);
+}
+
+/** Both editions share this custody boundary; the app root scans `all` once, including its sides. */
+export function scriptHygieneFindings({ repoRoot, files = [], all = files, repo, resolver, isRoot, inScope = () => true }) {
+  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
+  const findings = [];
+  for (const file of new Set(all)) {
+    if (!inScope(file) || !isSource(file)) continue;
+    const raw = sourceText(repoRoot, file);
+    if (raw === null) continue;
+    const text = executableText(raw);
+    if (plaintextLoad(text)) findings.push(found(PLAINTEXT_LOAD, file, 'Executable source loads a plaintext secret file; use starci app secret with sealed envelopes.'));
+    if (enablesTracing(text)) findings.push(found(XTRACE, file, 'Executable source enables shell tracing or secret reveal; remove xtrace and --reveal.'));
+    if (SERVICE_ROLE_NAME.test(text.replace(/([a-z0-9])([A-Z])/gu, '$1_$2')) && !integrationOwns(file, resolver)) findings.push(found(SERVICE_ROLE, file, 'Service-role access belongs only to be/src/modules/integrations/supabase/ and its configuration.'));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/secret-custody-only.mjs

@@ -0,0 +1,65 @@
+// secret-custody-only.mjs - R277: the only custody a tracked secret may take is a sops envelope at
+// `.starcistacks/<env>/secrets/**.enc`. Everything else is refused in every edition:
+//   - a tracked plaintext secret file by being (`secrets.env`, a non-dot `*.env` with secret keys, a member of
+//     a `secrets/` directory, deploy-side dotenv) - HFS_SECRET_PLAINTEXT_FILE;
+//   - an `.enc` outside the sealed home - HFS_SECRET_OUTSIDE_ENC (lite already reports it as
+//     HFS_LITE_SECRET_CUSTODY, so the lite check keeps that one code).
+// Dotfile `.env*`, `.secrets/` and `.starcistacks/<env>/secrets/` plaintext are already refused by R06's
+// FORBIDDEN_FILES; this rule refuses the names R06's path list does not name. A finding never carries a value.
+import { secretHits, secretNameLike } from '../../lib/secret-patterns.mjs';
+import { found, readText } from './read.mjs';
+
+const PLAINTEXT_FILE = 'HFS_SECRET_PLAINTEXT_FILE';
+const OUTSIDE_ENC = 'HFS_SECRET_OUTSIDE_ENC';
+
+// `secrets.env` at any depth, plus `.secret.env`/`.secrets.env` - a dotenv file named for what it holds.
+const SECRET_ENV = /(?:^|\/)\.?secrets?\.env$/i;
+// A non-dot `<name>.env` or `<name>.env.<profile>` tracked file (deploy/prod.env, config.env.local); the
+// documented example/template suffixes are shareable forms, not custody.
+const ENV_FILE = /(?:^|\/)[^/.][^/]*\.env(?:\.(?!example|sample|template)[^/]*)?$/i;
+// A plaintext secret store: `secrets/<name>.yaml` and friends - except under `.starcistacks/<env>/secrets/`,
+// which R06 already judges, and the sealed `.enc` members, which are custody.
+const SECRETS_DIR = /(?:^|\/)secrets\/[^/]+\.(?:ya?ml|env|json|conf|cfg|ini|toml|txt|properties)$/i;
+const SEALED_DIR = /^\.starcistacks\/[^/]+\/secrets\//;
+const SEALED_HOME = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc$/;
+
+const KEY_LINE = /^\s*(?:export\s+)?([A-Za-z_$][\w$]*)\s*=/;
+const hasSecretKeys = (file, text) =>
+  text.split(/\r?\n/).some((line) => {
+    const key = KEY_LINE.exec(line);
+    return (key && secretNameLike(key[1])) || secretHits(file, line).length > 0;
+  });
+
+const sealedCustodyFindings = (file, posix, repo) => {
+  if (SEALED_HOME.test(posix) || repo.edition === 'lite') return [];
+  return [found(OUTSIDE_ENC, file,
+    `${file} is a sealed secret outside .starcistacks/<env>/secrets/; only that directory may hold committed secret envelopes`)];
+};
+
+export function secretCustodyOnlyFindings({ repoRoot, files, repo, inScope }) {
+  const findings = [];
+  for (const file of files.filter((f) => !inScope || inScope(f))) {
+    const posix = file.replaceAll('\\', '/');
+    if (file.endsWith('.enc')) {
+      findings.push(...sealedCustodyFindings(file, posix, repo));
+      continue;
+    }
+    if (SEALED_DIR.test(posix)) continue;
+    if (SECRET_ENV.test(posix)) {
+      findings.push(found(PLAINTEXT_FILE, file,
+        `${file} is a tracked plaintext secrets dotenv; seal secrets with starci app secret set into .starcistacks/<env>/secrets/<slug>.enc - never commit the plaintext`));
+      continue;
+    }
+    if (SECRETS_DIR.test(posix)) {
+      findings.push(found(PLAINTEXT_FILE, file,
+        `${file} is a tracked plaintext file inside a secrets/ directory; seal secrets with sops into .starcistacks/<env>/secrets/<slug>.enc - never commit the plaintext`));
+      continue;
+    }
+    if (!ENV_FILE.test(posix)) continue;
+    const text = readText(repoRoot, file);
+    if (text === null || !hasSecretKeys(file, text)) continue;
+    findings.push(found(PLAINTEXT_FILE, file,
+      `${file} is a tracked dotenv file holding secret keys; seal secrets with sops into .starcistacks/<env>/secrets/<slug>.enc - never commit the plaintext`));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/secrets.mjs

@@ -66,3 +66,16 @@ export function secretFindings({ repoRoot, files, resolver }) {
   }
   return findings;
 }
+
+// The age identity stays on the host: `.claude/secret.env` (SOPS_AGE_KEY) or the sops config dir's `keys.txt`,
+// both host-local files. A tracked `secret.env`, `keys.txt` or `*.agekey` is the identity committed.
+const AGE_KEY_FILE = /^\.claude\/secret\.env$|(?:^|\/)keys\.txt$|\.agekey$/i;
+export function ageKeyCustodyFindings({ files, inScope }) {
+  const findings = [];
+  for (const file of files.filter((f) => !inScope || inScope(f))) {
+    if (!AGE_KEY_FILE.test(file)) continue;
+    findings.push(found('HFS_AGE_KEY_CUSTODY', file,
+      `${file} is a tracked sops/age identity file; the age key lives only in the host-local .claude/secret.env or the sops keys.txt - never commit the identity`));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/services.mjs

@@ -21,6 +21,7 @@ import { propertyText } from '../../lib/ts-ast.mjs';
 import { folded, readEventClasses, snapshotText } from '../../lib/event-contract.mjs';
 import { found, readText } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
+import { eventTableFindings, eventTableServices } from './event-tables.mjs';
 
 const SERVICE_PLACEMENT = 'HFS_SERVICE_PLACEMENT';
 const IMAGE_UNPINNED = 'HFS_IMAGE_UNPINNED';
@@ -165,11 +166,9 @@ function undeclaredCompensationFindings(classes, declared) {
     .map((event) => found(EVENT_CONTRACT, event.file, `${event.file}: event "${event.name}" compensates "${event.compensates}", which no event class declares; name the event whose step it undoes.`, { service: event.service, event: event.name }));
 }
 
-/** Findings of R166: each service's event classes are the one source of its vendored `events.json`, and a compensating event names a declared event. */
+/** Findings of R166: event classes and literal tables match their snapshots, consumers agree, and compensation targets exist. */
 function eventContractFindings({ repoRoot, files }) {
-  const classFiles = files.filter((file) => EVENT_CLASS_FILE.test(file));
   const snapshots = files.filter((file) => SNAPSHOT.test(file));
-  if (classFiles.length === 0 && snapshots.length === 0) return [];
   const ts = typescriptFor(repoRoot);
   if (ts === null) return [];
   const tracked = new Set(files);
@@ -177,7 +176,8 @@ function eventContractFindings({ repoRoot, files }) {
   const findings = problems.map(({ service, file, problem }) => found(EVENT_CONTRACT, file, `${file} is not an event class the contract can be emitted from: ${problem}.`, { service }));
   const services = [...new Set(classes.map((event) => event.service))].sort(byCodeUnit);
   const declared = new Set(classes.map((event) => event.name));
-  findings.push(...snapshotDriftFindings(repoRoot, tracked, services, classes), ...leftBehindSnapshotFindings(snapshots, services, problems), ...undeclaredCompensationFindings(classes, declared));
+  const providers = [...services, ...eventTableServices(files)];
+  findings.push(...snapshotDriftFindings(repoRoot, tracked, services, classes), ...leftBehindSnapshotFindings(snapshots, providers, problems), ...undeclaredCompensationFindings(classes, declared), ...eventTableFindings({ ts, repoRoot, files }));
   return findings;
 }