@starci/hfs 4.9.8 → 4.9.11

package/release/gate.mjs

@@ -8,9 +8,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
 import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { openHfs } from '../runtime/scripts/hfs/slots.mjs';
 import { firstLine, lines, tool } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
 import { produceLintReports } from './lint-report.mjs';
+import { URGENT_RULING, l4Path, readUrgent, recordRow, writeUrgent } from './records.mjs';
 import { sonarQualityGate } from './sonar-quality-gate.mjs';
 
 export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
@@ -38,6 +40,8 @@ const SCRIPT_GATES = ['format:check', 'typecheck', 'build:be', 'lint', 'db:lint'
 const WORLD_SCRIPTS = ['test:integration', 'test:e2e', 'test:contract'];
 const DB_TYPES_SCRIPTS = ['db:start', 'db:reset', 'db:types', 'db:stop'];
 const DB_TYPES_COMMITTED = { name: 'db-types-committed', command: ['git', 'diff', '--exit-code', '--', 'supabase/types/database.types.ts'], summary: null, env: {} };
+// An app with an entity list (db/entity-list.mjs) checks its entities against the migrated schema: a row of every gate, declared or default.
+const DB_DRIFT = { name: 'db-drift', command: ['npx', 'starci', 'app', 'db', 'drift'], summary: null, env: {} };
 
 /** True for a branch or remote name git can take as one argument (no leading dash, only path-like characters). */
 export const refName = (value) => typeof value === 'string' && REF_NAME.test(value);
@@ -59,11 +63,11 @@ function dbTypesGates(scripts) {
   return [start, reset, types, DB_TYPES_COMMITTED, { ...stop, teardownOf: start.name }];
 }
 
-/** Default gates run app-check, the enabled audit, then every managed script present in the app and the database-types rows, Sonar following when it is declared. */
-function defaultGates(scripts, audit) {
+/** Default gates run app-check, the enabled audit, then every managed script present in the app, the database-types rows and the entity drift row, Sonar following when it is declared. */
+function defaultGates(scripts, audit, entities) {
   const present = SCRIPT_GATES.filter((script) => typeof scripts?.[script] === 'string');
   const world = typeof scripts?.['test:e2e'] === 'string' ? WORLD_SCRIPTS.filter((script) => typeof scripts?.[script] === 'string') : [];
-  return [{ name: 'app-check', command: ['npx', 'starci', 'app', 'check'], summary: null, env: {} }, ...(audit ? [audit] : []), ...present.map(scriptGate), ...world.map(scriptGate), ...dbTypesGates(scripts)];
+  return [{ name: 'app-check', command: ['npx', 'starci', 'app', 'check'], summary: null, env: {} }, ...(audit ? [audit] : []), ...present.map(scriptGate), ...world.map(scriptGate), ...dbTypesGates(scripts), ...(entities ? [DB_DRIFT] : [])];
 }
 
 /** Shared quality settings retain the release reader's audit validation, disabled mode and legacy string host compatibility. */
@@ -148,8 +152,9 @@ export function normalizeRelease(block, scripts = {}, services = {}, options = {
   if (typeof requireCi !== 'boolean') problems.push('release.requireCi: must be true or false');
   const quality = releaseServices(services, options);
   const audit = auditGate(quality.audit);
-  const gates = raw.gates === undefined ? defaultGates(scripts, audit) : gatesOf(raw.gates, problems);
+  const gates = raw.gates === undefined ? defaultGates(scripts, audit, options.entities === true) : gatesOf(raw.gates, problems);
   if (raw.gates !== undefined && audit && !gates.some((gate) => gate.name === 'audit')) gates.push(audit);
+  if (raw.gates !== undefined && options.entities === true && !gates.some((gate) => gate.name === DB_DRIFT.name)) gates.push(DB_DRIFT);
   return problems.length === 0 ? { config: { gates, tagPrefix, defaultBranch, requireCi, services: quality } } : { problems };
 }
 
@@ -175,7 +180,22 @@ export function annotatedOnHead(ctx, prefix) {
 /** Every tag on HEAD whose name ends in a version, annotated or not, under any prefix: a release commit carries exactly one. */
 const versionTagsOnHead = (ctx) => lines(git(ctx, ['tag', '--points-at', 'HEAD']).stdout).filter((name) => /[0-9]+[.][0-9]+[.][0-9]+$/u.test(name));
 
-const dirtyPaths = (ctx) => lines(git(ctx, ['status', '--porcelain', '--untracked-files=normal']).stdout);
+/** The rewrittenBy predicate of the app's slots: true for a path a dev server writes (hfs slots `rewrittenBy`); without a readable hfs.json, for none. */
+function rewrittenByDevServer(root) {
+  let hfs;
+  try { hfs = openHfs({ repoRoot: root }); } catch { return () => false; }
+  return (file) => typeof hfs.slotOf(file)?.rewrittenBy === 'string';
+}
+
+/**
+ * The paths that make the tree dirty: every changed tracked path and every untracked one, except an untracked file the app's slots declare a dev
+ * server rewrites (`rewrittenBy`, e.g. the AGENTS.md `next dev` writes): that one is known generated output, never a change of the release.
+ */
+export function dirtyPaths(ctx) {
+  const rewritten = rewrittenByDevServer(ctx.cwd);
+  return lines(git(ctx, ['status', '--porcelain', '--untracked-files=all']).stdout)
+    .filter((line) => !(line.startsWith('?? ') && rewritten(line.slice(3).replace(/^"|"$/gu, ''))));
+}
 
 /** Tag names that exist locally or on the remote. */
 function takenTags(ctx, prefix, remote) {
@@ -243,7 +263,7 @@ async function sonarAvailability(ctx, gate) {
 }
 
 /** An unreachable Sonar host stays a red row with a real log and no scan invocation. */
-async function runAvailableGate(ctx, gate, options) {
+export async function runAvailableGate(ctx, gate, options) {
   const availability = await sonarAvailability(ctx, gate);
   const log = path.join(options.dir, `${gate.name}.log`);
   if (!availability) {
@@ -274,12 +294,12 @@ async function judgeQualityGate(ctx, gate, row) {
   return { ...row, pass: verdict.pass, detail: verdict.detail, seconds: row.seconds + Math.round((ctx.now() - started) / 1000), logSha256: sha256(row.log) };
 }
 
-const withoutCredentials = (values, credentialNames) => {
+export const withoutCredentials = (values, credentialNames) => {
   const selected = new Set(credentialNames);
   return Object.fromEntries(Object.entries(values ?? {}).filter(([key]) => !selected.has(key.toUpperCase())));
 };
 
-function runGate(ctx, gate, { dir, platform, credentialNames, preface = '' }) {
+export function runGate(ctx, gate, { dir, platform, credentialNames, preface = '' }) {
   const log = path.join(dir, `${gate.name}.log`);
   const started = ctx.now();
   const [command, args] = launch(gate.command, platform);
@@ -323,7 +343,7 @@ function tagLine({ tag, state }) {
 }
 
 /** Everything that can be known without running a gate: the facts, the red preconditions and the lines that describe them. */
-function inspect(ctx, config, options) {
+export function inspect(ctx, config, options) {
   const head = git(ctx, ['rev-parse', 'HEAD']).stdout;
   const branch = git(ctx, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true }).stdout;
   const out = [`checkout       ${ctx.cwd}`, `HEAD           ${head} (${branch})`];
@@ -354,18 +374,19 @@ function planLines(config, facts, dir, recordPath) {
   return out;
 }
 
-function assertUnmoved(ctx, head) {
+export function assertUnmoved(ctx, head) {
   const now = git(ctx, ['rev-parse', 'HEAD']).stdout;
   if (now !== head) throw failure('RELEASE_HEAD_MOVED', `HEAD moved during the gates (${head.slice(0, 10)} -> ${now.slice(0, 10)}). No record.`);
   const dirty = dirtyPaths(ctx);
   if (dirty.length > 0) throw failure('RELEASE_TREE_DIRTY', `the gates left ${dirty.length} changed or untracked path(s) (first: ${dirty[0].slice(0, 100)}): generated files differ from HEAD. Commit or ignore them properly, then rerun. No record.`);
 }
 
-function writeRecord(ctx, { head, tag, results, recordPath, requireCi }) {
+function writeRecord(ctx, { head, tag, results, recordPath, requireCi, promotedFrom = null }) {
   const record = {
     schema: 'starci-app-l4-record/1', head, tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release gate',
     note: 'Every gate passed on a clean HEAD; every entry links its log and sha256.',
     ci: requireCi === true ? { required: true, note: 'starci app release push waits for the candidate CI of this sha (release.requireCi=true)' } : { required: false, note: CI_NOT_REQUIRED },
+    ...(promotedFrom ? { promotedFrom } : {}),
     gates: results,
   };
   fs.mkdirSync(path.dirname(recordPath), { recursive: true });
@@ -381,17 +402,48 @@ async function runAll(ctx, config, options) {
   return config.gates.reduce(async (pending, gate) => {
     const results = await pending;
     if (results.some((result) => !result.pass) && !(gate.teardownOf && results.some((result) => result.name === gate.teardownOf))) return results;
-    return [...results, await runAvailableGate(ctx, gate, options)];
+    const result = await runAvailableGate(ctx, gate, options);
+    recordRow(options.common, options.head, result);
+    return [...results, result];
   }, Promise.resolve([]));
 }
 
-function summaryOf(result) {
+export function summaryOf(result) {
   return `${result.pass ? 'PASS' : 'FAIL'} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
 }
 
+/**
+ * The urgent release a back-fill judges: `tag` must name HEAD (the back-fill runs on the very commit that shipped, never a re-release) and HEAD must
+ * carry an urgent record of that tag. Returns the record; refuses otherwise.
+ */
+function backfillTarget(ctx, common, tag, head) {
+  if (!refName(tag)) throw refusal('RELEASE_USAGE', `--backfill ${tag} is not a tag name`);
+  const resolved = git(ctx, ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}^{commit}`], { allowFail: true });
+  if (resolved.code !== 0 || resolved.stdout === '') throw refusal('RELEASE_BACKFILL_TAG_UNKNOWN', `no tag ${tag} in this repository`);
+  if (resolved.stdout !== head) throw refusal('RELEASE_BACKFILL_NOT_ON_TAG', `${tag} is ${resolved.stdout.slice(0, 10)} but HEAD is ${head.slice(0, 10)}: run the back-fill in a clean checkout of the tag (git worktree add --detach <dir> ${tag}), so the full gate judges exactly what shipped`);
+  const urgent = readUrgent(common, head);
+  if (!urgent || urgent.tag !== tag) throw refusal('RELEASE_BACKFILL_NOT_URGENT', `${tag} has no urgent record on ${head.slice(0, 10)}: only a release pushed with release push --urgent is back-filled`);
+  return urgent;
+}
+
+/** A red back-fill: the urgent record keeps the verdict and the fix ticket (kind verify) the harness opened; nothing on the remote or on prod changes. */
+function backfillRed(ctx, { common, urgent, failed, openTicket }) {
+  const names = failed.map((item) => item.name);
+  const title = `RELEASE_BACKFILL_RED: the back-fill of urgent release ${urgent.tag} (${urgent.head.slice(0, 12)}) is red at ${names.join(', ')}`;
+  const tail = failed.map((item) => `${item.name}: ${item.detail} (log ${item.log})`).join('\n');
+  const ticket = typeof openTicket === 'function' ? openTicket({ title, tail, code: 'RELEASE_BACKFILL_RED', tag: urgent.tag, head: urgent.head }) : null;
+  writeUrgent(common, { ...urgent, backfill: { state: 'red', at: new Date(ctx.now()).toISOString(), failed: names, ticket: ticket ?? null } });
+  const said = ticket
+    ? `back-fill red: fix ticket ${ticket} opened (kind verify); ${urgent.tag} stays an urgent release and nothing on the remote or on prod changed`
+    : `back-fill red: no ticket queue in this run (run it through the starci CLI to open one); ${urgent.tag} stays an urgent release and nothing on the remote or on prod changed`;
+  return { said, ticket: ticket ?? null };
+}
+
 /**
  * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if required gates pass,
- * writes the L4 record and creates the annotated tag. options: { execute, sonar, source, tagPrefix, platform }.
+ * writes the L4 record and creates the annotated tag. options: { execute, sonar, source, tagPrefix, platform, backfill, openTicket }.
+ * With `backfill` (a tag pushed by `release push --urgent`, checked out at HEAD) the same full gate judges that commit: green writes its L4 record
+ * (promotedFrom the urgent record) and marks the urgent record promoted, with no new tag and no push; red opens a fix ticket through `openTicket`.
  */
 export async function releaseGate(ctx, config, options = {}) {
   // Sonar is a row of the managed CI, so it is a row of the local gate whenever the app declares it (and when --sonar asks for it); a missing token is a refusal, never a skip.
@@ -402,18 +454,29 @@ export async function releaseGate(ctx, config, options = {}) {
   // the gate no longer refuses over the latest default-branch run.
   const facts = inspect(ctx, config, options);
   const common = releaseDir(ctx);
-  const recordPath = path.join(common, `${facts.head}.l4.json`);
+  const urgent = options.backfill === undefined ? null : backfillTarget(ctx, common, options.backfill, facts.head);
+  const recordPath = l4Path(common, facts.head);
   const dir = path.join(common, facts.head.slice(0, 12));
   const plan = [...facts.out, ...planLines(config, facts, dir, recordPath)];
-  const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name) };
+  if (urgent) plan.push(`back-fill      urgent release ${urgent.tag} (${URGENT_RULING}): green promotes it to this L4 record with no new tag and no push; red opens a fix ticket and changes nothing on prod`);
+  const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name), ...(urgent ? { backfill: urgent.tag } : {}) };
+  if (urgent?.backfill?.state === 'promoted') return { ok: true, lines: [...plan, `back-fill already promoted ${urgent.tag} to ${urgent.backfill.l4}. Nothing to do.`], data: { ...base, red: [], executed: false, promoted: true } };
   if (facts.red.length > 0) return { ok: false, lines: [...plan, ...facts.red.map((item) => `RED: ${item}`), 'nothing was run.'], data: { ...base, red: facts.red, executed: false } };
   if (options.execute !== true) return { ok: true, lines: [...plan, '', 'dry run: no gate was run, nothing written. preconditions OK.'], data: { ...base, red: [], executed: false } };
-  const results = await runAll(ctx, config, { dir, platform: options.platform ?? process.platform, credentialNames });
+  const results = await runAll(ctx, config, { dir, common, head: facts.head, platform: options.platform ?? process.platform, credentialNames });
   const report = results.map(summaryOf);
   const failed = results.filter((result) => !result.pass);
+  if (failed.length > 0 && urgent) {
+    const { said, ticket } = backfillRed(ctx, { common, urgent, failed, openTicket: options.openTicket });
+    return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record.`, said], data: { ...base, executed: true, results, promoted: false, ticket } };
+  }
   if (failed.length > 0) return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record, no tag.`], data: { ...base, executed: true, results } };
   assertUnmoved(ctx, facts.head);
-  writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath, requireCi: config.requireCi });
+  writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath, requireCi: config.requireCi, promotedFrom: urgent ? { record: `${facts.head}.urgent.json`, reason: urgent.reason, role: urgent.role, at: urgent.createdAt } : null });
+  if (urgent) {
+    writeUrgent(common, { ...urgent, backfill: { state: 'promoted', at: new Date(ctx.now()).toISOString(), l4: recordPath } });
+    return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, `back-fill green: urgent release ${urgent.tag} is promoted to a normal L4 release (no re-release, no push)`], data: { ...base, executed: true, results, promoted: true } };
+  }
   const created = facts.chosen.state !== 'on-head';
   if (created) git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: required gates passed on ${facts.head.slice(0, 12)} (L4 record ${path.basename(recordPath)})`, facts.head]);
   const tagged = created ? `annotated tag ${facts.chosen.tag} created on ${facts.head.slice(0, 10)}` : `annotated tag ${facts.chosen.tag} already on ${facts.head.slice(0, 10)}`;

package/release/index.mjs

@@ -1,18 +1,22 @@
 // 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>] [--json]
-//   starci app release push [--execute] [--remote <name>] [--json]
+//   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]
+// `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).
 import fs from 'node:fs';
 import path from 'node:path';
 import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
+import { hasEntityList } from '../db/entity-list.mjs';
 import { STACKS_DIR, STACKS_FILE } from '../stack/config.mjs';
 import { stackContext } from '../stack/context.mjs';
 import { EXIT, StackError, refusal } from '../stack/errors.mjs';
 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'];
 
@@ -58,7 +62,7 @@ function loadReleaseConfig(root) {
   const pkg = readPackage(root);
   if (typeof pkg.version !== 'string' || !VERSION.test(pkg.version)) throw refusal(RELEASE_CODE, 'package.json needs a version like 1.2.3 (the release tag derives from it)');
   const declaration = readDeclaration(root);
-  const { config, problems } = normalizeRelease(declaration.release, pkg.scripts, declaration.services, { example: isRuntimeExampleApp(root) });
+  const { config, problems } = normalizeRelease(declaration.release, pkg.scripts, declaration.services, { example: isRuntimeExampleApp(root), entities: hasEntityList(root) });
   if (!config) throw refusal(RELEASE_CODE, `${problems.length} problem(s) in release: ${problems.slice(0, 6).join('; ')}`);
   return { root, version: pkg.version, ...config };
 }
@@ -85,12 +89,19 @@ export async function runVerb({ label, name, io, argv, spec, run, code = 'RELEAS
 
 const ACTIONS = {
   gate: {
-    spec: { boolean: ['--execute', '--json', '--sonar'], value: ['--source', '--tag-prefix'] },
-    run: (ctx, flags) => releaseGate(ctx, loadReleaseConfig(ctx.cwd), { execute: flags.execute === true, sonar: flags.sonar === true, source: flags.source, tagPrefix: flags['tag-prefix'] }),
+    spec: { boolean: ['--execute', '--json', '--sonar'], value: ['--source', '--tag-prefix', '--backfill'] },
+    run: (ctx, flags, harness) => releaseGate(ctx, loadReleaseConfig(ctx.cwd), {
+      execute: flags.execute === true, sonar: flags.sonar === true, source: flags.source, tagPrefix: flags['tag-prefix'], backfill: flags.backfill, openTicket: harness?.openTicket,
+    }),
   },
   push: {
-    spec: { boolean: ['--execute', '--json'], value: ['--remote'] },
-    run: (ctx, flags) => releasePush(ctx, loadReleaseConfig(ctx.cwd), { execute: flags.execute === true, remote: flags.remote }),
+    spec: { boolean: ['--execute', '--json', '--urgent'], value: ['--remote', '--reason'] },
+    run: (ctx, flags, harness) => {
+      if (flags.reason !== undefined && flags.urgent !== true) throw refusal('RELEASE_USAGE', '--reason 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 });
+      return releasePush(ctx, config, { execute: flags.execute === true, remote: flags.remote });
+    },
   },
 };
 
@@ -101,5 +112,5 @@ export async function releaseMain(argv, io = {}) {
     contextOf(io).stderr('starci app release: takes gate or push\n');
     return EXIT.refused;
   }
-  return runVerb({ label: 'starci app release', name: argv[0], io, argv: argv.slice(1), spec: action.spec, run: action.run });
+  return runVerb({ label: 'starci app release', name: argv[0], io, argv: argv.slice(1), spec: action.spec, run: (ctx, flags) => action.run(ctx, flags, io.harness) });
 }

package/release/push.mjs

@@ -49,7 +49,7 @@ function remoteTagObject(ctx, remote, tag) {
   return listed.map((line) => line.split('\t')).find((parts) => parts[1] === wanted)?.[0] ?? '';
 }
 
-function branchRefs(ctx, { head, remote, branch }, red) {
+export function branchRefs(ctx, { head, remote, branch }, red) {
   const tip = remoteTip(ctx, remote, branch);
   if (tip === null || isAncestor(ctx, tip, head)) return { refs: tip === head ? [] : [`${head}:refs/heads/${branch}`], tip };
   if (isAncestor(ctx, head, tip)) return { refs: [], tip };
@@ -57,14 +57,14 @@ function branchRefs(ctx, { head, remote, branch }, red) {
   return { refs: [], tip };
 }
 
-function tagRefs(ctx, { remote, tag }, red) {
+export function tagRefs(ctx, { remote, tag }, red) {
   const object = remoteTagObject(ctx, remote, tag);
   if (object === '') return [`refs/tags/${tag}`];
   if (object !== git(ctx, ['rev-parse', `refs/tags/${tag}`]).stdout) red.push(`tag ${tag} exists on ${remote} as a different object`);
   return [];
 }
 
-function probe(ctx, remote, refs, red) {
+export function probe(ctx, remote, refs, red) {
   const run = git(ctx, ['push', '--dry-run', '--atomic', remote, ...refs], { allowFail: true });
   const verdict = `${run.stderr}\n${run.stdout}`.split('\n').filter((line) => VERDICT.test(line)).slice(0, 4);
   if (run.code !== 0) red.push('the pre-push hook refuses this push as things stand');
@@ -73,7 +73,7 @@ function probe(ctx, remote, refs, red) {
 
 const NAME_RULE = '^[A-Za-z0-9._/-]+$';
 
-function assertNames(remote, branch) {
+export function assertNames(remote, branch) {
   if (!refName(remote)) throw refusal('RELEASE_USAGE', `--remote ${remote} must match ${NAME_RULE}`);
   if (!refName(branch)) throw refusal('RELEASE_USAGE', `the default branch ${branch} must match ${NAME_RULE}`);
 }

package/release/records.mjs

@@ -0,0 +1,54 @@
+// records.mjs - the release records of an app, all under <git common dir>/starci-release (gate.mjs releaseDir):
+//   <head>.l4.json        the L4 record: every gate of the release gate passed on a clean HEAD (gate.mjs writes it)
+//   <head>.urgent.json    the URGENT record (owner ruling urgent-release, 2026-10-29): `release push --urgent` tagged and pushed HEAD after the
+//                         fast local checks alone; it names who (role), why (reason), the checks with their verdicts and the commit, and
+//                         carries the back-fill verdict once `release gate --backfill <tag>` has run the full gate on the same commit
+//   <head12>/rows.json    every gate row run on that head (name, command, verdict, log and its sha256), so a later urgent push reuses a green
+//                         row whose command and log are unchanged instead of running it again
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const URGENT_SCHEMA = 'starci-app-urgent-record/1';
+/** The owner's ruling an urgent record cites: CI and the full gate wait for the back-fill, the safety floor of the deploy never does. */
+export const URGENT_RULING = 'owner ruling urgent-release 2026-10-29: an urgent release ships after the fast local checks; the full gate runs later on the same tag (release gate --backfill) and the deploy safety floor is never skipped';
+
+const readJson = (file) => {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+};
+
+const writeJson = (file, value) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+};
+
+/** The sha256 of a file, or null when it cannot be read. */
+export const fileSha256 = (file) => {
+  try { return createHash('sha256').update(fs.readFileSync(file)).digest('hex'); } catch { return null; }
+};
+
+export const l4Path = (dir, head) => path.join(dir, `${head}.l4.json`);
+export const urgentPath = (dir, head) => path.join(dir, `${head}.urgent.json`);
+const rowsPath = (dir, head) => path.join(dir, head.slice(0, 12), 'rows.json');
+
+/** The urgent record of `head`, or null when there is none or it is not an urgent record of that head. */
+export function readUrgent(dir, head) {
+  const record = readJson(urgentPath(dir, head));
+  return record?.schema === URGENT_SCHEMA && record.head === head ? record : null;
+}
+
+export const writeUrgent = (dir, record) => writeJson(urgentPath(dir, record.head), record);
+
+/** Appends a gate row to the rows of `head` (a row of the same name is replaced). */
+export function recordRow(dir, head, row) {
+  const file = rowsPath(dir, head);
+  const rows = (readJson(file) ?? []).filter((known) => known?.name !== row.name);
+  writeJson(file, [...rows, row]);
+}
+
+/** The recorded green row of `head` whose name and command match and whose log still has the recorded sha256, or null. */
+export function greenRow(dir, head, name, command) {
+  const rows = readJson(rowsPath(dir, head)) ?? [];
+  const row = rows.find((known) => known?.name === name && known.command === command && known.pass === true);
+  return row && row.log && fileSha256(row.log) === row.logSha256 ? row : null;
+}

package/release/urgent.mjs

@@ -0,0 +1,129 @@
+// urgent.mjs - `starci app release push --urgent --reason "<text>"`, the sanctioned urgent path (owner ruling urgent-release, 2026-10-29: an urgent
+// deploy needs no CI). It runs only the fast local checks (app check, typecheck, lint of the files changed since the previous release tag, unit), or
+// reuses a green row the gate already recorded for HEAD with the same command and an unchanged log; tags HEAD (annotated) and pushes the default
+// branch and the tag in ONE atomic push through the repository's hook (never --no-verify, `git push --dry-run --atomic` first); then writes the
+// URGENT record <git common dir>/starci-release/<HEAD>.urgent.json naming who (the caller's role), why (the reason), each check with its verdict and the
+// commit. The candidate CI is not waited for. The full gate runs later on the same tag (`release gate --backfill <tag>`, gate.mjs), and the deploy
+// safety floor (backup, migrate preview then execute, readiness, rollback) is never skipped (stack/urgent-floor.mjs).
+import fs from 'node:fs';
+import path from 'node:path';
+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 { 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. */
+export const URGENT_CHECKS = Object.freeze(['app-check', 'typecheck', 'lint', 'test']);
+const REASON_MAX = 500;
+const CHANGED_MAX = 200;
+const PATH_WORD = /^[A-Za-z0-9_@%+=:,./\\-]+$/u;
+const MANAGED_LINT = 'npm run lint';
+
+/** The reason, one line of plain text; an urgent release without one is refused. */
+function reasonOf(value) {
+  const reason = String(value ?? '').replaceAll(/\s+/gu, ' ').trim();
+  if (reason === '') throw refusal('RELEASE_URGENT_REASON_MISSING', 'an urgent release says why: --reason "<text>"');
+  if (reason.length > REASON_MAX) throw refusal('RELEASE_URGENT_REASON_MISSING', `--reason is one line of at most ${REASON_MAX} characters`);
+  return reason;
+}
+
+/** The newest release tag reachable from HEAD's parent, or null on a first release. */
+function previousTag(ctx, prefix) {
+  const found = git(ctx, ['describe', '--tags', '--abbrev=0', '--match', `${prefix}[0-9]*`, 'HEAD^'], { allowFail: true });
+  return found.code === 0 && found.stdout !== '' ? found.stdout : null;
+}
+
+/** The lint row of an urgent release: the managed whole-app lint narrowed to the source files changed since the previous release tag. */
+function changedLint(ctx, gate, prefix) {
+  if (gate.command.join(' ') !== MANAGED_LINT) return { gate, note: null };
+  const since = previousTag(ctx, prefix);
+  if (!since) return { gate, note: 'no previous release tag: the whole app is linted' };
+  const files = git(ctx, ['diff', '--name-only', '--diff-filter=d', `${since}..HEAD`]).stdout.split('\n').map((file) => file.trim())
+    .filter((file) => /\.(?:[cm]?[jt]sx?|css)$/u.test(file));
+  if (files.length === 0) return { gate: null, note: `no source file changed since ${since}` };
+  if (files.length > CHANGED_MAX || !files.every((file) => PATH_WORD.test(file))) return { gate, note: `${files.length} changed file(s) since ${since}: the whole app is linted` };
+  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) {
+  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 }));
+}
+
+/** Runs (or reuses) each check in order and stops at the first red one. Returns the rows of the record. */
+function runChecks(ctx, checks, { common, head, dir, platform }) {
+  fs.mkdirSync(dir, { recursive: true });
+  const rows = [];
+  for (const check of checks) {
+    if (!check.gate) {
+      rows.push({ name: check.name, command: null, pass: true, reused: false, detail: check.note, log: null, logSha256: null });
+      continue;
+    }
+    const command = check.gate.command.join(' ');
+    const reused = greenRow(common, head, check.name, command);
+    if (reused) {
+      rows.push({ ...reused, reused: true, ...(check.note ? { note: check.note } : {}) });
+      continue;
+    }
+    const row = runGate(ctx, check.gate, { dir, platform, credentialNames: [] });
+    recordRow(common, head, row);
+    rows.push({ ...row, reused: false, ...(check.note ? { note: check.note } : {}) });
+    if (!row.pass) break;
+  }
+  return rows;
+}
+
+const checkLine = (row) => (row.command === null ? `SKIP ${row.name} (${row.detail})` : `${row.reused ? 'REUSED ' : ''}${summaryOf(row)}`);
+
+function planOf(checks) {
+  return ['urgent checks (each must pass; a green row recorded for HEAD with the same command and log is reused):',
+    ...checks.map((check) => `  ${check.name.padEnd(10)} ${check.gate ? check.gate.command.join(' ') : '(nothing to run)'}${check.note ? `  [${check.note}]` : ''}`)];
+}
+
+/**
+ * `starci app release push --urgent`. options: { execute, remote, reason, role, platform }. Dry run prints the checks, the tag and the push it would
+ * make; --execute runs them, tags, pushes atomically and writes the urgent record. A red check is RELEASE_URGENT_CHECK_RED: nothing tagged, nothing pushed.
+ */
+export async function releaseUrgentPush(ctx, config, options = {}) {
+  const reason = reasonOf(options.reason);
+  const role = options.role ?? 'unset';
+  const remote = options.remote ?? 'origin';
+  const branch = config.defaultBranch;
+  assertNames(remote, branch);
+  const facts = inspect(ctx, config, {});
+  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 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 } };
+  const red = [];
+  const refs = [...branchRefs(ctx, { head, remote, branch }, red).refs, ...(chosen.state === 'on-head' ? tagRefs(ctx, { remote, tag: chosen.tag }, red) : [`refs/tags/${chosen.tag}`])];
+  out.push(`plan           git tag -a ${chosen.tag}${chosen.state === 'on-head' ? ' (already on HEAD)' : ''}, then git push --atomic ${remote} ${refs.join(' ') || '(nothing)'}; no candidate CI`);
+  if (red.length > 0) return { ok: false, lines: [...out, ...red.map((item) => `RED: ${item}`), 'nothing run, nothing pushed.'], data: { ...data, red } };
+  if (options.execute !== true) return { ok: true, lines: [...out, 'dry run: no check run, nothing tagged or pushed. ready; re-run with --execute.'], data };
+  const rows = runChecks(ctx, checks, { common, head, dir, platform: options.platform ?? process.platform });
+  data.checks = rows;
+  out.push(...rows.map(checkLine));
+  const failed = rows.find((row) => !row.pass);
+  if (failed) throw failure('RELEASE_URGENT_CHECK_RED', `${failed.name} is red (${failed.detail}; log ${failed.log}): nothing tagged, nothing pushed`);
+  assertUnmoved(ctx, head);
+  if (chosen.state !== 'on-head') git(ctx, ['tag', '-a', chosen.tag, '-m', `URGENT release ${chosen.tag} on ${head.slice(0, 12)} by ${role}: ${reason} (fast local checks only; back-fill: starci app release gate --backfill ${chosen.tag})`, head]);
+  if (refs.length > 0) {
+    const hook = probe(ctx, remote, refs, red);
+    out.push(...hook.lines);
+    if (red.length > 0) return { ok: false, lines: [...out, ...red.map((item) => `RED: ${item}`), `nothing pushed; ${chosen.tag} stays local.`], data };
+    const run = git(ctx, ['push', '--atomic', remote, ...refs], { allowFail: true });
+    if (run.code !== 0) return { ok: false, lines: [...out, `push failed: ${firstLine(run.stderr)}; ${chosen.tag} stays local.`], data };
+  }
+  const record = {
+    schema: URGENT_SCHEMA, head, tag: chosen.tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release push --urgent',
+    role, reason, ruling: URGENT_RULING, remote, branch, refs, pushed: true, checks: rows, backfill: null,
+  };
+  writeUrgent(common, record);
+  return { ok: true, lines: [...out, `pushed to ${remote}: ${refs.join(' ') || '(already there)'}`, `URGENT record written: ${path.join(common, `${head}.urgent.json`)}`, `back-fill later: starci app release gate --backfill ${chosen.tag} --execute (in a clean checkout of ${chosen.tag})`], data: { ...data, pushed: true, record: path.join(common, `${head}.urgent.json`) } };
+}

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.6
+    version: 0.15.10
     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.6.4
+    version: 3.6.8
     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.4.5
+    version: 9.4.9
     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.6
+    version: 0.15.10
     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.6
+    version: 0.15.10
     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.9.8
+    version: 4.9.11
     group: starci
     install: registry
     side: both
@@ -241,6 +241,16 @@ pins:
     group: framework
     side: be
     why: readiness probes with dependency indicators use Terminus (the liveness route of the scaffolded skeleton does not, being a thin door over the liveness service); every measured product back end resolves 11.1.1.
+  '@langchain/core':
+    version: 1.3.1
+    group: framework
+    side: be
+    why: 'the LangChain core of the one AI integration (BE-AI-3): prompt templates, output parsers, runnables and BaseRetriever; @langchain/openai takes it as its peer. The registry latest on 2026-10-29.'
+  '@langchain/openai':
+    version: 1.8.0
+    group: framework
+    side: be
+    why: 'ChatOpenAI and OpenAIEmbeddings of the one AI integration, pointed at the ai-router gateway with a virtual key (BE-AI-1, BE-AI-3, R327); peer @langchain/core ^1.3.1. The registry latest on 2026-10-29.'
   '@nestjs/cqrs':
     version: 11.0.3
     group: framework