@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/lib/starciwork-boundary.mjs

@@ -7,11 +7,8 @@
 // Paths are relative to the .starciwork root, '/'-separated.
 import fs from 'node:fs';
 import path from 'node:path';
-
 // The one source of the .starciwork/.gitignore text: the app root template `starci app sync` renders (packages/hfs/templates).
 const TEMPLATE = path.join(import.meta.dirname, '..', '..', 'packages', 'hfs', 'templates', 'app', 'starciwork.gitignore');
-const LITE_TEMPLATE = path.join(path.dirname(TEMPLATE), 'starciwork.gitignore-lite');
-
 // The record families that hold nothing but index.yaml and evidence.yaml (ui, impl, uat and ac have their own rows).
 const PLAIN_FAMILIES = Object.freeze(['br', 'fr', 'nfr', 'data', 'journey', 'decision', 'sds', 'contract', 'integration', 'gap', 'event']);
 const RECORD_FILE = /^(index|evidence)\.yaml$/;
@@ -24,76 +21,71 @@ const REST = '**';
 // folder (DENY_SEGMENT), so a capture or run can never pass as a record.
 const NEST = '+';
 const NEST_SEGMENT = /^(?!assets$).+$/;
-
-// Each pattern is a list of segment matchers: a string (exact), a RegExp (one segment), '+' (one or more record-name
-// folders) or '**' (one or more segments of anything). Order follows §5.1.
 const PRODUCT_PATTERNS = Object.freeze([
-  ['.gitignore'], ['.gitattributes'], ['workspace.yaml'], ['index.yaml'],
-  ['brand', RECORD_FILE], ['brand', 'assets', REST],
-  ['shell', RECORD_FILE],
-  ['_resources', /^(environments|identities|fixtures|runtimes)$/, ANY, REST],
-  ['_resources', 'grammar-captures', REST],
-  ['_derived', /^(index\.yaml|frontier\.md|critique\.yaml|critique\.md)$/],
-  ['features', 'index.yaml'],
-  ['features', ANY, 'index.yaml'],
-  ['features', ANY, /^(br|ac|fr|nfr|data|journey|decision|sds|ui|impl|uat|contract|integration|gap|event)$/, 'index.yaml'],
-  ['features', ANY, PLAIN, NEST, RECORD_FILE],
-  ['features', ANY, 'br', NEST, 'ac', NEST, RECORD_FILE],
-  ['features', ANY, 'ui', NEST, RECORD_FILE],
-  ['features', ANY, 'ui', NEST, /^(flow|lifecycle-interface)\.yaml$/],
-  ['features', ANY, 'ui', NEST, 'assets', REST],
-  ['features', ANY, 'impl', ANY, 'index.yaml'],
-  ['features', ANY, 'impl', ANY, NEST, RECORD_FILE],
-  ['features', ANY, 'uat', NEST, UAT_FILE],
-].map(Object.freeze));
-
+    ['.gitignore'], ['.gitattributes'], ['workspace.yaml'], ['index.yaml'],
+    ['brand', RECORD_FILE], ['brand', 'assets', REST],
+    ['shell', RECORD_FILE],
+    ['_resources', /^(environments|identities|fixtures|runtimes)$/, ANY, REST],
+    ['_resources', 'grammar-captures', REST],
+    ['_derived', /^(index\.yaml|frontier\.md|critique\.yaml|critique\.md)$/],
+    ['features', 'index.yaml'],
+    ['features', ANY, 'index.yaml'],
+    ['features', ANY, /^(br|ac|fr|nfr|data|journey|decision|sds|ui|impl|uat|contract|integration|gap|event)$/, 'index.yaml'],
+    ['features', ANY, PLAIN, NEST, RECORD_FILE],
+    ['features', ANY, 'br', NEST, 'ac', NEST, RECORD_FILE],
+    ['features', ANY, 'ui', NEST, RECORD_FILE],
+    ['features', ANY, 'ui', NEST, /^(flow|lifecycle-interface)\.yaml$/],
+    ['features', ANY, 'ui', NEST, 'assets', REST],
+    ['features', ANY, 'impl', ANY, 'index.yaml'],
+    ['features', ANY, 'impl', ANY, NEST, RECORD_FILE],
+    ['features', ANY, 'uat', NEST, UAT_FILE],
+].map((pattern) => Object.freeze(pattern)));
 // Agent output that is refused even where a pattern above would admit it: draw rounds inside a ui record's
 // assets, stray report copies, evidence bundles, evidence/ captures and UAT runs anywhere, temp JSON.
 const DENY_SEGMENT = /^(draw-loop|evidence|runs|kernel-evidence|kernel-strays|kernel-approvals)$/;
 const DENY_FILE = /^(report.*\.json|.*\.tmp\.json)$/;
