@starci/hfs 4.2.16 → 4.3.0

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/swarm-stack.mjs

@@ -0,0 +1,139 @@
+// Shared static Swarm contract for app checks and rendered deployment evidence.
+import { isPlainObject as plain } from '../../engine/plain-object.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);
+}
+
+/** Match image repository names, including registry and vendor namespaces, without matching application tags. */
+function duplicatesManagedBacking(image) {
+  if (!present(image)) return false;
+  const repository = image.split('@')[0].split('/').at(-1).split(':')[0];
+  return BACKING_IMAGE.test(repository);
+}
+
+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 && duplicatesManagedBacking(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 labelsOf(value) {
+  if (!Array.isArray(value)) return mapping(value);
+  return Object.fromEntries(value.map(label => {
+    const text = String(label), separator = text.indexOf('=');
+    return separator < 0 ? [text, ''] : [text.slice(0, separator), text.slice(separator + 1)];
+  }));
+}
+
+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 = labelsOf(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 && duplicatesManagedBacking(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/ts-analysis.mjs

@@ -0,0 +1,20 @@
+/** The expression under the wrappers selected by an AST check's contract. */
+export function unwrapExpression(ts, expression, { awaitExpressions = false, typeAssertions = true, satisfiesExpressions = true } = {}) {
+  while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
+    || (typeAssertions && ts.isTypeAssertionExpression(expression)) || 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;
+}

package/scaffold/add-cli-lite.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveRepoDeclaration } from "../runtime/scripts/hfs/slots.mjs";
 import { parseYaml } from "../runtime/engine/yaml.mjs";
-import { appScripts, imageFiles, TEMPLATES_DIR } from "../sync/index.mjs";
+import { appScripts, appSource, imageFiles, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError } from "./service.mjs";
 import { jsonText, packageJsonText } from "./app.mjs";
 import { registerLiteExports } from "./lite-exports.mjs";
@@ -15,14 +15,12 @@ const read = (relative) =>
 const PINS_FILE = path.join(import.meta.dirname, "..", "runtime", "knowledge", "hfs", "canon-pins.yaml");
 
 
-const managedScripts = (repo) => {
-  const fragment = appScripts(repo).replace(/,\s*$/, "");
+const managedScripts = (repo, source) => {
+  const fragment = appScripts(repo, source).replace(/,\s*$/, "");
   return fragment === "" ? {} : JSON.parse(`{${fragment}}`);
 };
 
-const CLI_OPTIONS = `import type { EnvSource } from "@modules/platform/config"
-import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
-import type { DatabaseConnectionOptions } from "@modules/platform/database"
+const CLI_OPTIONS = `import type { DatabaseConnectionOptions } from "@modules/platform/database"
 
 /** Everything the lite cli needs: the least-privilege Supabase PostgreSQL connection. */
 export interface CliAppOptions {
@@ -30,9 +28,9 @@ export interface CliAppOptions {
     readonly connections: ReadonlyArray<DatabaseConnectionOptions>
 }
 
-/** Reads the one declared connection without adding entities or TypeORM migrations. */
-export const parseCliAppOptions = (env: EnvSource): CliAppOptions => ({
-    connections: [parsePrimaryDatabaseConfig(env)],
+/** Uses the parsed connection without adding entities or TypeORM migrations. */
+export const createCliAppOptions = (primary: DatabaseConnectionOptions): CliAppOptions => ({
+    connections: [primary],
 })
 `;
 
@@ -142,7 +140,7 @@ function enableLiteCliDatabase(root) {
 }
 
 /**
- * Creates the optional lite cli app and its Supabase migrate/seed groups on first `add cli`.
+ * Creates the optional lite cli app, its typed CliEnv/readCliEnv boundary and Supabase migrate/seed groups on first `add cli`.
  * Existing cli trees are never repaired or overwritten: drift remains a check finding.
  */
 export function ensureLiteCli({ root, manifest, repo }) {
@@ -182,6 +180,7 @@ export function ensureLiteCli({ root, manifest, repo }) {
       "be/apps/cli/src/app.module.ts",
       read("be/skeleton/apps/cli/src/app.module.ts"),
     ],
+    ["be/apps/cli/src/cli.env.ts", read("be/skeleton-lite/apps/cli/src/cli.env.ts")],
     ["be/apps/cli/src/cli.options.ts", CLI_OPTIONS],
     [
       "be/src/features/cli/index.ts",
@@ -273,7 +272,7 @@ export function ensureLiteCli({ root, manifest, repo }) {
   packageManifest.dependencies = { ...(packageManifest.dependencies ?? {}), "nest-commander": pin };
   packageManifest.scripts = {
     ...(packageManifest.scripts ?? {}),
-    ...managedScripts(resolved),
+    ...managedScripts(resolved, appSource(root)),
   };
   for (const [relative, body] of files) {
     const target = path.join(root, ...relative.split("/"));

package/scaffold/add-inbox-lite.mjs

@@ -25,13 +25,13 @@ const template = (relative, values) => {
   });
 };
 
-/** The lite templates of the webhook door and its unit spec: the door hands the delivery id to the provider inbox. */
+/** The lite templates of the webhook door and its unit spec: the door records the delivery in the provider inbox. */
 const LITE_WEBHOOK_TEMPLATES = Object.freeze({
   "webhooks/webhook.door.ts.tpl": "../inbox/webhook-door.ts.tpl",
   "webhooks/webhook.door.spec.ts.tpl": "../inbox/webhook-door.spec.ts.tpl",
 });
 
-/** Lite replaces only the webhook door and its spec; the full-edition pattern remains byte-identical. */
+/** Lite replaces only the webhook door and its spec with the durable provider inbox intake. */
 export const selectLiteWebhookEntries = (entries) =>
   entries.map((entry) =>
     LITE_WEBHOOK_TEMPLATES[entry.template] === undefined
@@ -39,86 +39,24 @@ export const selectLiteWebhookEntries = (entries) =>
       : { ...entry, template: LITE_WEBHOOK_TEMPLATES[entry.template] },
   );
 
-const matchingBrace = (text, open) => {
-  let depth = 0;
-  for (let index = open; index < text.length; index += 1) {
-    if (text[index] === "{") depth += 1;
-    else if (text[index] === "}") {
-      depth -= 1;
-      if (depth === 0) return index;
-    }
-  }
-  return -1;
-};
-
-const addEntityManagerImport = (text) => {
-  if (/import type \{[^}]*\bEntityManager\b[^}]*\} from "typeorm"/.test(text))
-    return text;
-  return `import type { EntityManager } from "typeorm"\n${text}`;
-};
-
-/** Gives the selected domain intake the transaction manager while preserving its existing processing body. */
-function adaptedDomainService({ root, service, serviceModule, provider, Provider }) {
+/** Validates the selected processing owner for a later reactor/job without invoking or changing that service in the door. */
+function validateProcessingOwner({ root, service, serviceModule, provider }) {
   const prefix = "@modules/domain/";
-  if (!serviceModule.startsWith(prefix))
+  const capability = serviceModule.slice(prefix.length);
+  if (!serviceModule.startsWith(prefix) || !/^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)*$/.test(capability))
     throw new ScaffoldError(
       "HFS_ADD_INBOX_SERVICE",
-      `lite add webhook needs a domain service module below ${prefix}`,
+      `lite add webhook needs a processing service module below ${prefix}`,
     );
-  const owner = path.join(
-    root,
-    "be",
-    "src",
-    "modules",
-    "domain",
-    ...serviceModule.slice(prefix.length).split("/"),
-  );
-  const candidates = filesBelow(owner).filter(
-    (file) =>
-      file.endsWith(".service.ts") &&
-      new RegExp(`\\bexport\\s+class\\s+${service}\\b`).test(
-        fs.readFileSync(file, "utf8"),
-      ),
+  const owner = path.join(root, "be", "src", "modules", "domain", ...capability.split("/"));
+  const candidates = filesBelow(owner).filter((file) =>
+    file.endsWith(".service.ts") && new RegExp(`\\bexport\\s+class\\s+${service}\\b`).test(fs.readFileSync(file, "utf8")),
   );
   if (candidates.length !== 1)
-    throw new ScaffoldError(
-      "HFS_ADD_INBOX_SERVICE",
-      `${serviceModule} must export exactly one ${service} class from a .service.ts file before adding the ${provider} webhook`,
-    );
-  const file = candidates[0];
-  let text = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
-  const method = `accept${Provider}Delivery`;
-  const methodAt = text.search(new RegExp(`\\b${method}\\s*\\(`));
-  if (methodAt < 0)
-    throw new ScaffoldError(
-      "HFS_ADD_INBOX_INTAKE",
-      `${service} must declare ${method}(delivery) before adding the ${provider} webhook`,
-    );
-  const paramsOpen = text.indexOf("(", methodAt);
-  const paramsClose = text.indexOf(")", paramsOpen);
-  const bodyOpen = text.indexOf("{", paramsClose);
-  const bodyClose = matchingBrace(text, bodyOpen);
-  if (paramsClose < 0 || bodyOpen < 0 || bodyClose < 0)
-    throw new ScaffoldError(
-      "HFS_ADD_INBOX_INTAKE",
-      `${service}.${method} is not a readable method declaration`,
-    );
-  const parameters = text.slice(paramsOpen + 1, paramsClose).trim();
-  if (/(?:^|,)\s*(?:manager|entityManager)\s*:/.test(parameters)) return { file, text };
-  const manager =
-    /private\s+readonly\s+([A-Za-z][A-Za-z0-9]*)\s*:\s*EntityManager/.exec(
-      text,
-    )?.[1];
-  if (!manager)
     throw new ScaffoldError(
       "HFS_ADD_INBOX_INTAKE",
-      `${service}.${method} needs an injected EntityManager so the inbox can keep its processing in one transaction`,
+      `${serviceModule} must export exactly one ${service} from a .service.ts file as the processing owner of the ${provider} inbox`,
     );
-  const body = text
-    .slice(bodyOpen + 1, bodyClose)
-    .replaceAll(`this.${manager}`, "entityManager");
-  text = `${text.slice(0, paramsOpen + 1)}${parameters}, entityManager: EntityManager = this.${manager}${text.slice(paramsClose, bodyOpen + 1)}${body}${text.slice(bodyClose)}`;
-  return { file, text: addEntityManagerImport(text) };
 }
 
 const databasePatches = (root) => {
@@ -131,8 +69,8 @@ const databasePatches = (root) => {
       "lite add webhook needs the scaffolded platform/database capability",
     );
   let index = fs.readFileSync(indexFile, "utf8").replace(/\r\n/g, "\n");
-  if (!index.includes('export { acceptWebhookDelivery } from "./webhook-inbox.client"'))
-    index = `${index.replace(/\n+$/, "")}\nexport { acceptWebhookDelivery } from "./webhook-inbox.client"\n`;
+  if (!index.includes('export { recordWebhookDelivery } from "./webhook-inbox.client"'))
+    index = `${index.replace(/\n+$/, "")}\nexport { recordWebhookDelivery } from "./webhook-inbox.client"\n`;
   let error = fs.readFileSync(errorFile, "utf8").replace(/\r\n/g, "\n");
   const enumLine =
     '    WebhookDeliveryIdRequired = "DATABASE_WEBHOOK_DELIVERY_ID_REQUIRED",';
@@ -199,7 +137,7 @@ const wiredAppModule = ({ root, repo, provider, Provider }) => {
   return { file, text: `${lines.join("\n").replace(/\n+$/, "")}\n` };
 };
 
-/** Writes the lite provider inbox and adapts the selected domain intake to share its transaction. */
+/** Writes the lite provider inbox. Processing belongs to a separately added reactor or job, after the record commits. */
 export function addLiteWebhookInbox({
   root,
   repo,
@@ -209,6 +147,7 @@ export function addLiteWebhookInbox({
   now = Date.now,
 }) {
   if (repo.edition !== "lite" || noun !== "webhook") return [];
+  validateProcessingOwner({ root, ...values, provider });
   const Provider = pascalOf(provider);
   const table = `${snakeOf(provider)}_inbox`;
   const migrationsDir = path.join(root, "supabase", "migrations");
@@ -308,15 +247,7 @@ export function addLiteWebhookInbox({
       "HFS_ADD_EXISTS",
       `webhook ${provider} inbox already exists: ${clashes.join(", ")}`,
     );
-  const servicePatch = adaptedDomainService({
-    root,
-    service: values.service,
-    serviceModule: values.serviceModule,
-    provider,
-    Provider,
-  });
   const patches = [
-    servicePatch,
     ...databasePatches(root),
     wiredAppModule({ root, repo, provider, Provider }),
   ];

package/scaffold/add-plan.mjs

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createSlotResolver, loadSlotManifest, readRepoDeclaration, ruleParams } from '../runtime/scripts/hfs/slots.mjs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { TEMPLATES_DIR } from '../sync/index.mjs';
+import { ScaffoldError, pascalOf } from './service.mjs';
+import { refuseFullAdapterInLite, refuseInEdition } from './edition-gate.mjs';
+import { selectLiteWebhookEntries } from './add-inbox-lite.mjs';
+import { ensureLiteCli } from './add-cli-lite.mjs';
+
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const VARIABLE = /<([A-Za-z][A-Za-z0-9]*)>/g;
+const PLACEHOLDER = /@@([A-Za-z][A-Za-z0-9]*)@@/g;
+const PLATFORM_PREFIX = 'src/modules/platform/';
+const TOPICS_DIR = path.join(import.meta.dirname, '..', 'runtime', 'knowledge', 'patterns', 'be');
+const PATTERN_TEMPLATES = path.join(TEMPLATES_DIR, 'be', 'patterns');
+const camelOf = (name) => { const pascal = pascalOf(name); return pascal[0].toLowerCase() + pascal.slice(1); };
+
+/** The noun's app declaration and the ruleParams entry that supplies its topic and options. */
+export function readAddContext(input) {
+  const manifest = loadSlotManifest();
+  const params = ruleParams(manifest, 'be');
+  const spec = params.addKinds[input.noun];
+  if (!spec) throw new ScaffoldError('HFS_ADD_NOUN_UNKNOWN', `starci app add knows ${Object.keys(params.addKinds).join(', ')}; ${input.noun} is none of them`);
+  const declarationFile = path.join(input.repoRoot, 'hfs.json');
+  if (!fs.existsSync(declarationFile)) throw new ScaffoldError('HFS_ADD_NOT_AN_APP', 'starci app add runs at the app root (the folder of hfs.json)');
+  const repo = readRepoDeclaration(manifest, input.repoRoot);
+  if (!repo.sides?.be) throw new ScaffoldError('HFS_ADD_NO_BACK_END', 'this app has no back-end side');
+  return { ...input, manifest, params, spec, declarationFile, repo };
+}
+
+/** Lite's built-in migrate and seed groups come from its one CLI bootstrap, without a second instance tree. */
+export function addBuiltinLiteCli({ noun, name, repo, repoRoot, manifest }) {
+  if (noun !== 'cli' || repo.edition !== 'lite' || !['migrate', 'seed'].includes(name)) return null;
+  if (repo.sides.be.apps.some(app => app.kind === 'cli')) throw new ScaffoldError('HFS_ADD_EXISTS', `the lite cli already carries its built-in ${name} group`);
+  return { created: ensureLiteCli({ root: repoRoot, manifest, repo }), registered: { patterns: [], kinds: ['cli'] } };
+}
+
+const readTopic = (topic) => ({ id: topic, doc: parseYaml(fs.readFileSync(path.join(TOPICS_DIR, `${topic}.yaml`), 'utf8')) });
+
+function readTree(topic) {
+  const file = path.join(TOPICS_DIR, `${topic}.yaml`);
+  if (!fs.existsSync(file)) throw new ScaffoldError('HFS_ADD_TOPIC_MISSING', `the pattern topic ${topic} (knowledge/patterns/be/${topic}.yaml) is not carried by this package`);
+  const doc = parseYaml(fs.readFileSync(file, 'utf8'));
+  if (!Array.isArray(doc?.files)) throw new ScaffoldError('HFS_ADD_TREE_MISSING', `knowledge/patterns/be/${topic}.yaml has no files tree`);
+  return doc.files;
+}
+
+const selectLiteApiEntries = entries => entries.map(entry => {
+  if (entry.path === 'src/features/api/<feature>/application/<action>.command.ts') return { ...entry, template: 'api/application.command.principal.ts.tpl' };
+  if (entry.path === 'src/features/api/<feature>/application/<action>.handler.ts') return { ...entry, template: 'api/application.handler.principal.ts.tpl' };
+  return entry;
+});
+
+/** Extra lite api templates stay in the same template set as the pattern topics. */
+export const liteApiTemplates = () => selectLiteApiEntries(readTree('api')).map(entry => entry.template).filter(Boolean);
+
+function topicsOfPatterns(patterns) {
+  const topics = new Set();
+  for (const file of fs.readdirSync(TOPICS_DIR).filter((entry) => entry.endsWith('.yaml'))) {
+    const doc = parseYaml(fs.readFileSync(path.join(TOPICS_DIR, file), 'utf8'));
+    if (patterns.includes(doc?.pattern)) topics.add(file.slice(0, -'.yaml'.length));
+  }
+  return topics;
+}
+
+function requiredOption(need, value, noun) {
+  if (typeof value !== 'string' || !value) throw new ScaffoldError('HFS_ADD_OPTION_MISSING', `starci app add ${noun} needs --${need}`);
+  if (need === 'service') {
+    const [service, serviceModule] = value.split('=');
+    if (!service || !serviceModule) throw new ScaffoldError('HFS_ADD_OPTION_INVALID', '--service takes <ServiceClass>=<module specifier>');
+    return { service, serviceModule };
+  }
+  if (!KEBAB.test(value)) throw new ScaffoldError('HFS_ADD_OPTION_INVALID', `--${need} ${value} must be kebab-case`);
+  return { [need]: value };
+}
+
+function variablesOf({ spec, noun, name, options }) {
+  if (!KEBAB.test(name)) throw new ScaffoldError('HFS_ADD_NAME_INVALID', `${noun} name ${name} must be kebab-case (letters, digits and single dashes)`);
+  const values = { [spec.variable]: name };
+  for (const need of spec.needs ?? []) Object.assign(values, requiredOption(need, options[need], noun));
+  for (const [key, rule] of Object.entries(spec.defaults ?? {})) {
+    if (values[key] === undefined) values[key] = rule === '@name' ? name : String(rule);
+  }
+  return values;
+}
+
+export function formsOf(values) {
+  const forms = {};
+  for (const [name, value] of Object.entries(values)) {
+    const kebab = KEBAB.test(value);
+    forms[name] = value;
+    forms[name[0].toUpperCase() + name.slice(1)] = kebab ? pascalOf(value) : value[0].toUpperCase() + value.slice(1);
+    forms[`${name}Camel`] = kebab ? camelOf(value) : value[0].toLowerCase() + value.slice(1);
+    forms[`${name}Upper`] = kebab ? value.replaceAll('-', '_').toUpperCase() : value;
+    forms[`${name}Snake`] = kebab ? value.replaceAll('-', '_') : value;
+  }
+  return forms;
+}
+
+const fillPath = (text, values) => {
+  let missing = false;
+  const filled = text.replace(VARIABLE, (whole, name) => (values[name] === undefined ? ((missing = true), whole) : values[name]));
+  return missing ? null : filled;
+};
+
+const renderBody = (text, forms, template) => text.replace(PLACEHOLDER, (whole, name) => {
+  if (forms[name] === undefined) throw new ScaffoldError('HFS_ADD_PLACEHOLDER_UNKNOWN', `template ${template} uses ${whole}, which no variable of this noun provides`);
+  return forms[name];
+});
+
+/** Wiring may leave a placeholder unchanged; template bodies use the strict rendering refusal above. */
+export const fillKnownForms = (text, forms) => text.replace(PLACEHOLDER, (whole, name) => forms[name] ?? whole);
+
+function treesOf({ topics, repo, noun, spec }) {
+  const liteApi = noun === 'api' && repo.edition === 'lite';
+  return new Map([...topics].map((topic) => {
+    const entries = repo.edition === 'lite' ? selectLiteWebhookEntries(readTree(topic)) : readTree(topic);
+    return [topic, liteApi && topic === spec.topic ? selectLiteApiEntries(entries) : entries];
+  }));
+}
+
+function collectSlots(entries, platform, slots) {
+  for (const entry of entries) {
+    if (entry.path.startsWith(PLATFORM_PREFIX) === platform && entry.optional !== true && entry.slot) slots.add(entry.slot);
+  }
+}
+
+/** Optional entries gate nothing; the generated instance and platform slots decide the edition. */
+function validateWrittenSlots({ specs, topics, trees, manifest, repo, noun }) {
+  const slots = new Set();
+  for (const [, spec] of specs) collectSlots(trees.get(spec.topic), false, slots);
+  for (const topic of topics) collectSlots(trees.get(topic), true, slots);
+  refuseInEdition({ resolver: createSlotResolver(manifest, repo), slotIds: [...slots], command: `add ${noun}` });
+}
+
+function planEntry(entry, { topic, instance, shared, beRoot, withStamp, forms }) {
+  if (entry.optional === true) return null;
+  const target = fillPath(entry.path, withStamp);
+  if (target === null) return null;
+  const absolute = path.join(beRoot, ...target.split('/'));
+  // A platform capability is whole or absent: its index prevents regeneration of all its files.
+  if (!instance && fs.existsSync(path.join(beRoot, ...target.split('/').slice(0, 4), 'index.ts'))) return null;
+  if ((!instance || shared) && fs.existsSync(absolute)) return null;
+  if (!entry.template) throw new ScaffoldError('HFS_ADD_TEMPLATE_MISSING', `${topic}.yaml lists ${entry.path} without a template, so it cannot be generated`);
+  const templateFile = path.join(PATTERN_TEMPLATES, ...entry.template.split('/'));
+  if (!fs.existsSync(templateFile)) throw new ScaffoldError('HFS_ADD_TEMPLATE_MISSING', `${topic}.yaml names template ${entry.template} for ${entry.path}, which the package does not carry`);
+  return { target, absolute, body: renderBody(fs.readFileSync(templateFile, 'utf8'), forms, entry.template), instance };
+}
+
+function appendEntries(entries, context, planned) {
+  for (const entry of entries) {
+    const file = planEntry(entry, context);
+    if (file) planned.push(file);
+  }
+}
+
+/** Renders all topic-owned paths and bodies before any instance file is written. */
+export function planKind(context) {
+  const { noun, name, spec, params, repo, options, now } = context;
+  const specs = [noun, ...(spec.also ?? [])].map((each) => [each, params.addKinds[each]]);
+  const patterns = [...new Set(specs.flatMap(([, eachSpec]) => eachSpec.patterns))];
+  const topics = new Set([...specs.map(([, eachSpec]) => eachSpec.topic), ...topicsOfPatterns(patterns)]);
+  refuseFullAdapterInLite({ edition: repo.edition, topics: [...topics].map(readTopic), command: `add ${noun}` });
+  const trees = treesOf({ topics, repo, noun, spec });
+  validateWrittenSlots({ ...context, specs, topics, trees });
+  const values = Object.assign({}, ...specs.map(([each, eachSpec]) => variablesOf({ spec: eachSpec, noun: each, name, options })), variablesOf({ spec, noun, name, options }));
+  const withStamp = { ...values, epochMs13: String(now()).padStart(13, '0').slice(0, 13) };
+  const forms = formsOf(withStamp);
+  const beRoot = path.join(context.repoRoot, 'be');
+  const planned = [];
+  for (const [each, eachSpec] of specs) {
+    const entries = trees.get(eachSpec.topic).filter(entry => !entry.path.startsWith(PLATFORM_PREFIX));
+    appendEntries(entries, { topic: eachSpec.topic, instance: true, shared: each !== noun, beRoot, withStamp, forms }, planned);
+  }
+  for (const topic of topics) {
+    const entries = trees.get(topic).filter(entry => entry.path.startsWith(PLATFORM_PREFIX));
+    appendEntries(entries, { topic, instance: false, shared: false, beRoot, withStamp, forms }, planned);
+  }
+  const clash = planned.filter(file => file.instance && fs.existsSync(file.absolute)).map(file => file.target);
+  if (clash.length) throw new ScaffoldError('HFS_ADD_EXISTS', `${noun} ${name} already exists: ${clash.join(', ')}`);
+  return { values, forms, beRoot, patterns, planned };
+}