@starci/hfs 4.11.22 → 4.12.0

package/scaffold/add-queue-lite.mjs

@@ -17,111 +17,104 @@ import { bundledPins } from '../runtime/scripts/hfs/canon-pins.mjs';
 import { registerLiteExports } from './lite-exports.mjs';
 import { ScaffoldError } from './service.mjs';
 import { YamlBlockEdit } from './yaml-block-edit.mjs';
-
 /** The pattern topics whose lite templates this package carries; `starci app add` refuses the other lite-adapted topics. */
 export const LITE_TEMPLATED_TOPICS = Object.freeze(['jobs', 'queues']);
-
 const LITE_TEMPLATES = Object.freeze({
-  'queues/platform/queue.index.ts.tpl': 'queues/platform-lite/queue.index.ts.tpl',
-  'queues/platform/queue.options.ts.tpl': 'queues/platform-lite/queue.options.ts.tpl',
-  'queues/platform/queue.config.ts.tpl': 'queues/platform-lite/queue.config.ts.tpl',
-  'queues/platform/bullmq-queue-transport.client.ts.tpl': 'queues/platform-lite/bullmq-queue-transport.client.ts.tpl',
-  'queues/platform/bullmq-queue-transport.client.spec.ts.tpl': 'queues/platform-lite/bullmq-queue-transport.client.spec.ts.tpl',
-  'queues/platform/queue-transport.port.ts.tpl': 'queues/platform-lite/queue-transport.port.ts.tpl',
-  // The error family also refuses a mark Redis has not persisted (QUEUE_NOT_PERSISTED, QUEUE_JOB_LOST): R276 runs the lite Redis with AOF.
-  'queues/platform/errors/queue.error.ts.tpl': 'queues/platform-lite/queue.error.ts.tpl',
-  'queues/platform/messages/queue.messages.ts.tpl': 'queues/platform-lite/queue.messages.ts.tpl',
-  'queues/platform/queue-relay.service.ts.tpl': 'queues/platform-lite/queue-relay.service.ts.tpl',
-  'queues/platform/queue-relay.service.spec.ts.tpl': 'queues/platform-lite/queue-relay.service.spec.ts.tpl',
-  'queues/platform/queue.module.ts.tpl': 'queues/platform-lite/queue.module.ts.tpl',
-  'queues/platform/queue-outbox.service.ts.tpl': 'queues/platform-lite/queue-outbox.service.ts.tpl',
-  'queues/platform/queue-outbox.service.spec.ts.tpl': 'queues/platform-lite/queue-outbox.service.spec.ts.tpl',
-  'jobs/platform/jobs.index.ts.tpl': 'jobs/platform-lite/jobs.index.ts.tpl',
-  'jobs/platform/job-claim.service.ts.tpl': 'jobs/platform-lite/job-claim.service.ts.tpl',
-  'jobs/platform/job-claim.service.spec.ts.tpl': 'jobs/platform-lite/job-claim.service.spec.ts.tpl',
-  // The jobs module composes the one tick scheduler (R335, ruling:lite-official-postgres-image): ScheduleModule.forRoot() and JobTickService.
-  'jobs/platform/jobs.module.ts.tpl': 'jobs/platform-lite/jobs.module.ts.tpl',
+    'queues/platform/queue.index.ts.tpl': 'queues/platform-lite/queue.index.ts.tpl',
+    'queues/platform/queue.options.ts.tpl': 'queues/platform-lite/queue.options.ts.tpl',
+    'queues/platform/queue.config.ts.tpl': 'queues/platform-lite/queue.config.ts.tpl',
+    'queues/platform/bullmq-queue-transport.client.ts.tpl': 'queues/platform-lite/bullmq-queue-transport.client.ts.tpl',
+    'queues/platform/bullmq-queue-transport.client.spec.ts.tpl': 'queues/platform-lite/bullmq-queue-transport.client.spec.ts.tpl',
+    'queues/platform/queue-transport.port.ts.tpl': 'queues/platform-lite/queue-transport.port.ts.tpl',
+    // The error family also refuses a mark Redis has not persisted (QUEUE_NOT_PERSISTED, QUEUE_JOB_LOST): R276 runs the lite Redis with AOF.
+    'queues/platform/errors/queue.error.ts.tpl': 'queues/platform-lite/queue.error.ts.tpl',
+    'queues/platform/messages/queue.messages.ts.tpl': 'queues/platform-lite/queue.messages.ts.tpl',
+    'queues/platform/queue-relay.service.ts.tpl': 'queues/platform-lite/queue-relay.service.ts.tpl',
+    'queues/platform/queue-relay.service.spec.ts.tpl': 'queues/platform-lite/queue-relay.service.spec.ts.tpl',
+    'queues/platform/queue.module.ts.tpl': 'queues/platform-lite/queue.module.ts.tpl',
+    'queues/platform/queue-outbox.service.ts.tpl': 'queues/platform-lite/queue-outbox.service.ts.tpl',
+    'queues/platform/queue-outbox.service.spec.ts.tpl': 'queues/platform-lite/queue-outbox.service.spec.ts.tpl',
+    'jobs/platform/jobs.index.ts.tpl': 'jobs/platform-lite/jobs.index.ts.tpl',
+    'jobs/platform/job-claim.service.ts.tpl': 'jobs/platform-lite/job-claim.service.ts.tpl',
+    'jobs/platform/job-claim.service.spec.ts.tpl': 'jobs/platform-lite/job-claim.service.spec.ts.tpl',
+    // The jobs module composes the one tick scheduler (R335, ruling:lite-official-postgres-image): ScheduleModule.forRoot() and JobTickService.
+    'jobs/platform/jobs.module.ts.tpl': 'jobs/platform-lite/jobs.module.ts.tpl',
 });
