@starci/hfs 4.11.13 → 4.11.15

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 4.11.15 - 2026-10-29
+
+- Added: `platform/database/returned-rows.policy.ts` in the skeleton of both editions, exported from the database barrel: `rowShape({ column: kind })` builds the guard of the rows a RETURNING clause answers (kinds `string`, `number`, `boolean`, `date`, `json`, and `string?`, `number?`, `boolean?`, `date?` that also admit SQL null; a column the statement does not return is refused), and `returnedRows(raw, isRow)` narrows the result of `manager.query` or the `raw` of a query builder's `execute()` to typed rows with no cast. A result that is not a list of rows (the `[rows, count]` of a bare UPDATE included) or a row the guard refuses throws the new `DATABASE_RETURNING_ROW_REJECTED` (internal) of both editions' `DatabaseErrorCode`. The policy spec proves every kind, null, a missing column and both refusals.
+- Changed: the skeleton's RETURNING call sites read their rows through it: full `NoteService.create` (`isNoteRow` beside `NoteRow` in `note.rows.ts`) and the full `RateLimitGuard` (`isRateWindowRow` in `rate-limit.rows.ts`); the lite webhook receipt insert (`webhook-inbox.client.ts`, the `inbox` templates' `database-client.ts.tpl`), with a spec for a receipt row of another shape.
+- Changed: the lite `RateLimitGuard` counts a live window in one query builder `UPDATE ... SET hits = hits + 1 ... RETURNING hits` read through `returnedRows`, no longer an `increment` followed by a `findOneBy` (BE-PERSISTENCE-4: an UPDATE that answers rows stays one statement); the spec reads the counting builder's calls and refuses a returned row whose hits are not a number.
+- Added: the lite inbox capability (`templates/be/inbox/platform/inbox`, written by the first `add webhook`) carries the entity receipt port: `EntityInbox extends Inbox` with `claimRow(source, eventId, tx, { entity, row })`, which claims the delivery and, only for the winning claim, inserts the provider's receipt entity row (`orIgnore`, `returning("id")`, read through `returnedRows`) in the caller transaction, answering the receipt id (`InboxReceiptId`) or undefined for a repeat. `PostgresInbox` implements it, and `InjectEntityInbox()` (a `TypedParameterDecorator<EntityInbox>` on the same `INBOX` token) injects it, so an app no longer hand-rolls the port or injects `@InjectInbox()` into an `EntityInbox` parameter. The barrel exports `InjectEntityInbox` and the types `EntityInbox` and `InboxEntityReceipt`. Specs: `inbox.service.spec.ts.tpl` (claim then insert, a repeat inserts nothing, an existing receipt, a receipt row of another shape, a missing delivery id) and `src/inbox-scaffold.spec.mjs` (the written decorator, barrel and class).
+- Added: the first start of the urgent floor (owner ruling `urgent-first-start`): `stack deploy --urgent --first-start --db-service <service>` deploys a release whose self-hosted database it starts itself. In place of the backup and test decrypt (nothing exists to back up, and the database is reachable only inside the stack), a `first-start` step between the stack deploy and converge waits up to 180s for the service's container to accept connections (`pg_isready`), proves the database empty (no `supabase_migrations.schema_migrations`, no table in `public`) and runs migrate preview then execute inside that container (db/bootstrap.sql first, as the `--db-url-env` role); the record, the rollback target, readiness verify and automatic rollback hold. Codes: `STACK_FIRST_START_USAGE`, `STACK_FIRST_START_NO_DATABASE`, `STACK_FIRST_START_NOT_EMPTY`, `STACK_FIRST_START_MIGRATE_RED`; each red first start rolls the release back.
+- Added: `release push --urgent --lint-baseline <tag>` (owner ruling `urgent-lint-baseline`, `release/lint-baseline.mjs`): the managed lint (`npm run lint`) runs over the whole app at HEAD and at the tag, in a throwaway worktree that borrows HEAD's node_modules as directory junctions (unlinked before the worktree is removed, which is skipped when one is left), each writing a Sonar report (`-- --sonar`); a HEAD finding the tag has (engine, rule, file and message; then engine, rule and message for a moved file) is the accepted backlog, anything beyond it is new and red, and a lint that could not run on either side is red. The lint row of the urgent record names both counts, both reports with their sha256 and the first new findings; `lint-new.json` lists them all. Codes: `RELEASE_URGENT_LINT_BASELINE_TAG`, `RELEASE_URGENT_LINT_BASELINE_UNMANAGED`. Specs: `src/release-lint-baseline.spec.mjs` (matching, and a real git worktree with a stand-in `npm run lint`).
+- Added: `inContainer(target, container)` in `db/postgres.mjs`: the db verbs' client tools run inside the database's container through `docker exec` against 127.0.0.1, each `-f` file copied in first (`docker cp`), the password on the exec's stdin (never argv, a file or an environment); `migrateDatabase` takes such a prebuilt `target`. Specs: `src/db-in-container.spec.mjs`, the first-start cases of `src/stack-urgent-floor.spec.mjs`.
+- Changed: `InboxEntityReceipt.row` is a builder, `row(deliveryId)`, called with the delivery id the claim trimmed, so the receipt row keys exactly what was claimed (`claim` and `claimRow` share the refusal of a missing or blank id, `DATABASE_WEBHOOK_DELIVERY_ID_REQUIRED`).
+- Changed: the lite provider intake `add webhook` writes claims through the `EntityInbox`: `<Provider>InboxService` injects `@InjectEntityInbox() inbox: EntityInbox` and awaits `claimRow("webhook.<provider>", request.eventId, manager, { entity: <Provider>InboxEntity, row } satisfies InboxEntityReceipt<...>)` first in its transaction, returning when it answers undefined, then publishes the recorded event. The receipt is an entity row: `persistence/entities/<provider>-inbox.entity.ts` (`<Provider>InboxEntity` over `public.<provider>_inbox`) and its `<provider>InboxEntities` list, exported from the domain barrel and spread into `PRIMARY_ENTITIES` of `platform/database/entities.ts`. The raw receipt insert is gone: no `webhook-inbox.client.ts` (`recordWebhookDelivery`, `webhookReceiptInsert`) is written or exported. A shared inbox written before the `EntityInbox` port refuses a further provider (`HFS_ADD_INBOX_ENTITY_PORT`). The new inbox exports now have that caller in a fresh `add webhook` app.
+- Fixed: lite `add webhook` exports `CorrelationRequest` and `isCorrelationId` from `platform/logging` (the door and the event bus import them), its door spec overrides the `ReadinessService` the http-security module provides (it needs the database probe and retry timer the door never reaches), and an area group already spread in the API root (`...domainModules(tokens.verify)`) is no longer spread a second time with another argument (`add-compose.mjs`, also for `add table`).
+- Fixed: the lite inbox spec's "rolls the claim back when later work in the receipt transaction fails" failed on every generated app: its claim is a database-function call (`SELECT * FROM "public"."inbox_claim_event"($1, $2)`), which `fakeTransaction` did not record as a write; `@starci/jest-preset` 2.5.1 records it, and the template asserts it unchanged.
+- Changed: the bundled canon pins name hfs 4.11.15, eslint-canon-be 3.8.14, eslint-canon-fe 9.5.16, the Grammar family 0.15.27 and jest-preset 2.5.1.
+
+## 4.11.14 - 2026-10-29
+
+- Fixed: R253 (`HFS_CANON_COPY_DRIFT`, `rules/canon-copy-drift.mjs`) judges a hash-sensitive canon copy against the be/skeleton of the @starci/hfs version the app pins (its lockfile's resolution of `node_modules/@starci/hfs`, else an exact package.json pin), never against a newer hfs that runs the check: this package's own templates serve when it is that version or the app pins none, else an installed copy at the pinned version; with neither at hand the copy is left to the app's own run of its pinned hfs. A skeleton change reaches an app only when the app raises its hfs.
+- Changed: the bundled canon pins name hfs 4.11.14, eslint-canon-be 3.8.13, eslint-canon-fe 9.5.15 and the Grammar family 0.15.26.
+- Spec: `src/hfs-secret-custody.spec.mjs` pins an older hfs with an installed copy whose skeleton differs: a copy equal to the pinned skeleton is clean, one equal to this package's skeleton drifts, and with no copy of the pinned version nothing is judged against another.
+
 ## 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.

package/db/migrate.mjs

@@ -132,7 +132,7 @@ export function buildModel(root, decl) {
 /* ---- the target */
 
 /** The database of `--url-env` (default DATABASE_URL). */
-export const resolveTarget = (ctx, options = {}) => dbTarget(ctx, options.urlEnv ?? DEFAULT_DB_URL_ENV);
+export const resolveTarget = (ctx, options = {}) => options.target ?? dbTarget(ctx, options.urlEnv ?? DEFAULT_DB_URL_ENV);
 
 /** True for a database on this machine's loopback (the local db service): applying to it needs no arming. */
 export const isLoopback = (url) => ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname);

package/db/postgres.mjs

@@ -1,6 +1,8 @@
 // postgres.mjs - the one door of the `starci app db` verbs to a self-hosted PostgreSQL: psql and pg_dump through ctx.spawn (never a
 // shell). The database is named by an environment variable holding a postgres connection URL (`--url-env <NAME>`, default
-// DATABASE_URL); the password travels only in the child's PGPASSWORD, never in argv, a file, a line or an error.
+// DATABASE_URL); the password travels only in the child's PGPASSWORD, never in argv, a file, a line or an error. An in-container target
+// (`inContainer`) runs the same tools inside the database's own container through docker exec, the password on stdin.
+import path from 'node:path';
 import { failure, refusal } from '../stack/errors.mjs';
 import { firstLine, tool } from '../stack/context.mjs';
 
@@ -34,10 +36,43 @@ export function dbTarget(ctx, name = DEFAULT_DB_URL_ENV) {
   return { kind: 'url', how: `connection string from ${name}`, urlEnv: name, url: parsed.url, env: parsed.password ? { PGPASSWORD: parsed.password } : {}, secrets: [value, parsed.password].filter(Boolean) };
 }
 
+/** Where a `-f` file of an in-container target is copied before the client reads it. */
+const CONTAINER_DIR = '/tmp/starci-db';
+/** The shell an in-container client runs under: the password comes in on stdin into PGPASSWORD, then the tool runs with its arguments. */
+const STDIN_PASSWORD = 'IFS= read -r PGPASSWORD; export PGPASSWORD; exec "$@"';
+
+/**
+ * `target` reached inside the running container `container` (`docker exec` through this invocation's daemon), for a database only the stack's
+ * network reaches (the first start of a self-hosted database, `stack deploy --urgent --first-start`): the image's own client tools run there
+ * against the URL's database on 127.0.0.1, a `-f` file is copied in first, and the password travels on the exec's stdin, never in argv, a file
+ * or an environment of this machine.
+ */
+export function inContainer(target, container) {
+  const url = new URL(target.url);
+  url.hostname = '127.0.0.1';
+  return { ...target, how: `${target.how}, inside container ${container.slice(0, 12)}`, url: url.toString(), container };
+}
+
+/** Runs `command` of an in-container target: copies each `-f` file in, then execs the tool through the stdin-password shell. */
+function containerRun(ctx, target, command, args) {
+  const short = target.container.slice(0, 12);
+  const step = (what, run) => {
+    if (run.error || run.status !== 0) throw failure('DB_CLI_FAILED', `${what} in container ${short} failed: ${scrub(firstLine(run.stderr), target.secrets)}`);
+  };
+  step('mkdir', tool(ctx, 'docker', ['exec', target.container, 'mkdir', '-p', CONTAINER_DIR]));
+  const inside = args.map((arg, index) => {
+    if (args[index - 1] !== '-f') return arg;
+    const copied = `${CONTAINER_DIR}/${index}-${path.basename(arg)}`;
+    step(`docker cp of ${path.basename(arg)}`, tool(ctx, 'docker', ['cp', arg, `${target.container}:${copied}`]));
+    return copied;
+  });
+  return tool(ctx, 'docker', ['exec', '-i', target.container, 'sh', '-c', STDIN_PASSWORD, 'sh', command, ...inside], { input: `${target.env.PGPASSWORD ?? ''}\n` });
+}
+
 /** Runs a PostgreSQL client tool against `target`; a failure names the first stderr line with every secret scrubbed (or withholds it). */
 export function pgTool(ctx, target, command, args, { withhold = false, code = 'DB_CLI_FAILED' } = {}) {
-  const run = tool(ctx, command, args, { cwd: ctx.cwd, env: { ...ctx.env, ...target.env } });
-  if (run.error) throw failure('DB_CLI_MISSING', `cannot run ${command}; install the PostgreSQL client tools (psql, pg_dump)`);
+  const run = target.container ? containerRun(ctx, target, command, args) : tool(ctx, command, args, { cwd: ctx.cwd, env: { ...ctx.env, ...target.env } });
+  if (run.error) throw failure('DB_CLI_MISSING', target.container ? `cannot run docker exec ${command} in container ${target.container.slice(0, 12)}` : `cannot run ${command}; install the PostgreSQL client tools (psql, pg_dump)`);
   if (run.status !== 0) throw failure(code, withhold ? `${command} failed; output withheld` : `${command} failed: ${scrub(firstLine(run.stderr), target.secrets)}`);
   return { stdout: run.stdout ?? '', text: `${run.stdout ?? ''}${run.stderr ?? ''}` };
 }

package/package.json

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

package/release/index.mjs

@@ -1,7 +1,7 @@
 // index.mjs - `starci app release <gate|push>` and the plumbing the release and database verbs share: the context built from the app's IO, strict flag
 // parsing, the optional `release:` / `database:` blocks of .starcistacks/application-stacks.yaml, text and --json output and the exit-code mapping.
 //   starci app release gate [--execute] [--sonar] [--source <ref>] [--tag-prefix <prefix>] [--backfill <tag>] [--json]
-//   starci app release push [--execute] [--remote <name>] [--urgent --reason <text>] [--json]
+//   starci app release push [--execute] [--remote <name>] [--urgent --reason <text> [--lint-baseline <tag>]] [--json]
 // `harness` of the app IO ({ version, role, openTicket }) is what the starci CLI hands in: the caller's role an urgent record names and the ticket
 // queue a red back-fill files into.
 // Every action is a dry run unless --execute is given. A refusal is a StackError (exit 2); a failed step returns ok false (exit 1).
@@ -95,11 +95,12 @@ const ACTIONS = {
     }),
   },
   push: {
-    spec: { boolean: ['--execute', '--json', '--urgent'], value: ['--remote', '--reason'] },
+    spec: { boolean: ['--execute', '--json', '--urgent'], value: ['--remote', '--reason', '--lint-baseline'] },
     run: (ctx, flags, harness) => {
       if (flags.reason !== undefined && flags.urgent !== true) throw refusal('RELEASE_USAGE', '--reason belongs to an urgent release (--urgent)');
+      if (flags['lint-baseline'] !== undefined && flags.urgent !== true) throw refusal('RELEASE_USAGE', '--lint-baseline belongs to an urgent release (--urgent)');
       const config = loadReleaseConfig(ctx.cwd);
-      if (flags.urgent === true) return releaseUrgentPush(ctx, config, { execute: flags.execute === true, remote: flags.remote, reason: flags.reason, role: harness?.role ?? ctx.env.STARCI_ROLE });
+      if (flags.urgent === true) return releaseUrgentPush(ctx, config, { execute: flags.execute === true, remote: flags.remote, reason: flags.reason, lintBaseline: flags['lint-baseline'], role: harness?.role ?? ctx.env.STARCI_ROLE });
       return releasePush(ctx, config, { execute: flags.execute === true, remote: flags.remote });
     },
   },

