@starci/hfs 4.9.9 → 4.10.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 4.10.0 - 2026-10-29
+
+Breaking for lite apps (ruling lite-self-hosted-postgres-passport-minio; the migration note is contexts/project/lite.md "Moving an app off Supabase").
+
+- Changed: the lite edition leaves Supabase. `starci app db` runs against a self-hosted PostgreSQL named by `--url-env <NAME>` (default `DATABASE_URL`) through psql and pg_dump (`db/postgres.mjs`): `migrate` applies each `db/migrations/<ts14>_<kebab>.sql` with its history row in one transaction (the `supabase_migrations.schema_migrations` layout, so a restored history carries over), runs `db/bootstrap.sql` first on an empty database and needs no `STARCI_DB_ARMED` on the loopback; `dump` writes roles, schema and data with pg_dumpall and pg_dump; `plan`, `baseline`, `restamp` and `post-cutover` query and repair the history through psql. New `db new <kebab-name>`. Removed: `db reset`, `--linked`, `--local`, `--target-binding` of the db verbs, the bundled Supabase CLI wrappers and the generated database types (`emit/db-types.mjs`, `app check --db-types`, `add --no-types`).
+- Changed: the lite templates. Managed: the db package scripts (`db:create|start|stop|reset` of the pinned `supabase/postgres` image, `db:new`, `db:push`, `db:plan`, `db:dump`), `scripts/codegen.mjs` (GraphQL only), `ci.yml` (no database-types job), `db-deploy.yml` (`starci app db migrate --url-env DATABASE_URL`), `.gitignore`, `.prettierignore` and `db/bootstrap.sql`; `starci app sync --write` deletes a leftover `supabase/types/` of a lite app. Scaffolded: `db/` instead of `supabase/`, a `db` service in both Swarm stacks with its volume, backup and sealed password, `backing.db`, the passport (Google OAuth with state and PKCE, email and password with bcryptjs, own ES256 tokens and JWKS, the refresh cookie) and storage (S3 client, presigned PUT and GET) integrations, the identity guard on the own-token verifier, `platform/database` entities option, `PRIMARY_ENTITIES` and the `callDbFunction`, `advisoryXactLock` and `notify` helpers, and the front end's `modules/auth` over the app's own auth doors (`auth-door.ts`, `token-store.ts`).
+- Changed: the checks. `LITE_DB_MIGRATION` (R332) refuses a `supabase/` tree or SQL outside `db/`; the database rules read `db/migrations` and hfs.json `db` (`forceRls`, `forceRlsExemptions`, `appRole`, `urlEnv`, `image`) and drop the config.toml, browser-access and realtime-publication checks; R276 admits the lite `db` component of image `supabase/postgres`; `backing` entries are `{provider: postgres, component}`; the architecture machine's identity check (`identity.mjs`) holds R329 and R260; SQL table ownership reads the tables the migrations create; hfs.json `sides.be.dbFunctions` joins `ruleParams.be.dbFunctions`.
+- Changed: `starci app add table` in lite writes a TypeORM entity (`persistence/entities/<table>.entity.ts`, `@Entity({ schema: "public", name })`) and the capability's `persistence/entities/index.ts` (`<c>Entities`), exports it from the capability entry and names it in `PRIMARY_ENTITIES` of `platform/database/entities.ts`; the service reads through `requireOwnedEntity` of `platform/database` (the entity's query builder, named parameters) and inserts with `save`. No `<name>.rows.ts` or `<name>.sql.ts` is written (ruling lite-persistence-typeorm-entities). The machine `schema-owner` (R35) checks that lite shape: the entity list in `persistence/entities/index.ts` and its name in `PRIMARY_ENTITIES`.
+- Changed: the lite queue, jobs and webhook generators write no SQL text outside platform/database (R334): their statements are functions of the generated db migrations (job_claim, job_advance, job_complete, job_fail, queue_write, queue_waiting, queue_mark_sent, inbox_claim_event, inbox_claim_client, inbox_save_client_outcome, inbox_sweep_clients, event_bus_write) called through `callDbFunction`, listed with their reasons in the canon `ruleParams.be.dbFunctions`; no `persistence/*.sql.ts` or `*.rows.ts` is written, and the webhook receipt insert is `webhookReceiptInsert(table)` of `platform/database`. The storage integration is `be.integrations.object-storage` (`src/modules/integrations/object-storage/`, `parseObjectStorageConfig`, `ObjectStorageOptions`, options member `objectStorage`). `db/entity-list.mjs` reads the lite entity list at `be/src/modules/platform/database/entities.ts`, where the skeleton keeps it.
+- Changed: the bundled lite pattern knowledge (event-bus, idempotency, jobs, projections, queues, reactors, realtime, saga, webhooks) names db migrations and the local db service instead of Supabase; the command policy points `supabase` at `starci app db` and the db scripts.
+- Changed: the bundled slot manifest 3.9.0 replaces the lite `app.supabase*` slots with `app.db` (`db/migrations`, `db/migrations/archive`, `db/seed.sql`, the managed `db/bootstrap.sql`), `be.integrations.supabase` with `be.integrations.passport` and `be.integrations.object-storage`, removes `fe.route.callback`, sets lite `schemaAuthority: sql`, gives lite TypeORM entities in `be.persistence`, adds `ruleParams.be.dbFunctions`, and moves the S3 SDKs to `integrations/object-storage` and the identity libraries to `integrations/passport` in `infraOwners` (`@supabase/*`, `minio` and `bcrypt` nowhere); the bundled rule catalog retires R216, R217, R219, R254 and R287 and adds R328-R334; the bundled canon pins name hfs 4.10.0, eslint-canon-be 3.7.0, eslint-canon-fe 9.5.0 and the Grammar family 0.15.11, pin `@nestjs/passport` 11.0.5 (CommonJS on the Nest 11 line), `passport` 0.7.0, `passport-google-oauth20` 2.0.0, `passport-local` 1.0.0, `bcryptjs` 3.0.3 and their types (tokens are signed and verified with `jose`; `@nestjs/jwt` stays allowed in `integrations/passport` but unpinned), and drop `@supabase/ssr`, `@supabase/supabase-js` and the `supabase` CLI.
+
+
+## 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>]
@@ -54,9 +55,9 @@ Lite is the smaller edition of the same HFS standard, not another profile or eng
 the same slot manifest, rule catalog, lint canons, grammar, security rules and Docker rules apply, while edition fields filter
 out the test world and event machinery.
 
