@starci/hfs 4.9.9 → 4.9.11

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 4.9.11 - 2026-10-29
+
+- Added: `starci app db drift [--url-env <NAME>] [--json]` (`db/drift.mjs`, owner ruling 2026-10-29: lite tables are mapped by TypeORM entities while `db/migrations/*.sql` stays the only DDL and `synchronize` is false). It builds TypeORM's metadata from `be/src/platform/database/entities.ts` with the app's own typescript, typeorm and pg (a `DataSource` that never connects), applies `db/bootstrap.sql` and every active migration to a scratch container of the app's `components.db` image (or the empty database `--url-env` names), and reports every missing table or column, type mismatch and nullability mismatch as `BE_ENTITY_SCHEMA_DRIFT` (R333 in the bundled rule catalog, with its failure-code entry). No Docker, no app packages or an unreadable target is no verdict (`DB_DRIFT_NEEDS_DATABASE`, exit 2), never a green; a migration that does not apply to an empty database is `DB_DRIFT_MIGRATION_FAILED`. An app with an entity list gets a `db-drift` row in its release gate (default or declared gates) and `npx starci app db drift` after `npm run db:lint` in its managed CI's build job. Specs: `src/db-drift.spec.mjs` (real TypeORM metadata over a fixture app, stubbed schema) and `src/db-drift-docker.spec.mjs` (a real postgres:17-alpine scratch database where Docker runs, else the no-verdict answer); typeorm 0.3.31 and pg 8.23.1 are dev dependencies for them.
+
+- Changed: the bundled slot manifest gives the model libraries their owners in `ruleParams.be.infraOwners` (`@starci/ai-router` to `integrations/ai-gateway`, `@langchain/*` to `integrations/ai`; `openai`, `langchain`, `@langchain/langgraph`, `@langchain/community` and the provider SDKs nowhere) and lists R326 and R327 on `be.integrations`; the bundled rule catalog carries R326 `BE_AI_KEY_CUSTODY` and R327 `BE_AI_GATEWAY_CLIENT`; the bundled canon pins name hfs 4.9.11, eslint-canon-be 3.6.8, eslint-canon-fe 9.4.9, the Grammar family 0.15.10 (grammar, eslint-grammar-core, eslint-grammar-offset-pop), and pin `@langchain/core` 1.3.1 and `@langchain/openai` 1.8.0.
+- Added: the urgent release (owner ruling 2026-10-29, "deploy gấp không cần ci cd gì hết"). `starci app release push --urgent --reason "<text>" [--execute]` runs only the fast local checks among the release gates (`app-check`, `typecheck`, `lint`, `test`; the managed `npm run lint` narrowed to `starci app lint --changed` over the source files changed since the previous release tag), reusing a green row the gate already recorded for HEAD (same command, unchanged log; every gate row now lands in `<git common dir>/starci-release/<head12>/rows.json`), then tags HEAD (annotated), pushes the default branch and the tag in one atomic push through the hook (dry run first, no candidate CI) and writes `<head>.urgent.json` naming the role, the reason, each check with its verdict and the commit (`release/urgent.mjs`, `release/records.mjs`). A missing reason is `RELEASE_URGENT_REASON_MISSING`, a red check `RELEASE_URGENT_CHECK_RED` (nothing tagged or pushed).
+- Added: `starci app release gate --backfill <tag> [--execute]` runs the full gate on the urgent release's own commit (checked out at HEAD; `RELEASE_BACKFILL_TAG_UNKNOWN`, `RELEASE_BACKFILL_NOT_ON_TAG`, `RELEASE_BACKFILL_NOT_URGENT` otherwise). Green writes its L4 record (`promotedFrom` the urgent record) and marks the urgent record promoted, with no new tag and no push; red records the verdict on the urgent record and files one fix ticket through the CLI's ticket queue (`RELEASE_BACKFILL_RED`), changing nothing on the remote or on prod.
+- Added: the safety floor of `starci app stack deploy --urgent [--db-url-env <NAME>] [--backup-out <dir>]` (`stack/urgent-floor.mjs`), every failed step a refusal with its own code: the pushed urgent record of `--source-sha` (`STACK_URGENT_NO_RECORD`, `STACK_URGENT_NOT_PUSHED`), a declared database (`STACK_URGENT_NO_DATABASE`), the full public verify (`STACK_URGENT_SKIP_PUBLIC`), a fresh full database backup encrypted to the app's recipients (`STACK_URGENT_BACKUP_FAILED`) whose receipt matches the archive (`STACK_URGENT_BACKUP_UNVERIFIED`) and which a test decrypt with `SOPS_AGE_KEY_FILE` opens with every part (`STACK_URGENT_DECRYPT_UNAVAILABLE`, `STACK_URGENT_DECRYPT_FAILED`), an accepted previous release to roll back to (`STACK_URGENT_NO_ROLLBACK_TARGET`), `db migrate` previewed then executed (`STACK_URGENT_MIGRATE_PREVIEW_RED`, `STACK_URGENT_MIGRATE_FAILED`), then the release with its readiness verify and automatic rollback (`STACK_URGENT_RED_ROLLED_BACK`, `STACK_URGENT_ROLLBACK_FAILED`, `STACK_URGENT_DEPLOY_NOT_STARTED`). A refused floor exits 2 after printing the steps that led to it. `db dump` and `db migrate` export `dumpDatabase` and `migrateDatabase` for it.
+- Added: slot manifest 3.8.0 adds the optional `fe.dev-server-generated` slot (`apps/*/AGENTS.md`, which `next dev` rewrites) and the slot field `rewrittenBy`; the release gate's clean-tree check (`dirtyPaths`, now over `--untracked-files=all`) passes over an untracked file such a slot owns, and over nothing else.
+- Changed: the ESLint child of `starci app lint` and `starci app check` runs with `--max-old-space-size` from `STARCI_ESLINT_HEAP_MB`, which the CLI sets from the eslint memory of ops/liveness.yaml (8192); unset, it keeps node's default.
+- Changed: the lite boot proof's worker has its own budget from its spawn (`STARCI_BOOT_PROOF_TIMEOUT_MS`, which the CLI sets from `heavy.bootProofTimeoutSeconds`), is retried once when it runs out, and a second timeout is `BOOT_PROOF_TIMEOUT` (R272, a warning: no verdict on a loaded host), never `BE_APP_BOOT_PROOF_MISSING`.
+- Changed: the managed `stack-deploy.yml` passes the workflow token (`GH_TOKEN`, `actions: read`) to the deploy step, which reads the CI verdict of the tag's commit a production deploy waits for.
+
+## 4.9.10 - 2026-10-29
+
+- Fixed: the back-end skeleton's `OriginGuard` (`platform/http-security`, BE-AUTH-5) refuses a state-changing request (`POST`, `PUT`, `PATCH`, `DELETE`) that names no usable origin, with `HTTP_SECURITY_ORIGIN_REJECTED` (403). It admitted a request with neither `Origin` nor `Referer`, which a session-cookie mutation must never be. `Referer` stands in only when `Origin` is absent, so a foreign or `null` `Origin` is never rescued by an allowed `Referer`; safe methods are not judged.
+- Added: the `ServerToServer` marker of `platform/http-security` exempts a door that proves its caller itself from the origin check. `@Public({ reason: PublicReason.SignedWebhook })` (signature verified first, BE-WEBHOOK-2) and `@Credential({ kind })` (a header credential `CredentialGuard` authenticates) apply it, in full and lite, so the generated webhook doors keep answering providers that send no `Origin`. Both decorators, and `@RateLimit`, are typed with the new `DoorDecorator` of `platform/composition`.
+- Added: `@RateLimit(tier, { redirect })` (BE-AUTH-4): a redirect-only door (an OAuth callback answering `303 /sign-in?auth=error`) names its error redirect, and a caller over the limit gets that 303 from `RateLimitGuard` instead of a 429 body. The redirect must be a same-site path (one leading `/`), refused with `HTTP_SECURITY_REQUEST_INVALID` when the decorator is applied. `ErrorsFilter` leaves a response a guard already sent as it is.
+- Changed: the unit specs of `OriginGuard`, `RateLimitGuard` and `ErrorsFilter` cover the new paths at 100 per file; the bundled canon pins name hfs 4.9.10, eslint-canon-be 3.6.7, eslint-canon-fe 9.4.8, eslint-grammar-core 0.15.9 and eslint-grammar-offset-pop 0.15.9.
+
 ## 4.9.9 - 2026-10-29
 
 - Fixed: the back-end skeleton's `RateLimitGuard` counts in a store every replica shares (BE-AUTH-4), not a process-local map. Each hit is one upsert of the caller's window (tier and address) in the primary database, answering its hits; a hit that opens a fresh window prunes up to 100 ended windows (`FOR UPDATE SKIP LOCKED`). `platform/http-security` owns the table `http_security_rate_windows`: in full through its `persistence/` entity and migration (`httpSecurityEntities`, `httpSecurityMigrations`, registered on the primary connection by the api and cli apps), in lite in the Supabase baseline with forced RLS and `app_be` policies. The lite starter now ships `platform/database/database.sql.ts` (with `DATABASE_IDENTIFIER_REJECTED`) and exports `sql`, `InjectPrimaryEntityManager` and `PRIMARY_ENTITY_MANAGER`, which the guard and its spec consume; a lite starter leaves out a platform capability's TypeORM schema files. Needs `@starci/eslint-canon-be` 3.6.5, which admits `http-security` as a persistence capability.

