@starci/hfs 4.9.9 → 4.10.0

package/db/post-cutover.mjs

@@ -6,12 +6,13 @@
 //   2. a time gate: --green-at <ISO> at least minAgeHours (48) ago, or --owner-confirms-old-app-gone;
 //   3. STARCI_DB_ARMED=1.
 // Idempotent: when every held-back version is already on the remote it prints `nothing to do`. The pg_proc query goes through `options.query(sql)`
-// (specs inject one) or, by default, `supabase db query` of the linked project or the --url-env connection.
+// (specs inject one) or, by default, psql against the database --url-env names (default DATABASE_URL).
 import fs from 'node:fs';
 import path from 'node:path';
 import { failure, refusal } from '../stack/errors.mjs';
 import { runVerb } from '../release/index.mjs';
-import { buildModel, listRemote, loadDatabase, pendingVersions, requireArmed, resolveTarget, runCli, targetArgs } from './migrate.mjs';
+import { applyVersions, buildModel, listRemote, loadDatabase, requireArmed, resolveTarget } from './migrate.mjs';
+import { queryRows as psqlRows } from './postgres.mjs';
 
 const DROP_FUNCTION = /^drop\s+function\s+/iu;
 const IF_EXISTS = /^if\s+exists\s+/iu;
@@ -54,7 +55,7 @@ function preflightSql({ schema, prefixes, names }) {
   return `select oid::regprocedure::text as signature from pg_proc where pronamespace = '${schema}'::regnamespace and (${clauses.join(' or ')})`;
 }
 