-`starci app scaffold <name> --edition lite` creates the minimum single-api, single-Next-app Supabase product. It generates the
-`app.supabase.types` artifact from the app's local Supabase stack; if that generation cannot run, scaffolding fails and removes
-the app it began instead of leaving a partial tree.
+`starci app scaffold <name> --edition lite` creates the minimum single-api, single-Next-app product on its own PostgreSQL (`db/`,
+the `db` service of its stack), its Passport identity and its S3 storage; a failed step removes the app it began instead of leaving a
+partial tree. `starci app db new|plan|migrate|dump|post-cutover --url-env <NAME>` drives that database (default `DATABASE_URL`).
 
 The lite `app.starciwork` slot is optional when the app has no brand records. When present, it holds only `.gitignore`,
 optional `workspace.yaml` metadata and `brand/**` (R212): the existing brand record, drawing records, references and assets.
@@ -66,19 +67,30 @@ and `workspace.yaml` and retains `brand/` only when present.
 
 The lite additions are deliberately narrow:
 
-- `starci app add table <name> [--fe] [--no-types]` adds the migration and matching back-end capability. `--fe` also adds the table's
+- `starci app add table <name> [--fe]` adds the migration and matching back-end capability. `--fe` also adds the table's
   api feature over GraphQL (get-<singular> query, create-<singular> mutation, the GraphQL server capability on first use) and, in
   every product Next app, one operation file per operation under `modules/api/graphql` and its `useQuery*Swr` / `useMutate*Swr`
-  hook under `hooks/swr/api/graphql`; never a Server Action or a Supabase reader. Types regenerate by default, while `--no-types` is
-  the explicit opt-out.
+  hook under `hooks/swr/api/graphql`; never a Server Action or a database reader.
 - `starci app add cli <group>` creates the optional cli app on first use, including its built-in migration and seed groups, then adds
   the requested group without full-edition specs.
 - `starci app add app <name>` adds another Next app in either edition: the edition's app skeleton plus the shared app core
   (modules/api, auth, toast, redux, the providers and the hooks), one fe structure for lite and full (owner ruling 2026-10-13).
 - An `add` or `new` whose target slot is unavailable in lite stops before writing with `<verb> <noun>: full edition only`.
 
