@starci/hfs 4.11.12 → 4.11.15

package/runtime/scripts/hfs/rules/canon-copy-drift.mjs

@@ -1,18 +1,25 @@
 // canon-copy-drift.mjs - HFS_CANON_COPY_DRIFT (R253): a handful of scaffolded files are hash-sensitive canon,
 // not files to edit. The drift judgement is one sha256 against the bytes of the be/skeleton template the file was
-// scaffolded from - the file equals canon, or it has drifted. A finding carries the path and both hashes, never
-// file content.
+// scaffolded from - the file equals canon, or it has drifted. That template is the one of the @starci/hfs version the app
+// pins (its lockfile's resolution of node_modules/@starci/hfs, else an exact package.json pin), never a newer hfs that
+// happens to run the check: a skeleton change reaches an app only when the app raises its hfs. This package's own
+// templates serve when it is that version or the app pins none; else an installed copy at the pinned version does; with
+// neither at hand the copy is left to the app's own run of its pinned hfs. A finding carries the path and both hashes,
+// never file content.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { found } from './read.mjs';
 
 const CANON_COPY = 'HFS_CANON_COPY_DRIFT';
-const TEMPLATE_ROOTS = [
+const OWN_ROOT = path.resolve(import.meta.dirname, '../../../..');
+const OWN_TEMPLATE_ROOTS = [
   path.resolve(import.meta.dirname, '../../../packages/hfs/templates'),
-  path.resolve(import.meta.dirname, '../../../../templates'),
+  path.join(OWN_ROOT, 'templates'),
 ];
 const TEMPLATE_DIR = 'be/skeleton/';
+const HFS_LOCK_KEY = 'node_modules/@starci/hfs';
+const EXACT = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 
 // The three managed files the standard's secret-custody law pins byte-for-byte.
 const CANON_PATHS = [
@@ -23,8 +30,46 @@ const CANON_PATHS = [
 const REGEX_ESCAPE = String.raw`\$&`;
 const CANON_SUFFIX = new RegExp(`(?:^|/)(${CANON_PATHS.map((rel) => rel.replace(/[.*+?^${}()|[\]\\]/g, REGEX_ESCAPE)).join('|')})$`);
 
-const templateBytes = (rel) => {
-  for (const root of TEMPLATE_ROOTS) {
+const readJson = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return undefined;
+  }
+};
+const versionAt = (folder) => readJson(path.join(folder, 'package.json'))?.version;
+
+/** The @starci/hfs version the app at `repoRoot` pins: its lockfile's resolution (hoisted first), else an exact package.json pin. */
+export function pinnedHfsVersion(repoRoot) {
+  const packages = readJson(path.join(repoRoot, 'package-lock.json'))?.packages ?? {};
+  const locked = Object.keys(packages)
+    .filter((key) => key === HFS_LOCK_KEY || key.endsWith(`/${HFS_LOCK_KEY}`))
+    .sort((left, right) => left.length - right.length)
+    .map((key) => packages[key]?.version)
+    .find((version) => typeof version === 'string');
+  if (locked) return locked;
+  const manifest = readJson(path.join(repoRoot, 'package.json')) ?? {};
+  for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+    const spec = manifest[field]?.['@starci/hfs'];
+    if (typeof spec === 'string' && EXACT.test(spec)) return spec;
+  }
+  return undefined;
+}
+
+/** The template roots of the app's pinned @starci/hfs, or null when no copy of that version is at hand. */
+export function pinnedTemplateRoots(repoRoot) {
+  const pin = pinnedHfsVersion(repoRoot);
+  if (pin === undefined || versionAt(OWN_ROOT) === pin) return OWN_TEMPLATE_ROOTS;
+  const copies = [
+    path.join(repoRoot, 'node_modules', '@starci', 'hfs'),
+    path.join(repoRoot, 'node_modules', 'starci-harness', 'node_modules', '@starci', 'hfs'),
+  ];
+  const installed = copies.find((copy) => versionAt(copy) === pin);
+  return installed === undefined ? null : [path.join(installed, 'templates')];
+}
+
+const templateBytes = (roots, rel) => {
+  for (const root of roots) {
     const file = path.join(root, TEMPLATE_DIR, rel);
     try {
       const bytes = fs.readFileSync(file);
@@ -37,10 +82,12 @@ const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex'
 
 export function canonCopyDriftFindings({ repoRoot, files, inScope }) {
   const findings = [];
+  const roots = pinnedTemplateRoots(repoRoot);
+  if (roots === null) return findings;
   for (const file of files.filter((f) => !inScope || inScope(f))) {
     const hit = CANON_SUFFIX.exec(file.replaceAll('\\', '/'));
     if (!hit) continue;
-    const expected = templateBytes(hit[1]);
+    const expected = templateBytes(roots, hit[1]);
     if (!expected) continue;
     let actual;
     try {

package/runtime/scripts/hfs/secret-init.mjs

@@ -106,6 +106,21 @@ export function localAgeIdentity(repoRoot, env, tools, host = null) {
   return { env: { ...env }, source: null, looked };
 }
 
+/**
+ * The one age identity every decrypt of a sealed member opens with (secret get, verify, materialize, set over an existing member,
+ * migrate, split, the edit verbs, updatekeys, server-key, the stack's sealed members and the CLI's custody): localAgeIdentity's
+ * order (the environment, the app's `.claude/secret.env`, its main checkout's, the `host` port), then sops' per-user keys.txt.
+ * Same shape as localAgeIdentity; `looked` names every place read, keys.txt last.
+ */
+export function decryptionIdentity(repoRoot, env, { tools, host = null, platform = process.platform } = {}) {
+  const local = localAgeIdentity(repoRoot, env, tools, host);
+  if (local.source !== null) return local;
+  const keys = secretRoots(env, platform).identity;
+  const looked = [...local.looked, keys];
+  if (!fs.existsSync(keys)) return { ...local, looked };
+  return { env: { ...local.env, SOPS_AGE_KEY_FILE: keys }, source: keys, looked };
+}
+
 /** Load host-local age selections below the explicit environment (localAgeIdentity), without copying any other credentials. */
 export function ageIdentityEnv(repoRoot, env, tools) {
   return localAgeIdentity(repoRoot, env, tools).env;

package/runtime/scripts/hfs/secret-sops.mjs

@@ -1,5 +1,6 @@
 // secret-sops.mjs - runtime SOPS adapter and age identity selection.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { runProgram } from "../api/process/run-program.mjs";
 import { resolveRealTool } from "../api/process/resolve-real-tool.mjs";
@@ -9,8 +10,8 @@ import { updateKeys as sopsUpdateKeys } from "../api/sops/update-keys.mjs";
 import { isLegacyName } from "../lib/sealed-member.mjs";
 import { invocationDir } from "../lib/roots.mjs";
 import { envelopeOf } from "./secret-document.mjs";
-import { configuredRecipients, localAgeIdentity, secretTools } from "./secret-init.mjs";
-import { outsideRepository, secretRoots } from "./secret-files.mjs";
+import { configuredRecipients, decryptionIdentity, secretTools } from "./secret-init.mjs";
+import { outsideRepository } from "./secret-files.mjs";
 import { SecretError, publicStorage } from "./secret-errors.mjs";
 
 const sopsInvocation = Object.freeze({ runProgram, resolveRealTool });
@@ -45,15 +46,27 @@ function recipientsOf(file) {
  * The refusal of a decrypt whose selected identity is not one `file` is sealed to: names where the identity came from and the
  * member's recipients, and the two ways out. It carries no value.
  */
-function identityMismatch(repoRoot, identity, file) {
+function identityMismatch(repoRoot, identity, file, publicRecipient) {
   const recipients = recipientsOf(file);
+  const own = publicRecipient ? ` (recipient ${publicRecipient})` : "";
   return new SecretError(
-    `the age identity of ${identity.source ?? "the environment"} does not open ${path.basename(file)}, ` +
-      `sealed to ${recipients.join(", ") || "another recipient"}. Fix: put that recipient's age secret key in ${path.join(repoRoot, ".claude", "secret.env")} as SOPS_AGE_KEY, ` +
-      "or, when no one holds it any more, seal the member's keys again (remove it and set them) after .sops.yaml names this identity's recipient",
+    `the age identity of ${identity.source ?? "the environment"}${own} does not open ${path.basename(file)}, ` +
+      `sealed to ${recipients.join(", ") || "another recipient"}. Fix: put one of those recipients' age secret key in ${path.join(repoRoot, ".claude", "secret.env")} as SOPS_AGE_KEY, ` +
+      "or, when no one holds any of them any more, seal the member's keys again (remove it and set them) after .sops.yaml names this identity's recipient",
   );
 }
 
+/**
+ * Any other refusal of a decrypt: the member, the format it was read as, the recipients it is sealed to, where the age identity
+ * came from and (when derived) its recipient, then the refusal itself. Public facts only.
+ */
+function identityRefused(identity, file, format, error) {
+  const recipients = recipientsOf(file);
+  const own = error.publicRecipient ? `, recipient ${error.publicRecipient}` : "";
+  const source = identity.source ? `the age identity of ${identity.source}${own}` : `no age identity (looked in ${identity.looked.join(", ") || "the environment"})`;
+  return `${path.basename(file)} (read as ${format ?? "its own format"}, sealed to ${recipients.join(", ") || "no age recipient"}) cannot be opened with ${source}: ${error.message}`;
+}
+
 /**
  * The refusal of an operation that must decrypt `file` with no age identity selected: it names the recipient the member is
  * sealed to, every place looked, and the one line that fixes it. It carries no value.
@@ -70,8 +83,40 @@ function identityMissing(repoRoot, identity, file) {
 }
 
 /**
- * The default sops seam: the runtime's sops api, which finds the binary on this machine; the age identity is localAgeIdentity's
- * (`host` its last source), then the legacy sops keys.txt. `identity` says where the age identity
+ * The recipient set a seal of `file` writes: the caller's `named` set, else the environment's .sops.yaml rule, else the full set
+ * the existing member is sealed to, so no rewrite (set, migrate, split, an edit) drops a recipient such as the deploy server's.
+ * `ruled` says whether a rule of the app's .sops.yaml matches the file. Refused, as the rule refuses, when none names one.
+ */
+function sealRecipients(repoRoot, file, named) {
+  try {
+    const rule = configuredRecipients(repoRoot, file);
+    return { recipients: named.length ? named : rule, ruled: true };
+  } catch (error) {
+    const existing = named.length ? named : fs.existsSync(file) ? recipientsOf(file) : [];
+    if (existing.length) return { recipients: existing, ruled: false };
+    throw error;
+  }
+}
+
+/**
+ * Runs `seal` with a private sops configuration naming only `recipients` when the app's .sops.yaml has no rule for the member
+ * (sops refuses a file no rule matches even with --age); the folder is removed after. Public keys only.
+ */
+function withOwnRule(ruled, recipients, seal) {
+  if (ruled) return seal(null);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "starci-sops-rule-"));
+  try {
+    const config = path.join(dir, ".sops.yaml");
+    fs.writeFileSync(config, `creation_rules:\n  - age: ${recipients.join(",")}\n`);
+    return seal(config);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The default sops seam: the runtime's sops api, which finds the binary on this machine; the age identity is decryptionIdentity's
+ * (`host` the harness CLI's secret.env, then sops' keys.txt). `identity` says where the age identity
  * was found (`source`, null when nowhere) and where it was looked for; `requireIdentity(file)` refuses, before any value is
  * read, an operation that must decrypt `file` with no identity.
  */
@@ -83,7 +128,7 @@ export function defaultSops(
   host = null,
 ) {
   const { sops: binary } = publicStorage(() => secretTools(env, tools));
-  const local = localAgeIdentity(repoRoot, env, tools, host);
+  const local = decryptionIdentity(repoRoot, env, { tools, host, platform });
   const selectedEnv = local.env;
   const identity = { source: local.source, looked: [...local.looked] };
   const invocation = {
@@ -109,27 +154,16 @@ export function defaultSops(
         );
       checkIdentity(value);
     }
-  if (
-    !Object.keys(selectedEnv).some((name) => AGE_IDENTITY_NAME.test(name))
-  ) {
-    const keys = secretRoots(env, platform).identity;
-    checkIdentity(keys);
-    identity.looked.push(keys);
-    if (fs.existsSync(keys)) {
-      selectedEnv.SOPS_AGE_KEY_FILE = keys;
-      identity.source = keys;
-    }
-  }
   const requireIdentity = (file) => {
     if (identity.source === null) throw identityMissing(repoRoot, identity, file);
   };
-  const refuse = (what, result, file) => {
+  const refuse = (what, result, file, format) => {
     if (result.error?.identityRefusal === "identity-not-supplied" && file)
       return identityMissing(repoRoot, identity, file);
     if (result.error?.identityRefusal === "recipient-mismatch" && file)
-      return identityMismatch(repoRoot, identity, file);
+      return identityMismatch(repoRoot, identity, file, result.error.publicRecipient);
     if (result.error?.identityRefusal)
-      return Object.assign(new SecretError(result.error.message), {
+      return Object.assign(new SecretError(file ? identityRefused(identity, file, format, result.error) : result.error.message), {
         identityRefusal: result.error.identityRefusal,
       });
     if (result.error?.code === "SOPS_MISSING")
@@ -157,6 +191,7 @@ export function defaultSops(
           `decrypt ${path.basename(file)}; is the age identity installed?`,
           result,
           file,
+          format,
         );
       if (exact) return exactMap(result.stdout);
       const map = Object.create(null);
@@ -193,6 +228,7 @@ export function defaultSops(
           `decrypt ${path.basename(file)}; is the age identity installed?`,
           result,
           file,
+          types[0],
         );
       return String(result.stdout);
     },
@@ -207,21 +243,17 @@ export function defaultSops(
         { env: selectedEnv, cwd: repoRoot, invocation },
       );
       if (result.status !== 0)
-        throw refuse(`update the keys of ${path.basename(file)}; is the age identity a recipient of it?`, result, file);
+        throw refuse(`update the keys of ${path.basename(file)}; is the age identity a recipient of it?`, result, file, isLegacyName(file) ? "dotenv" : "yaml");
     },
     seal(request) {
-      const recipients = request.recipients.length
-        ? request.recipients
-        : publicStorage(() =>
-            configuredRecipients(repoRoot, request.filenameOverride),
-          );
-      // Sealing needs only public recipients, so it runs with no identity selected and may name several (an environment's
+      const { recipients, ruled } = publicStorage(() => sealRecipients(repoRoot, request.filenameOverride, request.recipients));
+      // Sealing needs only public recipients, so it runs with no identity selected and seals to the whole set (an environment's
       // server key and the owner key both).
-      const result = sopsSeal(
+      const result = withOwnRule(ruled, recipients, (config) => sopsSeal(
         binary,
-        { ...request, recipients },
+        { ...request, recipients, config },
         { env: withoutIdentity(selectedEnv), cwd: repoRoot, invocation },
-      );
+      ));
       if (result.status !== 0) throw refuse("seal the secret", result);
       return result.stdout;
     },

package/runtime/scripts/lib/sops-envelope.mjs

@@ -62,13 +62,17 @@ export function isSopsEnvelope(text) {
   try { return sopsTree(parseYaml(src)); } catch { return false; }
 }
 
-/** Admit one flat age envelope for the native selected-identity invocation; this is shape admission, never cryptographic proof. */
+/** A refused admission, named by its reason. */
 const refusal = (reason) => ({ ok: false, reason });
 
+const DOTENV_AGE_FIELD = /^age__list_(0|[1-9]\d{0,2})__map_(recipient|enc)$/u;
+
 function dotenvMetadataValue(meta, age, key, value) {
-  if (key === 'age__list_0__map_recipient') age.recipient = value;
-  else if (key === 'age__list_0__map_enc') age.enc = value;
-  else if (key === 'mac_only_encrypted') {
+  const field = DOTENV_AGE_FIELD.exec(key);
+  if (field) {
+    const entry = (age[Number(field[1])] ??= {});
+    entry[field[2]] = value;
+  } else if (key === 'mac_only_encrypted') {
     if (value !== 'false') return 'partial-mac';
     meta[key] = false;
   } else if (key.includes('__')) return 'unsupported-key-group';
@@ -88,13 +92,14 @@ function readDotenvMetadata(text) {
     pairs.set(name, line.slice(at + 1).replaceAll(String.raw`\n`, '\n'));
   }
   const meta = {};
-  const age = {};
+  const age = [];
   for (const [name, value] of pairs) {
     if (!name.startsWith('sops_')) continue;
     const reason = dotenvMetadataValue(meta, age, name.slice('sops_'.length), value);
     if (reason) return { refusal: reason };
   }
-  meta.age = [age];
+  // A gap in the list indices is an entry sops never wrote: refused as an empty entry, never skipped.
+  meta.age = Array.from(age, (entry) => entry ?? null);
   return { meta };
 }
 
@@ -142,15 +147,35 @@ function validateAgeMetadata(meta, text, recipient) {
   const fields = new Set([...providers, 'age', 'lastmodified', 'mac', 'version', 'unencrypted_suffix', 'encrypted_suffix', 'unencrypted_regex', 'encrypted_regex', 'unencrypted_comment_regex', 'encrypted_comment_regex', 'mac_only_encrypted']);
   if (Object.keys(meta).some(name => !fields.has(name))) return refusal('unknown-metadata');
   if (Object.hasOwn(meta, 'mac_only_encrypted') && meta.mac_only_encrypted !== false) return refusal('partial-mac');
-  if (!Array.isArray(meta.age) || meta.age.length !== 1) return refusal('unsupported-age-set');
-  const entry = meta.age[0];
-  if (!isAgeEntry(entry)) return refusal('invalid-age-entry');
-  if (typeof entry.recipient !== 'string' || entry.recipient !== recipient) return refusal('recipient-mismatch');
-  if (!hasValidAgePayload(entry)) return refusal('invalid-age-entry');
+  const set = ageSet(meta.age);
+  if (!set.ok) return set;
+  if (!set.recipients.includes(recipient)) return refusal('recipient-mismatch');
   if (!hasValidEnvelopeVersion(meta)) return refusal('invalid-envelope');
   return { ok: true };
 }
 
+const AGE_RECIPIENT = /^age1[ac-hj-np-z02-9]+$/u;
+
+/**
+ * The age set of an envelope: one or more entries (the owner key and an environment's server key are the standard pair), each a
+ * well-formed recipient with its wrapped data key; an empty entry or a recipient named twice is refused.
+ */
+function ageSet(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return refusal('unsupported-age-set');
+  const recipients = [];
+  for (const entry of entries) {
+    if (!isAgeEntry(entry) || typeof entry.recipient !== 'string' || !AGE_RECIPIENT.test(entry.recipient) || !hasValidAgePayload(entry))
+      return refusal('invalid-age-entry');
+    if (recipients.includes(entry.recipient)) return refusal('duplicate-age-recipient');
+    recipients.push(entry.recipient);
+  }
+  return { ok: true, recipients };
+}
+
+/**
+ * Admit one flat age envelope for the native selected-identity invocation when `recipient` (the selected identity's public key) is
+ * one of its age set. Shape admission, never cryptographic proof.
+ */
 export function selectedAgeEnvelope(text, format, recipient) {
   if (!['binary', 'json', 'yaml', 'dotenv'].includes(format)) return refusal('unsupported-format');
   const parsed = readAgeMetadata(text, format);

package/scaffold/add-compose.mjs

@@ -7,7 +7,10 @@ import { ScaffoldError } from './service.mjs';
 export function addModuleImport(lines, { importLine, entry, relative, noun }) {
   const active = compositionCode(lines.join('\n')).split('\n');
   const imported = active.some(line => line.replace(/;\s*$/, '') === importLine);
+  // An area group spread once is registered whatever its argument (the lite root passes `tokens.verify` to domainModules).
+  const group = /^\.\.\.(\w+Modules)\(/.exec(entry)?.[1];
   const registered = active.some(line => line.trim() === `${entry},` ||
+    (group !== undefined && line.includes(`...${group}(`)) ||
     (/\bimports:\s*\[/.test(line) && !line.trim().startsWith('//') && line.replace(/\s+/g, '').includes(entry.replace(/\s+/g, ''))));
   const lastImport = active.reduce((last, line, index) => line.startsWith('import ') ? index : last, -1);
   const importsLine = line => /\bimports:\s*\[/.test(line) && !line.trim().startsWith('//');

package/scaffold/add-inbox-lite.mjs

@@ -13,6 +13,10 @@ const PLACEHOLDER = /@@([A-Za-z][A-Za-z0-9]*)@@/g;
 const timestampOf = (now) =>
   new Date(now()).toISOString().replace(/\D/g, "").slice(0, 14);
 const upperOf = (name) => name.replaceAll("-", "_").toUpperCase();
+const camelOf = (name) => {
+  const pascal = pascalOf(name);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+};
 const snakeOf = (name) => name.replaceAll("-", "_");
 
 const template = (relative, values) => {
@@ -72,8 +76,6 @@ 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 { recordWebhookDelivery, webhookReceiptInsert } from "./webhook-inbox.client"'))
-    index = `${index.trimEnd()}\nexport { recordWebhookDelivery, webhookReceiptInsert } from "./webhook-inbox.client"\n`;
   if (!index.split("\n").some((line) => line.startsWith("export { ") && line.includes("DatabaseErrorCode") && line.endsWith(' } from "./errors/database.error"')))
     index = `${index.trimEnd()}\nexport { DatabaseError, DatabaseErrorCode } from "./errors/database.error"\n`;
   let error = withSqlIdentifierError(fs.readFileSync(errorFile, "utf8").replace(/\r\n/g, "\n"));
@@ -107,7 +109,15 @@ const handoffPlatformFiles = (root, values) => {
   const planned = [];
   for (const capability of ["inbox", "idempotency", "event-bus"]) {
     const base = `be/src/modules/platform/${capability}`;
-    if (fs.existsSync(path.join(root, base, "index.ts"))) continue;
+    if (fs.existsSync(path.join(root, base, "index.ts"))) {
+      // The provider intake claims through the EntityInbox port; an inbox written before it cannot serve a new provider.
+      if (capability === "inbox" && !fs.readFileSync(path.join(root, base, "index.ts"), "utf8").includes("InjectEntityInbox"))
+        throw new ScaffoldError(
+          "HFS_ADD_INBOX_ENTITY_PORT",
+          `${base} predates the EntityInbox port (InjectEntityInbox, claimRow) the ${values.provider} intake claims through; bring it to the inbox of this hfs first`,
+        );
+      continue;
+    }
     const folder = path.join(TEMPLATES_DIR, "be", "inbox", "platform", capability);
     for (const file of filesBelow(folder)) {
       const relative = path.relative(folder, file).replaceAll("\\", "/");
@@ -149,6 +159,28 @@ const eventFiles = (root, provider, values) => {
   return { planned, patches };
 };
 
+/** The lite entity list (BE-PERSISTENCE-3), where the provider inbox's `<provider>InboxEntities` is spread once. */
+const PRIMARY_ENTITIES_FILE = ["be", "src", "modules", "platform", "database", "entities.ts"];
+const PRIMARY_ENTITIES = /(export const PRIMARY_ENTITIES[^=]*=\s*\[)([\s\S]*?)(\])/;
+
+/** entities.ts with the receipt entity list imported from the provider inbox barrel and spread into PRIMARY_ENTITIES. */
+const primaryEntitiesPatch = (root, provider, list) => {
+  const file = path.join(root, ...PRIMARY_ENTITIES_FILE);
+  const relative = PRIMARY_ENTITIES_FILE.join("/");
+  if (!fs.existsSync(file))
+    throw new ScaffoldError("HFS_ADD_INBOX_DATABASE", `lite add webhook names ${list} in PRIMARY_ENTITIES of ${relative}, which is missing`);
+  const text = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+  if (!PRIMARY_ENTITIES.test(text))
+    throw new ScaffoldError("HFS_ADD_INBOX_DATABASE", `lite add webhook names ${list} in PRIMARY_ENTITIES of ${relative}, which declares no PRIMARY_ENTITIES array`);
+  if (new RegExp(String.raw`\.\.\.${list}\b`).test(text)) return { file, text };
+  const withList = text.replace(PRIMARY_ENTITIES, (all, head, items, tail) =>
+    `${head}${[...items.split(",").map((item) => item.trim()).filter(Boolean), `...${list}`].join(", ")}${tail}`);
+  const lines = withList.split("\n");
+  const lastImport = lines.reduce((at, line, index) => (line.startsWith("import ") ? index : at), -1);
+  lines.splice(lastImport + 1, 0, `import { ${list} } from "@modules/domain/${provider}-inbox"`);
+  return { file, text: lines.join("\n") };
+};
+
 const eventPatternPatch = (root) => {
   const file = path.join(root, "hfs.json");
   const declaration = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -190,6 +222,7 @@ export function addLiteWebhookInbox({
     ...values,
     provider,
     Provider,
+    providerCamel: camelOf(provider),
     providerUpper: upperOf(provider),
     table,
   };
@@ -221,6 +254,14 @@ export function addLiteWebhookInbox({
       relative: `${base}/${provider}-inbox.service.spec.ts`,
       text: template("service.spec.ts.tpl", renderValues),
     },
+    {
+      relative: `${base}/persistence/entities/${provider}-inbox.entity.ts`,
+      text: template("entity.ts.tpl", renderValues),
+    },
+    {
+      relative: `${base}/persistence/entities/index.ts`,
+      text: template("entities.index.ts.tpl", renderValues),
+    },
     {
       relative: `be/src/modules/events/${provider}/${provider}-delivery-recorded.event.ts`,
       text: template("delivery-recorded.event.ts.tpl", renderValues),
@@ -242,26 +283,6 @@ export function addLiteWebhookInbox({
       text: render(fs.readFileSync(path.join(TEMPLATES_DIR, "be", "skeleton-lite", "src", "modules", "platform", "database", file), "utf8"), {}),
     });
   }
-  const databaseClient = path.join(
-    root,
-    "be",
-    "src",
-    "modules",
-    "platform",
-    "database",
-    "webhook-inbox.client.ts",
-  );
-  if (!fs.existsSync(databaseClient))
-    planned.push(
-      {
-        relative: "be/src/modules/platform/database/webhook-inbox.client.ts",
-        text: template("database-client.ts.tpl", renderValues),
-      },
-      {
-        relative: "be/src/modules/platform/database/webhook-inbox.client.spec.ts",
-        text: template("database-client.spec.ts.tpl", renderValues),
-      },
-    );
   const clashes = planned
     .filter((entry) => fs.existsSync(path.join(root, ...entry.relative.split("/"))))
     .map((entry) => entry.relative);
@@ -272,6 +293,7 @@ export function addLiteWebhookInbox({
     );
   const patches = [
     ...databasePatches(root),
+    primaryEntitiesPatch(root, provider, `${renderValues.providerCamel}InboxEntities`),
     ...events.patches,
     eventPatternPatch(root),
   ];

package/scaffold/lite-exports.mjs

@@ -108,6 +108,19 @@ const REGISTRATIONS = Object.freeze({
       source: "./webhook-signature.service",
       names: ["WebhookSignatureService"],
     },
+    {
+      // The webhook door types its request with the correlation the logging middleware stamps on it.
+      file: "be/src/modules/platform/logging/index.ts",
+      source: "./correlation.contracts",
+      names: ["CorrelationRequest"],
+      type: true,
+    },
+    {
+      // The lite event bus refuses an envelope whose correlation id is not one the logging capability issues.
+      file: "be/src/modules/platform/logging/index.ts",
+      source: "./correlation.policy",
+      names: ["isCorrelationId"],
+    },
   ],
   "webhook-full": [
     {

package/src/main.mjs

@@ -116,11 +116,11 @@ starci app db migrate [--execute] [--url-env <NAME>] [--json] [--cwd <dir>]
 starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--url-env <NAME>] [--json] [--cwd <dir>]
 starci app db drift [--url-env <NAME>] [--json] [--cwd <dir>]
 starci app release gate [--execute] [--source <ref>] [--tag-prefix <prefix>] [--backfill <tag>] [--json] [--cwd <dir>]
-starci app release push [--execute] [--remote <name>] [--urgent --reason <text>] [--json] [--cwd <dir>]
+starci app release push [--execute] [--remote <name>] [--urgent --reason <text> [--lint-baseline <tag>]] [--json] [--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 stack deploy --env <env> --source-sha <sha> --urgent [--db-url-env <NAME>] [--backup-out <dir>] [--execute] [--json] [--cwd <dir>]
+starci app stack deploy --env <env> --source-sha <sha> --urgent [--db-url-env <NAME>] [--backup-out <dir>] [--first-start --db-service <service>] [--execute] [--json] [--cwd <dir>]
 starci app explain <path> [--cwd <dir>] [--json]
 starci app emit [--cwd <dir>]
 starci app new service <dir> <name> [--inject <binding>...] [--cwd <dir>]
@@ -435,8 +435,8 @@ function declaredEdition(cwd) {
  * `starci app stack`: the deploy actions (prepare, doctor, render, deploy, converge, verify, rollback, prune, backup, jobs, ...) are the Swarm
  * tooling of stack/cli.mjs; up, down and status are the full edition's test-world infrastructure.
  */
-async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr: err, env, sops, stackIo }) {
-  if (STACK_ACTIONS.includes(argv[0])) return deployStackMain(argv, { ...stackIo, cwd, stdout: out, stderr: err, env, ...(sops ? { sops } : {}) });
+async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr: err, env, sops, hostIdentity, stackIo }) {
+  if (STACK_ACTIONS.includes(argv[0])) return deployStackMain(argv, { ...stackIo, cwd, stdout: out, stderr: err, env, hostIdentity, ...(sops ? { sops } : {}) });
   if ((edition ?? declaredEdition(cwd)) === 'lite') throw new Error('starci app stack up|down|status manage the local test world of the full edition; a lite app starts its local database with npm run db:start');
   const run = stackMain ?? await installedStackMain(cwd);
   return run(argv, { cwd, out, err });
@@ -462,7 +462,7 @@ function errorMessage(error) {
  * `harness` ({ version }) is the CLI that runs this package in-process: its version is the starci-harness an app is judged and
  * scaffolded at (runtime/scripts/hfs/canon-pins.mjs). `run` injects the database runner, `runLinter` the linter transport, `checkApp`
  * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
- * harness CLI's own secret.env SOPS_AGE_KEY, which `secret` reads last for the age identity; `prompt` replaces its masked prompt.
+ * harness CLI's own secret.env SOPS_AGE_KEY, which every verb that opens a sealed member (secret, stack, release, db) reads last for the age identity (decryptionIdentity); `prompt` replaces its masked prompt.
  */
 export async function main(argv, {
   cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,

package/stack/age-install.mjs

@@ -17,10 +17,18 @@ const STATIC_INSTALL = [
   `echo "${AGE_SHA256}  $tmp/age.tgz" | sha256sum -c -`,
   'tar -xzf "$tmp/age.tgz" -C "$tmp"',
   'sudo -n install -m 0755 "$tmp/age/age" "$tmp/age/age-keygen" /usr/local/bin/',
+  // sudo's secure_path (AlmaLinux 10, RHEL) leaves /usr/local/bin out: a link in /usr/bin makes both tools visible to the deploy
+  // user and to root alike; an existing /usr/bin tool (a packaged age) is kept.
+  'for b in age age-keygen; do if [ ! -e "/usr/bin/$b" ]; then sudo -n ln -s "/usr/local/bin/$b" "/usr/bin/$b"; fi; done',
 ].join('; ');
 
 const packageManager = (run) => run('for m in dnf yum apk apt-get; do command -v $m >/dev/null 2>&1 && echo $m && break; done').stdout.trim();
-const present = (run) => run('command -v age').status === 0;
+/**
+ * Both tools, as the deploy user and, where passwordless sudo exists, as root: an install the root PATH cannot see is not taken
+ * for present.
+ */
+const PRESENT = 'command -v age >/dev/null 2>&1 && command -v age-keygen >/dev/null 2>&1 && { [ "$(id -u)" -eq 0 ] || ! sudo -n true 2>/dev/null || sudo -n sh -c \'command -v age >/dev/null 2>&1 && command -v age-keygen >/dev/null 2>&1\'; }';
+const present = (run) => run(PRESENT).status === 0;
 
 /** Installs age when it is missing; reports through `report`. */
 export function installAge(run, report) {
@@ -33,6 +41,6 @@ export function installAge(run, report) {
     failure = `${manager} could not install age: ${firstLine(packaged.stderr)}`;
   }
   const fetched = run(STATIC_INSTALL);
-  if (fetched.status === 0 && present(run)) report.note(`installed the official static age ${AGE_VERSION} (sha256 verified) into /usr/local/bin; ${failure}`);
+  if (fetched.status === 0 && present(run)) report.note(`installed the official static age ${AGE_VERSION} (sha256 verified) into /usr/local/bin, linked from /usr/bin; ${failure}`);
   else report.bad(`cannot install age (${failure}); the static install failed too: ${firstLine(fetched.stderr)} (needs passwordless sudo once, or install age by hand)`);
 }

package/stack/cli.mjs

@@ -14,8 +14,8 @@ const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollb
 
 export const ACTIONS = Object.freeze(['prepare', 'doctor', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept']);
 
-const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent']);
-const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out']);
+const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start']);
+const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service']);
 const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
 
 /** Splits argv into { flags, positional }; an unknown flag or a flag without its value is a refusal. */
@@ -72,6 +72,7 @@ const OPTIONS = {
     images: parseImages(flags.image), sourceSha: flags['source-sha'], execute: flags.execute === true,
     out: flags.out ? path.resolve(cwd, flags.out) : null, timeoutSeconds: number(flags, 'timeout'), retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true,
     urgent: flags.urgent === true, dbUrlEnv: flags['db-url-env'], backupOut: flags['backup-out'] ? path.resolve(cwd, flags['backup-out']) : undefined,
+    firstStart: flags['first-start'] === true, dbService: flags['db-service'],
   }),
   converge: ({ flags }) => ({ since: flags.since, timeoutSeconds: number(flags, 'timeout') }),
   verify: ({ flags }) => ({ retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true, skipInternal: flags['skip-internal'] === true }),
@@ -126,7 +127,8 @@ export async function stackMain(argv, io = {}) {
     if (binding && (!['deploy', 'verify'].includes(action) || flags['ssh-cmd'] || flags['skip-public'] || flags['skip-internal']))
       throw refusal('STACK_USAGE', 'the bound native consumer supports only complete deploy or verify');
     const config = bindStackTarget(ctx, loadDeployConfig({ repoRoot: ctx.cwd, env: flags.env ?? 'production' }), binding);
-    if (action !== 'deploy' && (flags.urgent || flags['db-url-env'] || flags['backup-out'])) throw refusal('STACK_USAGE', '--urgent, --db-url-env and --backup-out belong to deploy');
+    if (action !== 'deploy' && (flags.urgent || flags['db-url-env'] || flags['backup-out'] || flags['first-start'] || flags['db-service'])) throw refusal('STACK_USAGE', '--urgent, --db-url-env, --backup-out, --first-start and --db-service belong to deploy');
+    if (!flags.urgent && (flags['first-start'] || flags['db-service'])) throw refusal('STACK_USAGE', '--first-start and --db-service are the first start of an empty database under the urgent floor: add --urgent');
     if (action === 'deploy' && !flags.urgent && (flags['db-url-env'] || flags['backup-out'])) throw refusal('STACK_USAGE', '--db-url-env and --backup-out choose the urgent floor\'s database and backup folder: add --urgent');
     const options = OPTIONS[action]({ flags, positional, cwd: ctx.cwd });
     const handler = await handlerOf(action, io.importer ?? ((file) => import(file)));