@starci/hfs 4.2.17 → 4.4.0

package/runtime/scripts/lib/json-clone.mjs

@@ -0,0 +1,61 @@
+// json-clone.mjs — a deep copy that keeps exactly what survives a JSON text and nothing else: the plain-data
+// copy of a value, detached from every reference, frozen state and class of the original. `structuredClone` keeps
+// what JSON drops (undefined members, Dates, Maps, sparse holes) and refuses what JSON accepts (functions,
+// `toJSON` objects), so it is not a substitute; this walks the value once under the JSON.stringify rules.
+
+/** The boxed primitives JSON.stringify unwraps: recognised by the internal slot a valueOf call reads, as JSON does. */
+const BOXED = [
+  { slot: Number.prototype.valueOf, read: Number },
+  { slot: String.prototype.valueOf, read: String },
+  { slot: Boolean.prototype.valueOf, read: (box) => Boolean.prototype.valueOf.call(box) },
+  { slot: BigInt.prototype.valueOf, read: (box) => BigInt.prototype.valueOf.call(box) },
+];
+
+/** Whether `value` carries the internal slot `slot` reads (a valueOf of that boxed type does not throw on it). */
+const hasSlot = (slot, value) => {
+  try { slot.call(value); return true; } catch { return false; }
+};
+
+/** What JSON.stringify takes of `holder[key]`: the toJSON result when there is one, a boxed primitive unwrapped. */
+const serialized = (holder, key) => {
+  let value = holder[key];
+  if (value !== null && (typeof value === 'object' || typeof value === 'bigint') && typeof value.toJSON === 'function') value = value.toJSON(key);
+  if (value === null || typeof value !== 'object') return value;
+  const box = BOXED.find((candidate) => hasSlot(candidate.slot, value));
+  return box ? box.read(value) : value;
+};
+
+/** A member JSON leaves out of an object (and writes as null in an array). */
+const isAbsent = (value) => value === undefined || typeof value === 'function' || typeof value === 'symbol';
+
+const copyValue = (value, ancestors) => {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value + 0 : null;
+  if (typeof value === 'bigint') throw new TypeError('Do not know how to serialize a BigInt');
+  if (ancestors.includes(value)) throw new TypeError('Converting circular structure to JSON');
+  const inside = [...ancestors, value];
+  if (Array.isArray(value)) {
+    return Array.from({ length: value.length }, (_, index) => {
+      const item = serialized(value, String(index));
+      return isAbsent(item) ? null : copyValue(item, inside);
+    });
+  }
+  const entries = [];
+  for (const name of Object.keys(value)) {
+    const member = serialized(value, name);
+    if (!isAbsent(member)) entries.push([name, copyValue(member, inside)]);
+  }
+  return Object.fromEntries(entries);
+};
+
+/**
+ * `value` copied as JSON data: members that are undefined, functions or symbols are dropped (an array item becomes
+ * null), non-finite numbers become null and -0 becomes 0, `toJSON` results replace their objects (a Date becomes its ISO string), boxed
+ * primitives unwrap, and a cycle or a BigInt throws a TypeError. A value JSON has no text for (undefined, a function,
+ * a symbol) throws a SyntaxError, as parsing the missing text does.
+ */
+export function jsonClone(value) {
+  const top = serialized({ '': value }, '');
+  if (isAbsent(top)) throw new SyntaxError('"undefined" is not valid JSON');
+  return copyValue(top, []);
+}

package/runtime/scripts/lib/list.mjs

@@ -17,6 +17,10 @@ export const objectList = (v) => (Array.isArray(v) ? v : []).filter((item) => it
 export const stringList = (v, { blank = true } = {}) =>
   Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0 && (blank || s.trim().length > 0));
 
+/** A non-empty list of distinct values, all accepted by the supplied predicate. */
+export const nonemptyUniqueList = (values, accepts) => Array.isArray(values) && values.length > 0
+  && values.every((entry) => accepts(entry)) && new Set(values).size === values.length;
+
 /** The items of a `sep`-separated list: trimmed, empties dropped; `dedupe` keeps first occurrences only. */
 export const splitList = (v, { sep = ',', dedupe = false } = {}) => {
   const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);