-`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 emit` emits the enabled back-end contract snapshots; a lite app generates no database types.
+
+`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/modules/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

package/db/backup-receipt.mjs

@@ -1,11 +1,10 @@
-// backup-receipt.mjs - encrypted database backup custody, shared by dump and reset; tool output never enters diagnostics.
+// backup-receipt.mjs - encrypted database backup custody of `starci app db dump`; tool output never enters diagnostics.
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
-import { readDeclaration } from '../release/index.mjs';
-import { resolveTarget, runCli as migrationCli, targetArgs } from './migrate.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
+import { DEFAULT_DB_URL_ENV, dbTarget, pgTool, queryRows as psqlRows } from './postgres.mjs';
 
 export const RECEIPT_SCHEMA = 'starci/db-backup@1';
 export function sha256(file) {
@@ -20,10 +19,9 @@ export function sha256(file) {
 }
 const inside = (root, file) => { const rel = path.relative(root, file); return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel)); };
 
-/** Backup/restore SQL can hold row values, so even the migration runner's scrubbed stderr must be withheld. */
-export function runCli(session, args) {
-  try { return migrationCli(session, args); }
-  catch { throw failure('DB_BACKUP_CLI_FAILED', `supabase ${args.slice(0, 2).join(' ')} failed; output withheld`); }
+/** Backup SQL can hold row values, so a client tool's stderr is withheld whole. */
+export function runPgTool(session, command, args) {
+  return pgTool(session.ctx, session.target, command, args, { withhold: true, code: 'DB_BACKUP_CLI_FAILED' });
 }
 
 /** Resolves existing ancestors before checking containment, including symlinked output directories and Git worktree marker files. */
@@ -40,27 +38,17 @@ export function outsideRepository(root, output) {
   return resolved;
 }
 
-/** Uses migrate's linked/password/URL resolution; local is explicitly selected and never silently defaults to linked. */
+/** The database of `--url-env` (default DATABASE_URL) and the project name the archive carries. */
 export function backupSession(ctx, options) {
-  const database = readDeclaration(ctx.cwd).database ?? {};
-  const selections = [options.linked === true, options.local === true, options.urlEnv !== undefined].filter(Boolean).length;
-  if (selections !== 1) throw refusal('DB_USAGE', 'select exactly one of --linked, --local or --url-env');
-  const target = options.local ? { kind: 'local', ref: null, env: {}, secrets: [], how: 'local database' }
-    : resolveTarget(ctx, { projectRef: null, password: null, ...database }, options);
-  if (target.kind === 'linked' && !/^[a-z0-9]{10,40}$/u.test(target.ref)) throw refusal('DB_NOT_LINKED', 'linked project ref is invalid');
+  const target = dbTarget(ctx, options.urlEnv ?? DEFAULT_DB_URL_ENV);
   const project = path.basename(ctx.cwd).replace(/[^A-Za-z0-9_-]/gu, '-') || 'database';
-  return { ctx, target, database, project };
+  return { ctx, target, project };
 }
 
-export const backupArgs = (session) => session.target.kind === 'local' ? ['--local', '--workdir', session.ctx.cwd] : targetArgs(session.target, session.ctx.cwd);
-
-/** Queries via the same injected Supabase runner; malformed output is withheld. */
+/** One read-only query through psql; failures and malformed output are withheld. */
 export function queryRows(session, sql) {
-  let rows;
-  try { rows = JSON.parse(runCli(session, ['db', 'query', sql, '--output', 'json', '--agent', 'no', ...backupArgs(session)]).stdout); }
+  try { return psqlRows(session.ctx, session.target, sql, { withhold: true }); }
   catch { throw failure('DB_BACKUP_QUERY_FAILED', 'database inventory query failed; output withheld'); }
-  if (!Array.isArray(rows) || rows.some((row) => !row || typeof row !== 'object' || Array.isArray(row))) throw failure('DB_BACKUP_QUERY_FAILED', 'database inventory is not a rows array');
-  return rows;
 }
 
 /** Executes local tar/age through ctx.spawn, the same seam used by the stack's age installer; never relays tool errors containing data. */
@@ -102,28 +90,3 @@ export function encryptFile(ctx, input, output, recipients) {
   return checkArchive(output);
 }
 
-/** Validates a complete, recent, full-data receipt and its encrypted bytes before any destructive reset call. */
-export function validateReceipt(session, receiptPath) {
-  if (!receiptPath) throw refusal('DB_RESET_BACKUP_MISSING', '--backup must name an encrypted backup receipt');
-  let receipt;
-  try { receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8')); } catch { throw refusal('DB_RESET_BACKUP_INVALID', 'backup receipt is missing or invalid JSON'); }
-  const valid = receipt && receipt.schema === RECEIPT_SCHEMA && receipt.target === 'linked' && receipt.schemaOnly === false
-    && typeof receipt.project === 'string' && typeof receipt.ref === 'string' && typeof receipt.file === 'string'
-    && path.basename(receipt.file) === receipt.file && receipt.file.endsWith('.age') && Number.isSafeInteger(receipt.bytes) && receipt.bytes >= 100
-    && /^[a-f0-9]{64}$/u.test(receipt.sha256 ?? '') && Array.isArray(receipt.parts)
-    && ['roles.sql', 'schema.sql', 'auth-storage-schema.sql', 'data.sql', 'auth-storage-data.sql', 'rowcounts.json'].every((part) => receipt.parts.includes(part))
-    && Number.isSafeInteger(receipt.rowcounts?.tables) && receipt.rowcounts.tables >= 0 && /^\d+$/u.test(receipt.rowcounts?.rows ?? '')
-    && typeof receipt.at === 'string' && Number.isFinite(Date.parse(receipt.at));
-  if (!valid) throw refusal('DB_RESET_BACKUP_INVALID', 'backup receipt is not a full starci/db-backup@1 linked backup');
-  if (receipt.ref !== session.target.ref) throw refusal('DB_RESET_BACKUP_PROJECT', 'backup targets a different project ref');
-  const maxAge = session.database.reset?.backupMaxAgeHours ?? 24;
-  if (!Number.isFinite(maxAge) || maxAge <= 0) throw refusal('DB_CONFIG_INVALID', 'database.reset.backupMaxAgeHours must be positive');
-  const age = session.ctx.now() - Date.parse(receipt.at);
-  if (age < 0 || age > maxAge * 3600000) throw refusal('DB_RESET_BACKUP_STALE', 'backup is future-dated or older than the allowed backup age');
-  const file = path.resolve(path.dirname(receiptPath), receipt.file);
-  if (!fs.existsSync(file)) throw refusal('DB_RESET_BACKUP_ARCHIVE_MISSING', 'backup archive is absent');
-  try {
-    if (checkArchive(file) !== receipt.bytes || sha256(file) !== receipt.sha256) throw new Error('mismatch');
-  } catch { throw refusal('DB_RESET_BACKUP_HASH', 'backup archive size, header or sha256 differs from the receipt'); }
-  return receipt;
-}

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/modules/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

@@ -1,17 +1,18 @@
-// dump.mjs - full Supabase backup, encrypted outside Git; every plaintext part is removed even when a tool fails.
+// dump.mjs - `starci app db dump`: a full backup of the database --url-env names (pg_dumpall roles, pg_dump schema and data),
+// encrypted outside Git; every plaintext part is removed even when a tool fails.
 import fs from 'node:fs';
 import path from 'node:path';
 import { runVerb } from '../release/index.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
-import { RECEIPT_SCHEMA, outsideRepository, backupSession, backupArgs, backupRecipients, backupTool, encryptFile, queryRows, sha256, runCli } from './backup-receipt.mjs';
+import { RECEIPT_SCHEMA, outsideRepository, backupSession, backupRecipients, backupTool, encryptFile, queryRows, sha256, runPgTool } from './backup-receipt.mjs';
 
-/** Counts every ordinary table with quoted identifiers in a read-only transaction, including auth and storage. */
+/** Counts every ordinary table with quoted identifiers, every schema but the catalogs (auth included). */
 export function rowcounts(session) {
   const tables = queryRows(session, "select schemaname, tablename from pg_catalog.pg_tables where schemaname not in ('pg_catalog', 'information_schema') order by schemaname, tablename;");
   const quote = (name) => `"${String(name).replaceAll('"', '""')}"`;
   return tables.map((table) => {
     if (typeof table.schemaname !== 'string' || typeof table.tablename !== 'string') throw failure('DB_BACKUP_QUERY_FAILED', 'invalid table inventory');
-    const rows = queryRows(session, `begin read only; select count(*)::text as count from ${quote(table.schemaname)}.${quote(table.tablename)}; commit;`);
+    const rows = queryRows(session, `select count(*)::text as count from ${quote(table.schemaname)}.${quote(table.tablename)}`);
     if (rows.length !== 1 || !/^\d+$/u.test(String(rows[0].count))) throw failure('DB_BACKUP_QUERY_FAILED', 'invalid rowcount');
     return { schema: table.schemaname, table: table.tablename, count: String(rows[0].count) };
   });