-
 const segs = (rel) => String(rel ?? '').replaceAll('\\', '/').split('/').filter((s) => s && s !== '.');
 const fits = (matcher, seg) => (typeof matcher === 'string' ? matcher === seg : matcher.test(seg));
-
 function denied(parts, { dir = false } = {}) {
-  // The last segment of a file path is a file name: `evidence.yaml` is a record file, never an evidence/ bundle.
-  const dirs = dir ? parts : parts.slice(0, -1);
-  if (dirs.some((s) => DENY_SEGMENT.test(s))) return true;
-  return !dir && parts.length > 0 && DENY_FILE.test(parts.at(-1));
+    // The last segment of a file path is a file name: `evidence.yaml` is a record file, never an evidence/ bundle.
+    const dirs = dir ? parts : parts.slice(0, -1);
+    if (dirs.some((s) => DENY_SEGMENT.test(s)))
+        return true;
+    return !dir && parts.length > 0 && DENY_FILE.test(parts.at(-1));
 }
-
 // Match parts[i..] against pattern[p..]. `prefix`: parts is a directory, true when some file under it could match.
 function walk(pattern, p, parts, i, prefix) {
-  if (i === parts.length) return prefix ? p < pattern.length : p === pattern.length;
-  if (p === pattern.length) return false;
-  const m = pattern[p];
-  if (m === REST) return prefix || parts.length > i;
-  if (m === NEST) {
-    if (!NEST_SEGMENT.test(parts[i])) return false;
-    // consume this folder, then either stop nesting or keep nesting
-    return walk(pattern, p + 1, parts, i + 1, prefix) || walk(pattern, p, parts, i + 1, prefix);
-  }
-  return fits(m, parts[i]) && walk(pattern, p + 1, parts, i + 1, prefix);
+    if (i === parts.length)
+        return prefix ? p < pattern.length : p === pattern.length;
+    if (p === pattern.length)
+        return false;
+    const m = pattern[p];
+    if (m === REST)
+        return prefix || parts.length > i;
+    if (m === NEST) {
+        if (!NEST_SEGMENT.test(parts[i]))
+            return false;
+        // consume this folder, then either stop nesting or keep nesting
+        return walk(pattern, p + 1, parts, i + 1, prefix) || walk(pattern, p, parts, i + 1, prefix);
+    }
+    return fits(m, parts[i]) && walk(pattern, p + 1, parts, i + 1, prefix);
 }
 const matchFile = (pattern, parts) => walk(pattern, 0, parts, 0, false);
-
 /** True when the FILE at `rel` (relative to .starciwork) is product content §5.1 admits. */
 export function isProductPath(rel) {
-  const parts = segs(rel);
-  if (!parts.length || denied(parts)) return false;
-  return PRODUCT_PATTERNS.some((p) => matchFile(p, parts));
+    const parts = segs(rel);
+    if (!parts.length || denied(parts))
+        return false;
+    return PRODUCT_PATTERNS.some((p) => matchFile(p, parts));
 }