package/README.md

@@ -20,6 +20,7 @@ starci app upgrade [--plan]
 starci app stack <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--cwd <dir>]
 starci app explain <path> [--cwd <dir>] [--json]
 starci app emit [--cwd <dir>]
+starci app db drift [--url-env <NAME>] [--json] [--cwd <dir>]
 starci app new service <dir> <name> [--inject <binding>...] [--cwd <dir>]
 starci app new spec <file>.service.ts [--cwd <dir>]
 starci app new image [--cwd <dir>]
@@ -80,6 +81,19 @@ The lite additions are deliberately narrow:
 `starci app emit` continues to emit the enabled back-end snapshots and also writes `supabase/types/database.types.ts` when
 the `app.supabase.types` slot is enabled. The local Supabase stack must be running for generation.
 
+`starci app db drift` holds a lite app's TypeORM entities to the schema its migrations build (R333, `BE_ENTITY_SCHEMA_DRIFT`; `db/drift.mjs`).
+It loads the entity list `be/src/platform/database/entities.ts` with the app's own `typescript`, `typeorm` and `pg` (its `be/tsconfig.json`
+path aliases resolved) and builds TypeORM's metadata through a postgres `DataSource` with `synchronize` false that never connects. It applies
+`db/bootstrap.sql`, when present, and every active `db/migrations/*.sql`, each file in one transaction, to a scratch database: a throwaway
+container of the image `.starcistacks/application-stacks.yaml` declares for `components.db`, or with `--url-env <NAME>` the database that
+variable names, which must hold no relation in `public` yet (`DB_DRIFT_TARGET_NOT_EMPTY`). It reads the result from
+`information_schema.columns` and `pg_catalog` and reports each entity column whose table or column is missing, whose type differs once
+both are spelled as `format_type` names (an enum matches an enum of the name the entity gives), or whose nullability differs; a column no
+entity maps is fine. Exit 0 is green, 1 is drift or a migration that does not apply to an empty database (`DB_DRIFT_MIGRATION_FAILED`),
+and 2 is no verdict: a host without Docker or without the app's packages gets `DB_DRIFT_NEEDS_DATABASE` (needs a database), never a
+green. An app with an entity list runs it as the `db-drift` row of `starci app release gate` and in the database step of its managed CI's
+build job.
+
 Input bounds stay with the backend DTO: `MaxLength`, `ArrayMaxSize`, `Min` and `Max` become GraphQL `@inputBounds`
 input-field directives or JSON Schema constraints on the REST operation table's DTO properties. Codegen derives
 `INPUT_BOUNDS` beside GraphQL wire types and `REST_INPUT_BOUNDS` under the REST API owner's `__generated__/` directory.