@@ -31,7 +32,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);
@@ -48,15 +49,15 @@ function dumpDatabase(ctx, options = {}) {
   let complete = false;
   try {
     fs.mkdirSync(scratch, { mode: 0o700 });
-    const jobs = [['roles.sql', ['--role-only']], ['schema.sql', []], ['auth-storage-schema.sql', ['--schema', 'auth,storage']]];
-    if (!options.schemaOnly) jobs.push(['data.sql', ['--data-only']], ['auth-storage-data.sql', ['--data-only', '--schema', 'auth,storage']]);
-    for (const [file, flags] of jobs) runCli(session, ['db', 'dump', ...flags, '--file', path.join(scratch, file), ...backupArgs(session)]);
+    const jobs = [['roles.sql', 'pg_dumpall', ['--roles-only', '--no-role-passwords']], ['schema.sql', 'pg_dump', ['--schema-only']]];
+    if (!options.schemaOnly) jobs.push(['data.sql', 'pg_dump', ['--data-only']]);
+    for (const [file, command, flags] of jobs) runPgTool(session, command, [...flags, '--file', path.join(scratch, file), '--dbname', session.target.url]);
     const counts = rowcounts(session);
     fs.writeFileSync(path.join(scratch, 'rowcounts.json'), `${JSON.stringify(counts, null, 2)}\n`, { mode: 0o600 });
     const parts = [...jobs.map(([file]) => file), 'rowcounts.json'];
     const tar = archiveParts(ctx, scratch, parts);
     const bytes = encryptFile(ctx, tar, archive, recipients);
-    const receipt = { schema: RECEIPT_SCHEMA, project: session.project, target: session.target.kind, ref: session.target.ref ?? null,
+    const receipt = { schema: RECEIPT_SCHEMA, project: session.project, target: session.target.kind, ref: session.target.urlEnv,
       at, file: path.basename(archive), bytes, sha256: sha256(archive), parts,
       rowcounts: { tables: counts.length, rows: counts.reduce((sum, row) => sum + BigInt(row.count), 0n).toString(), tablesByName: counts }, schemaOnly: options.schemaOnly === true };
     fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
@@ -70,9 +71,9 @@ function dumpDatabase(ctx, options = {}) {
 
 export function dbDumpMain(argv, io = {}) {
   return runVerb({ label: 'starci app db dump', name: 'db dump', code: 'DB_USAGE', io, argv,
-    spec: { boolean: ['--linked', '--local', '--schema-only', '--json'], value: ['--url-env', '--out'] },
+    spec: { boolean: ['--schema-only', '--json'], value: ['--url-env', '--out'] },
     run: (ctx, flags, positional) => {
       if (positional.length) throw refusal('DB_USAGE', 'dump takes flags only');
-      return dumpDatabase(ctx, { linked: flags.linked, local: flags.local, urlEnv: flags['url-env'], out: flags.out, schemaOnly: flags['schema-only'] });
+      return dumpDatabase(ctx, { urlEnv: flags['url-env'], out: flags.out, schemaOnly: flags['schema-only'] });
     } });
 }

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/modules/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));