-
 /** The lite app boundary: its optional Work tree holds .gitignore, workspace.yaml and brand/** only. */
 export function isLiteProductPath(rel, { dir = false } = {}) {
-  const parts = segs(rel);
-  return (!dir && parts.length === 1 && ['.gitignore', 'workspace.yaml'].includes(parts[0]))
-    || (parts[0] === 'brand' && (parts.length > 1 || dir));
+    const parts = segs(rel);
+    return (!dir && parts.length === 1 && ['.gitignore', 'workspace.yaml'].includes(parts[0]))
+        || (parts[0] === 'brand' && (parts.length > 1 || dir));
 }
-
 const ROOT_CACHE_DIRS = new Set(['settle-parity', 'settle-tail', 'runtime', 'canon-seams']);
 const ROOT_CACHE_FILE = /^(.*\.tmp\.json|tmp-.*\.json|scan-i18n.*\.json|runtime-budget\.json|ledger-anchor\.json|supervisor-precheck\.mjs)$/;
-
 /**
  * The §5.2 category of a KNOWN agent-data path, or null when the path is not one. Known agent data — the
  * categories scripts/work/validate/check-example-work.mjs refuses in a .starciwork tree [HFS_AGENT_DATA_TRACKED]:
@@ -103,37 +95,50 @@ const ROOT_CACHE_FILE = /^(.*\.tmp\.json|tmp-.*\.json|scan-i18n.*\.json|runtime-
  * (isProductPath) is drift: product records in a retired layout, kept and reported, never removed by a script.
  */
 const rootAgentDataCategory = (parts, dir, top) => {
-  if (parts.length === 1 && !dir && top.startsWith('runtime.sqlite')) return 'ledger';
-  if (parts.length === 1 && !dir && top.startsWith('logs.sqlite')) return 'logs-db';
-  if (top === 'worktrees') return 'worktrees';
-  if (top === 'kernel-evidence') return 'kernel-evidence';
-  if (top === 'kernel-strays' || top === 'kernel-approvals') return 'kernel-strays';
-  if (ROOT_CACHE_DIRS.has(top) && (dir || parts.length > 1)) return 'cache';
-  if (parts.length === 1 && !dir && ROOT_CACHE_FILE.test(top)) return 'cache';
-  return null;
+    if (parts.length === 1 && !dir && top.startsWith('runtime.sqlite'))
+        return 'ledger';
+    if (parts.length === 1 && !dir && top.startsWith('logs.sqlite'))
+        return 'logs-db';
+    if (top === 'worktrees')
+        return 'worktrees';
+    if (top === 'kernel-evidence')
+        return 'kernel-evidence';
+    if (top === 'kernel-strays' || top === 'kernel-approvals')
+        return 'kernel-strays';
+    if (ROOT_CACHE_DIRS.has(top) && (dir || parts.length > 1))
+        return 'cache';
+    if (parts.length === 1 && !dir && ROOT_CACHE_FILE.test(top))
+        return 'cache';
+    return null;
 };
-
 const nestedAgentDataCategory = (dirs, name) => {
-  if (dirs.includes('draw-loop')) return 'draw-round';
-  if (dirs.includes('runs') && dirs[0] === 'features' && dirs.includes('uat')) return 'uat-run';
-  if (dirs.includes('evidence')) return 'evidence-bundle';
-  if (dirs[0] === 'features' && dirs.includes('operations')) return 'interface-audit';
-  if (dirs[0] === 'features' && dirs.includes('impl') && dirs.includes('assets')) return 'capture';
-  if (dirs[0] === 'shell' && dirs[1] === 'assets') return 'layout-capture';
-  if (name && /^report.*\.json$/.test(name)) return 'stray-report';
-  if (name?.endsWith('.tmp.json')) return 'cache';
-  return null;
+    if (dirs.includes('draw-loop'))
+        return 'draw-round';
+    if (dirs.includes('runs') && dirs[0] === 'features' && dirs.includes('uat'))
+        return 'uat-run';
+    if (dirs.includes('evidence'))
+        return 'evidence-bundle';
+    if (dirs[0] === 'features' && dirs.includes('operations'))
+        return 'interface-audit';
+    if (dirs[0] === 'features' && dirs.includes('impl') && dirs.includes('assets'))
+        return 'capture';
+    if (dirs[0] === 'shell' && dirs[1] === 'assets')
+        return 'layout-capture';
+    if (name && /^report.*\.json$/.test(name))
+        return 'stray-report';
+    if (name?.endsWith('.tmp.json'))
+        return 'cache';
+    return null;
 };