package/release/lint-baseline.mjs

@@ -0,0 +1,123 @@
+// lint-baseline.mjs - the lint row of an urgent release judged against a baseline release tag (`release push --urgent --lint-baseline <tag>`,
+// owner ruling urgent-lint-baseline 2026-10-29: an app whose lint backlog predates the release ships when the release adds no finding of its own).
+// The managed lint (`npm run lint`, which ends in `starci app lint`) runs twice, each writing its findings as a Sonar Generic Issue Import file
+// (`-- --sonar <file>`): at HEAD, and at the baseline tag in a throwaway `git worktree` that borrows HEAD's installs (each node_modules folder is
+// linked in as a directory junction, unlinked before the worktree is removed, never deleted through). A finding is the same finding when its
+// engine, rule, file and message match (lines move); a finding left over is then matched on engine, rule and message alone (a file that moved).
+// What HEAD holds beyond the baseline is new: zero new findings is green, any is red, and a lint that could not run on either side is red. The
+// row names both counts and both reports with their sha256, and the new findings go to lint-new.json beside the record, so the back-fill's full
+// gate (which this changes nothing in) still sees the whole backlog.
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { refusal } from '../stack/errors.mjs';
+import { git, runGate } from './gate.mjs';
+
+/** The owner's ruling a baseline-judged lint row cites. */
+export const LINT_BASELINE_RULING = 'owner ruling urgent-lint-baseline 2026-10-29: an urgent release whose lint is red only with findings its baseline tag already had ships; a new finding is red';
+const LINK_DEPTH = 3;
+const NEW_SHOWN = 50;
+
+const sha256 = (file) => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+/** The findings of a Sonar Generic Issue Import file as { engine, rule, file, line, message }, or null when it is missing or unreadable. */
+export function sonarFindings(file) {
+  let doc;
+  try { doc = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+  if (!doc || !Array.isArray(doc.issues)) return null;
+  return doc.issues.map((issue) => ({
+    engine: String(issue.engineId ?? ''), rule: String(issue.ruleId ?? ''), file: String(issue.primaryLocation?.filePath ?? ''),
+    line: issue.primaryLocation?.textRange?.startLine ?? null, message: String(issue.primaryLocation?.message ?? ''),
+  }));
+}
+
+/** The findings of `head` the `baseline` does not hold: matched on engine, rule, file and message, then the rest on engine, rule and message. */
+export function newFindings(head, baseline) {
+  const take = (pool, key) => { const left = pool.get(key) ?? 0; if (left === 0) return false; pool.set(key, left - 1); return true; };
+  const exact = (finding) => `${finding.engine}\u0000${finding.rule}\u0000${finding.file}\u0000${finding.message}`;
+  const loose = (finding) => `${finding.engine}\u0000${finding.rule}\u0000${finding.message}`;
+  const exactPool = new Map();
+  for (const finding of baseline) exactPool.set(exact(finding), (exactPool.get(exact(finding)) ?? 0) + 1);
+  const unmatched = head.filter((finding) => !take(exactPool, exact(finding)));
+  const loosePool = new Map();
+  for (const finding of baseline) {
+    const left = exactPool.get(exact(finding)) ?? 0;
+    if (left > 0) { exactPool.set(exact(finding), left - 1); loosePool.set(loose(finding), (loosePool.get(loose(finding)) ?? 0) + 1); }
+  }
+  return unmatched.filter((finding) => !take(loosePool, loose(finding)));
+}
+
+/** Every node_modules folder of `root` within LINK_DEPTH levels (never inside one), app-relative. */
+function installFolders(root) {
+  const found = [];
+  const walk = (rel, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === '.git') continue;
+      const child = rel ? path.join(rel, entry.name) : entry.name;
+      if (entry.name === 'node_modules') found.push(child);
+      else if (depth < LINK_DEPTH) walk(child, depth + 1);
+    }
+  };
+  walk('', 0);
+  return found;
+}
+
+/** Removes a link made by this module: the link alone, never what it points at. */
+function unlink(link) {
+  try { fs.unlinkSync(link); } catch { try { fs.rmdirSync(link); } catch { /* already gone */ } }
+}
+
+/** The lint of `gate` with its findings written to `report`: { row, findings } (findings null when the lint could not run). */
+function lintTo(ctx, gate, { name, report, dir, platform }) {
+  fs.rmSync(report, { force: true });
+  const row = runGate(ctx, { ...gate, name, command: [...gate.command, '--', '--sonar', report] }, { dir, platform, credentialNames: [] });
+  const ran = row.pass || row.detail === 'exit 1';
+  return { row, findings: ran ? sonarFindings(report) : null };
+}
+
+/**
+ * The lint row of an urgent release against `tag`: { name, command, pass, detail, log, logSha256, baseline }. Refuses a tag that is not a
+ * commit. `dir` is the record folder of HEAD, where both reports, both logs and lint-new.json are written.
+ */
+export function baselineLint(ctx, gate, { tag, dir, platform }) {
+  const commit = git(ctx, ['rev-parse', '--verify', '--quiet', `${tag}^{commit}`], { allowFail: true });
+  if (commit.code !== 0 || commit.stdout === '') throw refusal('RELEASE_URGENT_LINT_BASELINE_TAG', `--lint-baseline ${tag} names no commit`);
+  fs.mkdirSync(dir, { recursive: true });
+  const headReport = path.join(dir, 'lint-head.sonar.json');
+  const head = lintTo(ctx, gate, { name: 'lint', report: headReport, dir, platform });
+  const row = (pass, detail, baseline = null) => ({ ...head.row, pass, detail, baseline: baseline && { tag, commit: commit.stdout, ruling: LINT_BASELINE_RULING, ...baseline } });
+  if (head.findings === null) return row(false, `the lint at HEAD could not run (${head.row.detail})`);
+  if (head.findings.length === 0) return row(true, 'no finding at HEAD', { findings: 0, headFindings: 0, newFindings: 0 });
+  const tree = path.join(os.tmpdir(), `starci-lint-baseline-${randomBytes(4).toString('hex')}`);
+  const links = [];
+  const added = git(ctx, ['worktree', 'add', '--detach', tree, commit.stdout], { allowFail: true });
+  if (added.code !== 0) return row(false, `the baseline worktree of ${tag} could not be made`);
+  try {
+    for (const rel of installFolders(ctx.cwd)) {
+      const link = path.join(tree, rel);
+      if (fs.existsSync(link) || !fs.existsSync(path.dirname(link))) continue;
+      fs.symlinkSync(path.join(ctx.cwd, rel), link, 'junction');
+      links.push(link);
+    }
+    const baseReport = path.join(dir, 'lint-baseline.sonar.json');
+    const base = lintTo(Object.create(ctx, { cwd: { value: tree } }), gate, { name: 'lint-baseline', report: baseReport, dir, platform });
+    if (base.findings === null) return row(false, `the lint at the baseline ${tag} could not run (${base.row.detail}; log ${base.row.log})`);
+    const fresh = newFindings(head.findings, base.findings);
+    fs.writeFileSync(path.join(dir, 'lint-new.json'), `${JSON.stringify(fresh, null, 2)}\n`);
+    const counts = {
+      findings: base.findings.length, headFindings: head.findings.length, newFindings: fresh.length,
+      headReport, headReportSha256: sha256(headReport), baselineReport: baseReport, baselineReportSha256: sha256(baseReport), baselineLog: base.row.log,
+      newShown: fresh.slice(0, NEW_SHOWN).map((finding) => `${finding.file}:${finding.line ?? '-'} ${finding.rule} ${finding.message}`),
+    };
+    const detail = `${head.findings.length} finding(s) at HEAD, ${base.findings.length} at ${tag}, ${fresh.length} new${fresh.length > 0 ? ` (${path.join(dir, 'lint-new.json')})` : ''}`;
+    return row(fresh.length === 0, detail, counts);
+  } finally {
+    links.reverse().forEach(unlink);
+    // A link still present would let the removal delete through it into HEAD's installs: the worktree then stays for a person to unlink.
+    if (links.every((link) => !fs.existsSync(link))) git(ctx, ['worktree', 'remove', '--force', tree], { allowFail: true });
+    else ctx.stderr?.(`lint baseline: ${tree} keeps a linked node_modules; unlink it (cmd /c rmdir <link>) before removing the worktree\n`);
+  }
+}

