@starci/hfs 4.7.31 → 4.7.33

package/scaffold/add.mjs

@@ -22,6 +22,7 @@ import { addModuleImport, compositionCode, readComposeGroup, writeComposeGroup }
 import { addApp } from './add-app.mjs';
 import { ensureLiteCli } from './add-cli-lite.mjs';
 import { addLiteWebhookInbox } from './add-inbox-lite.mjs';
+import { planLiteQueue } from './add-queue-lite.mjs';
 import { addBuiltinLiteCli, fillKnownForms, formsOf, planKind, readAddContext } from './add-plan.mjs';
 export { liteApiTemplates } from './add-plan.mjs';
 import { bundledPins, jsonText, packageJsonText, peerDependencies } from './app.mjs';
@@ -58,8 +59,9 @@ function registerFeatureExports({ repoRoot, repo, noun, values }) {
   }
 }
 
-function writeKind({ repoRoot, noun, name, now, manifest, repo, spec, declarationFile, values, forms, beRoot, patterns, planned }) {
+function writeKind({ repoRoot, noun, name, now, options, manifest, repo, spec, declarationFile, values, forms, beRoot, patterns, planned }) {
   if (noun === 'api' || noun === 'webhook') preflightFeatureComposition({ repoRoot, repo, noun, name });
+  const liteQueue = planLiteQueue({ repoRoot, repo, noun, patterns, now, emitTypes: options.noTypes === true ? false : options.emitTypes });
   const bootstrapCreated = noun === 'cli' && repo.edition === 'lite' ? ensureLiteCli({ root: repoRoot, manifest, repo }) : [];
   for (const file of planned) {
     fs.mkdirSync(path.dirname(file.absolute), { recursive: true });
@@ -68,10 +70,11 @@ function writeKind({ repoRoot, noun, name, now, manifest, repo, spec, declaratio
   registerFeatureExports({ repoRoot, repo, noun, values });
   if (spec.wire) wire({ beRoot, wire: spec.wire, forms, noun, name });
   const inboxCreated = addLiteWebhookInbox({ root: repoRoot, repo, noun, provider: name, values, now });
+  const queueBacking = liteQueue ? liteQueue.apply() : [];
   const platformCreated = noun === 'api' || noun === 'webhook' ? wireFeature({ repoRoot, repo, noun, name }) : [];
   const graphqlDoor = noun === 'api' ? ensureGraphqlPeers(repoRoot) : [];
   const registered = register({ declarationFile, spec: { patterns, trigger: spec.trigger, optionalSlots: noun === 'api' ? [GRAPHQL_CONTRACT_SLOT] : [] } });
-  return { created: [...bootstrapCreated, ...planned.map((file) => `be/${file.target}`), ...platformCreated, ...inboxCreated, ...graphqlDoor], registered };
+  return { created: [...bootstrapCreated, ...planned.map((file) => path.relative(repoRoot, file.absolute).replaceAll('\\', '/')), ...platformCreated, ...inboxCreated, ...queueBacking, ...graphqlDoor], registered };
 }
 
 /** The slot of the emitted GraphQL snapshot (contracts/<app>/schema.graphql), which an app serving a GraphQL api feature opts into. */

package/scaffold/app.mjs

@@ -417,7 +417,6 @@ const liteBaseSource = (rel) => !rel.startsWith('apps/cli/')
     && rel !== 'src/modules/platform/database/connection-source.client.ts'
     && rel !== 'src/modules/platform/database/migrate-connections.client.ts'
     && rel !== 'src/modules/platform/database/seed-connections.client.ts'
-    && rel !== 'src/modules/platform/primitives/sequence.policy.ts'
     && !LITE_DEFERRED_GENERATOR_FILES.has(rel)
     && !rel.startsWith('src/tests/');
 /** The be files the lite overlay replaces: a base unit spec of such a file tests the full variant, so lite carries its own. */
@@ -488,7 +487,7 @@ function skeletonDirectory(scope, directory, app, vars, include = () => true) {
 }
 
 /** The canonical full Work workspace, catalog and feature nodes an edition upgrade may need. */
-export function scaffoldWorkSeeds(project) {
+function scaffoldWorkSeeds(project) {
   return skeletonDirectory('app', 'skeleton', { project }, {},
     rel => rel === '.starciwork/workspace.yaml' || rel === '.starciwork/index.yaml' || rel.startsWith('.starciwork/features/'));
 }

package/scaffold/edition-gate.mjs

@@ -7,28 +7,32 @@
 
 /** The refusal of a verb a non-full edition does not carry: printed verbatim by the CLI, exit 2, nothing written. */
 export class EditionRefusal extends Error {
-  constructor(command, message = `${command}: full edition only; run starci app upgrade --edition full`) {
+  constructor(command, message = `${command}: full edition only; editions are fixed at scaffold, a lite app stays lite`) {
     super(message);
     this.name = 'EditionRefusal';
   }
 }
 
 /**
- * The refusal of a pattern noun in a lite app whose topic carries a `liteAdapter` (ruling:R212/case-1, amended by ruling:R212/case-4):
- * lite has the pattern, but the package carries only its full-adapter templates, so generating them would write adapter paths
+ * The refusal of a pattern noun in a lite app whose topic carries a `liteAdapter` (ruling:R212/case-1, amended by ruling:R212/case-4)
+ * and no lite template in this package: lite has the pattern, but generating its full-adapter templates would write adapter paths
  * unavailable in lite. The pattern is written by hand using the topic's declared lite adapter until the package carries a lite template.
  */
 export class LiteAdapterRefusal extends EditionRefusal {
   constructor(command, topics) {
-    super(command, `${command}: the package carries only the full adapter of ${topics.join(', ')}; in a lite app write it on its Supabase adapter (knowledge/patterns/be/${topics[0]}.yaml liteAdapter, knowledge/patterns/be/supabase-queues.yaml)`);
+    super(command, `${command}: the package carries only the full adapter of ${topics.join(', ')}; in a lite app write it on its lite adapter (knowledge/patterns/be/${topics[0]}.yaml liteAdapter)`);
     this.name = 'LiteAdapterRefusal';
   }
 }
 
-/** Refuses `command` in a lite app when one of `topics` (pattern topic ids with their parsed documents) carries a `liteAdapter`. */
-export function refuseFullAdapterInLite({ edition, topics, command }) {
+/**
+ * Refuses `command` in a lite app when one of `topics` (pattern topic ids with their parsed documents) carries a `liteAdapter` and
+ * has no complete edition-specific file tree: neither a `liteFiles` list nor a place among `liteTemplated`, the topics whose lite
+ * templates the package carries.
+ */
+export function refuseFullAdapterInLite({ edition, topics, command, liteTemplated = [] }) {
   if (edition !== 'lite') return;
-  const adapted = topics.filter(({ doc }) => doc?.liteAdapter !== undefined).map(({ id }) => id).sort();
+  const adapted = topics.filter(({ id, doc }) => doc?.liteAdapter !== undefined && !liteTemplated.includes(id) && (!Array.isArray(doc.liteFiles) || doc.liteFiles.length === 0)).map(({ id }) => id).sort();
   if (adapted.length) throw new LiteAdapterRefusal(command, adapted);
 }
 

package/scaffold/lite-exports.mjs

@@ -36,6 +36,16 @@ const REGISTRATIONS = Object.freeze({
       names: ["InjectPrimaryEntityManager", "PRIMARY_ENTITY_MANAGER"],
     },
   ],
+  // The queue and jobs capabilities state their outbox and claim statements with the sql tag (the lite starter already carries the
+  // in-order relay and the record guard the BullMQ client reads stored jobs with).
+  queue: [
+    {
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./database.sql",
+      names: ["sql"],
+      beforeSource: "./errors/database.error",
+    },
+  ],
   webhook: [
     {
       file: "be/src/modules/platform/database/index.ts",

package/scaffold/pattern-file-slots.mjs

@@ -0,0 +1,33 @@
+/** The app-relative path of a topic file, whose root defaults to the back end. */
+export const patternFilePath = (file, root = 'be') => root === 'app' ? file : `${root}/${file}`;
+
+const unquote = (item) => item.trim().replace(/^["']|["']$/g, '');
+
+/** Derives slots for files/liteFiles entries through the app resolver supplied by the caller. */
+export function derivePatternFileSlots(text, classify) {
+  const lines = text.split('\n');
+  const problems = [];
+  let inFiles = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^[A-Za-z][A-Za-z0-9_-]*:/.test(lines[i])) inFiles = /^(?:files|liteFiles):\s*$/.test(lines[i]);
+    if (!inFiles) continue;
+    const match = /^ {2}- path: (.+)$/.exec(lines[i]);
+    if (!match) continue;
+    const entry = deriveFileSlot(lines, i, match[1], classify);
+    if (entry.problem) problems.push(entry.problem);
+    else lines[entry.slotAt] = `    slot: ${entry.slot}`;
+  }
+  return { text: lines.join('\n'), problems };
+}
+
+/** The fields of one file entry stop at the next entry or top-level YAML key. */
+function deriveFileSlot(lines, start, file, classify) {
+  let end = start + 1;
+  while (end < lines.length && !/^(?:[A-Za-z][A-Za-z0-9_-]*:| {2}- )/.test(lines[end])) end += 1;
+  const slotAt = lines.findIndex((line, index) => index > start && index < end && /^ {4}slot: /.test(line));
+  if (slotAt < 0) return { problem: `${file} has no slot line` };
+  const rootLine = lines.slice(start + 1, end).find((line) => /^ {4}root: /.test(line));
+  const root = rootLine ? unquote(rootLine.replace(/^ {4}root: /, '')) : 'be';
+  const slot = classify(patternFilePath(unquote(file), root));
+  return slot ? { slotAt, slot } : { problem: `${file} is owned by no slot` };
+}

package/scaffold/test-world.mjs

@@ -57,7 +57,7 @@ function worldConfig({ apis, connections }) {
     appModuleImports: apis.map((api) => `import { AppModule as ${pascalOf(api.name)}App } from "../../../apps/${api.name}/src/app.module"`).join('\n'),
     optionsImports: ['cliOptionsOf', ...apis.map((api) => `${camelOf(api.name)}OptionsOf`), 'migrateCli', 'platformBase'].sort().join(', '),
     connectionDeclarations: connections.map((connection) => `{ name: ${JSON.stringify(connection.name)} }`).join(', '),
-    worldApps: apis.map((api) => `        ${IDENTIFIER.test(api.name) ? api.name : JSON.stringify(api.name)}: { module: ${pascalOf(api.name)}App, options: ${camelOf(api.name)}OptionsOf },`).join('\n'),
+    worldApps: apis.map((api) => `        ${IDENTIFIER.test(api.name) ? api.name : JSON.stringify(api.name)}: { module: ${pascalOf(api.name)}App, options: ${camelOf(api.name)}OptionsOf, configure: applyCorrelation },`).join('\n'),
   });
 }
 

package/scaffold/yaml-block-edit.mjs

@@ -0,0 +1,117 @@
+// Comment-preserving additions to a block-style YAML file an app owns (its stack declaration, its Swarm model). The caller
+// applies every addition to the parsed document as well and accepts the edited text only when it parses to that document, so
+// a shape this editor does not understand refuses instead of writing a wrong file.
+import { isDeepStrictEqual } from 'node:util';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { ScaffoldError } from './service.mjs';
+
+const significant = (line) => line.trim() !== '' && !line.trimStart().startsWith('#');
+const indentOf = (line) => line.length - line.trimStart().length;
+const isItem = (line) => /^\s*-(?:\s|$)/.test(line);
+
+/** The key's own indent: a `- key:` item line carries its first key two columns after the dash. */
+const keyIndentOf = (line) => (isItem(line) ? indentOf(line) + 2 : indentOf(line));
+
+/** The body of the value that starts after line `at` (a key line, or an item line for an item's body): its lines and their indent. */
+function bodyOf(lines, at, ownIndent) {
+  let last = at;
+  let childIndent = null;
+  for (let index = at + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!significant(line)) continue;
+    const indent = indentOf(line);
+    const indentless = indent === ownIndent && isItem(line) && (childIndent === null || childIndent === ownIndent);
+    if (indent <= ownIndent && !indentless) break;
+    childIndent ??= indent;
+    last = index;
+  }
+  return { from: at + 1, to: last + 1, childIndent };
+}
+
+/** The line of `key` among the direct children (indent `indent`) of lines [from, to); `itemLine` may hold the first key of an item. */
+function keyLine(lines, { from, to }, indent, key, itemLine = -1) {
+  const pattern = new RegExp(`^\\s*(?:- )?${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:(?:\\s|$)`);
+  for (let index = itemLine >= 0 ? itemLine : from; index < to; index += 1) {
+    const line = lines[index];
+    if (!significant(line) || keyIndentOf(line) !== indent || (isItem(line) && index !== itemLine)) continue;
+    if (pattern.test(line)) return index;
+  }
+  return -1;
+}
+
+/**
+ * Resolves `path` to the value it names: a string steps into a mapping key, `{ item: key, is: value }` into the sequence item whose
+ * `key` is `value`. Returns the line that opens the value (the key or item line), the indent of its keys and its body.
+ */
+function locate(lines, path, file) {
+  let at = { line: -1, indent: -1, itemLine: -1, body: { from: 0, to: lines.length, childIndent: 0 } };
+  for (const step of path) {
+    const { body } = at;
+    if (typeof step === 'string') {
+      const indent = at.itemLine >= 0 ? at.indent : body.childIndent;
+      const line = keyLine(lines, body, indent, step, at.itemLine);
+      if (line < 0) throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${file} has no ${path.map(describe).join('.')}; add the declared Redis by hand`);
+      at = { line, indent: keyIndentOf(lines[line]), itemLine: -1, body: bodyOf(lines, line, keyIndentOf(lines[line])) };
+      continue;
+    }
+    const items = [];
+    for (let index = body.from; index < body.to; index += 1) if (significant(lines[index]) && isItem(lines[index]) && indentOf(lines[index]) === body.childIndent) items.push(index);
+    const match = items.find((line, position) => {
+      const end = items[position + 1] ?? body.to;
+      return keyLine(lines, { from: line, to: end }, body.childIndent + 2, step.item, line) >= 0
+        && new RegExp(`^\\s*(?:- )?${step.item}:\\s*${step.is}\\s*$`).test(lines[keyLine(lines, { from: line, to: end }, body.childIndent + 2, step.item, line)]);
+    });
+    if (match === undefined) throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${file} has no ${path.map(describe).join('.')}; add the declared Redis by hand`);
+    const itemBody = bodyOf(lines, match, body.childIndent);
+    at = { line: match, indent: body.childIndent + 2, itemLine: match, body: { ...itemBody, from: match, childIndent: body.childIndent + 2 } };
+  }
+  return at;
+}
+
+const describe = (step) => (typeof step === 'string' ? step : `[${step.item}=${step.is}]`);
+
+/** The lines of `block` (written at indent 0) moved to `indent`. */
+const indented = (block, indent) => block.replace(/\n$/, '').split('\n').map((line) => (line ? ' '.repeat(indent) + line : line));
+
+/** A YAML text that adds entries under one mapping or items to one block sequence, and applies the same change to its document. */
+export class YamlBlockEdit {
+  constructor(text, file) {
+    this.file = file;
+    this.newline = text.includes('\r\n') ? '\r\n' : '\n';
+    this.lines = text.replace(/\r\n/g, '\n').split('\n');
+    this.document = parseYaml(text);
+    this.expected = structuredClone(this.document);
+  }
+
+  /** The parsed document as the edits leave it; mutate it in step with each text edit. */
+  get value() { return this.expected; }
+
+  /** Appends `block` (YAML lines at indent 0) as the last children of the mapping or sequence at `path`. */
+  append(path, block) {
+    const at = locate(this.lines, path, this.file);
+    const { body } = at;
+    const indent = body.to > body.from && body.childIndent !== null ? body.childIndent : at.indent + 2;
+    this.lines.splice(body.to, 0, ...indented(block, indent));
+    return this;
+  }
+
+  /** Adds `value` to the flow sequence (`key: [a, b]`) at `path`. */
+  extendFlow(path, value) {
+    const at = locate(this.lines, path, this.file);
+    const line = this.lines[at.line];
+    const flow = /^(.*:\s*\[)(.*)\](\s*)$/.exec(line);
+    if (!flow) throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${this.file} writes ${path.map(describe).join('.')} as no one-line flow sequence; add the declared Redis by hand`);
+    const items = flow[2].trim();
+    this.lines[at.line] = `${flow[1]}${items ? `${items}, ` : ''}${value}]${flow[3]}`;
+    return this;
+  }
+
+  /** The edited text, or a refusal when it does not parse to the expected document. */
+  text() {
+    const text = this.lines.join(this.newline);
+    let parsed;
+    try { parsed = parseYaml(text); } catch { parsed = undefined; }
+    if (!isDeepStrictEqual(parsed, this.expected)) throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${this.file} is not in a shape the declared Redis can be added to; add it by hand`);
+    return text;
+  }
+}

package/src/main.mjs

@@ -97,7 +97,7 @@ const USAGE = `starci app scaffold <name> [--into <dir>] [--edition full|lite] [
 starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [options] [--cwd <dir>]
 starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--format text|json] [--sonar <file>]
 starci app sync (--check | --write) [--cwd <dir>]
-starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--edition full] [--db-types] [--wiring] [--coverage-from <lcov>]
+starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--db-types] [--wiring] [--coverage-from <lcov>]
 starci app db baseline [--stamp <version>] [--local] [--apply] [--cwd <dir>]
 starci app db restamp --map <restamp.yaml> [--local] [--apply] [--cwd <dir>]
 starci app db plan [--local] [--json] [--cwd <dir>]
@@ -107,7 +107,7 @@ starci app db migrate [--execute] [--local | --linked | --url-env <NAME>] [--jso
 starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--linked | --url-env <NAME>] [--json] [--cwd <dir>]
 starci app release gate [--execute] [--source <ref>] [--tag-prefix <prefix>] [--json] [--cwd <dir>]
 starci app release push [--execute] [--remote <name>] [--json] [--cwd <dir>]
-starci app upgrade [--edition full] [--plan] [--cwd <dir>]
+starci app upgrade [--plan] [--cwd <dir>]
 starci app stack <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--cwd <dir>]
 starci app stack <prepare|doctor|connect|disconnect|build-args|render|deploy|converge|verify|rollback|prune|backup|jobs> --env <env> [--execute] [--json] [--cwd <dir>]
 starci app explain <path> [--cwd <dir>] [--json]
@@ -397,8 +397,9 @@ function explainMain(opts, { cwd: repoRoot, stdout: out }) {
   return explained.status === 'no-slot' || explained.status === 'ambiguous' ? 1 : 0;
 }
 
-function upgradeAppMain(argv, { cwd, edition, stdout, presets }) {
-  return upgradeMain(['--repo', cwd, ...(edition ? ['--edition', edition] : []), ...argv], { stdout, presets });
+async function upgradeAppMain(argv, { cwd, edition, stdout }) {
+  await checkEdition({ repoRoot: cwd, edition, normal: () => null });
+  return upgradeMain(['--repo', cwd, ...argv], { stdout });
 }
 
 /** The edition `hfs.json` declares, or undefined when it cannot be read (the test-world verbs then decide on their own). */

package/stack/deploy.mjs

@@ -1,5 +1,5 @@
 // deploy.mjs - the whole release (deployRelease) and the redeploy of a stored release (rollbackRelease).
-// deploy: render, provision, store the release record, pre-pull, `docker stack deploy`, converge, verify, accept, prune. A failure at or
+// deploy: render, provision, store the release record, pre-pull, `docker stack deploy`, converge, post-deploy tasks (deploy.postDeploy, when declared), verify, accept, prune. A failure at or
 // after the stack deploy redeploys the previous accepted release from its STORED bytes; a failure before it leaves the services untouched.
 // Without `execute` a deploy renders locally and prints the plan: NO remote call at all. A rollback cannot undo data effects.
 //
@@ -17,6 +17,7 @@ import { describeClash, edgeCollisions, reconcileEdgeAliases } from './edge-alia
 import { firstLine, tool } from './context.mjs';
 import { hasPlaceholderDigest, isReleaseId } from './digest.mjs';
 import { failure, refusal } from './errors.mjs';
+import { postDeployStack } from './post-deploy.mjs';
 import { pruneStack } from './prune.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { createReleaseStore } from './release-store.mjs';
@@ -33,6 +34,7 @@ export const DEFAULT_DEPS = Object.freeze({
   provisionRelease: lazy('./provision.mjs', 'provisionRelease'),
   convergeStack,
   reconcileEdge: reconcileEdgeAliases,
+  postDeployStack,
   verifyStack,
   pruneStack,
   releaseStore: createReleaseStore,
@@ -190,6 +192,7 @@ async function deployExecute(ctx, config, options, d, out, cleanups) {
     ['deploy', () => stackDeploy(ctx, config, path.join(out, 'stack.yaml'))],
     ['edge', async () => d.reconcileEdge(ctx, config, path.join(out, 'stack.yaml'))],
     ['converge', () => d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds })],
+    ...(config.postDeploy.length > 0 ? [['post-deploy', () => d.postDeployStack(ctx, config)]] : []),
     ['verify', () => d.verifyStack(ctx, config, { retrySeconds: options.retrySeconds, skipPublic: skipPublic === true, stackFile: path.join(out, 'stack.yaml') })],
     ...(skipPublic ? [] : [['accept', async () => { await store.accept(releaseId); return { ok: true, lines: [`accepted release ${releaseId}`] }; }]]),
   ], lines, steps);
@@ -224,9 +227,10 @@ export async function deployRelease(ctx, config, options = {}, deps = {}) {
     const rendered = await d.renderRelease(ctx, config, renderOptions(options, out, null));
     const { releaseId } = inspectRendered(out, config);
     if (options.execute !== true) {
+      const post = config.postDeploy.length > 0 ? ` post-deploy tasks (${config.postDeploy.join(', ')}),` : '';
       const plan = options.skipPublic
-        ? `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged and verified inside the stack (public hosts skipped); it would stay pending until ingress publish and stack accept`
-        : `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged, verified, accepted`;
+        ? `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} and verified inside the stack (public hosts skipped); it would stay pending until ingress publish and stack accept`
+        : `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} verified, accepted`;
       return { ok: true, lines: [...(rendered.lines ?? []), plan], data: { releaseId, steps: [{ step: 'render', ok: true }], executed: false } };
     }
     return await deployExecute(ctx, config, options, d, out, cleanups);

package/stack/post-deploy.mjs

@@ -0,0 +1,48 @@
+// post-deploy.mjs - the release tasks of a deploy (deploy.postDeploy): after the stack converged and before verification, each declared task
+// (deploy.tasks.<name>) runs in order inside the running task of its service, through the daemon of this invocation like verify's checks.
+// A post-deploy task is the place for an idempotent write a release owes the data (a catalogue sync, a seed upsert), so verification stays read-only.
+// The first task that exits non-zero, or runs past its timeout, fails the step and the deploy rolls back; a rollback cannot undo what a task wrote.
+// The deploy output carries the task's name, its exit and its line count only: the container holds decrypted secrets and the output reaches the
+// CI log, so stdout and stderr are never relayed (`starci app stack task <name>` is the operator verb that shows them).
+import { findInOrder } from '../runtime/scripts/lib/in-order.mjs';
+import { lines as splitLines, tool } from './context.mjs';
+
+/** The running container of a service on this daemon, or undefined. */
+function runningContainer(ctx, config, service) {
+  const found = tool(ctx, 'docker', ['ps', '-q', '--filter', `label=com.docker.swarm.service.name=${config.stack}_${service}`, '--filter', 'status=running']);
+  return splitLines(found.stdout)[0];
+}
+
+/** The verdict of one finished `docker exec`: a timeout, a launch failure or a non-zero exit is a failure, whatever it printed. */
+function verdictOf(run, timeoutSeconds) {
+  if (run.error?.code === 'ETIMEDOUT') return { ok: false, detail: `timed out after ${timeoutSeconds}s` };
+  if (run.error) return { ok: false, detail: 'could not run' };
+  if (run.status === null || run.status === undefined) return { ok: false, detail: 'ended without an exit status' };
+  return run.status === 0 ? { ok: true, detail: 'ok' } : { ok: false, detail: `exit ${run.status}` };
+}
+
+/** Runs one declared task; returns { name, ok, detail, outputLines }. */
+function runTask(ctx, config, name) {
+  const declared = config.tasks[name];
+  const container = runningContainer(ctx, config, declared.service);
+  if (!container) return { name, ok: false, detail: `no running container of ${config.stack}_${declared.service} on the daemon`, outputLines: 0 };
+  const run = tool(ctx, 'docker', ['exec', container, ...declared.command], { timeout: declared.timeoutSeconds * 1000, killSignal: 'SIGKILL' });
+  return { name, ...verdictOf(run, declared.timeoutSeconds), outputLines: splitLines(run.stdout).length + splitLines(run.stderr).length };
+}
+
+/**
+ * Runs the declared post-deploy tasks in order and stops at the first failure.
+ * Returns { ok, lines, data: { tasks: [{ name, ok }] } }; the lines read `PASS|FAIL  post-deploy <name>  detail (N output lines withheld)`.
+ */
+export async function postDeployStack(ctx, config) {
+  const results = [];
+  await findInOrder(config.postDeploy, async (name) => {
+    results.push(runTask(ctx, config, name));
+    return !results.at(-1).ok;
+  });
+  return {
+    ok: results.every((entry) => entry.ok),
+    lines: results.map((entry) => `${entry.ok ? 'PASS' : 'FAIL'}  post-deploy ${entry.name}  ${entry.detail} (${entry.outputLines} output line${entry.outputLines === 1 ? '' : 's'} withheld)`),
+    data: { tasks: results.map(({ name, ok }) => ({ name, ok })) },
+  };
+}

package/sync/index.mjs

@@ -150,6 +150,14 @@ function trailingNewline(text) {
   return text.slice(0, end) + '\n';
 }
 
+/** The digest-pinned image of a lite app's declared Redis, in every environment that runs it (ruling:R212/case-10). */
+export const REDIS_IMAGE = 'redis:7@sha256:c6eabf748fc7a61dbb5a705c78bcf3d6377b1127a97d0ce965c11c44ba46896f';
+
+const redisDevText = project => render(readBundled('app/package-scripts/redis-dev.json'), { project, redisImage: REDIS_IMAGE });
+
+/** The development scripts of a lite app's declared Redis (create once, then start and stop it), as a scripts object. */
+export const redisDevScripts = project => JSON.parse(`{${redisDevText(project).trim().replace(/,$/, '')}}`);
+
 /** What the app's sync reads from the jest preset it installs for its be side: the Sonar exclusions ({ sonarExclusions }); both editions install it (a lite back end keeps full's unit run, ruling:R212/case-1, amended by ruling:R212/case-4). */
 export async function loadPresets(root) {
   const name = '@starci/jest-preset';
@@ -341,6 +349,8 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     appScripts: appScripts(app, source),
     // A full upgrade keeps the app's declared Supabase connection and its local database commands.
     supabaseScripts: providers.includes('supabase') ? render(readBundled('app/package-scripts/supabase.json'), { appBinary: APP_BINARY }) : '',
+    // A lite app's declared Redis (sides.be.backing, ruling:R212/case-10) runs in development as one container of its pinned image.
+    backingScripts: lite && (app.sides.be.backing ?? []).includes('redis') ? redisDevText(app.project) : '',
     // turbo builds every fe app workspace; ^build (turbo.json) builds the packages each app imports first, and caches both.
     buildFe: 'npm run codegen --silent && turbo run build --filter=./fe/apps/*',
     // The be side with its tsc; every fe workspace with its own typecheck script through turbo (the packages are built first: ^build).

package/templates/app/ci-workflows/github/workflows/stack-deploy.yml

@@ -3,7 +3,7 @@
 # rollback and disconnect of "starci app stack". It runs by hand only (Actions > deploy stack > Run workflow) from a release tag v*
 # whose version is the package.json version; it has no push or schedule trigger.
 # operation deploy    builds and pushes one image per environments.<env>.deploy.images entry of .starcistacks/application-stacks.yaml,
-#                     then deploys their immutable digests (render, provision, converge, verify, accept; a failure redeploys the previous release)
+#                     then deploys their immutable digests (render, provision, converge, post-deploy tasks, verify, accept; a failure redeploys the previous release)
 # operation rollback  redeploys a stored release; "release" is 16 lowercase hex characters, empty means the previous accepted release
 # The environment input names a protected GitHub environment (required reviewers) that holds:
 #   vars    VPS_HOST, VPS_USER (the swarm manager); a variable named in deploy.passEnv, when the stack interpolates one

package/templates/app/ci-workflows-lite/github/workflows/stack-deploy.yml

@@ -3,7 +3,7 @@
 # rollback and disconnect of "starci app stack". It runs by hand only (Actions > deploy stack > Run workflow) from a release tag v*
 # whose version is the package.json version; it has no push or schedule trigger.
 # operation deploy    builds and pushes one image per environments.<env>.deploy.images entry of .starcistacks/application-stacks.yaml,
-#                     then deploys their immutable digests (render, provision, converge, verify, accept; a failure redeploys the previous release)
+#                     then deploys their immutable digests (render, provision, converge, post-deploy tasks, verify, accept; a failure redeploys the previous release)
 # operation rollback  redeploys a stored release; "release" is 16 lowercase hex characters, empty means the previous accepted release
 # The environment input names a protected GitHub environment (required reviewers) that holds:
 #   vars    VPS_HOST, VPS_USER (the swarm manager); a variable named in deploy.passEnv, when the stack interpolates one

package/templates/app/codegen-graphql.mjs.partial

@@ -1,36 +1,66 @@
 // GraphQL wire types, the same in both editions (owner ruling 2026-10-13): every fe app with operations under
-// src/modules/api/graphql/{queries,mutations} gets its typed documents generated from the contract snapshots the back end emits
+// src/modules/api/graphql/{queries,mutations,subscriptions} gets its typed documents generated from the contract snapshots the back end emits
 // (be/contracts/<app>/schema.graphql, `npm run contract:emit`) into the gitignored src/modules/api/graphql/__generated__/.
+// The input-bounds output carries the backend validators into translated form schemas through modules/api.
 // Nothing to generate (no snapshot yet, or no fe app with a modules/api/graphql folder) is not an error.
 const CONTRACTS = path.join("be", "contracts")
 const FE_APPS = path.join("fe", "apps")
 const posix = (file) => file.split(path.sep).join("/")
-const schemas = (fs.existsSync(CONTRACTS) ? fs.readdirSync(CONTRACTS) : [])
+const services = (fs.existsSync(CONTRACTS) ? fs.readdirSync(CONTRACTS) : []).sort(byCodeUnit)
+const frontendApps = (fs.existsSync(FE_APPS) ? fs.readdirSync(FE_APPS) : []).sort(byCodeUnit)
+const schemas = services
     .map((app) => path.join(CONTRACTS, app, "schema.graphql"))
     .filter((file) => fs.existsSync(file))
     .sort(byCodeUnit)
     .map(posix)
-const operationRoots = (fs.existsSync(FE_APPS) ? fs.readdirSync(FE_APPS) : [])
+const operationRoots = frontendApps
     .map((app) => path.join(FE_APPS, app, "src", "modules", "api", "graphql"))
     .filter((dir) => fs.existsSync(dir))
     .sort(byCodeUnit)
     .map(posix)
+const writeFormBounds = (roots, source) => {
+    for (const root of roots) {
+        const generated = `${root}/__generated__`
+        fs.mkdirSync(generated, { recursive: true })
+        fs.writeFileSync(`${generated}/input-bounds.ts`, source)
+    }
+}
 if (schemas.length === 0 || operationRoots.length === 0) {
     process.stdout.write("codegen: no GraphQL contract under be/contracts yet\n")
+    if (schemas.length === 0 && operationRoots.length) {
+        const { emptyInputBoundsSource } = await import("@starci/cli/input-bounds")
+        writeFormBounds(operationRoots, emptyInputBoundsSource())
+    }
 } else {
+    const { buildSchema } = await import("graphql")
+    const { assertCompatibleInputBounds } = await import("@starci/cli/input-bounds")
+    assertCompatibleInputBounds(
+        Object.fromEntries(schemas.map((file) => [file, buildSchema(fs.readFileSync(file, "utf8"))])),
+    )
     const { generate } = await import("@graphql-codegen/cli")
     const generates = Object.fromEntries(
-        operationRoots.map((root) => [
-            `${root}/__generated__/`,
-            {
-                preset: "client",
-                documents: [`${root}/queries/*.ts`, `${root}/mutations/*.ts`],
-                presetConfig: { fragmentMasking: false },
-                config: { useTypeImports: true, enumsAsTypes: true, avoidOptionals: true },
-            },
+        operationRoots.flatMap((root) => [
+            [
+                `${root}/__generated__/`,
+                {
+                    preset: "client",
+                    documents: [`${root}/queries/*.ts`, `${root}/mutations/*.ts`, `${root}/subscriptions/*.ts`],
+                    presetConfig: { fragmentMasking: false },
+                    config: { useTypeImports: true, enumsAsTypes: true, avoidOptionals: true },
+                },
+            ],
+            [`${root}/__generated__/input-bounds.ts`, { plugins: [{ "@starci/cli/input-bounds": {} }] }],
         ]),
     )
-    await generate({ schema: schemas, generates, ignoreNoDocuments: true, silent: true }, true)
+    await generate(
+        {
+            schema: schemas,
+            generates,
+            ignoreNoDocuments: true,
+            silent: true,
+        },
+        true,
+    )
     // Stamp only a successful generation, using the same sorted paths and LF-normalized schemas as R52.
     const hash = createHash("sha256")
     for (const schema of schemas) {
@@ -43,3 +73,20 @@ if (schemas.length === 0 || operationRoots.length === 0) {
         if (fs.existsSync(generated)) fs.writeFileSync(`${generated}/.schema-sha256`, `${digest}\n`)
     }
 }
+
+// REST forms consume the same backend DTO bounds through their API owner's generated output, even without GraphQL.
+const restRoots = frontendApps
+    .map((app) => path.join(FE_APPS, app, "src", "modules", "api", "rest"))
+    .filter((dir) => fs.existsSync(dir))
+    .map(posix)
+if (restRoots.length) {
+    const { openApiBoundsSource } = await import("@starci/cli/input-bounds")
+    const contracts = Object.fromEntries(
+        services
+            .map((service) => [service, path.join(CONTRACTS, service, "openapi.json")])
+            .filter(([, file]) => fs.existsSync(file))
+            .map(([service, file]) => [service, JSON.parse(fs.readFileSync(file, "utf8"))]),
+    )
+    // Generate an empty map when a contract disappears so stale form limits cannot survive a successful codegen.
+    writeFormBounds(restRoots, openApiBoundsSource(contracts))
+}

package/templates/app/hooks/husky/pre-commit

@@ -1,7 +1,7 @@
 {{header}}
 # Commit gate (L0 only): work hygiene, the secrets guard and the bypass guard (no inline disable, type-check escape, skipped test or
 # swallowed failure: HFS_BYPASS_MARKER) of the staged files, managed files equal to their render, eslint of the staged files of each
-# side, stylelint over the staged CSS of fe, a prettier check of the staged files. Every step ends the hook when it fails: none can be
+# side (the fe packages are built first: the apps import their emitted types, the way the managed lint script does), stylelint over the staged CSS of fe, a prettier check of the staged files. Every step ends the hook when it fails: none can be
 # skipped. Types and the targeted specs belong to the op gate.
 npx starci app hygiene || exit $?
 npx starci app sync --check || exit $?
@@ -9,7 +9,7 @@ npx starci app sync --check || exit $?
 git diff --cached --name-only --diff-filter=ACMR -z --relative=be -- '*.ts' '*.mts' '*.cts' '*.js' '*.mjs' '*.cjs' |
   xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then cd be && npx eslint -- "$@"; fi' sh || exit $?
 git diff --cached --name-only --diff-filter=ACMR -z --relative=fe -- '*.ts' '*.tsx' '*.mts' '*.cts' '*.js' '*.jsx' '*.mjs' '*.cjs' |
-  xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then cd fe && npx eslint --max-warnings=0 --no-warn-ignored -- "$@"; fi' sh || exit $?
+  xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then if [ -d fe/packages ]; then npx turbo run build --filter="./fe/packages/*" --output-logs=errors-only || exit $?; fi; cd fe && npx eslint --max-warnings=0 --no-warn-ignored -- "$@"; fi' sh || exit $?
 git diff --cached --name-only --diff-filter=ACMR -z --relative=fe -- '*.css' |
   xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then cd fe && npx stylelint "$@"; fi' sh || exit $?
 git diff --cached --name-only --diff-filter=ACMR -z |

package/templates/app/hooks/husky/pre-push

@@ -3,7 +3,8 @@
 # backs work up under refs/backup/*. Git hands this hook one line per ref: <local ref> <local sha> <remote ref> <remote sha>.
 #   refs/backup/*                  allowed: the coordinator backup namespace
 #   refs/heads/main, refs/tags/v*  allowed only when HEAD carries an annotated tag v[0-9]* and the release cut recorded the
-#                                  full suite of HEAD: <git common dir>/starci-release/<HEAD sha>.l4.json names that head and tag
+#                                  full suite of HEAD: <git common dir>/starci-release/<HEAD sha>.l4.json names that head and tag;
+#                                  a pushed tag must be that tag and must point at HEAD
 #   refs/heads/release/candidate-* the release candidate (starci app release push sends the release sha there first and moves main
 #                                  and the tag only when its ci.yml run is green): allowed under the same release gate, never deleted
 #   any other ref, a delete        refused
@@ -13,6 +14,7 @@ head=$(git rev-parse HEAD)
 record="$common/starci-release/$head.l4.json"
 status=0
 gate=""
+gate_tag=""
 refuse() {
   echo "RIGHTS_PUSH_NOT_RELEASE: $1 - the allowed path is the release cut (main, v* tags and the release/candidate-* ref) or refs/backup/* (backups)" >&2
   status=1
@@ -28,7 +30,7 @@ release_gate() {
     if [ ! -f "$record" ]; then gate="no L4 record $record"; continue; fi
     flat=$(tr -d ' \t\r\n' < "$record")
     case "$flat" in
-      *'"head":"'"$head"'"'*'"tag":"'"$tag"'"'* | *'"tag":"'"$tag"'"'*'"head":"'"$head"'"'*) gate="ok"; return 0 ;;
+      *'"head":"'"$head"'"'*'"tag":"'"$tag"'"'* | *'"tag":"'"$tag"'"'*'"head":"'"$head"'"'*) gate="ok"; gate_tag="$tag"; return 0 ;;
     esac
     gate="the L4 record $record does not name head $head and tag $tag"
   done
@@ -43,7 +45,12 @@ while read -r local_ref local_sha remote_ref remote_sha; do
         *) refuse "refusing to delete $remote_ref"; continue ;;
       esac
       release_gate
-      if [ "$gate" != "ok" ]; then refuse "$remote_ref is closed: $gate"; fi ;;
+      if [ "$gate" != "ok" ]; then refuse "$remote_ref is closed: $gate"; continue; fi
+      case "$remote_ref" in
+        refs/tags/*)
+          if [ "$remote_ref" != "refs/tags/$gate_tag" ]; then refuse "$remote_ref is not the release tag $gate_tag of HEAD $head"
+          elif [ "$(git rev-parse "$local_sha^{commit}" 2>/dev/null)" != "$head" ]; then refuse "$remote_ref does not point at HEAD $head"; fi ;;
+      esac ;;
     *) refuse "refusing to push $remote_ref" ;;
   esac
 done

package/templates/app/package-scripts/redis-dev.json

@@ -0,0 +1,3 @@
+    "redis:create": "docker create --name {{project}}-dev-redis -p 127.0.0.1:6379:6379 -v {{project}}-dev-redis-data:/data {{redisImage}} redis-server --appendonly yes",
+    "redis:start": "docker start {{project}}-dev-redis",
+    "redis:stop": "docker stop {{project}}-dev-redis",

package/templates/app/package-scripts-lite/package.json

@@ -7,6 +7,7 @@
     "test": "cd be && jest --selectProjects unit --coverage",
     "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
 {{> app/package-scripts/supabase.json}}
+{{backingScripts}}
     "contract:emit": "{{appBinary}} emit"
   }
 }