-
 export function agentDataCategory(rel, { dir = false } = {}) {
-  const parts = segs(rel);
-  if (!parts.length) return null;
-  const top = parts[0];
-  const dirs = dir ? parts : parts.slice(0, -1);
-  const name = dir ? null : parts.at(-1);
-  return rootAgentDataCategory(parts, dir, top) ?? nestedAgentDataCategory(dirs, name);
+    const parts = segs(rel);
+    if (!parts.length)
+        return null;
+    const top = parts[0];
+    const dirs = dir ? parts : parts.slice(0, -1);
+    const name = dir ? null : parts.at(-1);
+    return rootAgentDataCategory(parts, dir, top) ?? nestedAgentDataCategory(dirs, name);
 }
-
 /**
  * The .starciwork/.gitignore of a product repository: deny everything at the root, re-admit
  * the §5.1 roots, then deny agent output inside them. Tracked files are not affected by an ignore rule; a tracked
@@ -147,18 +152,19 @@ let cachedLines;
 const gitignoreLines = () => (cachedLines ??= Object.freeze(fs.readFileSync(TEMPLATE, 'utf8').trimEnd().split(/\r?\n/)));
 const frozenWrite = () => { throw new TypeError('STARCIWORK_GITIGNORE is a frozen view of the hfs template'); };
 export const STARCIWORK_GITIGNORE = new Proxy([], {
-  get: (_t, p) => Reflect.get(gitignoreLines(), p),
-  has: (_t, p) => Reflect.has(gitignoreLines(), p),
-  ownKeys: () => Reflect.ownKeys(gitignoreLines()),
-  getOwnPropertyDescriptor: (_t, p) => {
-    const d = Reflect.getOwnPropertyDescriptor(gitignoreLines(), p);
-    // The proxy target holds none of these slots: every index must report configurable, and 'length' must keep
-    // the writable shape of its non-configurable target slot.
-    if (!d) return d;
-    return p === 'length' ? { ...d, writable: true } : { ...d, configurable: true };
-  },
-  set: frozenWrite,
-  deleteProperty: frozenWrite,
-  defineProperty: frozenWrite,
-  setPrototypeOf: frozenWrite,
+    get: (_t, p) => Reflect.get(gitignoreLines(), p),
+    has: (_t, p) => Reflect.has(gitignoreLines(), p),
+    ownKeys: () => Reflect.ownKeys(gitignoreLines()),
+    getOwnPropertyDescriptor: (_t, p) => {
+        const d = Reflect.getOwnPropertyDescriptor(gitignoreLines(), p);
+        // The proxy target holds none of these slots: every index must report configurable, and 'length' must keep
+        // the writable shape of its non-configurable target slot.
+        if (!d)
+            return d;
+        return p === 'length' ? { ...d, writable: true } : { ...d, configurable: true };
+    },
+    set: frozenWrite,
+    deleteProperty: frozenWrite,
+    defineProperty: frozenWrite,
+    setPrototypeOf: frozenWrite,
 });

package/runtime/scripts/lib/swarm-stack.d.mts

@@ -0,0 +1,24 @@
+type Mapping = Record<string, any>;
+/** One finding of the Swarm contract: where it is and what is wrong. */
+export interface SwarmIssue {
+    at: string;
+    message: string;
+}
+/** Compose includes may be a path or an object whose path is a string or a list of source paths. */
+export declare function composeIncludePaths(doc: Mapping): {
+    paths: string[];
+    errors: string[];
+};
+/** Inventory rules are independent of a selected environment or rendered deployment model. */
+export declare function swarmInventoryIssues({ components, lite }: {
+    components: unknown;
+    lite?: boolean;
+}): SwarmIssue[];
+/** Validate the same deployment model in HFS and the deployment evidence gate. */
+export declare function swarmModelIssues({ model, components, bindings, lite }: {
+    model: unknown;
+    components: unknown;
+    bindings: unknown;
+    lite?: boolean;
+}): SwarmIssue[];
+export {};

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