-
 /** The tick scheduler of platform/jobs the lite jobs capability adds beside full's tree: the ticks as data, the scheduler and its spec (R335). */
 const TICK_FILES = Object.freeze([
-  ['be/src/modules/platform/jobs/job-ticks.contracts.ts', 'jobs/platform-lite/job-ticks.contracts.ts.tpl'],
-  ['be/src/modules/platform/jobs/job-tick.service.ts', 'jobs/platform-lite/job-tick.service.ts.tpl'],
-  ['be/src/modules/platform/jobs/job-tick.service.spec.ts', 'jobs/platform-lite/job-tick.service.spec.ts.tpl'],
+    ['be/src/modules/platform/jobs/job-ticks.contracts.ts', 'jobs/platform-lite/job-ticks.contracts.ts.tpl'],
+    ['be/src/modules/platform/jobs/job-tick.service.ts', 'jobs/platform-lite/job-tick.service.ts.tpl'],
+    ['be/src/modules/platform/jobs/job-tick.service.spec.ts', 'jobs/platform-lite/job-tick.service.spec.ts.tpl'],
 ]);
-
 /** The tick files of a jobs capability the verb adds for the first time; an app that already has platform/jobs keeps its own. */
 function tickFiles({ beRoot, patterns }) {
-  if (!patterns.includes('fenced-job') || fs.existsSync(path.join(beRoot, 'src', 'modules', 'platform', 'jobs', 'index.ts'))) return [];
-  return TICK_FILES.map(([relative, source]) => ({ relative, text: template(`be/patterns/${source}`) }));
+    if (!patterns.includes('fenced-job') || fs.existsSync(path.join(beRoot, 'src', 'modules', 'platform', 'jobs', 'index.ts')))
+        return [];
+    return TICK_FILES.map(([relative, source]) => ({ relative, text: template(`be/patterns/${source}`) }));
 }
-
 /**
  * The persistence files lite leaves out: the TypeORM schema (its authority is db/migrations) and the SQL text and row files (the
  * statements are database functions of the lite migration, called through callDbFunction; R334 and the be.persistence lite overlay).
  */
 const TYPEORM_ONLY = /\/persistence\/(?:connection\.ts$|entities\/|migrations\/|[^/]+\.(?:sql|rows)\.ts$)/;
-
 /** The e2e proof slot lite forbids (R212); a lite pattern proves itself with optional integration specs (the topic's liteAdapter proof). */
 const E2E_SLOT = 'be.tests.e2e';