package/runtime/scripts/lib/roots.mjs

@@ -0,0 +1,59 @@
+// roots.mjs - the one place that names a root of the runtime and says which tree wins when two hold the same record.
+//
+// A component that needs "which directory" asks here, so no component resolves it by itself (the wrong-tree reads of 2026-10-08/09:
+// a brand record read from the product's main checkout, a capture tool looked up only in product dirs, generated files written
+// through a home record, a Kernel start gated by another tree's build). The roots, each with its one resolver:
+//   runtime tree       runtimeTree        the checkout this code runs from (derived from the module location, never from a record)
+//   runtime state      runtimeState       <runtime tree>/.runtime, or STARCI_LOCAL_ROOT
+//   temp root          tempRoot           STARCI_TEMP_ROOT, the owner config, else the OS directory
+//   invocation dir     invocationDir      where the command was started; only ever a default for a flag the caller may override
+//   work dir           workDirName        the name of the Work records directory inside a product tree
+//   product trees      treesInOrder       the workflow tree first, then the product's main checkout
+//   Work records       workRecordPath     the first tree that holds the record, else the main checkout's path
+//   tool lookups       toolSearchDirs     the tree the work happens in first, the runtime's own install last
+// The workflow tree itself, a job's placement and the Critic directory are registry facts: scripts/machine/workflow-tree.mjs,
+// placement-rebound.mjs and the worktree registry resolve them, and a caller hands the result in as `tree`.
+// The `root-adhoc` self-check (scripts/checks/check-root-adhoc.mjs, rule R240) refuses a new path built from the process working
+// directory or from the Work directory name outside this module.
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot, runtimeStateDir, starciLocalRoot, starciSourceRoot } from '../../engine/runtime-root.mjs';
+import { tempRoot } from '../../engine/temp-root.mjs';
+
+export { tempRoot, starciLocalRoot, starciSourceRoot };
+
+/** The runtime tree this code runs from. */
+export const runtimeTree = skillRoot;
+
+/** The state directory of a runtime tree (default: this one). */
+export const runtimeState = (tree = runtimeTree) => runtimeStateDir(tree);
+
+/** The name of the Work records directory inside a product tree. */
+export const WORK_DIR_NAME = '.starciwork';
+
+/** The directory a command was started in: `io.cwd` when the caller injects one, else the process working directory. A default for flags only. */
+export const invocationDir = (io = undefined) => path.resolve(io?.cwd ?? process.cwd());
+
+/** The distinct, resolved trees that may hold a product's records, in precedence order: the workflow tree, then the main checkout. */
+export const treesInOrder = ({ tree = null, repo = null } = {}) => [...new Set([tree, repo].filter(Boolean).map((dir) => path.resolve(dir)))];
+
+/** The Work directories of those trees, in the same order. */
+export const workDirsInOrder = ({ tree = null, repo = null, workDirName = WORK_DIR_NAME } = {}) => treesInOrder({ tree, repo }).map((dir) => path.join(dir, workDirName));
+
+/**
+ * The first Work directory (workflow tree first, then the main checkout) that `holds` accepts, else the main checkout's own (the
+ * path a refusal names), else the tree's when there is no main checkout.
+ */
+export function workDirHolding(holds, { tree = null, repo = null, workDirName = WORK_DIR_NAME } = {}) {
+  const dirs = workDirsInOrder({ tree, repo, workDirName });
+  return dirs.find((dir) => holds(dir)) ?? (repo ? path.join(path.resolve(repo), workDirName) : (dirs[0] ?? null));
+}
+
+/** The file of a Work record (`rel` under the Work directory) from the first tree that has it, else the main checkout's path. */
+export function workRecordPath(rel, { tree = null, repo = null, workDirName = WORK_DIR_NAME, exists = fs.existsSync } = {}) {
+  const parts = String(rel).split('/');
+  return path.join(workDirHolding((dir) => exists(path.join(dir, ...parts)), { tree, repo, workDirName }) ?? '', ...parts);
+}
+
+/** The directories a tool is looked up from: the caller's (the tree the work happens in, then the project) first, the runtime's own install last. */
+export const toolSearchDirs = (dirs, runtime = runtimeTree) => [...dirs.filter(Boolean), runtime].filter(Boolean);

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