@@ -2,129 +2,141 @@
 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]\d*$/;
 // R276 (scripts/hfs/rules/stacks-lite-backing.mjs) judges declared Redis and refuses full-only backing services in lite.
 const BACKING_IMAGE_SQL_AND_CACHE = 'postgres(?:ql)?|postgresql-repmgr|mysql(?:-server)?|mongo(?:db)?|mongodb-community-server';
 const BACKING_IMAGE_BROKERS_AND_OTHERS = '(?:cp-)?kafka(?:-native)?|keycloak|minio|rabbitmq';
 const BACKING_IMAGE = new RegExp(`^(?:${BACKING_IMAGE_SQL_AND_CACHE}|${BACKING_IMAGE_BROKERS_AND_OTHERS})$`, '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);
-
+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 };
+    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);
+    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');
+    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 runs no backing image; its db component runs the image .starcistacks/images/db/Dockerfile builds, storage is the external S3 endpoint, identity the API');
-    jobDeclarationIssues(id, component, catalog, add);
-  }
-  return errors;
+    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 runs no backing image; its db component runs the image .starcistacks/images/db/Dockerfile builds, storage is the external S3 endpoint, identity the API');
+        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');
+    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');
+    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');
+    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 runs no backing image; its db service runs the image .starcistacks/images/db/Dockerfile builds');
-    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;
+    const errors = [], services = mapping(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 runs no backing image; its db service runs the image .starcistacks/images/db/Dockerfile builds');
+        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.d.mts

@@ -0,0 +1,2 @@
+/** `value` with its trailing characters removed while `matches(char)` holds. */
+export declare const trimEndWhile: (value: string, matches: (char: string) => boolean) => string;

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

@@ -1,8 +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);
+    let end = value.length;
+    while (end > 0 && matches(value.charAt(end - 1)))
+        end -= 1;
+    return value.slice(0, end);
 };

package/runtime/scripts/lib/ts-analysis.d.mts

@@ -0,0 +1,24 @@
+import type { Expression, Node, SourceFile, TypeChecker } from 'typescript';
+import type { TypeScript } from './ts-ast.mjs';
+/** The wrappers of an expression a contract may look through. */
+export interface UnwrapOptions {
+    awaitExpressions?: boolean;
+    typeAssertions?: boolean;
+    nonNullExpressions?: boolean;
+    satisfiesExpressions?: boolean;
+}
+/** What unwrapping `N` yields: every wrapper holds an Expression, so an Expression stays one; null and undefined pass through. */
+export type Unwrapped<N> = N extends Expression ? Expression : N extends Node ? Node : N;
+/** The expression under the wrappers selected by an AST check's contract. */
+export declare function unwrapExpression<N extends Node | null | undefined>(ts: TypeScript, expression: N, { awaitExpressions, typeAssertions, nonNullExpressions, satisfiesExpressions }?: UnwrapOptions): Unwrapped<N>;
+/** Local name -> imported name and module; callers select their existing module key and literal policy. */
+export declare function importsOf(ts: TypeScript, sourceFile: SourceFile, { moduleKey, stringLiteralsOnly }?: {
+    moduleKey?: string;
+    stringLiteralsOnly?: boolean;
+}): Map<string, {
+    name: string;
+} & Record<string, string>>;
+/** Catalog values unwrap parentheses, `as`, and `satisfies`, preserving assertions and non-null nodes. */
+export declare const unwrapCatalogExpression: <N extends Node | undefined>(ts: TypeScript, node: N) => Node | N;
+/** Bind this file in isolation: the compiler resolves lexical names, but imports and library files are never loaded. */
+export declare function lexicalChecker(ts: TypeScript, source: SourceFile): TypeChecker;