-
 /**
  * The lite entries of a queue or jobs topic tree: no TypeORM schema file or e2e proof, and the lite body where the package carries one.
  */
 export const selectLiteQueueEntries = (topic, entries) => (LITE_TEMPLATED_TOPICS.includes(topic)
-  ? [...entries.filter((entry) => !TYPEORM_ONLY.test(entry.path) && entry.slot !== E2E_SLOT)
-    .map((entry) => (LITE_TEMPLATES[entry.template] ? { ...entry, template: LITE_TEMPLATES[entry.template] } : entry))]
-  : entries);
-
+    ? [...entries.filter((entry) => !TYPEORM_ONLY.test(entry.path) && entry.slot !== E2E_SLOT)
+            .map((entry) => {
+            const lite = entry.template === undefined ? undefined : LITE_TEMPLATES[entry.template];
+            return lite ? { ...entry, template: lite } : entry;
+        })]
+    : entries);
 const MIGRATION = /^(\d{14})_[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.sql$/;
 const REDIS_PURPOSE = 'The declared Redis of the queue (hfs.json sides.be.backing) - one instance with AOF persistence (appendonly yes) on the named volume redis-data, on the internal backing network only, reached by the api and worker services as redis:6379 with the password of its sealed secret.';
 const MEMBER = 'redis-password';
 const quoted = (value) => JSON.stringify(value);
 const read = (file) => fs.readFileSync(file, 'utf8');
 const template = (relative) => read(path.join(TEMPLATES_DIR, ...relative.split('/'))).replace(/\r\n/g, '\n');
-
 const DATABASE_ERROR = 'be/src/modules/platform/database/errors/database.error.ts';
-
 /** Skeleton files the lite starter leaves out and the queue capabilities use, each from its skeleton template. */
 const SKELETON_FILES = Object.freeze([
-  ['be/src/modules/platform/database/database.client.ts', 'skeleton-lite/src/modules/platform/database/database.client.ts'],
-  ['be/src/modules/platform/database/database.client.spec.ts', 'skeleton-lite/src/modules/platform/database/database.client.spec.ts'],
-  ['be/src/modules/platform/database/database.sql.ts', 'skeleton-lite/src/modules/platform/database/database.sql.ts'],
-  ['be/src/modules/platform/primitives/sequence.policy.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.ts'],
-  ['be/src/modules/platform/primitives/sequence.policy.spec.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.spec.ts'],
+    ['be/src/modules/platform/database/database.client.ts', 'skeleton-lite/src/modules/platform/database/database.client.ts'],
+    ['be/src/modules/platform/database/database.client.spec.ts', 'skeleton-lite/src/modules/platform/database/database.client.spec.ts'],
+    ['be/src/modules/platform/database/database.sql.ts', 'skeleton-lite/src/modules/platform/database/database.sql.ts'],
+    ['be/src/modules/platform/primitives/sequence.policy.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.ts'],
+    ['be/src/modules/platform/primitives/sequence.policy.spec.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.spec.ts'],
 ]);
-
 /** The database-function call and the sql tag of the outbox and claim statements (with its identifier error) and the in-order relay the queue adapters walk their rows with. */
 function skeletonFiles(repoRoot) {
-  const created = SKELETON_FILES.filter(([relative]) => !fs.existsSync(path.join(repoRoot, ...relative.split('/'))))
-    .map(([relative, source]) => ({ relative, text: render(template(`be/${source}`), {}) }));
-  const errorFile = path.join(repoRoot, ...DATABASE_ERROR.split('/'));
-  const before = fs.existsSync(errorFile) ? read(errorFile).replace(/\r\n/g, '\n') : null;
-  const after = before === null ? null : withSqlIdentifierError(before);
-  return { created, patches: after === before ? [] : [{ file: errorFile, text: after }] };
+    const created = SKELETON_FILES.filter(([relative]) => !fs.existsSync(path.join(repoRoot, ...relative.split('/'))))
+        .map(([relative, source]) => ({ relative, text: render(template(`be/${source}`), {}) }));
+    const errorFile = path.join(repoRoot, ...DATABASE_ERROR.split('/'));
+    const before = fs.existsSync(errorFile) ? read(errorFile).replace(/\r\n/g, '\n') : null;
+    const after = before === null ? null : withSqlIdentifierError(before);
+    return { created, patches: after !== null && after !== before ? [{ file: errorFile, text: after }] : [] };
 }
-
 /** The capability tables a platform capability the verb adds for the first time needs, as one forward-only db migration. */
 function migrationFiles({ repoRoot, beRoot, patterns, now }) {
-  const sections = [
-    ['queue-outbox', 'queue', 'queues/platform-lite/queue-outbox.sql.tpl', 'queue'],
-    ['jobs', 'fenced-job', 'jobs/platform-lite/jobs.sql.tpl', 'jobs'],
-  ].filter(([, pattern, , capability]) => patterns.includes(pattern) && !fs.existsSync(path.join(beRoot, 'src', 'modules', 'platform', capability, 'index.ts')));
-  if (!sections.length) return [];
-  const folder = path.join(repoRoot, 'db', 'migrations');
-  const migrations = fs.existsSync(folder) ? fs.readdirSync(folder).filter((file) => MIGRATION.test(file)).sort(byCodeUnit) : [];
-  const stamp = new Date(now()).toISOString().replace(/\D/g, '').slice(0, 14);
-  const latest = migrations.at(-1)?.slice(0, 14);
-  if (latest && stamp <= latest) throw new ScaffoldError('HFS_ADD_MIGRATION_ORDER', `the current UTC timestamp ${stamp} is not later than the latest migration ${latest}; fix the clock or wait for the next second`);
-  const text = sections.map(([, , source]) => template(`be/patterns/${source}`)).join('\n');
-  return [{ relative: `db/migrations/${stamp}_${sections.map(([name]) => name).join('-')}.sql`, text }];
+    const candidates = [
+        ['queue-outbox', 'queue', 'queues/platform-lite/queue-outbox.sql.tpl', 'queue'],
+        ['jobs', 'fenced-job', 'jobs/platform-lite/jobs.sql.tpl', 'jobs'],
+    ];
+    const sections = candidates.filter(([, pattern, , capability]) => patterns.includes(pattern) && !fs.existsSync(path.join(beRoot, 'src', 'modules', 'platform', capability, 'index.ts')));
+    if (!sections.length)
+        return [];
+    const folder = path.join(repoRoot, 'db', 'migrations');
+    const migrations = fs.existsSync(folder) ? fs.readdirSync(folder).filter((file) => MIGRATION.test(file)).sort(byCodeUnit) : [];
+    const stamp = new Date(now()).toISOString().replace(/\D/g, '').slice(0, 14);
+    const latest = migrations.at(-1)?.slice(0, 14);
+    if (latest && stamp <= latest)
+        throw new ScaffoldError('HFS_ADD_MIGRATION_ORDER', `the current UTC timestamp ${stamp} is not later than the latest migration ${latest}; fix the clock or wait for the next second`);
+    const text = sections.map(([, , source]) => template(`be/patterns/${source}`)).join('\n');
+    return [{ relative: `db/migrations/${stamp}_${sections.map(([name]) => name).join('-')}.sql`, text }];
 }
-
 /** The queue imports bullmq, which loads ioredis as an optional peer and cannot connect without it. */
 const QUEUE_CLIENTS = Object.freeze(['bullmq', 'ioredis']);
 /** The jobs capability's tick scheduler imports @nestjs/schedule and its CronJob (R335). */
 const SCHEDULER_CLIENTS = Object.freeze(['@nestjs/schedule', 'cron']);
-
 /**
  * hfs.json declares redis in sides.be.backing; the package.json gains the queue's clients (and, for fenced-job, the tick
  * scheduler's) at their canon pins, and the managed
@@ -129,22 +122,23 @@ const SCHEDULER_CLIENTS = Object.freeze(['@nestjs/schedule', 'cron']);
  * earlier capability declared (a cache on ioredis) still gains bullmq; a file already complete is left alone.
  */
 function declarationPatches(repoRoot, project, patterns) {
-  const file = path.join(repoRoot, 'hfs.json');
-  const declaration = JSON.parse(read(file));
-  declaration.sides.be.backing = [...new Set([...(declaration.sides.be.backing ?? []), 'redis'])].sort(byCodeUnit);
-  const packageFile = path.join(repoRoot, 'package.json');
-  const pkg = JSON.parse(read(packageFile));
-  const pins = bundledPins();
-  const clients = [...QUEUE_CLIENTS, ...(patterns.includes('fenced-job') ? SCHEDULER_CLIENTS : [])];
-  const missing = clients.filter((name) => typeof pkg.dependencies?.[name] !== 'string');
-  for (const name of missing) if (!pins[name]) throw new ScaffoldError('HFS_SCAFFOLD_PIN_MISSING', `${name} has no canon pin in knowledge/hfs/canon-pins.yaml`);
-  if (missing.length)
-    pkg.dependencies = Object.fromEntries(Object.entries({ ...pkg.dependencies, ...Object.fromEntries(missing.map((name) => [name, pins[name].version])) }).sort(([a], [b]) => a.localeCompare(b)));
-  pkg.scripts = { ...pkg.scripts, ...redisDevScripts(project) };
-  return [{ file, text: jsonText(declaration) }, { file: packageFile, text: packageJsonText(pkg) }]
-    .filter((patch) => patch.text !== read(patch.file));
+    const file = path.join(repoRoot, 'hfs.json');
+    const declaration = JSON.parse(read(file));
+    declaration.sides.be.backing = [...new Set([...(declaration.sides.be.backing ?? []), 'redis'])].sort(byCodeUnit);
+    const packageFile = path.join(repoRoot, 'package.json');
+    const pkg = JSON.parse(read(packageFile));
+    const pins = bundledPins();
+    const clients = [...QUEUE_CLIENTS, ...(patterns.includes('fenced-job') ? SCHEDULER_CLIENTS : [])];
+    const missing = clients.filter((name) => typeof pkg.dependencies?.[name] !== 'string');
+    for (const name of missing)
+        if (!pins[name])
+            throw new ScaffoldError('HFS_SCAFFOLD_PIN_MISSING', `${name} has no canon pin in knowledge/hfs/canon-pins.yaml`);
+    if (missing.length)
+        pkg.dependencies = Object.fromEntries(Object.entries({ ...pkg.dependencies, ...Object.fromEntries(missing.map((name) => [name, pins[name]?.version])) }).sort(([a], [b]) => a.localeCompare(b)));
+    pkg.scripts = { ...pkg.scripts, ...redisDevScripts(project) };
+    return [{ file, text: jsonText(declaration) }, { file: packageFile, text: packageJsonText(pkg) }]
+        .filter((patch) => patch.text !== read(patch.file));
 }
-
 const redisComponent = `redis:
   role: stateful
   image: ${REDIS_IMAGE}
@@ -153,239 +147,245 @@ const redisComponent = `redis:
   purpose: ${quoted(REDIS_PURPOSE)}
   required: true
 `;
-
 /** The back-end app kinds that run the queue (its relay, workers and schedulers); a cli app only writes the outbox. */
 const QUEUE_APP_KINDS = Object.freeze(['api', 'worker']);
-
 /** The stack services of the back-end apps that run the queue: each reaches the declared Redis. */
 const queueServicesOf = (repo) => (repo.sides?.be?.apps ?? []).filter((app) => QUEUE_APP_KINDS.includes(app.kind)).map((app) => app.name);
-
 /** The application-stacks.yaml additions of one docker-swarm environment, applied to its text and to its document. */
 function declareEnvironment(edit, name, environment, { project, consumers }) {
-  const model = edit.value.environments[name];
-  edit.append(['environments', name, 'components'], 'redis: {replicas: 1, port: 6379}\n');
-  model.components.redis = { replicas: 1, port: 6379 };
-  const [backup] = environment.backup ?? [];
-  const recovery = `.starcistacks/${name}/infra/swarm/recovery/redis.yaml`;
-  const entry = { component: 'redis', target: 'Owner-provisioned encrypted off-host storage for the Redis volume (its AOF and RDB files)', retention: backup?.retention ?? 'Thirty daily snapshots', owner: backup?.owner ?? 'Product operator', restoreProof: recovery };
-  edit.append(['environments', name, 'backup'], `- component: redis\n  target: ${quoted(entry.target)}\n  retention: ${quoted(entry.retention)}\n  owner: ${quoted(entry.owner)}\n  restoreProof: ${entry.restoreProof}\n`);
-  model.backup.push(entry);
-  const [secret] = environment.secrets ?? [];
-  const runtimeName = `${project}-${name}-${MEMBER}-v1`;
-  const member = { name: MEMBER, runtimeName, version: 1, where: `secrets/${MEMBER}`, recipientPolicy: secret?.recipientPolicy ?? "This app's own age recipient configured in .sops.yaml", keyCustody: secret?.keyCustody ?? "SOPS_AGE_KEY in the host's untracked .claude/secret.env" };
-  edit.append(['environments', name, 'secrets'], `- name: ${MEMBER}\n  runtimeName: ${quoted(runtimeName)}\n  version: 1\n  where: secrets/${MEMBER}\n  recipientPolicy: ${quoted(member.recipientPolicy)}\n  keyCustody: ${quoted(member.keyCustody)}\n`);
-  model.secrets.push(member);
-  const deploy = environment.deploy;
-  if (Array.isArray(deploy?.volumes)) {
-    edit.append(['environments', name, 'deploy', 'volumes'], `- ${quoted(`${project}-${name}-redis-data`)}\n`);
-    model.deploy.volumes.push(`${project}-${name}-redis-data`);
-  }
-  const grants = deploy?.secrets?.grants;
-  if (Array.isArray(grants)) {
-    for (const service of [...consumers, 'redis']) {
-      const at = grants.findIndex((grant) => grant?.service === service);
-      if (at >= 0) {
-        edit.append(['environments', name, 'deploy', 'secrets', 'grants', { item: 'service', is: service }, 'from'], `- member: ${MEMBER}\n`);
-        model.deploy.secrets.grants[at].from.push({ member: MEMBER });
-      } else {
-        edit.append(['environments', name, 'deploy', 'secrets', 'grants'], `- service: ${service}\n  from:\n    - member: ${MEMBER}\n`);
-        model.deploy.secrets.grants.push({ service, from: [{ member: MEMBER }] });
-      }
+    const model = edit.value.environments[name];
+    edit.append(['environments', name, 'components'], 'redis: {replicas: 1, port: 6379}\n');
+    model.components.redis = { replicas: 1, port: 6379 };
+    const [backup] = environment.backup ?? [];
+    const recovery = `.starcistacks/${name}/infra/swarm/recovery/redis.yaml`;
+    const entry = { component: 'redis', target: 'Owner-provisioned encrypted off-host storage for the Redis volume (its AOF and RDB files)', retention: backup?.retention ?? 'Thirty daily snapshots', owner: backup?.owner ?? 'Product operator', restoreProof: recovery };
+    edit.append(['environments', name, 'backup'], `- component: redis\n  target: ${quoted(entry.target)}\n  retention: ${quoted(entry.retention)}\n  owner: ${quoted(entry.owner)}\n  restoreProof: ${entry.restoreProof}\n`);
+    model.backup.push(entry);
+    const [secret] = environment.secrets ?? [];
+    const runtimeName = `${project}-${name}-${MEMBER}-v1`;
+    const member = { name: MEMBER, runtimeName, version: 1, where: `secrets/${MEMBER}`, recipientPolicy: secret?.recipientPolicy ?? "This app's own age recipient configured in .sops.yaml", keyCustody: secret?.keyCustody ?? "SOPS_AGE_KEY in the host's untracked .claude/secret.env" };
+    edit.append(['environments', name, 'secrets'], `- name: ${MEMBER}\n  runtimeName: ${quoted(runtimeName)}\n  version: 1\n  where: secrets/${MEMBER}\n  recipientPolicy: ${quoted(member.recipientPolicy)}\n  keyCustody: ${quoted(member.keyCustody)}\n`);
+    model.secrets.push(member);
+    const deploy = environment.deploy;
+    if (Array.isArray(deploy?.volumes)) {
+        edit.append(['environments', name, 'deploy', 'volumes'], `- ${quoted(`${project}-${name}-redis-data`)}\n`);
+        model.deploy.volumes.push(`${project}-${name}-redis-data`);
     }
-  }
-  return { recovery, runtimeName };
+    const grants = deploy?.secrets?.grants;
+    if (Array.isArray(grants)) {
+        for (const service of [...consumers, 'redis']) {
+            const at = grants.findIndex((grant) => grant?.service === service);
+            if (at >= 0) {
+                edit.append(['environments', name, 'deploy', 'secrets', 'grants', { item: 'service', is: service }, 'from'], `- member: ${MEMBER}\n`);
+                model.deploy.secrets.grants[at].from.push({ member: MEMBER });
+            }
+            else {
+                edit.append(['environments', name, 'deploy', 'secrets', 'grants'], `- service: ${service}\n  from:\n    - member: ${MEMBER}\n`);
+                model.deploy.secrets.grants.push({ service, from: [{ member: MEMBER }] });
+            }
+        }
+    }
+    return { recovery, runtimeName };
 }
-
 /** The services of one Swarm model that run the queue; a model with none of them cannot reach the Redis it would gain. */
 function queueServicesIn(file, relative, consumers) {
-  const services = parseYaml(read(file))?.services ?? {};
-  const present = consumers.filter((name) => services[name]);
-  if (!present.length) throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${relative} has no service of a back-end api or worker app (${consumers.join(', ') || 'none declared'}); add the declared Redis by hand`);
-  return present;
+    const services = parseYaml(read(file))?.services ?? {};
+    const present = consumers.filter((name) => services[name]);
+    if (!present.length)
+        throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${relative} has no service of a back-end api or worker app (${consumers.join(', ') || 'none declared'}); add the declared Redis by hand`);
+    return present;
 }
-
 const QUEUE_ENVIRONMENT = Object.freeze({ QUEUE_REDIS_HOST: 'redis', QUEUE_REDIS_PORT: '6379', QUEUE_REDIS_PASSWORD_FILE: `/run/secrets/${MEMBER}` });
 const QUEUE_ENVIRONMENT_TEXT = `QUEUE_REDIS_HOST: redis\nQUEUE_REDIS_PORT: "6379"\nQUEUE_REDIS_PASSWORD_FILE: /run/secrets/${MEMBER}\n`;
 const SECRET_TEXT = `- source: ${MEMBER}\n  target: ${MEMBER}\n`;
-
 /** Adds `block` under the service's `key`, or opens the key with it when the service has none. */
 function appendToService(edit, service, key, block, apply) {
-  if (edit.value.services[service][key] === undefined) {
-    edit.append(['services', service], `${key}:\n${block.replace(/\n$/, '').split('\n').map((line) => `  ${line}`).join('\n')}\n`);
-    edit.value.services[service][key] = apply(undefined);
-  } else {
-    edit.append(['services', service, key], block);
-    edit.value.services[service][key] = apply(edit.value.services[service][key]);
-  }
+    if (edit.value.services[service][key] === undefined) {
+        edit.append(['services', service], `${key}:\n${block.replace(/\n$/, '').split('\n').map((line) => `  ${line}`).join('\n')}\n`);
+        edit.value.services[service][key] = apply(undefined);
+    }
+    else {
+        edit.append(['services', service, key], block);
+        edit.value.services[service][key] = apply(edit.value.services[service][key]);
+    }
 }
-
 /** One service that runs the queue reaches the Redis: its address and password file, the secret and the internal network. */
 function wireQueueService(edit, service) {
-  appendToService(edit, service, 'environment', QUEUE_ENVIRONMENT_TEXT, (environment) => Object.assign(environment ?? {}, QUEUE_ENVIRONMENT));
-  appendToService(edit, service, 'secrets', SECRET_TEXT, (secrets) => [...(secrets ?? []), { source: MEMBER, target: MEMBER }]);
-  edit.extendFlow(['services', service, 'networks'], 'backing');
-  edit.value.services[service].networks.push('backing');
+    appendToService(edit, service, 'environment', QUEUE_ENVIRONMENT_TEXT, (environment) => Object.assign(environment ?? {}, QUEUE_ENVIRONMENT));
+    appendToService(edit, service, 'secrets', SECRET_TEXT, (secrets) => [...(secrets ?? []), { source: MEMBER, target: MEMBER }]);
+    edit.extendFlow(['services', service, 'networks'], 'backing');
+    edit.value.services[service].networks.push('backing');
 }
-
 /** The Swarm model additions: every service that runs the queue reaches the Redis on an internal network with the shared secret, the Redis persists AOF. */
 function stackPatch(file, relative, { name, project, runtimeName, consumers }) {
-  const edit = new YamlBlockEdit(read(file), relative);
-  const model = edit.value;
-  for (const service of consumers) wireQueueService(edit, service);
-  const constraints = model.services[consumers[0]].deploy?.placement?.constraints ?? [];
-  const redis = {
-    image: REDIS_IMAGE,
-    command: ['sh', '-c', `exec redis-server --appendonly yes --appendfsync everysec --requirepass "$$(cat /run/secrets/${MEMBER})"`],
-    secrets: [{ source: MEMBER, target: MEMBER }],
-    volumes: ['redis-data:/data'],
-    networks: ['backing'],
-    healthcheck: { test: ['CMD-SHELL', `REDISCLI_AUTH="$$(cat /run/secrets/${MEMBER})" redis-cli ping | grep -q PONG`], interval: '30s', timeout: '5s', start_period: '10s', retries: 3 },
-    deploy: {
-      replicas: 1,
-      placement: { constraints },
-      update_config: { parallelism: 1, order: 'stop-first', failure_action: 'rollback', monitor: '30s' },
-      rollback_config: { parallelism: 1, order: 'stop-first' },
-      restart_policy: { condition: 'on-failure', delay: '5s' },
-    },
-  };
-  edit.append(['services'], [
-    'redis:',
-    `  image: ${REDIS_IMAGE}`,
-    `  command: ${JSON.stringify(redis.command)}`,
-    '  secrets:',
-    `    - source: ${MEMBER}`,
-    `      target: ${MEMBER}`,
-    '  volumes:',
-    '    - redis-data:/data',
-    '  networks: [backing]',
-    '  healthcheck:',
-    `    test: ${JSON.stringify(redis.healthcheck.test)}`,
-    '    interval: 30s',
-    '    timeout: 5s',
-    '    start_period: 10s',
-    '    retries: 3',
-    '  deploy:',
-    '    replicas: 1',
-    '    placement:',
-    `      constraints: ${JSON.stringify(constraints)}`,
-    '    update_config: { parallelism: 1, order: stop-first, failure_action: rollback, monitor: 30s }',
-    '    rollback_config: { parallelism: 1, order: stop-first }',
-    '    restart_policy: { condition: on-failure, delay: 5s }',
-    '',
-  ].join('\n'));
-  model.services.redis = redis;
-  edit.append(['networks'], 'backing:\n  driver: overlay\n  internal: true\n');
-  model.networks.backing = { driver: 'overlay', internal: true };
-  edit.append(['secrets'], `${MEMBER}:\n  external: true\n  name: ${quoted(runtimeName)}\n`);
-  model.secrets[MEMBER] = { external: true, name: runtimeName };
-  edit.append(['volumes'], `redis-data:\n  external: true\n  name: ${quoted(`${project}-${name}-redis-data`)}\n`);
-  model.volumes['redis-data'] = { external: true, name: `${project}-${name}-redis-data` };
-  return { file, text: edit.text() };
+    const edit = new YamlBlockEdit(read(file), relative);
+    const model = edit.value;
+    for (const service of consumers)
+        wireQueueService(edit, service);
+    const constraints = model.services[consumers[0]].deploy?.placement?.constraints ?? [];
+    const redis = {
+        image: REDIS_IMAGE,
+        command: ['sh', '-c', `exec redis-server --appendonly yes --appendfsync everysec --requirepass "$$(cat /run/secrets/${MEMBER})"`],
+        secrets: [{ source: MEMBER, target: MEMBER }],
+        volumes: ['redis-data:/data'],
+        networks: ['backing'],
+        healthcheck: { test: ['CMD-SHELL', `REDISCLI_AUTH="$$(cat /run/secrets/${MEMBER})" redis-cli ping | grep -q PONG`], interval: '30s', timeout: '5s', start_period: '10s', retries: 3 },
+        deploy: {
+            replicas: 1,
+            placement: { constraints },
+            update_config: { parallelism: 1, order: 'stop-first', failure_action: 'rollback', monitor: '30s' },
+            rollback_config: { parallelism: 1, order: 'stop-first' },
+            restart_policy: { condition: 'on-failure', delay: '5s' },
+        },
+    };
+    edit.append(['services'], [
+        'redis:',
+        `  image: ${REDIS_IMAGE}`,
+        `  command: ${JSON.stringify(redis.command)}`,
+        '  secrets:',
+        `    - source: ${MEMBER}`,
+        `      target: ${MEMBER}`,
+        '  volumes:',
+        '    - redis-data:/data',
+        '  networks: [backing]',
+        '  healthcheck:',
+        `    test: ${JSON.stringify(redis.healthcheck.test)}`,
+        '    interval: 30s',
+        '    timeout: 5s',
+        '    start_period: 10s',
+        '    retries: 3',
+        '  deploy:',
+        '    replicas: 1',
+        '    placement:',
+        `      constraints: ${JSON.stringify(constraints)}`,
+        '    update_config: { parallelism: 1, order: stop-first, failure_action: rollback, monitor: 30s }',
+        '    rollback_config: { parallelism: 1, order: stop-first }',
+        '    restart_policy: { condition: on-failure, delay: 5s }',
+        '',
+    ].join('\n'));
+    model.services.redis = redis;
+    edit.append(['networks'], 'backing:\n  driver: overlay\n  internal: true\n');
+    model.networks.backing = { driver: 'overlay', internal: true };
+    edit.append(['secrets'], `${MEMBER}:\n  external: true\n  name: ${quoted(runtimeName)}\n`);
+    model.secrets[MEMBER] = { external: true, name: runtimeName };
+    edit.append(['volumes'], `redis-data:\n  external: true\n  name: ${quoted(`${project}-${name}-redis-data`)}\n`);
+    model.volumes['redis-data'] = { external: true, name: `${project}-${name}-redis-data` };
+    return { file, text: edit.text() };
 }
-
 function imagesLockPatch(file, relative) {
-  const edit = new YamlBlockEdit(read(file), relative);
-  edit.append(['images'], `redis: ${REDIS_IMAGE}\n`);
-  edit.value.images.redis = REDIS_IMAGE;
-  return { file, text: edit.text() };
+    const edit = new YamlBlockEdit(read(file), relative);
+    edit.append(['images'], `redis: ${REDIS_IMAGE}\n`);
+    edit.value.images.redis = REDIS_IMAGE;
+    return { file, text: edit.text() };
 }
-
 const recoveryRecord = `component: "redis"
 status: "pending-owner-restore-proof"
 executedAt: null
 plan: "Restore the encrypted redis-data volume backup in isolation, start redis-server with --appendonly yes on it and verify the queued and failed BullMQ jobs of every queue."
 ownerAction: "Replace this record with the backup hash, isolated destination, timestamp and verification receipt before production."
 `;
-
 const KEY_ROWS = [
-  '| `QUEUE_REDIS_HOST` | API queue transport: the declared Redis service `redis` on the internal backing network |',
-  '| `QUEUE_REDIS_PORT` | API queue transport |',
-  '| `QUEUE_REDIS_PASSWORD` | API queue transport and the redis service (`requirepass`); reads `QUEUE_REDIS_PASSWORD_FILE` at `/run/secrets/redis-password`; holds no trailing newline |',
+    '| `QUEUE_REDIS_HOST` | API queue transport: the declared Redis service `redis` on the internal backing network |',
+    '| `QUEUE_REDIS_PORT` | API queue transport |',
+    '| `QUEUE_REDIS_PASSWORD` | API queue transport and the redis service (`requirepass`); reads `QUEUE_REDIS_PASSWORD_FILE` at `/run/secrets/redis-password`; holds no trailing newline |',
 ];
-
 /** The key roster gains the queue keys after the last row of its first table. */
 function keysPatch(file) {
-  const lines = read(file).replace(/\r\n/g, '\n').split('\n');
-  const first = lines.findIndex((line) => line.startsWith('|'));
-  if (first < 0) return null;
-  let last = first;
-  while (lines[last + 1]?.startsWith('|')) last += 1;
-  lines.splice(last + 1, 0, ...KEY_ROWS);
-  return { file, text: lines.join('\n') };
+    const lines = read(file).replace(/\r\n/g, '\n').split('\n');
+    const first = lines.findIndex((line) => line.startsWith('|'));
+    if (first < 0)
+        return null;
+    let last = first;
+    while (lines[last + 1]?.startsWith('|'))
+        last += 1;
+    lines.splice(last + 1, 0, ...KEY_ROWS);
+    return { file, text: lines.join('\n') };
 }
-
 /** Every stack file the declared Redis adds to or changes, planned before anything is written. */
 function stackFiles(repoRoot, { project, consumers }) {
-  const manifestRelative = '.starcistacks/application-stacks.yaml';
-  const manifestFile = path.join(repoRoot, ...manifestRelative.split('/'));
-  if (!fs.existsSync(manifestFile)) return { patches: [], created: [], environments: [] };
-  const manifest = parseYaml(read(manifestFile));
-  if (manifest?.components?.redis) return { patches: [], created: [], environments: [] };
-  const swarm = Object.entries(manifest?.environments ?? {}).filter(([, environment]) => environment?.runtime === 'docker-swarm');
-  const edit = new YamlBlockEdit(read(manifestFile), manifestRelative);
-  edit.append(['components'], redisComponent);
-  edit.value.components.redis = { role: 'stateful', image: REDIS_IMAGE, compose: 'infra/swarm/stack.yaml', volumes: ['redis-data'], purpose: REDIS_PURPOSE, required: true };
-  const patches = [];
-  const created = [];
-  for (const [name, environment] of swarm) {
-    const compose = `.starcistacks/${name}/${environment.composeFiles?.[0] ?? 'infra/swarm/stack.yaml'}`;
-    const composeFile = path.join(repoRoot, ...compose.split('/'));
-    const services = queueServicesIn(composeFile, compose, consumers);
-    const { recovery, runtimeName } = declareEnvironment(edit, name, environment, { project, consumers: services });
-    patches.push(stackPatch(composeFile, compose, { name, project, runtimeName, consumers: services }));
-    const lock = environment.release?.imagesLock;
-    if (lock && fs.existsSync(path.join(repoRoot, ...lock.split('/')))) patches.push(imagesLockPatch(path.join(repoRoot, ...lock.split('/')), lock));
-    const keys = path.join(repoRoot, '.starcistacks', name, 'runtime', 'env', 'KEYS.md');
-    if (fs.existsSync(keys)) patches.push(keysPatch(keys));
-    if (!fs.existsSync(path.join(repoRoot, ...recovery.split('/')))) created.push({ relative: recovery, text: recoveryRecord });
-  }
-  patches.unshift({ file: manifestFile, text: edit.text() });
-  return { patches: patches.filter(Boolean), created, environments: swarm.map(([name]) => name) };
+    const manifestRelative = '.starcistacks/application-stacks.yaml';
+    const manifestFile = path.join(repoRoot, ...manifestRelative.split('/'));
+    if (!fs.existsSync(manifestFile))
+        return { patches: [], created: [], environments: [] };
+    const manifest = parseYaml(read(manifestFile));
+    if (manifest?.components?.redis)
+        return { patches: [], created: [], environments: [] };
+    const swarm = Object.entries(manifest?.environments ?? {}).filter(([, environment]) => environment?.runtime === 'docker-swarm');
+    const edit = new YamlBlockEdit(read(manifestFile), manifestRelative);
+    edit.append(['components'], redisComponent);
+    edit.value.components.redis = { role: 'stateful', image: REDIS_IMAGE, compose: 'infra/swarm/stack.yaml', volumes: ['redis-data'], purpose: REDIS_PURPOSE, required: true };
+    const patches = [];
+    const created = [];
+    for (const [name, environment] of swarm) {
+        const compose = `.starcistacks/${name}/${environment.composeFiles?.[0] ?? 'infra/swarm/stack.yaml'}`;
+        const composeFile = path.join(repoRoot, ...compose.split('/'));
+        const services = queueServicesIn(composeFile, compose, consumers);
+        const { recovery, runtimeName } = declareEnvironment(edit, name, environment, { project, consumers: services });
+        patches.push(stackPatch(composeFile, compose, { name, project, runtimeName, consumers: services }));
+        const lock = environment.release?.imagesLock;
+        if (lock && fs.existsSync(path.join(repoRoot, ...lock.split('/'))))
+            patches.push(imagesLockPatch(path.join(repoRoot, ...lock.split('/')), lock));
+        const keys = path.join(repoRoot, '.starcistacks', name, 'runtime', 'env', 'KEYS.md');
+        if (fs.existsSync(keys))
+            patches.push(keysPatch(keys));
+        if (!fs.existsSync(path.join(repoRoot, ...recovery.split('/'))))
+            created.push({ relative: recovery, text: recoveryRecord });
+    }
+    patches.unshift({ file: manifestFile, text: edit.text() });
+    return { patches: patches.filter((patch) => patch !== null), created, environments: swarm.map(([name]) => name) };
 }
-
 /**
  * Plans the lite additions of `add queue|job` before any file is written; returns null outside lite or for another noun. The
  * plan's apply() writes them and returns the app-relative paths it created or changed.
  */
 export function planLiteQueue({ repoRoot, repo, noun, patterns, now }) {
-  if (repo.edition !== 'lite' || !['queue', 'job'].includes(noun)) return null;
-  const beRoot = path.join(repoRoot, 'be');
-  const migrations = migrationFiles({ repoRoot, beRoot, patterns, now });
-  const database = skeletonFiles(repoRoot);
-  const declaration = declarationPatches(repoRoot, repo.project, patterns);
-  const stack = stackFiles(repoRoot, { project: repo.project, consumers: queueServicesOf(repo) });
-  const created = [...migrations, ...tickFiles({ beRoot, patterns }), ...database.created, ...stack.created];
-  const patches = [...database.patches, ...declaration, ...stack.patches];
-  const clashes = created.filter((entry) => fs.existsSync(path.join(repoRoot, ...entry.relative.split('/')))).map((entry) => entry.relative);
-  if (clashes.length) throw new ScaffoldError('HFS_ADD_EXISTS', `add ${noun} would overwrite ${clashes.join(', ')}`);
-  return {
-    apply() {
-      for (const entry of created) {
-        const target = path.join(repoRoot, ...entry.relative.split('/'));
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        fs.writeFileSync(target, entry.text);
-      }
-      for (const patch of patches) fs.writeFileSync(patch.file, patch.text);
-      const exported = [
-        ...registerLiteExports({ root: repoRoot, generator: 'queue' }),
-        ...(patterns.includes('fenced-job') ? registerLiteExports({ root: repoRoot, generator: 'jobs' }) : []),
-      ];
-      const sealed = sealRedisMembers(repoRoot, stack.environments);
-      const changed = patches.map((patch) => path.relative(repoRoot, patch.file).split(path.sep).join('/'));
-      return [...new Set([...created.map((entry) => entry.relative), ...changed, ...exported, ...sealed])];
-    },
-  };
+    if (repo.edition !== 'lite' || !['queue', 'job'].includes(noun))
+        return null;
+    const beRoot = path.join(repoRoot, 'be');
+    const migrations = migrationFiles({ repoRoot, beRoot, patterns, now });
+    const database = skeletonFiles(repoRoot);
+    const declaration = declarationPatches(repoRoot, repo.project, patterns);
+    const stack = stackFiles(repoRoot, { project: repo.project, consumers: queueServicesOf(repo) });
+    const created = [...migrations, ...tickFiles({ beRoot, patterns }), ...database.created, ...stack.created];
+    const patches = [...database.patches, ...declaration, ...stack.patches];
+    const clashes = created.filter((entry) => fs.existsSync(path.join(repoRoot, ...entry.relative.split('/')))).map((entry) => entry.relative);
+    if (clashes.length)
+        throw new ScaffoldError('HFS_ADD_EXISTS', `add ${noun} would overwrite ${clashes.join(', ')}`);
+    return {
+        apply() {
+            for (const entry of created) {
+                const target = path.join(repoRoot, ...entry.relative.split('/'));
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                fs.writeFileSync(target, entry.text);
+            }
+            for (const patch of patches)
+                fs.writeFileSync(patch.file, patch.text);
+            const exported = [
+                ...registerLiteExports({ root: repoRoot, generator: 'queue' }),
+                ...(patterns.includes('fenced-job') ? registerLiteExports({ root: repoRoot, generator: 'jobs' }) : []),
+            ];
+            const sealed = sealRedisMembers(repoRoot, stack.environments);
+            const changed = patches.map((patch) => path.relative(repoRoot, patch.file).split(path.sep).join('/'));
+            return [...new Set([...created.map((entry) => entry.relative), ...changed, ...exported, ...sealed])];
+        },
+    };
 }
-
 /** Seals a placeholder redis-password member to the app's configured recipient; without one, `starci app secret init` seals it. */
 function sealRedisMembers(repoRoot, environments) {
-  if (!environments.length || !fs.existsSync(path.join(repoRoot, '.sops.yaml'))) return [];
-  const recipients = (env) => configuredRecipients(repoRoot, path.join(repoRoot, '.starcistacks', env, 'secrets', `${MEMBER}.enc`));
-  let single;
-  try { single = environments.every((env) => recipients(env).length === 1); } catch { single = false; }
-  if (!single) return [];
-  return materializeDeclaredPlaceholders(repoRoot, {
-    recipientsForFile: (file) => configuredRecipients(repoRoot, file),
-    only: (member) => member.slug === MEMBER && environments.includes(member.env),
-  }).members;
+    if (!environments.length || !fs.existsSync(path.join(repoRoot, '.sops.yaml')))
+        return [];
+    const recipients = (env) => configuredRecipients(repoRoot, path.join(repoRoot, '.starcistacks', env, 'secrets', `${MEMBER}.enc`));
+    let single;
+    try {
+        single = environments.every((env) => recipients(env).length === 1);
+    }
+    catch {
+        single = false;
+    }
+    if (!single)
+        return [];
+    return materializeDeclaredPlaceholders(repoRoot, {
+        recipientsForFile: (file) => configuredRecipients(repoRoot, file),
+        only: (member) => member.slug === MEMBER && environments.includes(member.env),
+    }).members;
 }