@starci/hfs 4.11.11 → 4.11.13

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 4.11.13 - 2026-10-29
+
+- Fixed: a member sealed to an environment's whole recipient set (the owner key and the deploy server key, the production standard after `server-key --execute`) opens with either identity alone. The selected-identity decrypt (`runtime/scripts/lib/sops-envelope.mjs` `selectedAgeEnvelope`) refused every envelope whose age list held more than one entry (`unsupported-age-set`), so every production read failed once the server key joined; it now admits a set that holds the selected recipient and refuses an empty entry or gap (`invalid-age-entry`) and a recipient named twice (`duplicate-age-recipient`); a dotenv envelope reads every `sops_age__list_<n>__` entry.
+- Fixed: every seal keeps the member's full recipient set (`secret-sops.mjs` `sealRecipients`): the caller's set, else the environment's `.sops.yaml` rule, else the set the existing member is sealed to, under a private one-rule sops config when no rule of the app matches (sops refuses an unmatched file even with `--age`). `set`, `migrate`, `split` and the edit verbs on a production member keep the server recipient.
+- Changed: one age identity lookup for every decrypt of a member, `decryptionIdentity` (`secret-init.mjs`): the environment, the app's `.claude/secret.env`, its main checkout's, the harness CLI's secret.env (`hostIdentity`), then sops' keys.txt. `defaultSops` uses it, `stack`, `release` and `db` hand their context `hostIdentity` (`stackContext`, `release/index.mjs` `contextOf`, `main.mjs`), so a stack deploy opens its members with the same identity `app secret` does; `stack/sealed.mjs` `hasAgeIdentity` reads the seam's finding instead of guessing from files.
+- Changed: a member that cannot be opened is refused naming the member, the format it was read as, its recipients, where the identity came from and its recipient, and why: a failed selected sops run names its class (`sopsFailureClass`: no-matching-identity, mac-mismatch, unparsable-document, timeout, exit-<n>) instead of "the selected invocation was not qualified" alone.
+- Changed: the deploy's sealed SSH members (`deploy.remote.sealed`) are read as what they are: a `.enc.yaml` member through `decrypt(file, "yaml")` and its key, a legacy `.enc` through the binary envelope. The keys are `SEALED_SSH_KEYS` (`stack/remote.mjs`): `privateKey` of `sshKey`, `knownHosts` of `knownHosts`; the `key` and `known_hosts` aliases are gone, and a member without its key is refused naming the keys it holds.
+- Fixed: `server-key` resolves age-keygen as root, the way it calls it (`RESOLVE_AGE_KEYGEN`, `ageKeygenScript`: root's PATH, then `/usr/local/bin`, `/usr/bin`, `/bin`): on AlmaLinux 10 sudo's secure_path leaves `/usr/local/bin` out, so the deploy user's `command -v age-keygen` passed and the root script exited 127 ("age-keygen failed on the server"). The static age installer links age and age-keygen from `/usr/bin` and counts age as present only when root sees it too; `stack-key-restore.yml` (both editions) adds `/usr/local/bin` to its root shell's PATH.
+- Changed: the bundled canon pins name hfs 4.11.13, eslint-canon-be 3.8.12, eslint-canon-fe 9.5.14 and the Grammar family 0.15.25.
+
+## 4.11.12 - 2026-10-29
+
+- Changed: the skeleton canon gate (`src/scaffold-template-canon-be.spec.mjs`) lints every file under `be/src/modules/platform` of both editions with the starci-be rules, no longer `platform/http` alone; both editions are green.
+- Fixed: the lite skeleton's `platform/http-security` reads and writes its rate limit windows through `RateWindowEntity` on the EntityManager (R334), no longer through full's `rate-limit.sql.ts` and `.query(`: a live window grows in one atomic `increment`, an ended one restarts with `update`, a missing one opens with an `orIgnore` insert builder, and the prune deletes a bounded `find` batch. The entity maps `public.http_security_rate_windows` of the baseline migration (`persistence/entities/rate-window.entity.ts`, `httpSecurityEntities` in its barrel, listed in `PRIMARY_ENTITIES`); a lite platform capability takes its `persistence/` from the lite overlay alone. The guard spec uses the kit's `mockEntityManager` and `queueQueryBuilders`.
+- Changed: a fresh lite app no longer carries the raw SQL helpers nothing in it calls: `platform/database/database.sql.ts` and `database.client.ts` (with its spec) are written by the first generator that needs them (`add table` the sql helpers, `add queue`, `add job` and `add webhook` both), and the barrel exports `sql`, `callDbFunction` and `advisoryXactLock` are registered by those generators (`jobs` registers `advisoryXactLock`); `notify` is no longer exported by the starter.
+- Fixed: `source-suffix` (BE_SOURCE_FORM, R89) admits the one file a file slot names by its path, read from the slot manifest: the lite entity registry `src/modules/platform/database/entities.ts` (slot `be.platform.database.entities`) was refused for having no role suffix.
+- Fixed: the lite skeleton types its entity lists with `EntityClass` (`new () => object`, declared in `platform/database/database.options.ts` as full declares it): `DatabaseOptions.entities` and `PRIMARY_ENTITIES` of `entities.ts` were `ReadonlyArray<Function>`, which `starci-be/no-function-or-eval` refuses.
+- Changed: R334 `BE_PERSISTENCE_NO_RAW_SQL` covers test code with one owner exception (ruling lite-test-sql-owner): specs, builders and fixtures seed and assert through entities on `world.db.<connection>`, and only `src/tests/world` holds raw SQL beside `platform/database`, as named world helpers for what entities cannot express. The bundled catalog law and the failure-code hint say so; the bundled canon pins name hfs 4.11.12, eslint-canon-be 3.8.11, eslint-canon-fe 9.5.13 and the Grammar family 0.15.24.
+
 ## 4.11.11 - 2026-10-29
 
 - Changed: `server-key <env> --backup github` stores the server identity as the secret `SOPS_AGE_KEY` of the GitHub Environment `<env>` (`BACKUP_SECRET`, `gh secret set SOPS_AGE_KEY --env <env>`), the name the deploy workflows read: an Environment secret overrides a repository secret of the same name for every job bound to that Environment, so the deploy of `<env>` decrypts with that environment's own server key. `backupSecretName` and the `SOPS_AGE_KEY_<ENV>` name are gone.

package/README.md

@@ -230,7 +230,7 @@ one key its whole text or several one `KEY=value` line each, `--from-file KEY=pa
 A member is sealed to its environment's rule of the managed `.sops.yaml`; `recipients <env> [--add|--remove <age1...|owner>]`
 rewrites that rule (`environmentRecipients`, `secret-init.mjs`), and `init` takes the owner's identity as the app's recipient.
 Re-sealing a member whose every key the set replaces needs no age identity; adding a key to one does, and the identity is found
-by itself (`localAgeIdentity`): SOPS_AGE_KEY or SOPS_AGE_KEY_FILE of the environment, else of the app's git-ignored
+by itself (`decryptionIdentity`, the one lookup every decrypt of a member uses: secret, stack, release, db): SOPS_AGE_KEY or SOPS_AGE_KEY_FILE of the environment, else of the app's git-ignored
 `.claude/secret.env`, else of its main checkout's when the app is a git worktree, else the `hostIdentity` the harness CLI passes
 (its own secret.env), else the sops `keys.txt`; with none, the verb refuses before asking for a value, naming every place it
 looked and the one line that fixes it. `audit [<env>]` names every deviation and exits 1; `migrate <env> <member> [--to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.11.11",
+  "version": "4.11.13",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/release/index.mjs

@@ -18,9 +18,9 @@ import { RELEASE_CODE, VERSION, normalizeRelease, releaseGate } from './gate.mjs
 import { releasePush } from './push.mjs';
 import { releaseUrgentPush } from './urgent.mjs';
 
-const IO_KEYS = ['cwd', 'stdout', 'stderr', 'env', 'sops'];
+const IO_KEYS = ['cwd', 'stdout', 'stderr', 'env', 'sops', 'hostIdentity'];
 
-/** The stack context of one invocation: the IO of the app (cwd, writers, env, sops) over the injectable seams of `io.stackIo` (spawn, sleep, now, fetch). */
+/** The stack context of one invocation: the IO of the app (cwd, writers, env, sops, hostIdentity) over the injectable seams of `io.stackIo` (spawn, sleep, now, fetch). */
 export function contextOf(io = {}) {
   const own = Object.fromEntries(IO_KEYS.filter((key) => io[key] !== undefined).map((key) => [key, io[key]]));
   return stackContext({ ...io.stackIo, ...own });

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.15.23
+    version: 0.15.25
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.8.10
+    version: 3.8.12
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.5.12
+    version: 9.5.14
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.15.23
+    version: 0.15.25
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.15.23
+    version: 0.15.25
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.11.11
+    version: 4.11.13
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -5828,7 +5828,7 @@ rules:
         ruling: "Lite entities only map tables the migrations create, so each entity column is checked against the migrated schema by starci app db drift, which CI runs in the build job and the release gate runs as its db-drift row."
   - id: R334
     code: "BE_PERSISTENCE_NO_RAW_SQL"
-    law: "Lite domain and feature code reads and writes through TypeORM entities on the injected EntityManager (find, findOne, findBy, count, exists, insert, save, update, delete, upsert, increment, and createQueryBuilder(Entity, alias) with named parameters for joins, aggregates, FOR UPDATE / SKIP LOCKED and jsonb or vector operators; never a table-name builder, a builder with no entity or a Repository); no .query( call and no sql template outside platform/database; a database function TypeORM cannot express is called through the callDbFunction, advisoryXactLock and notify helpers of platform/database/database.client.ts, and callDbFunction names only a function ruleParams.be.dbFunctions or hfs.json sides.be.dbFunctions lists with a reason: a function of a migration schema-qualified (public.job_claim), a pg built-in bare (pg_notify, called in pg_catalog). That file alone composes the call statement, from the name parts its validator checked and double-quotes and a numbered parameter list. Entities only map tables db/migrations created (synchronize stays false); entity-versus-schema drift is BE_ENTITY_SCHEMA_DRIFT of starci app db drift."
+    law: "Lite domain, feature and test code reads and writes through TypeORM entities on an EntityManager (domain code the injected one, integration and e2e specs, builders and fixtures the world's `world.db.<connection>`) (find, findOne, findBy, count, exists, insert, save, update, delete, upsert, increment, and createQueryBuilder(Entity, alias) with named parameters for joins, aggregates, FOR UPDATE / SKIP LOCKED and jsonb or vector operators; never a table-name builder, a builder with no entity or a Repository); no .query( call and no sql template outside the two raw SQL owners, platform/database and the test world src/tests/world, which wraps only what entities cannot express (a trigger, a database function, a row-level-security probe, a pgmq queue) in a named, typed world helper specs call; a database function TypeORM cannot express is called, in domain and test code alike, through the callDbFunction, advisoryXactLock and notify helpers of platform/database/database.client.ts, and callDbFunction names only a function ruleParams.be.dbFunctions or hfs.json sides.be.dbFunctions lists with a reason: a function of a migration schema-qualified (public.job_claim), a pg built-in bare (pg_notify, called in pg_catalog). That file alone composes the call statement, from the name parts its validator checked and double-quotes and a numbered parameter list. Entities only map tables db/migrations created (synchronize stays false); entity-versus-schema drift is BE_ENTITY_SCHEMA_DRIFT of starci app db drift."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["BE_PERSISTENCE_NO_RAW_SQL"]

package/runtime/modules/kernel/failure-codes.yaml

@@ -5581,12 +5581,12 @@ LITE_DB_MIGRATION:
   kind: check-finding
 
 BE_PERSISTENCE_NO_RAW_SQL:
-  title: "Lite domain code runs raw SQL instead of TypeORM entities"
-  title_vi: "Mã domain của app lite chạy SQL thô thay vì entity TypeORM"
-  meaning_vi: "File `<path>` gọi `.query(` hoặc dùng template `sql` ngoài platform/database và ngoài danh sách hàm ruleParams.be.lite.rawSqlFunctions."
+  title: "Lite domain, feature or test code runs raw SQL instead of TypeORM entities"
+  title_vi: "Mã domain, feature hoặc test của app lite chạy SQL thô thay vì entity TypeORM"
+  meaning_vi: "File `<path>` gọi `.query(` hoặc dùng template `sql` ngoài hai chủ của SQL thô là platform/database và test world src/tests/world, hoặc gọi callDbFunction với một hàm không có trong ruleParams.be.dbFunctions hay hfs.json sides.be.dbFunctions."
   causes_vi:
-    - "Vi phạm R334: dữ liệu của app lite đi qua entity TypeORM trên EntityManager (find, save, update, upsert, createQueryBuilder)."
-  nextStep_vi: "Khai entity ở persistence/entities/<table>.entity.ts và đọc/ghi bằng EntityManager hoặc createQueryBuilder với tham số có tên; hàm pg/SECURITY DEFINER không diễn đạt được thì khai vào rawSqlFunctions kèm lý do."
+    - "Vi phạm R334: dữ liệu của app lite, kể cả spec, builder và fixture, đi qua entity TypeORM trên EntityManager (find, save, update, upsert, createQueryBuilder); spec dùng world.db.<connection>."
+  nextStep_vi: "Đọc/ghi bằng entity trên EntityManager hoặc createQueryBuilder với tham số có tên (trong test là world.db.<connection>); hàm database TypeORM không diễn đạt được thì gọi qua callDbFunction với hàm đã khai kèm lý do; điều entity không diễn đạt được trong test (trigger, thăm dò row-level security, hàng đợi pgmq) thì gọi một helper có tên của src/tests/world."
   owner: op-retry
   kind: check-finding
 

package/runtime/scripts/api/sops/lib.mjs

@@ -116,7 +116,11 @@ function isolatedSopsEnv(env, inlineName = 'SOPS_AGE_KEY') {
   return out;
 }
 
-const held = reason => ({ status: null, stdout: '', stderr: '', error: Object.assign(new Error(`SOPS selected identity [${reason}]: the selected invocation was not qualified`), { name: 'SopsIdentityRefusal', identityRefusal: reason }) });
+/**
+ * A refusal of the selected invocation. `detail` says what failed in public words; `facts` carries only public values the caller
+ * names in its own refusal (`publicRecipient`, the selected identity's recipient; `sopsFailure`, the class of a failed sops run).
+ */
+const held = (reason, detail = 'the selected invocation was not qualified', facts = {}) => ({ status: null, stdout: '', stderr: '', error: Object.assign(new Error(`SOPS selected identity [${reason}]: ${detail}`), { name: 'SopsIdentityRefusal', identityRefusal: reason, ...facts }) });
 const nativeFile = file => {
   if (typeof file !== 'string' || !path.isAbsolute(file) || /\.(?:[cm]?js|cmd|bat|ps1|sh)$/i.test(file)) return false;
   let fd;
@@ -175,11 +179,29 @@ const selectedAdmission = (selection, spec, invocation, env) => {
 
 const decryptArgs = (file, inputType, outputType) => ['decrypt', '--input-type', inputType, '--output-type', outputType, '--filename-override', file, '--enable-local-keyservice=true', '--decryption-order', 'age'];
 
+/**
+ * The class of a failed sops run, read from its stderr and exit; sops prints no value there, and only the class leaves. Classes:
+ * no-matching-identity (no age entry opens with the identity), mac-mismatch (the document changed after it was sealed),
+ * unparsable-document (the bytes are not the format they were read as), timeout, or exit-<n>.
+ */
+export function sopsFailureClass(result) {
+  if (result?.error?.code === 'ETIMEDOUT' || result?.signal === 'SIGTERM') return 'timeout';
+  const text = Buffer.isBuffer(result?.stderr) ? result.stderr.toString('utf8') : String(result?.stderr ?? '');
+  if (/MAC mismatch/iu.test(text)) return 'mac-mismatch';
+  if (/no identity matched|failed to get the data key|could not decrypt data key|0 successful groups/iu.test(text)) return 'no-matching-identity';
+  if (/unmarshal|could not parse|error loading file|invalid character|yaml:/iu.test(text)) return 'unparsable-document';
+  return `exit-${String(result?.status ?? 'none')}`;
+}
+
 const decryptSelected = (run, exe, file, input, spec, recipient) => {
+  const facts = { publicRecipient: recipient };
   const envelope = selectedAgeEnvelope(decoded(input), spec.inputType, recipient);
-  if (!envelope.ok) return held(envelope.reason);
+  if (!envelope.ok) return held(envelope.reason, `the ${spec.inputType} envelope was refused for the selected recipient ${recipient}`, facts);
   const result = run(exe, decryptArgs(file, spec.inputType, spec.outputType), input);
-  if (!captured(result)) return held('selected-decryption-failed');
+  if (!captured(result)) {
+    const failure = sopsFailureClass(result);
+    return held('selected-decryption-failed', `sops could not decrypt the ${spec.inputType} document with the selected recipient ${recipient} (${failure})`, { ...facts, sopsFailure: failure });
+  }
   return { status: 0, stdout: decoded(result.stdout), stderr: '', error: null };
 };
 

package/runtime/scripts/api/sops/seal.mjs

@@ -7,10 +7,11 @@ import { resolveSops, runSelectedSops } from './lib.mjs';
 
 /**
  * Run `<bin> encrypt` (bin null: the sops resolveSops finds) over `plaintext` of format `inputType` (json, yaml or dotenv). Sops reads stdin only with a `--filename-override`, the path the sealed
- * file will have: recipients are age keys (`--age`), and when none are given sops picks them from the repository's .sops.yaml for that path. {status, stdout, stderr, error}.
+ * file will have: recipients are age keys (`--age`), and when none are given sops picks them from the repository's .sops.yaml for that path. `config` names
+ * the sops configuration to read instead of the repository's (a rule-less member sealed to its own recipients). {status, stdout, stderr, error}.
  */
-export function seal(bin, { inputType, plaintext, recipients = [], filenameOverride }, { invocation = null, env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024, timeout = undefined } = {}) {
-  const args = ['encrypt', '--input-type', inputType, '--output-type', inputType, '--filename-override', filenameOverride];
+export function seal(bin, { inputType, plaintext, recipients = [], filenameOverride, config = null }, { invocation = null, env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024, timeout = undefined } = {}) {
+  const args = [...(config ? ['--config', config] : []), 'encrypt', '--input-type', inputType, '--output-type', inputType, '--filename-override', filenameOverride];
   if (recipients.length) args.push('--age', recipients.join(','));
   const selected = sopsIdentityEnv(env);
   if (selected.error?.identityRefusal === 'inline-context-unqualified') return runSelectedSops(bin, { operation: 'seal', params: { inputType, plaintext, recipients, filenameOverride } }, { selection: selected, invocation, env, cwd, maxBuffer, timeout });

package/runtime/scripts/hfs/path-findings.mjs

@@ -29,6 +29,8 @@ function sourceFormContext(file, resolver, suffixes, bannedSuffixes) {
   const base = path.posix.basename(file);
   if (FREE_NAMES.has(base)) return null;
   const slot = resolver.slot(c.slot);
+  // A file slot declares its one file by its path (be.platform.database.entities: src/modules/platform/database/entities.ts).
+  if (slot?.path === c.path) return null;
   if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].includes(base)) return null;
   const admitted = allowsFile(resolver, file);
   // Environment parsing is an app slot role, not a source suffix admitted outside that matching app file.
@@ -57,8 +59,8 @@ function sourceFormFinding(file, { c, base, suffixes, bannedSuffixes }, boundSuf
 }
 
 /**
- * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
- * be.persistence, the matching <app>.env.ts explicitly admitted by its app slot, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
+ * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, the one file a file
+ * slot names by its path (the lite entity registry src/modules/platform/database/entities.ts), a migration of be.persistence, the matching <app>.env.ts explicitly admitted by its app slot, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
  * as order.service.spec.ts keeps its inner words kebab-case). A suffix of ruleParams.be.bannedSuffixes anywhere in the
  * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
  */

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-inbox-lite.mjs

@@ -233,17 +233,13 @@ export function addLiteWebhookInbox({
   );
   if (!hasHandoffStorage)
     planned[0].text = `${template("platform/migration.sql.tpl", renderValues)}\n${template("platform/client-operation-outcomes.sql.tpl", renderValues)}\n${planned[0].text}`;
-  const databaseSql = "be/src/modules/platform/database/database.sql.ts";
-  if (!fs.existsSync(path.join(root, ...databaseSql.split("/")))) {
+  // The sql tag and the database-function call (with its spec) the inbox and the event bus use; the lite starter leaves them out.
+  for (const file of ["database.sql.ts", "database.client.ts", "database.client.spec.ts"]) {
+    const relative = `be/src/modules/platform/database/${file}`;
+    if (fs.existsSync(path.join(root, ...relative.split("/")))) continue;
     planned.push({
-      relative: databaseSql,
-      text: render(
-        fs.readFileSync(
-          path.join(TEMPLATES_DIR, "be", "skeleton-lite", "src", "modules", "platform", "database", "database.sql.ts"),
-          "utf8",
-        ),
-        {},
-      ),
+      relative,
+      text: render(fs.readFileSync(path.join(TEMPLATES_DIR, "be", "skeleton-lite", "src", "modules", "platform", "database", file), "utf8"), {}),
     });
   }
   const databaseClient = path.join(

package/scaffold/add-queue-lite.mjs

@@ -84,12 +84,14 @@ const DATABASE_ERROR = 'be/src/modules/platform/database/errors/database.error.t
 
 /** 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'],
 ]);
 
-/** 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. */
+/** 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}`), {}) }));
@@ -364,7 +366,10 @@ export function planLiteQueue({ repoRoot, repo, noun, patterns, now }) {
         fs.writeFileSync(target, entry.text);
       }
       for (const patch of patches) fs.writeFileSync(patch.file, patch.text);
-      const exported = registerLiteExports({ root: repoRoot, generator: 'queue' });
+      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])];

package/scaffold/add-table.mjs

@@ -472,9 +472,14 @@ function writeTableFiles({ root, planned, edit }, created) {
 
 }
 
+/** The lite sql helpers of platform/database (requireOwnedEntity, the bounds and the sql tag). */
+const DATABASE_SQL_FILE = "be/src/modules/platform/database/database.sql.ts";
+
 function tableRegistrations({ root, repo, fe, edit }) {
   const errorFile = "be/src/modules/platform/database/errors/database.error.ts";
   if (repo.edition === "lite" && fs.existsSync(at(root, errorFile))) edit(errorFile, withSqlIdentifierError);
+  // requireOwnedEntity lives in the sql helpers the lite starter leaves out; the first table writes them.
+  if (repo.edition === "lite") edit(DATABASE_SQL_FILE, (text) => text || render(fs.readFileSync(path.join(TEMPLATES_DIR, "be", "skeleton-lite", "src", "modules", "platform", "database", "database.sql.ts"), "utf8"), {}));
     const registrations = [
       ...(repo.edition === "lite" ? ["table"] : []),
       ...(fe ? ["api", "graphql"] : []),