@@ -0,0 +1,13 @@
+// Identify runtime-owned example apps; an unrelated directory named examples grants no fixture behavior.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function isRuntimeExampleApp(repoRoot) {
+  if (path.basename(path.dirname(repoRoot)) !== 'examples') return false;
+  try {
+    const runtime = JSON.parse(fs.readFileSync(path.resolve(repoRoot, '..', '..', 'hfs.json'), 'utf8'));
+    return runtime.kind === 'runtime';
+  } catch {
+    return false;
+  }
+}

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

@@ -12,6 +12,57 @@ export const FORBIDDEN_FILES = [
   { name: 'starcistacks-secret-plaintext', test: (f) => /(^|\/)\.starcistacks\/[^/]+\/secrets\//i.test(f) && !/(\.enc|\/\.gitkeep|\/KEYS\.md)$/i.test(f) },
   { name: 'credentials-json', test: (f) => /(^|\/)(credentials|service-account|client_secret)[^/]*\.json$/i.test(f) },
 ];
+// `word` in any case (name checks are case-aware by construction, not by flag).
+const fold = (word) => word.replace(/[a-z]/gi, (c) => `[${c.toLowerCase()}${c.toUpperCase()}]`);
+
+// A name that holds secret material: the keyword is an identifier segment, so DB_PASSWORD, dbPassword,
+// OPENAI_API_KEY, api_secret and accessToken are candidates while `secondary`, `tokenize`, `monkey`, `secrets.x`
+// and `$secret` are not. A segment starts at the name edge, after `_`/`-`/`.`, or at a camel hump.
+const SECRET_WORD = [
+  'password', 'passwd', 'passphrase', 'secret', 'credentials?', 'token',
+  'api[_-]?key', 'access[_-]?token', 'auth[_-]?token', 'refresh[_-]?token', 'id[_-]?token', 'session[_-]?token',
+  'client[_-]?secret', 'api[_-]?secret', 'session[_-]?secret', 'jwt[_-]?secret',
+  'private[_-]?key', 'secret[_-]?key', 'signing[_-]?key', 'encryption[_-]?key', 'master[_-]?key',
+  'service[_-]?role[_-]?key', 'service[_-]?key', 'session[_-]?key',
+].map((word) => fold(word)).join('|');
+
+// A name whose last segment is configuration, not material: SECRET_FILE and *_PATH point at the materialized
+// secret file (the materializer's own form), PASSWORD_MIN_LENGTH is a number, *_REF/_ID a reference.
+const BENIGN_WORD = [
+  'file', 'path', 'dir', 'url', 'uri', 'endpoint', 'host', 'refs?', 'names?', 'ids?', 'arn', 'urn',
+  'length', 'min', 'max', 'size', 'count', 'budget', 'limit', 'regex', 'pattern', 'policy',
+  'algorithm', 'scheme', 'expiry', 'expires', 'ttl', 'required', 'enabled', 'disabled', 'type', 'version',
+].map((word) => fold(word)).join('|');
+
+const SEGMENT_BEFORE = String.raw`(?:(?<![A-Za-z0-9_$])|(?<=[_\-.])|(?<=[a-z])(?=[A-Z]))`;
+const NAME_REST = '[A-Za-z0-9_$.-]*?';
+const SECRET_NAME = [
+  '(?<![A-Za-z0-9_$])',
+  String.raw`(?!${NAME_REST}${SEGMENT_BEFORE}(?:${BENIGN_WORD})(?=\s*[:=]))`,
+  String.raw`(?=${NAME_REST}${SEGMENT_BEFORE}(?:${SECRET_WORD})(?=[_\-.]|[A-Z]|[^A-Za-z0-9_$]|$))`,
+  String.raw`[A-Za-z_$][A-Za-z0-9_$.-]*\s*[:=]\s*`,
+].join('');
+
+// `password = "hunter2hunter2"` — the quoted literal. `env(NAME)` is a reference, never a secret.
+const ASSIGNED_QUOTED = new RegExp(
+  SECRET_NAME + String.raw`['"\`](?!env\([A-Z_][A-Z0-9_]*\)['"\`])([^'"\`\n\s$<{]{12,})['"\`]`,
+);
+// `DB_PASSWORD=hunter2hunter2` — the compose list-item and dotenv form; the dotenv value has no `:` so
+// `password: secret:db/password` and `token: ref:vault/api` stay references, and the end boundary keeps
+// calls and member/index references such as `secret = credentialsSource.current` out of the literals.
+const ASSIGNED_UNQUOTED = new RegExp(
+  SECRET_NAME + String.raw`(?!['"\`]|env\()([A-Za-z0-9_+=-]{12,})(?![A-Za-z0-9_+=.(\[-])`,
+);
+
+const NAME_WORD = (word, tail) => new RegExp(`^${NAME_REST}${SEGMENT_BEFORE}(?:${word})${tail}`);
+const SECRET_NAME_TEST = NAME_WORD(SECRET_WORD, String.raw`(?:[_\-.]|[A-Z]|[^A-Za-z0-9_$]|$)`);
+const BENIGN_TAIL_TEST = NAME_WORD(BENIGN_WORD, '$');
+
+/** True when a bare variable `name` holds secret material as an identifier segment (DB_PASSWORD, dbPassword,
+ *  SUPABASE_SERVICE_ROLE_KEY) and does not end in a config suffix (PASSWORD_MIN_LENGTH, SECRET_FILE,
+ *  tokenBudget). The same name judgement the `assigned-secret` patterns make, for callers that read keys. */
+export const secretNameLike = (name) => SECRET_NAME_TEST.test(name) && !BENIGN_TAIL_TEST.test(name);
+
 export const SECRET_PATTERNS = [
   { name: 'private-key-block', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
   { name: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/ },
@@ -23,17 +74,20 @@ export const SECRET_PATTERNS = [
   { name: 'telegram-bot-token', re: /\b\d{8,10}:AA[0-9A-Za-z_-]{33}\b/ },
   { name: 'stripe-secret', re: /\b(?:sk|rk)_live_[0-9A-Za-z]{20,}\b/ },
   { name: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+  { name: 'age-secret-key', re: /\bAGE-SECRET-KEY-1[0-9A-Z]{20,}\b/ },
+  { name: 'password-connection-string', re: /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis):\/\/[^:\s/@]+:[^@\s/${}]{8,}@/iu },
   // A value written `env(NAME)` (the Supabase config.toml reference form) names a variable, not a secret.
   // A keyword-assigned value that names itself a stand-in (a test stub's `accessToken: "fixture-..."`) is no
   // candidate; only this heuristic takes the exemption, never a provider-shaped token above.
   // A spec file's keyword-assigned values are test inputs (a spec's sign-in
   // form password and a mocked accessToken once refused a push): the heuristic skips spec files too.
-  { name: 'assigned-secret', re: new RegExp([
-    String.raw`\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|client[_-]?secret)`,
-    String.raw`\b\s*[:=]\s*['"](?!env\([A-Z_][A-Z0-9_]*\)['"])([^'"\s$<{]{12,})`,
-    `['"]`,
-  ].join(''), 'i'), placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+  // A SCREAMING_SNAKE quoted value in source is a public code (an enum member whose value is an upper-case code), not a credential.
+  { name: 'assigned-secret', re: ASSIGNED_QUOTED, sourceCode: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
     skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$/ },
+  // An unquoted value in TypeScript or JavaScript source is an identifier or a type (`token: InjectionToken`,
+  // `MODULE_OPTIONS_TOKEN: DATABASE_OPTIONS_TOKEN`), never a literal; the unquoted form is the dotenv, compose and toml shape.
+  { name: 'assigned-secret', re: ASSIGNED_UNQUOTED, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+    skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$|\.[cm]?[jt]sx?$/ },
 ];
 
 
@@ -43,6 +97,7 @@ export function secretHits(file, text) {
   for (const rule of SECRET_PATTERNS) {
     if (rule.skipFile?.test(file ?? '')) continue;
     const hit = rule.re.exec(text);
+    if (hit && rule.sourceCode?.test(hit[1] ?? '') && /\.[cm]?[jt]sx?$/.test(file ?? '')) continue;
     if (hit && !rule.placeholder?.test(hit[1] ?? '')) names.push(rule.name);
   }
   return names;

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

@@ -0,0 +1,32 @@
+// PostgreSQL AST primitives shared by database verbs and synchronous content rules.
+
+/** String identifier components from libpg-query's wrapped String nodes. */
+export const sqlStringParts = (nodes) => (nodes ?? []).map((node) => node?.String?.sval).filter((value) => value !== undefined);
+
+/** Traverse SQL/PLpgSQL objects; executable scans leave function declarations inert. */
+export function walkSqlAst(value, visit, executable = false) {
+  if (!value || typeof value !== 'object' || (executable && value.CreateFunctionStmt)) return;
+  visit(value);
+  for (const child of Object.values(value)) walkSqlAst(child, visit, executable);
+}
+
+/** Build a synchronous parser with the caller's failure policy and initialized parser. */
+export function sqlParser(parser, reject = () => null) {
+  return (text) => {
+    try { return parser?.parseSync(text) ?? null; }
+    catch (error) { return reject(error); }
+  };
+}
+
+/** Resolve named arguments before positional arguments, as PostgreSQL does. */
+export function sqlCallArgument(call, position, names = []) {
+  const args = call.args ?? [];
+  return args.find((item) => names.includes(item?.NamedArgExpr?.name))?.NamedArgExpr?.arg
+    ?? args.filter((item) => !item.NamedArgExpr)[position];
+}
+
+/** Read a literal string through static casts without evaluating an expression. */
+export function sqlStringLiteral(node) {
+  if (node?.TypeCast) return sqlStringLiteral(node.TypeCast.arg);
+  return node?.A_Const?.sval?.sval ?? null;
+}

package/runtime/scripts/lib/stack-services.mjs

@@ -58,7 +58,7 @@ const KNOWN_IMAGES = Object.freeze({
 export const STATEFUL_KINDS = Object.freeze(new Set(['database', 'cache', 'identity', 'storage', 'mail', 'queue', 'search']));
 
 /** The repository name of an image reference: `quay.io/keycloak/keycloak:26.0` -> `keycloak`. */
-const repositoryOf = image => {
+export const repositoryOf = image => {
   const withoutDigest = image.split('@')[0];
   const lastSegment = withoutDigest.split('/').at(-1) ?? withoutDigest;
   return lastSegment.split(':')[0];

package/runtime/scripts/lib/swarm-stack.mjs

@@ -0,0 +1,126 @@
+// Shared static Swarm contract for app checks and rendered deployment evidence.
+import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+import { composeEntries } from './compose-values.mjs';
+import { repositoryOf } from './stack-services.mjs';
+
+const PINNED_IMAGE = /@sha256:[a-f0-9]{64}$/i;
+const VERSIONED_SECRET = /-v[1-9][0-9]*$/;
+const BACKING_IMAGE = /^(?:postgres(?:ql)?|postgresql-repmgr|redis(?:-stack(?:-server)?)?|(?:cp-)?kafka(?:-native)?|keycloak|minio|rabbitmq|mysql(?:-server)?|mongo(?:db)?|mongodb-community-server)$/i;
+const mapping = value => plain(value) ? value : {};
+const present = value => typeof value === 'string' && Boolean(value.trim());
+const configured = value => Object.keys(mapping(value)).length > 0;
+const schedulerImage = image => present(image) && /(?:^|\/)swarm-cronjob(?:[:@]|$)/.test(image);
+
+/** Compose includes may be a path or an object whose path is a string or a list of source paths. */
+export function composeIncludePaths(doc) {
+  const paths = [], errors = [];
+  if (doc.include === undefined) return { paths, errors };
+  if (!Array.isArray(doc.include)) return { paths, errors: ['Compose include must be an array of source paths'] };
+  for (const entry of doc.include) {
+    let values = [entry];
+    if (plain(entry)) values = Array.isArray(entry.path) ? entry.path : [entry.path];
+    if (!values.length || values.some(value => !present(value))) errors.push('Compose include must declare nonempty string source paths');
+    else paths.push(...values);
+  }
+  return { paths, errors };
+}
+
+function runnableHealthcheck(value) {
+  if (present(value)) return value !== 'NONE';
+  if (!Array.isArray(value) || !['CMD', 'CMD-SHELL'].includes(value[0])) return false;
+  return value.slice(1).some(present);
+}
+
+function jobDeclarationIssues(id, component, components, add) {
+  if (component.mode !== 'replicated-job') return;
+  const scheduler = components[component.scheduler];
+  if (!present(component.scheduler) || !plain(scheduler) || scheduler.role !== 'scheduler' || scheduler.mode === 'replicated-job')
+    add(`components.${id}.scheduler`, 'replicated-job must name a declared service component with role scheduler');
+  else if (!schedulerImage(scheduler.image)) add(`components.${id}.scheduler`, 'replicated-job scheduler must declare the swarm-cronjob image');
+  if (!present(component.schedule)) add(`components.${id}.schedule`, 'replicated-job must declare its cron schedule');
+}
+
+/** Inventory rules are independent of a selected environment or rendered deployment model. */
+export function swarmInventoryIssues({ components, lite = false }) {
+  const errors = [], catalog = mapping(components);
+  const add = (at, message) => errors.push({ at, message });
+  for (const [id, entry] of Object.entries(catalog)) {
+    const component = mapping(entry);
+    if (lite && present(component.image) && BACKING_IMAGE.test(repositoryOf(component.image)))
+      add(`components.${id}.image`, 'lite must use managed Supabase backing services; this image duplicates a Supabase-provided service');
+    jobDeclarationIssues(id, component, catalog, add);
+  }
+  return errors;
+}
+
+function serviceSafetyIssues(id, service, add) {
+  const at = `services.${id}`, deploy = mapping(service.deploy), healthcheck = mapping(service.healthcheck);
+  if (!present(service.image)) add(`${at}.image`, 'managed Swarm service needs a nonempty rendered image');
+  else if (!PINNED_IMAGE.test(service.image)) add(`${at}.image`, 'Swarm image must be pinned by a sha256 digest');
+  if (service.build !== undefined) add(`${at}.build`, 'rendered Swarm model must not retain a build section');
+  if (!runnableHealthcheck(healthcheck.test) || healthcheck.disable === true)
+    add(`${at}.healthcheck`, 'every Swarm service needs an enabled healthcheck with a test');
+  const update = mapping(deploy.update_config);
+  if (!['start-first', 'stop-first'].includes(update.order) || update.failure_action !== 'rollback' || !update.monitor)
+    add(`${at}.deploy.update_config`, 'Swarm update_config must declare order, failure_action: rollback and monitor');
+  if (!configured(deploy.rollback_config)) add(`${at}.deploy.rollback_config`, 'every Swarm service needs deploy.rollback_config');
+  if (!['none', 'any', 'on-failure'].includes(deploy.restart_policy?.condition))
+    add(`${at}.deploy.restart_policy`, 'every Swarm service needs deploy.restart_policy with a condition');
+}
+
+function jobServiceIssues(id, service, component, services, bindings, add) {
+  const deploy = mapping(service.deploy), at = `services.${id}.deploy`;
+  if (component.mode !== 'replicated-job') {
+    if (deploy.mode === 'replicated-job') add(`${at}.mode`, 'replicated-job deployment must be declared as mode: replicated-job in the component inventory');
+    return;
+  }
+  if (deploy.mode !== 'replicated-job') add(`${at}.mode`, 'replicated-job component must use deploy.mode: replicated-job');
+  if (deploy.replicas !== 0) add(`${at}.replicas`, 'scheduled replicated-job must keep deploy.replicas: 0 until its scheduler triggers it');
+  if (deploy.restart_policy?.condition !== 'none') add(`${at}.restart_policy.condition`, 'scheduled replicated-job must use restart_policy.condition: none');
+  const labels = Object.fromEntries(composeEntries(deploy.labels));
+  if (String(labels['swarm.cronjob.enable']) !== 'true') add(`${at}.labels`, 'scheduled replicated-job needs swarm.cronjob.enable: "true"');
+  if (!present(component.schedule) || labels['swarm.cronjob.schedule'] !== component.schedule)
+    add(`${at}.labels`, 'swarm.cronjob.schedule must match the component cron schedule');
+  if (!services[component.scheduler] || !Object.hasOwn(bindings, component.scheduler))
+    add(`components.${id}.scheduler`, 'the declared scheduler must be bound and deployed in this environment');
+  else if (!schedulerImage(services[component.scheduler].image))
+    add(`components.${id}.scheduler`, 'the deployed scheduler must run the declared swarm-cronjob image');
+}
+
+function secretIssues(model, services, add) {
+  const secrets = mapping(model.secrets);
+  for (const [id, entry] of Object.entries(secrets)) {
+    const secret = mapping(entry);
+    if (secret.external !== true || !present(secret.name) || !VERSIONED_SECRET.test(secret.name) || secret.file !== undefined || secret.environment !== undefined || secret.content !== undefined)
+      add(`secrets.${id}`, 'Swarm secrets must be external: true with a versioned name <logical>-v<N> and no embedded value source');
+  }
+  for (const [id, service] of Object.entries(services)) {
+    for (const entry of Array.isArray(service?.secrets) ? service.secrets : []) {
+      const source = plain(entry) ? entry.source : entry;
+      if (!Object.hasOwn(secrets, source)) add(`services.${id}.secrets`, 'Swarm service secret must reference a declared external versioned secret');
+    }
+  }
+}
+
+/** Validate the same deployment model in HFS and the deployment evidence gate. */
+export function swarmModelIssues({ model, components, bindings, lite = false }) {
+  const errors = [], services = mapping(model?.services), catalog = mapping(components), bound = mapping(bindings);
+  const add = (at, message) => errors.push({ at, message });
+  for (const [id, entry] of Object.entries(services)) {
+    const service = mapping(entry), component = mapping(catalog[id]);
+    serviceSafetyIssues(id, service, add);
+    if (!Object.hasOwn(catalog, id)) add(`services.${id}`, 'Swarm service name must be a declared component id');
+    if (service.ports !== undefined && !Array.isArray(service.ports))
+      add(`services.${id}.ports`, 'Swarm ports must be an array of published port definitions');
+    else if (service.ports?.length && component.role !== 'ingress')
+      add(`services.${id}.ports`, 'only a component with role ingress may publish Swarm ports');
+    if (lite && present(service.image) && BACKING_IMAGE.test(repositoryOf(service.image)))
+      add(`services.${id}.image`, 'lite stack must not run an image that duplicates a Supabase-provided backing service');
+    jobServiceIssues(id, service, component, services, bound, add);
+  }
+  for (const id of Object.keys(bound)) {
+    if (!Object.hasOwn(services, id)) add(`services.${id}`, 'environment component binding has no deployed Swarm service');
+  }
+  secretIssues(mapping(model), services, add);
+  return errors;
+}

package/runtime/scripts/lib/trim-end.mjs

@@ -0,0 +1,8 @@
+// trim-end.mjs — a string without the run of characters at its end that `matches` accepts.
+
+/** `value` with its trailing characters removed while `matches(char)` holds. */
+export const trimEndWhile = (value, matches) => {
+  let end = value.length;
+  while (end > 0 && matches(value[end - 1])) end -= 1;
+  return value.slice(0, end);
+};

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

@@ -0,0 +1,23 @@
+/** The expression under the wrappers selected by an AST check's contract. */
+export function unwrapExpression(ts, expression, { awaitExpressions = false, typeAssertions = true, nonNullExpressions = true, satisfiesExpressions = true } = {}) {
+  while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
+    || (typeAssertions && ts.isTypeAssertionExpression(expression)) || (nonNullExpressions && ts.isNonNullExpression(expression))
+    || (satisfiesExpressions && (ts.isSatisfiesExpression?.(expression) ?? false))
+    || (awaitExpressions && ts.isAwaitExpression(expression)))) expression = expression.expression;
+  return expression;
+}
+
+/** Local name -> imported name and module; callers select their existing module key and literal policy. */
+export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiteralsOnly = false } = {}) {
+  const imports = new Map();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || (stringLiteralsOnly && !ts.isStringLiteralLike(statement.moduleSpecifier))) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const binding of bindings.elements) imports.set(binding.name.text, { name: (binding.propertyName ?? binding.name).text, [moduleKey]: statement.moduleSpecifier.text });
+  }
+  return imports;
+}
+
+/** Catalog values unwrap parentheses, `as`, and `satisfies`, preserving assertions and non-null nodes. */
+export const unwrapCatalogExpression = (ts, node) => unwrapExpression(ts, node, { typeAssertions: false, nonNullExpressions: false });

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

@@ -11,8 +11,18 @@ export const hasAnyFlag = (flags, mask) => ((flags ?? 0) & mask) !== 0;
 /** Whether the variable `declaration` belongs to a `const` list: the TypeScript node-flag test, an explicit comparison of the masked flags. */
 export const isConstVariable = (ts, declaration) => (ts.getCombinedNodeFlags(declaration.parent) & ts.NodeFlags.Const) !== 0;
 
-/** The text of an identifier or a string-literal-like `node`, or null (property names, literal specifiers). */
-export const nameText = (ts, node) => (node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : null);
+/** Text of a string-literal-like node or an enabled identifier/numeric name; null for other expressions. */
+export function nameText(ts, node, { identifiers = true, numbers = false } = {}) {
+  if (!node) return null;
+  if (ts.isStringLiteralLike(node) || (identifiers && ts.isIdentifier(node)) || (numbers && ts.isNumericLiteral(node))) return node.text;
+  return null;
+}
+
+/** A statically selected property name, including string-literal element access; null for computed selections. */
+export function accessName(ts, node) {
+  if (ts.isPropertyAccessExpression(node)) return node.name.text;
+  return ts.isElementAccessExpression(node) ? literalText(ts, node.argumentExpression) : null;
+}
 
 /** The text of a string-literal-like `node` (a string literal or a no-substitution template), or null. */
 export const literalText = (ts, node) => (node && ts.isStringLiteralLike(node) ? node.text : null);
@@ -42,3 +52,18 @@ export function propertyText(ts, text, { file = 'source.ts', key, declaration =
   visit(source);
   return value;
 }
+
+/** Initializers of every identifier-named variable, grouped in traversal order across the source's scopes. */
+export function variableInitializerGroups(ts, source) {
+  const groups = new Map();
+  const collect = (node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      const initializers = groups.get(node.name.text) ?? [];
+      initializers.push(node.initializer);
+      groups.set(node.name.text, initializers);
+    }
+    ts.forEachChild(node, collect);
+  };
+  collect(source);
+  return groups;
+}

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

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