-const cliQuery = (session) => (sql) => JSON.parse(runCli(session, ['db', 'query', sql, '--output', 'json', '--agent', 'no', ...targetArgs(session.target, session.ctx.cwd)]).stdout);
+const cliQuery = (session) => (sql) => psqlRows(session.ctx, session.target, sql, { withhold: true });
 
 async function queryRows(session, sql, options) {
   try {
@@ -89,26 +90,21 @@ function timeGate(ctx, post, options) {
 }
 
 function applyHeld(session, remote) {
-  const { model, ctx } = session;
+  const { model } = session;
   const lacking = [...model.pushVersions].filter((version) => !remote.has(version));
-  if (lacking.length > 0) throw refusal('DB_BASELINE_NOT_APPLIED', `the remote history lacks ${lacking.join(', ')}: run starci app db migrate first`);
-  const args = ['db', 'push', '--include-all'];
-  const pending = pendingVersions(runCli(session, [...args, '--dry-run', ...targetArgs(session.target, ctx.cwd)]).text);
-  const stray = pending.filter((version) => !model.heldVersions.includes(version));
-  if (stray.length > 0) throw failure('DB_PUSH_STRAY', `the dry run lists more than the held-back migrations: ${pending.join(', ')}. Stopped.`);
-  if (pending.length > 0) runCli(session, [...args, '--yes', ...targetArgs(session.target, ctx.cwd)]);
-  return pending;
+  if (lacking.length > 0) throw refusal('DB_BASELINE_NOT_APPLIED', `the history lacks ${lacking.join(', ')}: run starci app db migrate first`);
+  return applyVersions(session, model.heldVersions.filter((version) => !remote.has(version)));
 }
 
 /**
- * `starci app db post-cutover`. options: { execute, linked, urlEnv, greenAt, ownerConfirms, query }. Dry run: remote read plus the read-only preflight.
- * --execute: gate open and STARCI_DB_ARMED=1, then `db push --include-all` of exactly the held-back versions.
+ * `starci app db post-cutover`. options: { execute, urlEnv, greenAt, ownerConfirms, query }. Dry run: history read plus the read-only preflight.
+ * --execute: gate open and STARCI_DB_ARMED=1, then exactly the held-back versions, each with its history row in one transaction.
  */
 async function postCutoverDatabase(ctx, decl, options = {}) {
   const model = buildModel(ctx.cwd, decl);
   if (model.held.length === 0) return { ok: true, lines: ['no held-back migration in the repository. Nothing to do.'], data: { held: [], done: true, executed: false } };
   if (decl.postCutover === null) throw refusal('DB_POSTCUTOVER_UNDECLARED', 'database.postCutover is not declared: the function preflight needs it (an empty mapping declares no family)');
-  const session = { ctx, decl, model, target: resolveTarget(ctx, decl, options) };
+  const session = { ctx, decl, model, target: resolveTarget(ctx, options) };
   const remote = listRemote(session);
   const data = { held: model.heldVersions, done: false, executed: false };
   if (model.heldVersions.every((version) => remote.has(version))) return { ok: true, lines: [`held-back migrations ${model.held.join(', ')} are already applied. Nothing to do.`], data: { ...data, done: true } };
@@ -123,14 +119,14 @@ async function postCutoverDatabase(ctx, decl, options = {}) {
   return { ok: true, lines: [...lines, pending.length > 0 ? `applied: ${pending.join(', ')}` : 'nothing pending: already applied.'], data: { ...data, done: true, executed: true, pushed: pending, signatures: preflight.count } };
 }
 
-const SPEC = { boolean: ['--execute', '--json', '--linked', '--owner-confirms-old-app-gone'], value: ['--url-env', '--green-at'] };
+const SPEC = { boolean: ['--execute', '--json', '--owner-confirms-old-app-gone'], value: ['--url-env', '--green-at'] };
 
-/** Entry of the verb: `starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--linked | --url-env NAME] [--json]`. */
+/** Entry of the verb: `starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--url-env NAME] [--json]`. */
 export function dbPostCutoverMain(argv, io = {}) {
   return runVerb({
     label: 'starci app db post-cutover', name: 'db post-cutover', code: 'DB_USAGE', io, argv, spec: SPEC,
     run: (ctx, flags) => postCutoverDatabase(ctx, loadDatabase(ctx.cwd), {
-      execute: flags.execute === true, linked: flags.linked === true, urlEnv: flags['url-env'], greenAt: flags['green-at'], ownerConfirms: flags['owner-confirms-old-app-gone'] === true,
+      execute: flags.execute === true, urlEnv: flags['url-env'], greenAt: flags['green-at'], ownerConfirms: flags['owner-confirms-old-app-gone'] === true,
     }),
   });
 }

package/db/postgres.mjs

@@ -0,0 +1,80 @@
+// 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.
+import { failure, refusal } from '../stack/errors.mjs';
+import { firstLine, tool } from '../stack/context.mjs';
+
+/** The default environment variable that names the app's database. */
+export const DEFAULT_DB_URL_ENV = 'DATABASE_URL';
+/** The history table `starci app db migrate` records applied migrations in (the layout the supabase/postgres image already ships). */
+export const HISTORY_TABLE = 'supabase_migrations.schema_migrations';
+
+const KEY = /^[A-Z][A-Z0-9_]*$/u;
+
+const scrub = (text, secrets) => secrets.reduce((out, secret) => out.replaceAll(secret, '[value]'), String(text));
+
+/** { url, password } of a postgres connection URL with the password removed, or null when `value` is not one. */
+export function parseConnection(value) {
+  try {
+    const url = new URL(value);
+    if (!/^postgres(?:ql)?:$/u.test(url.protocol)) return null;
+    const password = decodeURIComponent(url.password);
+    url.password = '';
+    return { url: url.toString(), password };
+  } catch { return null; }
+}
+
+/** The database `name` (an UPPER_CASE environment variable, default DATABASE_URL) names: { how, url, env, secrets }. */
+export function dbTarget(ctx, name = DEFAULT_DB_URL_ENV) {
+  if (!KEY.test(name)) throw refusal('DB_USAGE', '--url-env must name an UPPER_CASE environment variable');
+  const value = ctx.env[name];
+  if (typeof value !== 'string' || value === '') throw refusal('DB_URL_ENV_MISSING', `${name} is not set`);
+  const parsed = parseConnection(value);
+  if (!parsed) throw refusal('DB_URL_INVALID', `${name} is not a postgres connection URL`);
+  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) };
+}
+
+/** 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)`);
+  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 ?? ''}` };
+}
+
+const PSQL = ['-X', '-q', '-v', 'ON_ERROR_STOP=1'];
+
+/** Runs SQL statements (`-c`) and files (`-f`) in ONE transaction: each step is { sql } or { file }. */
+export function psqlTransaction(ctx, target, steps, options = {}) {
+  const args = [...PSQL, '-1', '-d', target.url, ...steps.flatMap((step) => (step.file !== undefined ? ['-f', step.file] : ['-c', step.sql]))];
+  return pgTool(ctx, target, 'psql', args, options);
+}
+
+/** The rows of one read-only query as plain objects (json_agg on the server, so no psql formatting is parsed). */
+export function queryRows(ctx, target, sql, options = {}) {
+  const wrapped = `select coalesce(json_agg(row_to_json(q)), '[]'::json) from (${sql.replace(/;\s*$/u, '')}) q`;
+  const { stdout } = pgTool(ctx, target, 'psql', [...PSQL, '-A', '-t', '-d', target.url, '-c', wrapped], options);
+  let rows;
+  try { rows = JSON.parse(stdout.trim() || '[]'); } catch { throw failure('DB_QUERY_UNREADABLE', 'the database answered rows psql could not print as JSON; output withheld'); }
+  if (!Array.isArray(rows) || rows.some((row) => !row || typeof row !== 'object' || Array.isArray(row))) throw failure('DB_QUERY_UNREADABLE', 'the database answer is not a rows array');
+  return rows;
+}
+
+/** A SQL string literal of `value`. */
+export const literal = (value) => `'${String(value).replaceAll("'", "''")}'`;
+
+/** The versions the history table records; an absent table is an empty history (a database `migrate` has never touched). */
+export function historyVersions(ctx, target) {
+  const [presence] = queryRows(ctx, target, `select pg_catalog.to_regclass(${literal(HISTORY_TABLE)}) is not null as present`);
+  if (presence?.present !== true) return new Set();
+  return new Set(queryRows(ctx, target, `select version from ${HISTORY_TABLE} order by version`).map((row) => String(row.version)));
+}
+
+/** The statement that creates the history table when it is absent (same columns as the image's own: version, statements, name). */
+export const HISTORY_DDL = `create schema if not exists supabase_migrations; create table if not exists ${HISTORY_TABLE} (version text primary key, statements text[], name text)`;
+
+/** Records `version` (named `name`) as applied. */
+export const markApplied = (version, name) => `insert into ${HISTORY_TABLE} (version, name) values (${literal(version)}, ${literal(name)}) on conflict (version) do update set name = excluded.name`;
+
+/** Removes `version` from the history. */
+export const markReverted = (version) => `delete from ${HISTORY_TABLE} where version = ${literal(version)}`;

package/emit/contracts.mjs

@@ -18,10 +18,7 @@
  * TypeScript, Nest and graphql are the repository's own packages; nothing is added to the managed devDependencies. Every app
  * runs in its own child process (`schema-worker.mjs`) because Nest GraphQL's type metadata is process-global.
  *
- * An app whose declaration enables the slot `app.supabase.types` (a connection with provider supabase) also gets its generated
- * Database types written: `supabase/types/database.types.ts` at the app root through `writeDbTypes` (emit/db-types.mjs), the
- * same `supabase gen types typescript --local` text L09 DB_TYPES_DRIFT regenerates to judge drift. The types are an app-level
- * artifact, so a redirected `outDir` (the R23 check mode, which emits into a scratch root) does not get them.
+ * * artifact, so a redirected `outDir` (the R23 check mode, which emits into a scratch root) does not get them.
  */
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
@@ -30,7 +27,6 @@ import { fileURLToPath } from 'node:url';
 import { emitEvents, eventServices, eventsSnapshotPath } from './events.mjs';
 import { openapiPath } from './operations.mjs';
 import { readEnv } from '../runtime/scripts/lib/env.mjs';
-import { appHasDbTypes, writeDbTypes } from './db-types.mjs';
 import { createSlotResolver, loadSlotManifest, locateDeclaration, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
 
 /** The stderr prefix of a dependency the worker could not load and stood in for. */
@@ -84,7 +80,7 @@ function emitApp(repoRoot, app) {
  * resolves there (a bare folder is not an app and emits no types). `repoRoot` is the be side folder, so `locateDeclaration`
  * answers the app root above it.
  */
-function appSupabaseScope(repoRoot) {
+function appDbScope(repoRoot) {
   try {
     const { appRoot } = locateDeclaration(repoRoot);
     const manifest = loadSlotManifest();
@@ -100,9 +96,9 @@ function appSupabaseScope(repoRoot) {
  * being the apps with neither. `declaration` is the parsed hfs.json. `outDir` (absolute) redirects the snapshots to another
  * root, keeping their relative paths.
  *
- * On the real write pass (`outDir` is `repoRoot`) the app's Supabase types are written too when the slot `app.supabase.types`
+ * On the real write pass (`outDir` is `repoRoot`) the app's database types are written too when the slot `app.db.types`
  * is enabled: `resolver` is the app-scope slot view (built from the declaration at the app root when not passed), `appRoot`
- * overrides where the types land, and `run` is the command runner `writeDbTypes` spawns `supabase` with. `types` in the answer
+ * overrides where the types land, and `run` is the command runner `writeDbTypes` spawns `psql` with. `types` in the answer
  * is `writeDbTypes`'s `{ path, changed }`, or null for an app without the slot or a redirected pass.
  */
 export function emitContracts({ repoRoot, declaration, outDir = repoRoot, resolver, appRoot, run } = {}) {
@@ -137,7 +133,7 @@ export function emitContracts({ repoRoot, declaration, outDir = repoRoot, resolv
   // The generated Database types are an app-level artifact of the write pass only: a redirected outDir is the R23 check
   // mode, and L09 judges drift on the same emitted text through the injected emitTypes (emit/db-types.mjs dbTypesEmitter).
   if (outDir === repoRoot) {
-    const scope = resolver === undefined ? appSupabaseScope(repoRoot) : { appRoot: locateDeclaration(repoRoot).appRoot, resolver };
+    const scope = resolver === undefined ? appDbScope(repoRoot) : { appRoot: locateDeclaration(repoRoot).appRoot, resolver };
     const target = appRoot ?? scope?.appRoot;
     if (target !== null && target !== undefined && scope?.resolver != null && appHasDbTypes(scope.resolver)) types = writeDbTypes({ root: target, run });
   }

package/lint/run.mjs

@@ -85,6 +85,15 @@ export function parseLintArgs(argv) {
 /** The typed ESLint run reads nothing above the app root: its TypeScript `sys` is bound by this preload (3.3, bound-sys.cjs). */
 const BOUND_ENV = 'STARCI_LINT_BOUND';
 const linterBoundArgs = () => ['--require', fileURLToPath(new URL('./bound-sys.cjs', import.meta.url))];
+/**
+ * The heap of the ESLint child in MiB: the starci CLI sets it from its one owner, the eslint memory of ops/liveness.yaml `heavy` (a typed whole-side
+ * lint of a large app outgrows node's default heap). Unset, ESLint runs on node's default.
+ */
+export const ESLINT_HEAP_ENV = 'STARCI_ESLINT_HEAP_MB';
+export function eslintHeapArgs(env = process.env) {
+  const mb = Number(env[ESLINT_HEAP_ENV]);
+  return Number.isInteger(mb) && mb > 0 ? [`--max-old-space-size=${mb}`] : [];
+}
 
 /** The child `node` ran with `args` from `cwd`: its exit status, signal, spawn error and the text of both streams, once it closes. */
 function runNode(args, options) {
@@ -103,7 +112,7 @@ function runNode(args, options) {
 }
 
 /** A linter's json results through the app's own install, run from `cwd` (a side folder): `{ results }` or `{ error }`. The child runs while the caller goes on. */
-async function runLinter({ cwd, pkg, bin, args, bound = null }) {
+export async function runLinter({ cwd, pkg, bin, args, bound = null }) {
   let entry;
   try {
     const manifest = createRequire(path.join(cwd, 'package.json')).resolve(`${pkg}/package.json`);
@@ -112,7 +121,8 @@ async function runLinter({ cwd, pkg, bin, args, bound = null }) {
   } catch {
     return { error: `${pkg} is not installed for ${cwd}` };
   }
-  const run = await runNode([...(bound ? linterBoundArgs() : []), entry, ...args], { cwd, ...(bound ? { env: { ...process.env, [BOUND_ENV]: bound } } : {}) });
+  const heap = pkg === 'eslint' ? eslintHeapArgs() : [];
+  const run = await runNode([...heap, ...(bound ? linterBoundArgs() : []), entry, ...args], { cwd, ...(bound ? { env: { ...process.env, [BOUND_ENV]: bound } } : {}) });
   // ESLint prints its report on stdout; stylelint uses stderr. JSON does not prove a completed child: only exits 0/1
   // without a spawn error or signal are measurable, and exit 1 must carry findings.
   let results;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.9.9",
+  "version": "4.10.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -26,20 +26,22 @@
     "smol-toml": "1.9.0"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "8.71.0",
-    "@typescript-eslint/parser": "8.71.0",
     "@graphql-codegen/cli": "7.4.6",
     "@graphql-codegen/client-preset": "6.2.3",
     "@nestjs/common": "11.2.5",
     "@nestjs/core": "11.2.5",
     "@nestjs/graphql": "13.4.5",
     "@nestjs/testing": "11.2.5",
+    "@typescript-eslint/eslint-plugin": "8.71.0",
+    "@typescript-eslint/parser": "8.71.0",
     "class-validator": "0.15.1",
     "eslint": "10.11.0",
     "graphql": "16.14.2",
+    "pg": "8.23.1",
     "prettier": "3.9.6",
     "reflect-metadata": "0.2.2",
     "rxjs": "7.8.2",
+    "typeorm": "0.3.31",
     "typescript": "5.9.3",
     "zod": "4.6.7"
   },

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';
@@ -31,13 +33,13 @@ export const VERSION = /^(\d+)\.(\d+)\.(\d+)$/u;
 const THRESHOLD_MISS = /coverage threshold .* not met/gu;
 const WRAPPED = new Set(['npm', 'npx']);
 // Every row the managed CI runs, so a release that does not wait for its candidate CI (release.requireCi false) still ran them all locally:
-// fast (audit, format, typecheck), lint, test + coverage (the managed `test` script is the per-file 100 threshold), build, the lite database lint and types, and Sonar.
+// fast (audit, format, typecheck), lint, test + coverage (the managed `test` script is the per-file 100 threshold), build, the lite database lint, and Sonar.
 const SCRIPT_GATES = ['format:check', 'typecheck', 'build:be', 'lint', 'db:lint', 'build:fe', 'test'];
 // A full app has a test world (integration, e2e and contract projects, always present: the managed `test:e2e` script marks it), so those layers are rows of its gate;
 // a lite app's integration project exists only where it has integration specs, so it has no world rows.
 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);
@@ -49,21 +51,11 @@ const scriptGate = (script) => ({
   env: {},
 });
 
-/**
- * The lite database-types rows of the managed CI, in its order: start Supabase, apply the migrations, regenerate the types, require them committed, stop.
- * The stop is the teardown of the start (`teardownOf`): it runs whenever the start ran, also after a red row, so a failed database row never leaves Supabase running.
- */
-function dbTypesGates(scripts) {
-  if (!DB_TYPES_SCRIPTS.every((script) => typeof scripts?.[script] === 'string')) return [];
-  const [start, reset, types, stop] = DB_TYPES_SCRIPTS.map(scriptGate);
-  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 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), ...(entities ? [DB_DRIFT] : [])];
 }
 
 /** Shared quality settings retain the release reader's audit validation, disabled mode and legacy string host compatibility. */
@@ -148,8 +140,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 +168,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 +251,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 +282,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 +331,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 +362,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 +390,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 +442,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}`);
 }