package/db/drift.mjs

@@ -0,0 +1,289 @@
+// drift.mjs - `starci app db drift`: the TypeORM entities of an app against the schema its SQL migrations build.
+// The migrations (db/migrations/*.sql, after db/bootstrap.sql when present) are the only DDL and `synchronize` is false, so an entity only
+// maps tables that already exist and can drift from them. The verb builds TypeORM's metadata from the app's entity list
+// (be/src/platform/database/entities.ts, compiled in-process with the app's own typescript and loaded with the app's own typeorm) through a
+// DataSource that never connects, applies the migrations to a scratch database (a throwaway container of the image the app's
+// .starcistacks declares for its db component, or the empty database named by --url-env), reads that schema from
+// information_schema.columns and pg_catalog, and reports every entity column whose table or column is missing, whose type differs (both
+// normalised to PostgreSQL's format_type names) or whose nullability differs, under BE_ENTITY_SCHEMA_DRIFT. Database columns no entity maps
+// are fine. Exit 0 is green, 1 is drift (or a migration that does not apply to an empty database), 2 is a refusal: no verdict, which is
+// also what a host without Docker gets ("needs a database"), never a green.
+import fs from 'node:fs';
+import path from 'node:path';
+import Module, { createRequire } from 'node:module';
+import { randomBytes } from 'node:crypto';
+import { runVerb, readDeclaration } from '../release/index.mjs';
+import { failure, refusal } from '../stack/errors.mjs';
+import { firstLine, tool } from '../stack/context.mjs';
+import { ENTITY_LIST, hasEntityList } from './entity-list.mjs';
+
+export const DRIFT_CODE = 'BE_ENTITY_SCHEMA_DRIFT';
+export const MIGRATIONS_DIR = 'db/migrations';
+export const BOOTSTRAP_FILE = 'db/bootstrap.sql';
+const NEEDS_DATABASE = 'DB_DRIFT_NEEDS_DATABASE';
+const KEY = /^[A-Z][A-Z0-9_]*$/u;
+const MIGRATION = /^\d{14}_[a-z0-9][a-z0-9_-]*\.sql$/u;
+const READY_TIMEOUT_MS = 120_000;
+const READY_POLL_MS = 500;
+
+const needsDatabase = (reason) => refusal(NEEDS_DATABASE, `needs a database: ${reason}`);
+
+/* ---- the entity side */
+
+/** The be/tsconfig.json `paths` as [prefix, absolute target prefix] pairs (only `name/*` -> `dir/*` forms, the canon's). */
+function aliases(ts, root) {
+  const file = path.join(root, 'be', 'tsconfig.json');
+  if (!fs.existsSync(file)) return [];
+  const { config } = ts.readConfigFile(file, ts.sys.readFile);
+  const options = config?.compilerOptions ?? {};
+  const base = path.resolve(path.dirname(file), options.baseUrl ?? '.');
+  return Object.entries(options.paths ?? {}).flatMap(([pattern, targets]) => (pattern.endsWith('/*') && targets?.[0]?.endsWith('/*')
+    ? [[pattern.slice(0, -1), path.resolve(base, targets[0].slice(0, -1))]] : []));
+}
+
+/** The source file a relative or aliased specifier names (exact, .ts, .js -> .ts, /index.ts), or null for a package. */
+function sourceFile(specifier, from, pairs) {
+  const alias = pairs.find(([prefix]) => specifier.startsWith(prefix));
+  const target = alias ? path.join(alias[1], specifier.slice(alias[0].length))
+    : specifier.startsWith('.') ? path.resolve(path.dirname(from), specifier) : null;
+  if (!target) return null;
+  const candidates = [target, `${target}.ts`, target.replace(/\.js$/u, '.ts'), path.join(target, 'index.ts')];
+  return candidates.find((file) => fs.existsSync(file) && fs.statSync(file).isFile()) ?? null;
+}
+
+/**
+ * Requires the entity list with a `.ts` loader that transpiles each source file with the app's typescript (CommonJS, legacy decorators and
+ * their design metadata, as Nest compiles them) and points every relative or aliased require at its source file. The previous loader is
+ * restored afterwards.
+ */
+function requireEntityList(ts, appRequire, root) {
+  const pairs = aliases(ts, root);
+  const previous = Module._extensions['.ts'];
+  Module._extensions['.ts'] = (module, filename) => {
+    const { outputText } = ts.transpileModule(fs.readFileSync(filename, 'utf8'), { fileName: filename, compilerOptions: {
+      module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022, experimentalDecorators: true, emitDecoratorMetadata: true,
+      esModuleInterop: true, useDefineForClassFields: false } });
+    const code = outputText.replace(/require\("([^"]+)"\)/gu, (call, specifier) => {
+      const file = sourceFile(specifier, filename, pairs);
+      return file ? `require(${JSON.stringify(file)})` : call;
+    });
+    module._compile(code, filename);
+  };
+  try { return appRequire(path.join(root, ENTITY_LIST)); }
+  finally {
+    if (previous) Module._extensions['.ts'] = previous;
+    else delete Module._extensions['.ts'];
+  }
+}
+
+/** The entity classes an entity-list module exports: every class, directly or inside an exported array, once. */
+const entityClasses = (exports) => [...new Set(Object.values(exports ?? {}).flat(Infinity).filter((value) => typeof value === 'function'))];
+
+/** PostgreSQL spellings TypeORM's normalizeType passes through unchanged, mapped to the name format_type answers. */
+const PG_ALIASES = new Map([['serial', 'integer'], ['serial4', 'integer'], ['bigserial', 'bigint'], ['serial8', 'bigint'], ['smallserial', 'smallint'],
+  ['serial2', 'smallint'], ['bool', 'boolean'], ['int', 'integer'], ['float', 'double precision'], ['dec', 'numeric']]);
+
+/** One entity column as the comparison reads it: { entity, schema, table, column, type, enumName, nullable, view }. */
+function entityColumn(driver, metadata, column) {
+  const base = String(driver.normalizeType(column)).toLowerCase();
+  const type = `${PG_ALIASES.get(base) ?? base}${column.isArray ? '[]' : ''}`;
+  return { entity: metadata.name, schema: metadata.schema ?? driver.options.schema ?? 'public', table: metadata.tableName, column: column.databaseName,
+    type, enumName: column.enumName ?? null, nullable: column.isNullable === true, view: metadata.tableType === 'view' };
+}
+
+/**
+ * The columns of every entity the app's entity list names, from TypeORM's own metadata: a postgres DataSource with synchronize false is
+ * built and its metadata derived (buildMetadatas), never initialized, so no connection is opened. typeorm, its pg driver and typescript are
+ * the app's (resolved from be/); an app without them gets no verdict.
+ */
+export async function loadEntityColumns(appRoot) {
+  const root = path.resolve(appRoot);
+  const appRequire = createRequire(path.join(root, 'be', 'package.json'));
+  const load = (name) => {
+    try { return appRequire(name); } catch { throw needsDatabase(`the app's ${name} is not installed (npm ci first)`); }
+  };
+  const ts = load('typescript');
+  load('reflect-metadata');
+  const { DataSource } = load('typeorm');
+  load('pg');
+  const entities = entityClasses(requireEntityList(ts, appRequire, root));
+  if (entities.length === 0) return [];
+  const source = new DataSource({ type: 'postgres', synchronize: false, migrationsRun: false, entities });
+  try { await source.buildMetadatas(); } catch (error) { throw refusal('DB_DRIFT_ENTITIES_INVALID', `TypeORM refuses the entity list: ${firstLine(error.message)}`); }
+  return source.entityMetadatas.flatMap((metadata) => metadata.columns.filter((column) => !column.isVirtual && !column.isVirtualProperty)
+    .map((column) => entityColumn(source.driver, metadata, column)));
+}
+
+/* ---- the schema side */
+
+/** Every column of the scratch schema with its format_type spelling (enums as `enum`, domains as their base type) and nullability. */
+export const SCHEMA_SQL = `select c.table_schema as "schema", c.table_name as "table", c.column_name as "column", c.is_nullable = 'YES' as "nullable",
+  case when t.typtype = 'e' then 'enum' when e.typtype = 'e' then 'enum[]' when t.typtype = 'd' then pg_catalog.format_type(t.typbasetype, null)
+    else pg_catalog.format_type(a.atttypid, null) end as "type",
+  case when t.typtype = 'e' then t.typname when e.typtype = 'e' then e.typname end as "enumName",
+  cl.relkind in ('v', 'm') as "view"
+from information_schema.columns c
+join pg_catalog.pg_namespace n on n.nspname = c.table_schema
+join pg_catalog.pg_class cl on cl.relnamespace = n.oid and cl.relname = c.table_name
+join pg_catalog.pg_attribute a on a.attrelid = cl.oid and a.attname = c.column_name and a.attnum > 0 and not a.attisdropped
+join pg_catalog.pg_type t on t.oid = a.atttypid
+left join pg_catalog.pg_type e on e.oid = t.typelem and t.typcategory = 'A'
+where c.table_schema not in ('pg_catalog', 'information_schema')`;
+
+const PUBLIC_RELATIONS_SQL = `select count(*)::int as "count" from pg_catalog.pg_class c join pg_catalog.pg_namespace n on n.oid = c.relnamespace
+where n.nspname = 'public' and c.relkind in ('r', 'p', 'v', 'm', 'f')`;
+
+/** The SQL files the scratch database receives, in order: db/bootstrap.sql when present, then the active migrations by stamp. */
+export function migrationFiles(root) {
+  const dir = path.join(root, MIGRATIONS_DIR);
+  if (!fs.existsSync(dir)) throw refusal('DB_DRIFT_NO_MIGRATIONS', `${MIGRATIONS_DIR}/ is missing: the migrations are the schema the entities are checked against`);
+  const migrations = fs.readdirSync(dir).filter((name) => MIGRATION.test(name)).sort().map((name) => `${MIGRATIONS_DIR}/${name}`);
+  return [...(fs.existsSync(path.join(root, BOOTSTRAP_FILE)) ? [BOOTSTRAP_FILE] : []), ...migrations];
+}
+
+/** The image of the app's db component (.starcistacks/application-stacks.yaml components.db.image), the one the scratch container runs. */
+export function scratchImage(root) {
+  const image = readDeclaration(root)?.components?.db?.image;
+  if (typeof image !== 'string' || image.trim() === '') throw refusal('DB_DRIFT_NO_IMAGE', 'declare components.db.image in .starcistacks/application-stacks.yaml (the scratch database runs the app\'s own db image) or pass --url-env');
+  return image.trim();
+}
+
+/** Starts a throwaway container of `image` on a loopback port; returns { connection, stop }. Docker missing or failing is no verdict. */
+function startScratch(ctx, image) {
+  const docker = (args, env) => tool(ctx, 'docker', args, { env: { ...ctx.env, ...env } });
+  const probe = docker(['version', '--format', '{{.Server.Version}}']);
+  if (probe.error || probe.status !== 0) throw needsDatabase('Docker is not available on this host; start it, or pass --url-env naming an empty database');
+  const password = randomBytes(18).toString('hex');
+  const name = `starci-db-drift-${randomBytes(6).toString('hex')}`;
+  const run = docker(['run', '-d', '--rm', '--name', name, '--label', 'starci.db-drift=1', '-e', 'POSTGRES_PASSWORD', '-p', '127.0.0.1::5432', image], { POSTGRES_PASSWORD: password });
+  const stop = () => { docker(['rm', '-f', name]); };
+  if (run.status !== 0) { stop(); throw needsDatabase(`docker could not start ${image}: ${firstLine(run.stderr)}`); }
+  const port = docker(['port', name, '5432/tcp']);
+  const match = /:(\d+)\s*$/mu.exec(String(port.stdout ?? '').split('\n')[0]);
+  if (port.status !== 0 || !match) { stop(); throw needsDatabase('docker published no port for the scratch database'); }
+  return { connection: { host: '127.0.0.1', port: Number(match[1]), user: 'postgres', password, database: 'postgres' }, stop, how: `scratch container of ${image}` };
+}
+
+/** Connects with the app's pg, retrying while a fresh container is still initialising; gives up after READY_TIMEOUT_MS. */
+async function connect(ctx, Client, connection, retry) {
+  const started = ctx.now();
+  for (;;) {
+    const client = new Client(connection);
+    client.on('error', () => {});
+    try {
+      await client.connect();
+      await client.query('select 1');
+      return client;
+    } catch (error) {
+      await client.end().catch(() => {});
+      if (!retry || ctx.now() - started > READY_TIMEOUT_MS) throw needsDatabase(`the database did not accept a connection (${firstLine(error.message)})`);
+      await ctx.sleep(READY_POLL_MS);
+    }
+  }
+}
+
+/**
+ * The columns of the migrated schema: a scratch database (a container of the app's db image, or the empty database `urlEnv` names) receives
+ * db/bootstrap.sql and every active migration, each file in one transaction, then is read with SCHEMA_SQL. A file that does not apply to an
+ * empty database is a red result of its own (DB_DRIFT_MIGRATION_FAILED). The container is removed in every case.
+ */
+export async function migratedSchema(ctx, appRoot, { urlEnv } = {}) {
+  const root = path.resolve(appRoot);
+  const files = migrationFiles(root);
+  let Client;
+  try { ({ Client } = createRequire(path.join(root, 'be', 'package.json'))('pg')); } catch { throw needsDatabase('the app\'s pg is not installed (npm ci first)'); }
+  let scratch;
+  let secrets = [];
+  if (urlEnv !== undefined) {
+    if (!KEY.test(urlEnv)) throw refusal('DB_USAGE', '--url-env must name an UPPER_CASE environment variable');
+    const value = ctx.env[urlEnv];
+    if (typeof value !== 'string' || !/^postgres(?:ql)?:\/\//u.test(value)) throw needsDatabase(`${urlEnv} holds no postgres connection URL`);
+    secrets = [value];
+    scratch = { connection: { connectionString: value }, stop: () => {}, how: `the database ${urlEnv} names` };
+  } else scratch = startScratch(ctx, scratchImage(root));
+  const scrub = (text) => secrets.reduce((out, secret) => out.replaceAll(secret, '[value]'), String(text));
+  let client;
+  try {
+    client = await connect(ctx, Client, scratch.connection, urlEnv === undefined);
+    if (urlEnv !== undefined) {
+      const { rows: [{ count }] } = await client.query(PUBLIC_RELATIONS_SQL);
+      if (count > 0) throw refusal('DB_DRIFT_TARGET_NOT_EMPTY', `the database ${urlEnv} names already holds ${count} relation(s) in public; drift migrates an empty scratch database itself`);
+    }
+    for (const file of files) {
+      try { await client.query(fs.readFileSync(path.join(root, file), 'utf8')); }
+      catch (error) { throw failure('DB_DRIFT_MIGRATION_FAILED', `${file} does not apply to an empty database: ${scrub(firstLine(error.message))}`); }
+    }
+    const { rows } = await client.query(SCHEMA_SQL);
+    return { columns: rows.map((row) => ({ ...row, type: String(row.type).toLowerCase() })), files, how: scratch.how };
+  } finally {
+    await client?.end().catch(() => {});
+    scratch.stop();
+  }
+}
+
+/* ---- the comparison */
+
+const key = (...parts) => parts.join('\u0000');
+
+/**
+ * The drift findings of `entityColumns` against `schemaColumns` ({schema, table, column, type, enumName, nullable, view} each): a missing
+ * table once per entity, then per column a missing column, a type mismatch (an enum matches an enum, by name when the entity names one) and,
+ * outside views, a nullability mismatch. Schema columns no entity maps are not findings.
+ */
+export function compareSchema(entityColumns, schemaColumns) {
+  const tables = new Set(schemaColumns.map((column) => key(column.schema, column.table)));
+  const columns = new Map(schemaColumns.map((column) => [key(column.schema, column.table, column.column), column]));
+  const findings = [];
+  const missingTables = new Set();
+  const found = (column, kind, message, extra = {}) => findings.push({ code: DRIFT_CODE, level: 'error', kind, entity: column.entity,
+    schema: column.schema, table: column.table, column: column.column, message: `${column.entity} ${column.schema}.${column.table}${kind === 'missing-table' ? '' : `.${column.column}`}: ${message}`, ...extra });
+  for (const column of entityColumns) {
+    const table = key(column.schema, column.table);
+    if (!tables.has(table)) {
+      if (!missingTables.has(table)) found(column, 'missing-table', 'the table is missing from the migrated schema');
+      missingTables.add(table);
+      continue;
+    }
+    const actual = columns.get(key(column.schema, column.table, column.column));
+    if (!actual) { found(column, 'missing-column', 'the column is missing from the migrated schema'); continue; }
+    const sameEnum = column.type === actual.type && actual.type.startsWith('enum') && (!column.enumName || column.enumName === actual.enumName);
+    const typeMatches = actual.type.startsWith('enum') ? sameEnum : column.type === actual.type;
+    if (!typeMatches) {
+      const name = (type, enumName) => (type.startsWith('enum') && enumName ? `${type} ${enumName}` : type);
+      found(column, 'type-mismatch', `type mismatch: entity ${name(column.type, column.enumName)}, schema ${name(actual.type, actual.enumName)}`,
+        { expected: column.type, actual: actual.type });
+    }
+    if (!actual.view && !column.view && column.nullable !== actual.nullable) {
+      found(column, 'nullable-mismatch', `nullability mismatch: entity ${column.nullable ? 'nullable' : 'not null'}, schema ${actual.nullable ? 'nullable' : 'not null'}`,
+        { expected: column.nullable, actual: actual.nullable });
+    }
+  }
+  return findings;
+}
+
+/**
+ * `starci app db drift`. options: { urlEnv, entityColumns(root), schema(ctx, root, { urlEnv }) }, the last two seams for specs. An app with
+ * no entity list is green with nothing to compare.
+ */
+export async function driftCheck(ctx, options = {}) {
+  const root = path.resolve(ctx.cwd);
+  if (!hasEntityList(root)) return { ok: true, lines: [`no entity list (${ENTITY_LIST}): nothing to compare`], data: { entities: 0, columns: 0, findings: [] } };
+  const entityColumns = await (options.entityColumns ?? loadEntityColumns)(root);
+  const schema = await (options.schema ?? migratedSchema)(ctx, root, { urlEnv: options.urlEnv });
+  const findings = compareSchema(entityColumns, schema.columns);
+  const entities = new Set(entityColumns.map((column) => column.entity)).size;
+  const head = `${entities} entit${entities === 1 ? 'y' : 'ies'}, ${entityColumns.length} column(s) against ${schema.files?.length ?? 0} SQL file(s) applied to ${schema.how ?? 'the schema'}`;
+  const lines = [head, ...findings.map((finding) => `${DRIFT_CODE} ${finding.message}`),
+    findings.length === 0 ? 'green: every entity column matches the migrated schema' : `red: ${findings.length} drift finding(s)`];
+  return { ok: findings.length === 0, lines, data: { entities, columns: entityColumns.length, files: schema.files ?? [], findings } };
+}
+
+/** Entry of the verb: `starci app db drift [--url-env NAME] [--json] [--cwd <dir>]`. */
+export function dbDriftMain(argv, io = {}) {
+  return runVerb({ label: 'starci app db drift', name: 'db drift', code: 'DB_USAGE', io, argv,
+    spec: { boolean: ['--json'], value: ['--url-env'] },
+    run: (ctx, flags, positional) => {
+      if (positional.length) throw refusal('DB_USAGE', 'drift takes flags only');
+      return driftCheck(ctx, { urlEnv: flags['url-env'] });
+    } });
+}

package/db/dump.mjs

@@ -31,7 +31,7 @@ export function archiveParts(ctx, scratch, parts) {
 }
 
 /** Writes only ciphertext and its receipt permanently; a receipt is published only after header, size and hash checks. */
-function dumpDatabase(ctx, options = {}) {
+export function dumpDatabase(ctx, options = {}) {
   if (!options.out) throw refusal('DB_USAGE', '--out is required');
   const out = outsideRepository(ctx.cwd, path.resolve(ctx.cwd, options.out));
   const session = backupSession(ctx, options);

package/db/entity-list.mjs

@@ -0,0 +1,9 @@
+// entity-list.mjs - where an app keeps its TypeORM entity list, read by `starci app db drift` and by the release gate that runs it.
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The app's one entity list: it re-exports the arrays each capability's persistence/entities/index.ts exports. */
+export const ENTITY_LIST = 'be/src/platform/database/entities.ts';
+
+/** True when the app at `root` keeps an entity list: the apps whose entities `starci app db drift` checks and whose release gate runs it. */
+export const hasEntityList = (root) => fs.existsSync(path.join(root, ENTITY_LIST));

package/db/migrate.mjs

@@ -386,7 +386,7 @@ function applyPlan(session, plan) {
  * `starci app db migrate`. options: { execute, linked, urlEnv }. Dry run reads the remote history once and prints the plan; --execute (with
  * STARCI_DB_ARMED=1) applies it. Already baseline + forward: `nothing to do`, no mutating call, ok.
  */
-async function migrateDatabase(ctx, decl, options = {}) {
+export async function migrateDatabase(ctx, decl, options = {}) {
   if (options.nativeTarget) boundSupabaseLauncher(ctx.cwd);
   const model = buildModel(ctx.cwd, decl);
   const session = { ctx, model, target: resolveTarget(ctx, decl, options) };

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.9.11",
   "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"
   },