package/release/urgent.mjs

@@ -11,6 +11,7 @@ import { firstLine } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
 import { assertUnmoved, git, inspect, releaseDir, runGate, summaryOf } from './gate.mjs';
 import { assertNames, branchRefs, probe, tagRefs } from './push.mjs';
+import { baselineLint } from './lint-baseline.mjs';
 import { URGENT_RULING, URGENT_SCHEMA, greenRow, recordRow, writeUrgent } from './records.mjs';
 
 /** The fast local checks of an urgent release, by gate name, in the order they run. */
@@ -46,11 +47,19 @@ function changedLint(ctx, gate, prefix) {
   return { gate: { ...gate, command: ['npx', 'starci', 'app', 'lint', '--changed', ...files] }, note: `${files.length} file(s) changed since ${since}` };
 }
 
-/** The urgent checks this app declares, from its release gates; a lint row is narrowed to the changed files. */
-function urgentGates(ctx, config, prefix) {
+/**
+ * The urgent checks this app declares, from its release gates; a lint row is narrowed to the changed files, or, with `lintBaseline` (a release
+ * tag), judged whole against that tag's findings (lint-baseline.mjs), which only the managed lint can be.
+ */
+function urgentGates(ctx, config, prefix, lintBaseline) {
   const declared = URGENT_CHECKS.map((name) => config.gates.find((gate) => gate.name === name)).filter(Boolean);
   if (declared.length === 0) throw refusal('RELEASE_URGENT_NO_CHECKS', `the release gates declare none of ${URGENT_CHECKS.join(', ')}: an urgent release still runs its fast local checks`);
-  return declared.map((gate) => (gate.name === 'lint' ? { name: gate.name, ...changedLint(ctx, gate, prefix) } : { name: gate.name, gate, note: null }));
+  return declared.map((gate) => {
+    if (gate.name !== 'lint') return { name: gate.name, gate, note: null };
+    if (lintBaseline === undefined) return { name: gate.name, ...changedLint(ctx, gate, prefix) };
+    if (gate.command.join(' ') !== MANAGED_LINT) throw refusal('RELEASE_URGENT_LINT_BASELINE_UNMANAGED', `--lint-baseline judges the managed lint (${MANAGED_LINT}), and this app's lint gate runs ${gate.command.join(' ')}`);
+    return { name: gate.name, gate, baseline: lintBaseline, note: `the whole app, judged against ${lintBaseline}: only a finding new since it is red (owner ruling urgent-lint-baseline)` };
+  });
 }
 
 /** Runs (or reuses) each check in order and stops at the first red one. Returns the rows of the record. */
@@ -62,6 +71,12 @@ function runChecks(ctx, checks, { common, head, dir, platform }) {
       rows.push({ name: check.name, command: null, pass: true, reused: false, detail: check.note, log: null, logSha256: null });
       continue;
     }
+    if (check.baseline !== undefined) {
+      const row = baselineLint(ctx, check.gate, { tag: check.baseline, dir, platform });
+      rows.push({ ...row, reused: false, note: check.note });
+      if (!row.pass) break;
+      continue;
+    }
     const command = check.gate.command.join(' ');
     const reused = greenRow(common, head, check.name, command);
     if (reused) {
@@ -97,7 +112,7 @@ export async function releaseUrgentPush(ctx, config, options = {}) {
   const { head, chosen } = facts;
   const common = releaseDir(ctx);
   const dir = path.join(common, head.slice(0, 12));
-  const checks = urgentGates(ctx, config, config.tagPrefix);
+  const checks = urgentGates(ctx, config, config.tagPrefix, options.lintBaseline);
   const out = [...facts.out, `urgent         ${URGENT_RULING}`, `reason         ${reason}`, `role           ${role}`, ...planOf(checks)];
   const data = { head, tag: chosen.tag, remote, branch, urgent: true, reason, role, checks: [], pushed: false };
   if (facts.red.length > 0) return { ok: false, lines: [...out, ...facts.red.map((item) => `RED: ${item}`), 'nothing run, nothing pushed.'], data: { ...data, red: facts.red } };

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.25
+    version: 0.15.27
     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.12
+    version: 3.8.14
     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.14
+    version: 9.5.16
     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.25
+    version: 0.15.27
     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.25
+    version: 0.15.27
     group: starci
     install: registry
     side: fe
@@ -85,7 +85,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.5.0
+    version: 2.5.1
     group: starci
     install: registry
     side: be
@@ -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.13
+    version: 4.11.15
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -1629,7 +1629,7 @@ rules:
     witness:
       - {"path":"packages/eslint/be/r80-inbox-dedupe-required.spec.mjs","edition":"lite","codes":["BE_INBOX_DEDUPE_MISSING"]}
       - {"path":"packages/eslint/be/r80-inbox-dedupe-required.spec.mjs","edition":"full","codes":["BE_INBOX_DEDUPE_MISSING"]}
-    law: "Every service method that takes a delivery (a public method of a `*.service.ts` whose first parameter has an `eventId`) makes `claim(source, eventId)` on the `Inbox` port its first awaited expression and returns early when the claim answers `false`; consumers stay thin doors (R88) and dispatch one command to the handler whose service claims. SignedWebhook controllers verify first and call one domain recording intake directly (R182, R183); a reactor or job dispatches the processing command after the inbox receipt commits."
+    law: "Every service method that takes a delivery (a public method of a `*.service.ts` whose first parameter has an `eventId`) makes `claim(source, eventId)` on the `Inbox` port, or `claimRow(source, eventId, tx, receipt)` on its `EntityInbox` extension (the claim, then the receipt entity row inserted only for the winning claim), its first awaited expression and returns early on a repeat: when `claim` answers `false` or `claimRow` answers no receipt id (`undefined`); consumers stay thin doors (R88) and dispatch one command to the handler whose service claims. SignedWebhook controllers verify first and call one domain recording intake directly (R182, R183); a reactor or job dispatches the processing command after the inbox receipt commits."
     kinds: [lint, design]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["BE_INBOX_DEDUPE_MISSING"]
@@ -4233,7 +4233,7 @@ rules:
     code: "HFS_AGE_KEY_CUSTODY"
     editions: [lite, full]
     docs: [docs/host-secrets.md#application-secret-rules]
-    law: "The age identity that seals and opens an app's `.starcistacks/<env>/secrets/*.enc` is host-local custody only: it lives in the untracked `.claude/secret.env` (as `SOPS_AGE_KEY`, which wins over the legacy `keys.txt` and is handed to sops through the `SOPS_AGE_KEY` child environment, never as an argument and never printed) or in the sops config dir's `keys.txt`; a tracked `.claude/secret.env`, `keys.txt` or `*.agekey` is the identity committed. The three files the secret custody depends on - `src/modules/platform/config/env-source.config.ts`, `src/modules/platform/http-security/origin.guard.ts` and `src/modules/platform/http-security/webhook-signature.service.ts` - are hash-sensitive canon, not files to edit: their bytes equal the `be/skeleton` template they were scaffolded from, judged by sha256."
+    law: "The age identity that seals and opens an app's `.starcistacks/<env>/secrets/*.enc` is host-local custody only: it lives in the untracked `.claude/secret.env` (as `SOPS_AGE_KEY`, which wins over the legacy `keys.txt` and is handed to sops through the `SOPS_AGE_KEY` child environment, never as an argument and never printed) or in the sops config dir's `keys.txt`; a tracked `.claude/secret.env`, `keys.txt` or `*.agekey` is the identity committed. The three files the secret custody depends on - `src/modules/platform/config/env-source.config.ts`, `src/modules/platform/http-security/origin.guard.ts` and `src/modules/platform/http-security/webhook-signature.service.ts` - are hash-sensitive canon, not files to edit: their bytes equal the `be/skeleton` template of the @starci/hfs version the app pins (never of a newer hfs running the check), judged by sha256."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["HFS_AGE_KEY_CUSTODY", "HFS_CANON_COPY_DRIFT"]
@@ -4418,7 +4418,7 @@ rules:
   - id: R263
     code: "BE_WEBHOOK_SCOPE"
     amendedBy: [owner:oauth-redirect-not-webhook, owner:webhook-receipt-port]
-    law: "SignedWebhook public metadata belongs only to a webhook HTTP door or an exact domain verifier declared in its HTTP module's exported webhookVerifiers array. A public controller route containing webhook, callback or events belongs in the webhook door; the one exception is a third-party OAuth redirect (owner:oauth-redirect-not-webhook): a GET route that declares PublicReason.AuthHandshake and whose path is not a webhook or events path, which has no signature to verify and is not a door. A POST, a webhook or events path, and any other reason are still judged. A receipt transaction may call a domain receipt port (owner:webhook-receipt-port): a class with no base class whose constructor takes only platform ports and TypeORM, one of them the platform Inbox; a call on any other domain service or on a bus inside the transaction is processing. Domain intake methods identified by a first *Id parameter or DTO property, or raw-body signature input, claim the shared Inbox with the stable delivery key and return early on a duplicate before doing work. The receipt transaction records the inbox delivery and publishes its typed outbox event; process callbacks, domain processing and command dispatch run only after commit in a reactor or job."
+    law: "SignedWebhook public metadata belongs only to a webhook HTTP door or an exact domain verifier declared in its HTTP module's exported webhookVerifiers array. A public controller route containing webhook, callback or events belongs in the webhook door; the one exception is a third-party OAuth redirect (owner:oauth-redirect-not-webhook): a GET route that declares PublicReason.AuthHandshake and whose path is not a webhook or events path, which has no signature to verify and is not a door. A POST, a webhook or events path, and any other reason are still judged. A receipt transaction may call a domain receipt port (owner:webhook-receipt-port): a class with no base class whose constructor takes only platform ports and TypeORM, one of them the platform Inbox or its EntityInbox; a call on any other domain service or on a bus inside the transaction is processing. Domain intake methods identified by a first *Id parameter or DTO property, or raw-body signature input, claim the shared Inbox with the stable delivery key (claim, or claimRow on its EntityInbox with the receipt row and the transaction's own manager) and return early on a duplicate (false from claim, undefined from claimRow) before doing work. The receipt transaction records the inbox delivery and publishes its typed outbox event; process callbacks, domain processing and command dispatch run only after commit in a reactor or job."
     kinds: [lint]
     gates: ["pre-commit","settle","land","ci"]
     failureCodes: ["BE_WEBHOOK_SCOPE", "BE_WEBHOOK_INBOX_KEY"]

package/runtime/knowledge/patterns/be/webhooks.yaml

@@ -370,8 +370,9 @@ sourceMaintenance: >-
   verifies first and calls the supplied domain service's record<Provider>Delivery once. Implement that method as the
   transactional inbox receipt/outbox recording intake above, then add its reactor or job separately.
   In lite, the generated POST verifies first and calls <Provider>InboxService.record<Provider>Delivery. This record-only
-  domain intake uses recordWebhookDelivery to insert a pending provider inbox row atomically in the app's Postgres, unique on
-  (provider, delivery_id), without processing it or marking it complete. Add a reactor or job separately to consume the
+  domain intake injects the EntityInbox (InjectEntityInbox) and awaits claimRow first: it claims the delivery id and, for the
+  winning claim only, inserts the pending provider inbox row through its <Provider>InboxEntity in the same transaction, unique
+  on (provider, delivery_id), without processing it or marking it complete. Add a reactor or job separately to consume the
   committed pending row and dispatch the processing command (reactors.yaml, jobs.yaml). The --service option validates the
   future domain processing owner; the webhook writer does not import or call that owner synchronously and does not
   synthesize a consumer.

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/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('//');