@starci/hfs 4.3.0 → 4.4.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.4.1 - 2026-10-17
+- Changed: the bundled runtime copies follow the runtime of 1.0.0-alpha.19 (owner ruling no-runtime-specs, 2026-10-17): the failure codes, the slot manifest (`exampleNa`) and the rule catalog (`specNa`, `exampleNa`) carry the removal of the runtime's own specs; package behavior is unchanged. The managed codecov.yml, the CI coverage upload and the hfs sync render stay (Codecov is kept for apps and examples); internal exports that only the deleted runtime specs read are no longer exported.
+
+## 4.4.0 - 2026-10-15
+- Fixed: a swarm service on a shared external edge network no longer keeps the implicit short service name as an alias (`docker stack deploy` adds `api` for nivo_api on every network, so another tenant resolving `http://api` reached the wrong stack). `starci app stack deploy` and rollback reconcile the edge attachment to exactly the declared aliases right after `docker stack deploy` (`STACK_DEPLOY_EDGE_ALIAS` when they still differ), `stack verify` refuses an undeclared alias on an edge-attached service, and the deploy preflight and `stack doctor` extend `STACK_DEPLOY_ALIAS_SHARED` to a short name that another container or service of the edge network already resolves (`STACK_DEPLOY_EDGE_UNREADABLE` when the network cannot be inspected).
+- Added: R295 `BE_MODULE_DEFINITION_MISSING`: every Nest module has a module definition (owner ruling 2026-10-15 `owner:module-definition-everywhere`). The slot manifest allows `<x>.module-definition.ts` and `<x>.options.ts` beside every feature, transport, cli group, queue, reactor and job module; the generators of `starci app add` and `starci app new` write the three files and register the module as `X.register({})`.
+- Changed: `module-per-transport` accepts a module-definition beside the application module, the transport module of its folder and a cli group, and refuses one anywhere else.
+
 ## 4.3.0 - 2026-10-14
 - Added: the app file role `<app>.env.ts` (`apps/<app>/src/`, every `be.app.*` slot, budget 150): a typed `<App>Env` interface and fail-fast `read<App>Env` reader (secrets `_FILE` first), imported by `main.ts` so the entry stays within its 80 lines. Only `main.ts` and the app's own env file read the environment; the env file lists no module and imports no feature. The api, lite api and cli scaffolds write it.
 - Added: `starci app secret` custody verbs `init`, `set <env> <slug> <KEY>` (stdin or `--generate <bytes>`), `get <env> <slug> [KEY] --to-file [--reveal]`, `materialize <env>` and `list <env>` over sops dotenv files under `.starcistacks/<env>/secrets/`; the age identity lives outside the repository, materialized values go under the local StarCi secrets directory for `*_FILE` reading, and no value reaches stdout unless `--reveal`. The scaffolded `.sops.yaml` carries the `init` instruction and the be config template reads `<NAME>_FILE` before `<NAME>`. An untracked root `secrets.env` of a lite app is an `HFS_PLAINTEXT_SECRET` warning.
@@ -116,6 +124,12 @@
 - New: `hfs secret list|show|set|gen` (alpha.5 item 6.4), the canon command over the sealed secrets of `.starcistacks/<env>/secrets/<slug>.enc`, on the runtime's sops api (a new `seal` call: the value travels on stdin, never on an argument list). Replaces the plain `sops` commands of runbooks and KEYS.md files.
 - Changed: HFS_REQUIRED_FILE_MISSING now also carries what BE_REQUIRED_MODULE_MISSING reported, and BE_TEST_TOPOLOGY what HFS_TEST_KIND_RETIRED reported (one code per obligation); the bundled architecture machine follows `APP_GUARD` and `APP_FILTER` providers built by a helper outside the app root file.
 - Changed: the managed fe scripts (`dev:fe`, `start:<app>`, `build:fe`) run `next` from the app directory (`cd fe/apps/<app> && next ...`) so next-intl finds its request config; the fe skeleton reads the request locale through `next/root-params` (`experimental.rootParams`), pins the workspace root three levels above the app and uses the `.*[.].*` proxy matcher; the bundled runtime carries the `&&`/`||`-aware FE_SWR_KEY_IDENTITY check.
+## Unreleased (a18 R281)
+
+- Fixed: the bundled architecture machine (`function-spec-providers.mjs`, `unit-spec-providers.mjs`) takes the callable subset of a function-only subject's exports (constants, enums, re-exports and overload signatures are ignored) and lets the spec of a value-object class (undecorated, no constructor injection token) construct it with `new`.
+- Security (canon pins, npm audit of 2026-10-16): `next` 16.1.6 to 16.4.2 (critical, with the `postcss` and `sharp` highs it brings), `axios` 1.15.2 to 1.20.0 and `@nestjs/platform-express` 11.2.5 to 11.2.7 (with `multer`) in `knowledge/hfs/canon-pins.yaml`; the example apps (`ecommerce-app`, `lite-app`, `shape-slot`) and `packages/test-world` carry the new pins and lockfiles.
+- Known advisory, accepted (owner ruling `graphql-13-advisory-accepted-until-a19`, 2026-10-16): `@nestjs/graphql` and `@nestjs/apollo` stay on 13.4.5. `npm audit --omit=dev --audit-level=high` still reports their highs (and `@graphql-tools/utils` through them); the fix is 14.0.3, a semver major, deferred to alpha.19.
+
 ## Unreleased (C0 batch)
 
 - Fixed (contract change `sonar-coverage-exclusions`): SonarQube has no `sonar.coverage.inclusions` property, so Sonar ignored it and counted every executable be/ file at 0% (overall coverage 65.8% and 45.2% on the examples, although every service was at 100). The managed `sonar-project.properties` now renders `sonar.coverage.exclusions` as the complement of the services. `coverageExclusions(presets, manifest)` in `sync/index.mjs` derives it from the preset's `COVERAGE_SOURCES` and the slot manifest, and lists:

package/README.md

@@ -185,7 +185,7 @@ The upload authenticates with GitHub's OIDC token: the managed `ci.yml` job has
 editing a list), plus the catalog slice of every code `starci app check` can emit: its own and the machine's (`ARCHITECTURE_RULE_IDS`,
 derived from the machine's rule id lists). After changing any of those files, `knowledge/hfs/slots.yaml`,
 `knowledge/hfs/canon-pins.yaml`, `knowledge/patterns/fe/folder.yaml` or the catalog entries of those codes, run `starci release sync-runtime`;
-`tests/packages-hfs/hfs-cli.spec.mjs` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.
+`starci release sync-runtime --check` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.
 
 The examples gate `starci runtime check --only example-architecture` runs `starci app lint` of this CLI at the root of every `examples/*`
 app with an `hfs.json` (each `examples/<app>` root) and fails on any finding or any tool that could not run;

package/db/migrate.mjs

@@ -0,0 +1,361 @@
+// migrate.mjs - `starci app db migrate`: puts a database's migration history in the state the app's repository declares, idempotently.
+// The optional `database:` block of .starcistacks/application-stacks.yaml names the baseline migration, the optional second baseline (standard),
+// the held-back migrations (applied later by `db post-cutover`), the restamp pairs and the archive directory. The plan, from the remote history:
+//   repair    revert each restamped old version still on the remote and mark its new version applied
+//   baseline  revert the archived rows, mark the baseline applied (it is NOT run)
+//   forward   push every other migration, EXCEPT the held-back ones (they are never copied into the push project)
+// When the remote already is baseline + forward (held-back ones may or may not be applied) it prints `nothing to do` and makes no mutating call.
+// The Supabase CLI runs through ctx.spawn with scratch workdirs; a password travels only in the child environment (SUPABASE_DB_PASSWORD from the
+// environment or the sealed custody, PGPASSWORD split off a --url-env connection string), never in argv, a file, a line or an error.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
+import { byCodeUnit } from '../runtime/engine/by-code-unit.mjs';
+import { readMap } from '../runtime/scripts/hfs/secret-store.mjs';
+import { STACKS_DIR } from '../stack/config.mjs';
+import { firstLine, tool } from '../stack/context.mjs';
+import { approvalMissing, failure, refusal } from '../stack/errors.mjs';
+import { readDeclaration, runVerb } from '../release/index.mjs';
+
+const DATABASE_CODE = 'DB_CONFIG_INVALID';
+
+const SEGMENT = /^[A-Za-z0-9._-]+$/u;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
+const IDENT = /^[a-z][a-z0-9_]*$/u;
+const SLUG = /^[a-z][a-z0-9-]*$/u;
+const KEY = /^[A-Z][A-Z0-9_]*$/u;
+const STAMP = /^\d{14}$/u;
+const PROJECT_REF = /^[a-z0-9]{10,40}$/u;
+const SIGNATURE = /^[A-Za-z0-9_."(), ]+$/u;
+const MIGRATION = /^(\d{14})_([A-Za-z0-9_-]+)\.sql$/u;
+const PENDING = /(\d{14})_[^\s"]+?\.sql/gu;
+
+const matches = (pattern) => (value) => typeof value === 'string' && pattern.test(value);
+const listOf = (item) => (value) => Array.isArray(value) && value.every((entry) => item(entry));
+const dirOk = (value) => typeof value === 'string' && value.split('/').every((part) => SEGMENT.test(part) && part !== '..');
+const pairOk = (value) => plain(value) && Object.keys(value).length === 2 && matches(STAMP)(value.from) && matches(STAMP)(value.to);
+const passwordOk = (value) => plain(value) && Object.keys(value).length === 3 && matches(SLUG)(value.env) && matches(SLUG)(value.member) && matches(KEY)(value.key);
+const POST_FIELDS = ['schema', 'functionPrefixes', 'functionNames', 'functions', 'minAgeHours'];
+const POST_CHECKS = {
+  schema: matches(IDENT), functionPrefixes: listOf(matches(IDENT)), functionNames: listOf(matches(IDENT)),
+  functions: listOf(matches(SIGNATURE)), minAgeHours: (value) => Number.isFinite(value) && value >= 0,
+};
+const postOk = (value) => plain(value) && Object.keys(value).every((key) => POST_FIELDS.includes(key) && POST_CHECKS[key](value[key]));
+
+const CHECKS = {
+  migrationsDir: [dirOk, 'must be a relative directory inside the app'],
+  archiveDir: [dirOk, 'must be a relative directory inside the app'],
+  baseline: [matches(NAME), `must match ${NAME} (the name after the stamp)`],
+  standard: [matches(NAME), `must match ${NAME} (the name after the stamp)`],
+  heldBack: [listOf(matches(NAME)), 'must be a list of migration names'],
+  projectRef: [matches(PROJECT_REF), `must match ${PROJECT_REF}`],
+  restamp: [listOf(pairOk), 'must be a list of { from, to } fourteen-digit stamps'],
+  password: [passwordOk, 'must be { env, member, key } naming a sealed value'],
+  postCutover: [postOk, `must use only ${POST_FIELDS.join(', ')} with valid values`],
+};
+
+/** Judges the `database:` block. Returns { config } or { problems }; `baseline` is the one required field. */
+function normalizeDatabase(block) {
+  if (!plain(block)) return { problems: ['database: must be a mapping'] };
+  const problems = [];
+  for (const [key, value] of Object.entries(block)) {
+    if (!Object.hasOwn(CHECKS, key)) problems.push(`database.${key}: is not a field of the database block`);
+    else if (!CHECKS[key][0](value)) problems.push(`database.${key}: ${CHECKS[key][1]}`);
+  }
+  if (block.baseline === undefined) problems.push('database.baseline: is required');
+  if (problems.length > 0) return { problems };
+  const config = {
+    migrationsDir: 'supabase/migrations', archiveDir: null, standard: null, heldBack: [], projectRef: null, restamp: [], password: null, postCutover: null, ...block,
+  };
+  return { config };
+}
+
+/** The normalised `database:` block of the app at `root`; absent or invalid is a refusal (these verbs need the declaration). */
+export function loadDatabase(root) {
+  const block = readDeclaration(root).database;
+  if (block === undefined) throw refusal('DB_UNDECLARED', 'the app declares no database: block in .starcistacks/application-stacks.yaml');
+  const { config, problems } = normalizeDatabase(block);
+  if (!config) throw refusal(DATABASE_CODE, `${problems.length} problem(s) in database: ${problems.slice(0, 6).join('; ')}`);
+  return config;
+}
+
+/* ---- the repository model */
+
+const sqlNames = (dir, what) => {
+  try { return fs.readdirSync(dir).filter((name) => name.endsWith('.sql')).sort(byCodeUnit); } catch { throw refusal('DB_MIGRATIONS_MISSING', `${what} (${dir}) is not readable`); }
+};
+
+const stampOf = (file) => file.split('_')[0];
+
+function archiveOf(root, decl) {
+  if (decl.archiveDir === null || !fs.existsSync(path.join(root, decl.archiveDir))) return [];
+  const moved = new Map(decl.restamp.map((pair) => [pair.from, pair.to]));
+  return sqlNames(path.join(root, decl.archiveDir), 'the archive directory').map((file) => {
+    const version = moved.get(stampOf(file)) ?? stampOf(file);
+    return { from: path.join(root, decl.archiveDir, file), name: `${version}_${file.slice(file.indexOf('_') + 1)}`, version };
+  });
+}
+
+function stampProblems(model, decl) {
+  const { files, baselineFile, standardFile, baseline, standard } = model;
+  for (const file of files) {
+    const version = stampOf(file);
+    if (file !== baselineFile && version <= baseline) throw refusal('DB_STAMP_ORDER', `${file} sorts at or before the baseline: it would run before the baseline on a fresh database`);
+    if (standardFile && file !== baselineFile && file !== standardFile && version <= standard) throw refusal('DB_STAMP_ORDER', `${file} sorts before the second baseline`);
+    if (decl.restamp.some((pair) => pair.to === version)) throw refusal('DB_STAMP_COLLISION', `${file} collides with a restamp target`);
+  }
+}
+
+/** The migration files of the app and its baseline pair; refuses badly named, duplicate-stamped or missing files. */
+function checkedFiles(root, decl) {
+  const files = sqlNames(path.join(root, decl.migrationsDir), 'the migrations directory');
+  const bad = files.filter((file) => !MIGRATION.test(file));
+  if (bad.length > 0) throw refusal('DB_MIGRATION_NAME', `migration files must be <14-digit stamp>_<name>.sql (got ${bad[0]})`);
+  if (new Set(files.map(stampOf)).size !== files.length) throw refusal('DB_STAMP_DUPLICATE', 'two migrations share one stamp');
+  const baselineFile = files.find((file) => file.endsWith(`_${decl.baseline}.sql`));
+  const standardFile = decl.standard === null ? undefined : files.find((file) => file.endsWith(`_${decl.standard}.sql`));
+  if (!baselineFile) throw refusal('DB_BASELINE_MISSING', `no migration named ${decl.baseline} in ${decl.migrationsDir}`);
+  if (decl.standard !== null && !standardFile) throw refusal('DB_BASELINE_MISSING', `no migration named ${decl.standard} in ${decl.migrationsDir}`);
+  return { files, baselineFile, standardFile };
+}
+
+/** Classifies the migration files of the app: baseline pair, held-back, forward, restamp pairs and archive. Refuses an inconsistent repository. */
+export function buildModel(root, decl) {
+  const { files, baselineFile, standardFile } = checkedFiles(root, decl);
+  const held = files.filter((file) => decl.heldBack.some((name) => file.endsWith(`_${name}.sql`)));
+  const push = files.filter((file) => !held.includes(file));
+  const baseline = stampOf(baselineFile);
+  const model = {
+    root, decl, files, baselineFile, standardFile, baseline, standard: standardFile ? stampOf(standardFile) : null, held, push,
+    heldVersions: held.map(stampOf), pushPending: push.filter((file) => file !== baselineFile).map(stampOf), archive: archiveOf(root, decl),
+  };
+  stampProblems(model, decl);
+  return { ...model, pushVersions: new Set([baseline, ...model.pushPending]), allowed: new Set([baseline, ...model.pushPending, ...model.heldVersions]) };
+}
+
+/* ---- reading the CLI */
+
+/** Versions from the JSON form of `supabase migration list`, or null when the text holds no readable JSON. */
+function jsonVersions(text) {
+  const start = text.indexOf('{"migrations"');
+  if (start < 0) return null;
+  const end = text.indexOf('\n', start);
+  try {
+    const items = JSON.parse(text.slice(start, end > 0 ? end : undefined)).migrations;
+    return { remote: new Set(items.filter((item) => item.remote).map((item) => item.remote)), local: new Set(items.filter((item) => item.local).map((item) => item.local)) };
+  } catch { return null; }
+}
+
+/** Versions from the older table form: rows of `local | remote | time`. */
+function tableVersions(text) {
+  const remote = new Set();
+  const local = new Set();
+  for (const cells of text.split('\n').map((line) => line.split('|').map((cell) => cell.trim())).filter((row) => row.length >= 3)) {
+    if (STAMP.test(cells[0])) local.add(cells[0]);
+    if (STAMP.test(cells[1])) remote.add(cells[1]);
+  }
+  return { remote, local };
+}
+
+/** Remote (and local) versions from `supabase migration list`: the JSON form, or the older table. */
+const parseMigrationList = (text) => jsonVersions(text) ?? tableVersions(text);
+
+/** The versions a `db push --dry-run` would apply. */
+export const pendingVersions = (text) => [...new Set([...text.matchAll(PENDING)].map((match) => match[1]))];
+
+/* ---- the target */
+
+const scrub = (text, secrets) => secrets.reduce((out, secret) => out.replaceAll(secret, '[value]'), String(text));
+
+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; }
+}
+
+function urlTarget(ctx, name) {
+  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`);
+  const secrets = [value, parsed.password].filter(Boolean);
+  return { kind: 'url', how: `connection string from ${name}`, url: parsed.url, env: parsed.password ? { PGPASSWORD: parsed.password } : {}, secrets };
+}
+
+function sealedPassword(ctx, spec) {
+  let map;
+  try { map = readMap(path.join(ctx.cwd, STACKS_DIR, spec.env, 'secrets', `${spec.member}.enc`), ctx.sops); } catch { throw refusal('DB_PASSWORD_UNREADABLE', `the sealed member ${spec.member} cannot be opened`); }
+  if (typeof map[spec.key] !== 'string' || map[spec.key] === '') throw refusal('DB_PASSWORD_UNREADABLE', `the sealed member ${spec.member} has no value for ${spec.key}`);
+  return map[spec.key];
+}
+
+/** The database password for the linked CLI: SUPABASE_DB_PASSWORD from the environment, else the declared sealed value, else none (the CLI mints a login). */
+function linkedPassword(ctx, decl) {
+  const given = ctx.env.SUPABASE_DB_PASSWORD;
+  if (typeof given === 'string' && given !== '') return given;
+  return decl.password === null ? null : sealedPassword(ctx, decl.password);
+}
+
+function linkedTarget(ctx, decl) {
+  let ref;
+  try { ref = fs.readFileSync(path.join(ctx.cwd, 'supabase', '.temp', 'project-ref'), 'utf8').trim(); } catch { throw refusal('DB_NOT_LINKED', 'no linked project (supabase/.temp/project-ref): run supabase link first'); }
+  if (decl.projectRef !== null && ref !== decl.projectRef) throw refusal('DB_WRONG_PROJECT', `the app is linked to ${ref}, not the declared project ${decl.projectRef}`);
+  const password = linkedPassword(ctx, decl);
+  return { kind: 'linked', how: `linked project ${ref}`, ref, url: null, env: password ? { SUPABASE_DB_PASSWORD: password } : {}, secrets: password ? [password] : [] };
+}
+
+/** { kind, how, env, secrets, url }: the linked project of the app (default) or the connection string in the named environment variable. */
+export function resolveTarget(ctx, decl, options) {
+  if (options.linked === true && options.urlEnv !== undefined) throw refusal('DB_USAGE', '--linked and --url-env exclude each other');
+  return options.urlEnv === undefined ? linkedTarget(ctx, decl) : urlTarget(ctx, options.urlEnv);
+}
+
+/** CLI arguments that select the database and the local supabase folder. */
+export const targetArgs = (target, dir) => (target.kind === 'url' ? ['--db-url', target.url, '--workdir', dir] : ['--linked', '--workdir', dir]);
+
+/** Refuses a mutation unless the operator armed it with STARCI_DB_ARMED=1. */
+export function requireArmed(ctx) {
+  if (ctx.env.STARCI_DB_ARMED !== '1') throw approvalMissing('DB_NOT_ARMED', 'set STARCI_DB_ARMED=1 to apply database changes');
+}
+
+const supabaseCommand = (root) => {
+  const script = path.join(root, 'node_modules', 'supabase', 'dist', 'supabase.js');
+  return fs.existsSync(script) ? [process.execPath, script] : ['supabase'];
+};
+
+/** Runs the Supabase CLI through the seam; a failure names the first stderr line with every secret scrubbed. Returns { stdout, text } (text = stdout plus stderr). */
+export function runCli(session, args) {
+  const { ctx, target } = session;
+  const [command, ...lead] = supabaseCommand(ctx.cwd);
+  const run = tool(ctx, command, [...lead, ...args], { cwd: ctx.cwd, env: { ...ctx.env, ...target.env } });
+  if (run.error) throw failure('DB_CLI_MISSING', `cannot run the Supabase CLI (${scrub(run.error.message, target.secrets)})`);
+  if (run.status !== 0) throw failure('DB_CLI_FAILED', `supabase ${args.slice(0, 2).join(' ')} failed: ${scrub(firstLine(run.stderr), target.secrets)}`);
+  return { stdout: run.stdout ?? '', text: `${run.stdout ?? ''}${run.stderr ?? ''}` };
+}
+
+/** The remote history as a Set of versions (read-only). */
+export const listRemote = (session) => parseMigrationList(runCli(session, ['migration', 'list', ...targetArgs(session.target, session.ctx.cwd)]).text).remote;
+
+/* ---- the plan */
+
+/** Pure: what to do given the remote history. `done` means baseline + forward are present and nothing else is. */
+function planMigration(model, remote) {
+  const done = [...model.pushVersions].every((version) => remote.has(version)) && [...remote].every((version) => model.allowed.has(version));
+  const sim = new Set(remote);
+  const repairs = model.decl.restamp.filter((pair) => sim.has(pair.from));
+  for (const pair of repairs) {
+    sim.delete(pair.from);
+    sim.add(pair.to);
+  }
+  const reverts = sim.has(model.baseline) ? [] : model.archive.map((item) => item.version).filter((version) => sim.has(version));
+  for (const version of reverts) sim.delete(version);
+  const mark = !sim.has(model.baseline);
+  sim.add(model.baseline);
+  const push = model.pushPending.filter((version) => !sim.has(version));
+  for (const version of push) sim.add(version);
+  const archived = new Set(model.archive.map((item) => item.version));
+  const missingFiles = repairs.map((pair) => pair.to).filter((version) => !archived.has(version));
+  return { done, repairs, reverts, mark, push, missingFiles, unexpected: [...sim].filter((version) => !model.allowed.has(version)), final: sim.size };
+}
+
+function planLines(model, session, remote, plan) {
+  const nameOf = (version) => model.files.find((file) => file.startsWith(`${version}_`));
+  return [
+    `target         ${session.target.how}`,
+    `remote history ${remote.size} version(s)`,
+    [`repairs        ${plan.repairs.length} restamped version(s) to move`, ...plan.repairs.map((pair) => `  ${pair.from} -> ${pair.to}`)].join('\n'),
+    `archive revert ${plan.reverts.length} archived version(s) present on the remote`,
+    `baseline       ${model.baseline} ${plan.mark ? 'will be marked applied (not run)' : 'already applied'}`,
+    `forward push   ${plan.push.length} migration(s): ${plan.push.map(nameOf).join(', ') || 'none'}`,
+    `held back      ${model.held.join(', ') || 'none'} (never applied here; starci app db post-cutover)`,
+  ];
+}
+
+const dataOf = (model, plan, remote, extra) => ({
+  remoteCount: remote.size, repairs: plan.repairs.length, reverts: plan.reverts, baseline: model.baseline, markBaseline: plan.mark, push: plan.push,
+  heldBack: model.heldVersions, done: plan.done, ...extra,
+});
+
+/* ---- applying */
+
+/** A scratch supabase project holding exactly the given migration files; the link state of the app is copied so --linked works from it. */
+function buildScratch(session, dir, copies) {
+  fs.mkdirSync(path.join(dir, 'supabase', 'migrations'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'supabase', 'config.toml'), 'project_id = "starci-db-scratch"\n');
+  for (const copy of copies) fs.copyFileSync(copy.from, path.join(dir, 'supabase', 'migrations', copy.name));
+  if (session.target.kind === 'linked') fs.cpSync(path.join(session.ctx.cwd, 'supabase', '.temp'), path.join(dir, 'supabase', '.temp'), { recursive: true });
+}
+
+const repair = (session, status, versions, dir) => runCli(session, ['migration', 'repair', '--status', status, ...versions, ...targetArgs(session.target, dir)]);
+
+function applyRepairs(session, plan, scratch) {
+  const dir = path.join(scratch, 'archive');
+  buildScratch(session, dir, session.model.archive.map((item) => ({ from: item.from, name: item.name })));
+  repair(session, 'reverted', plan.repairs.map((pair) => pair.from), dir);
+  repair(session, 'applied', plan.repairs.map((pair) => pair.to), dir);
+}
+
+function applyForward(session, plan, scratch) {
+  const { model } = session;
+  const dir = path.join(scratch, 'baseline');
+  buildScratch(session, dir, model.push.map((file) => ({ from: path.join(model.root, model.decl.migrationsDir, file), name: file })));
+  if (plan.reverts.length > 0) repair(session, 'reverted', plan.reverts, dir);
+  if (plan.mark) repair(session, 'applied', [model.baseline], dir);
+  const pending = pendingVersions(runCli(session, ['db', 'push', '--dry-run', ...targetArgs(session.target, dir)]).text);
+  const stray = pending.filter((version) => !model.pushPending.includes(version));
+  if (stray.length > 0) throw failure('DB_PUSH_STRAY', `the dry run lists versions outside the push list: ${stray.join(', ')}. Stopped before pushing.`);
+  if (pending.length > 0) runCli(session, ['db', 'push', '--yes', ...targetArgs(session.target, dir)]);
+  return pending;
+}
+
+function applyPlan(session, plan) {
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-db-'));
+  try {
+    if (plan.repairs.length > 0) applyRepairs(session, plan, scratch);
+    const after = planMigration(session.model, listRemote(session));
+    return applyForward(session, after, scratch);
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * `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 = {}) {
+  const model = buildModel(ctx.cwd, decl);
+  const session = { ctx, model, target: resolveTarget(ctx, decl, options) };
+  const remote = listRemote(session);
+  const plan = planMigration(model, remote);
+  if (plan.done) return { ok: true, lines: [`target         ${session.target.how}`, 'remote history already is the baseline plus the forward migrations (held-back ones may or may not be applied). Nothing to do.'], data: dataOf(model, plan, remote, { executed: false }) };
+  const lines = planLines(model, session, remote, plan);
+  const red = [
+    ...plan.missingFiles.map((version) => `no archived migration file for the restamped version ${version}`),
+    ...plan.unexpected.map((version) => `remote version ${version} is outside baseline + forward + held-back and no restamp or archive row explains it`),
+  ];
+  if (red.length > 0) return { ok: false, lines: [...lines, ...red.map((item) => `RED: ${item}`), 'nothing applied.'], data: dataOf(model, plan, remote, { red, executed: false }) };
+  if (options.execute !== true) return { ok: true, lines: [...lines, `dry run: read-only (one migration list); the final history would be ${plan.final} version(s). Nothing applied.`], data: dataOf(model, plan, remote, { executed: false }) };
+  requireArmed(ctx);
+  const pushed = applyPlan(session, plan);
+  const final = listRemote(session);
+  const verdict = planMigration(model, final);
+  if (!verdict.done) throw failure('DB_FINAL_MISMATCH', `the remote history is not baseline + forward migrations (${[...final].join(', ')})`);
+  return { ok: true, lines: [...lines, `applied: ${pushed.length} forward migration(s) pushed; the remote history now holds ${final.size} version(s). Held back: ${model.held.join(', ') || 'nothing'}.`], data: dataOf(model, plan, remote, { executed: true, pushed, remoteCountAfter: final.size }) };
+}
+
+const SPEC = { boolean: ['--execute', '--json', '--linked'], value: ['--url-env'] };
+
+/** Entry of the verb: `starci app db migrate [--execute] [--linked | --url-env NAME] [--json]`. `io` is the app IO of src/main.mjs. */
+export function dbMigrateMain(argv, io = {}) {
+  return runVerb({
+    label: 'starci app db migrate', name: 'db migrate', code: 'DB_USAGE', io, argv, spec: SPEC,
+    run: (ctx, flags) => migrateDatabase(ctx, loadDatabase(ctx.cwd), { execute: flags.execute === true, linked: flags.linked === true, urlEnv: flags['url-env'] }),
+  });
+}

package/db/post-cutover.mjs

@@ -0,0 +1,136 @@
+// post-cutover.mjs - `starci app db post-cutover`: applies the held-back migrations (database.heldBack) that `db migrate` skipped, e.g. the one that
+// drops the old engine's tables. After it a rollback to the old app needs a database restore, so it is guarded three ways:
+//   1. a READ-ONLY pg_proc preflight (also in the dry run): every function of the declared families (database.postCutover.functionPrefixes and
+//      functionNames in database.postCutover.schema) that exists on the database must be covered by the DROP FUNCTION statements of the held-back
+//      migration (or database.postCutover.functions); a function nobody drops is a function something may still need, so nothing is applied;
+//   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.
+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';
+
+const DROP_FUNCTION = /^drop\s+function\s+/iu;
+const IF_EXISTS = /^if\s+exists\s+/iu;
+const MS_PER_HOUR = 3.6e6;
+const DEFAULT_MIN_AGE_HOURS = 48;
+
+/** Makes a DROP signature comparable with pg_proc's regprocedure text. */
+function normalizeSignature(signature, schema) {
+  const lowered = signature.trim().toLowerCase();
+  const bare = lowered.startsWith(`${schema}.`) ? lowered.slice(schema.length + 1) : lowered;
+  const words = bare
+    .replace(/\bint\b/gu, 'integer')
+    .replace(/\btimestamptz\b/gu, 'timestamp with time zone')
+    .replace(/\s+/gu, ' ');
+  return [...'(),'].reduce((out, mark) => out.replaceAll(` ${mark}`, mark).replaceAll(`${mark} `, mark), words);
+}
+
+/** The signature a `DROP FUNCTION [IF EXISTS] <signature>` statement drops, or null for any other statement. */
+function droppedSignature(statement) {
+  const head = DROP_FUNCTION.exec(statement);
+  return head ? statement.slice(head[0].length).replace(IF_EXISTS, '') : null;
+}
+
+/** The signatures a migration drops: every `DROP FUNCTION [IF EXISTS] <signature>;` statement. */
+function dropSignatures(sql, schema) {
+  return sql.replace(/--[^\n]*/gu, '').split(';').flatMap((statement) => {
+    const signature = droppedSignature(statement.trim());
+    return signature === null ? [] : [normalizeSignature(signature, schema)];
+  });
+}
+
+const settingsOf = (post) => ({
+  schema: post.schema ?? 'public', prefixes: post.functionPrefixes ?? [], names: post.functionNames ?? [], extra: post.functions ?? [],
+});
+
+/** The read-only pg_proc query of the declared function families (identifiers are validated, so nothing free-form reaches the SQL). */
+function preflightSql({ schema, prefixes, names }) {
+  const escaped = (prefix) => prefix.replaceAll('_', String.raw`\_`);
+  const clauses = [...names.map((name) => `proname = '${name}'`), ...prefixes.map((prefix) => `proname like '${escaped(prefix)}%'`)];
+  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);
+
+async function queryRows(session, sql, options) {
+  try {
+    const rows = await (options.query ?? cliQuery(session))(sql);
+    if (Array.isArray(rows) && rows.every((row) => typeof row?.signature === 'string')) return rows;
+  } catch { /* the cause may hold a connection detail: it is withheld */ }
+  throw failure('DB_PREFLIGHT_UNREADABLE', 'the read-only function preflight could not query the database; nothing applied');
+}
+
+/** The pg_proc preflight: refuses when a function of the declared families is not dropped by the held-back migration(s). */
+async function functionPreflight(session, options) {
+  const { model, decl } = session;
+  const settings = settingsOf(decl.postCutover);
+  if (settings.prefixes.length + settings.names.length === 0) return { count: 0, line: 'function preflight: no function family declared; nothing to check' };
+  const dropped = model.held.flatMap((file) => dropSignatures(fs.readFileSync(path.join(model.root, decl.migrationsDir, file), 'utf8'), settings.schema));
+  const allowed = new Set([...dropped, ...settings.extra.map((item) => normalizeSignature(item, settings.schema))]);
+  const rows = await queryRows(session, preflightSql(settings), options);
+  const uncovered = rows.map((row) => normalizeSignature(row.signature, settings.schema)).filter((item) => !allowed.has(item));
+  if (uncovered.length > 0) throw refusal('DB_PREFLIGHT_UNCOVERED', `function signatures not covered by the held-back migration:\n${uncovered.join('\n')}`);
+  return { count: rows.length, line: `read-only function preflight: ${rows.length} signature(s), all covered by the held-back migration` };
+}
+
+/** The time gate: { open, line }. Dry run only reports it; --execute refuses while it is closed. */
+function timeGate(ctx, post, options) {
+  if (options.ownerConfirms === true) return { open: true, line: 'gate: the owner confirms the old app is gone: OPEN' };
+  if (options.greenAt === undefined) return { open: false, line: 'gate: CLOSED (needs --green-at <ISO> old enough, or --owner-confirms-old-app-gone)' };
+  const at = Date.parse(options.greenAt);
+  if (Number.isNaN(at)) throw refusal('DB_USAGE', '--green-at must be an ISO time');
+  const hours = (ctx.now() - at) / MS_PER_HOUR;
+  const need = post.minAgeHours ?? DEFAULT_MIN_AGE_HOURS;
+  return { open: hours >= need, line: `gate: last green ${options.greenAt} (${hours.toFixed(1)} h ago, ${need} h needed): ${hours >= need ? 'OPEN' : 'CLOSED'}` };
+}
+
+function applyHeld(session, remote) {
+  const { model, ctx } = 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;
+}
+
+/**
+ * `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.
+ */
+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 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 } };
+  const gate = timeGate(ctx, decl.postCutover, options);
+  const preflight = await functionPreflight(session, options);
+  const lines = [`held-back migrations: ${model.held.join(', ')}`, preflight.line, gate.line, 'WARNING: after this step a rollback to the old app needs a database restore.'];
+  if (options.execute !== true) return { ok: true, lines: [...lines, 'dry run: only read-only calls were made; nothing applied.'], data: { ...data, gateOpen: gate.open, signatures: preflight.count } };
+  if (!gate.open) throw refusal('DB_POSTCUTOVER_GATE_CLOSED', 'the time gate is closed; nothing applied');
+  requireArmed(ctx);
+  const pending = applyHeld(session, remote);
+  if (!model.heldVersions.every((version) => listRemote(session).has(version))) throw failure('DB_HELD_MISSING', 'a held-back migration is still missing from the remote history');
+  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'] };
+
+/** Entry of the verb: `starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--linked | --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,
+    }),
+  });
+}

package/emit/contracts.mjs

@@ -41,7 +41,7 @@ const OPERATIONS_WORKER = path.join(path.dirname(fileURLToPath(import.meta.url))
 export const appModulePath = (app) => `apps/${app}/src/app.module.ts`;
 
 /** The repository-relative path of an app's snapshot. */
-export const snapshotPath = (app) => `contracts/${app}/schema.graphql`;
+const snapshotPath = (app) => `contracts/${app}/schema.graphql`;
 
 /** The `paths` aliases of a tsconfig as [{ prefix, targets }], `@modules/*` giving prefix `@modules/`. Pure. */
 export function aliasesOf(paths, baseDir) {
@@ -57,7 +57,7 @@ export function aliasTarget(aliases, specifier) {
 }
 
 /** The api apps of a declaration that can serve GraphQL: kind `api`. Pure. */
-export const apiApps = (declaration) => (declaration.apps ?? []).filter((app) => app.kind === 'api').map((app) => app.name);
+const apiApps = (declaration) => (declaration.apps ?? []).filter((app) => app.kind === 'api').map((app) => app.name);
 
 /** The text written to a snapshot file: the printed schema and one final newline. Pure. */
 export const snapshotText = (printed) => `${printed.replace(/\n+$/, '')}\n`;

package/emit/db-types.mjs

@@ -22,13 +22,13 @@ export const dbTypesPath = 'supabase/types/database.types.ts';
 
 /** The folder of the app's migrations, and the first line of the committed types: the digest of the migrations they were generated from. */
 const MIGRATIONS_DIR = 'supabase/migrations';
-export const TYPES_STAMP = '// migrations-sha256: ';
+const TYPES_STAMP = '// migrations-sha256: ';
 
 /**
  * The sha256 of the app's migrations, hex: every `supabase/migrations/*.sql` by name, each as name, NUL, its text with LF line ends,
  * NUL. The offline codegen hook of a lite app (templates/app/codegen-lite) computes the same digest and refuses types stamped with another.
  */
-export function migrationsDigest(root) {
+function migrationsDigest(root) {
   const dir = path.join(root, MIGRATIONS_DIR);
   const hash = createHash('sha256');
   for (const name of (fs.existsSync(dir) ? fs.readdirSync(dir) : []).filter((file) => file.endsWith('.sql')).sort()) {
@@ -74,6 +74,15 @@ const withNpxFallback = (run, platform) => (file, args, options = {}) => {
 /** The first meaningful line of a failure output, for the error a human acts on. */
 const firstLine = (text) => String(text ?? '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean)[0];
 
+const START_TAIL_LINES = 12;
+const START_LINE_CHARS = 300;
+/** The last lines (bounded) of a failed `supabase start`: its cause (42501 permission denied to alter role) sits after the first progress lines, so the first line alone hid it. */
+const startDetail = (started) => {
+  const text = [started?.stderr, started?.stdout, started?.error?.message ?? started?.error].map((part) => String(part ?? '')).find((part) => part.trim()) ?? '';
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => (line.length > START_LINE_CHARS ? `${line.slice(0, START_LINE_CHARS)}...` : line));
+  return lines.length ? lines.slice(-START_TAIL_LINES).join(' | ') : 'no output';
+};
+
 /**
  * The schemas `supabase/config.toml` exposes under [api] (`[]` when the file or the list is absent - the CLI then reads its
  * own defaults). A config that does not parse is a refusal: L08 reads the same file and the emit must not guess.
@@ -127,7 +136,7 @@ export function generateDbTypes({ root, run = spawn, platform = process.platform
   const started = execute(SUPABASE_CLI, ['start', '-x', 'studio,mailpit,logflare,vector,edge-runtime,imgproxy,supavisor'], { cwd: root });
   const already = /already (?:running|started)/i.test(`${started?.stderr ?? ''}${started?.stdout ?? ''}`);
   if (started?.error || (started?.status !== 0 && !already)) {
-    throw new DbTypesError(`\`${SUPABASE_CLI} start\` failed${started?.status != null ? ` (exit ${started.status})` : ''}: ${firstLine(started?.stderr) ?? firstLine(started?.error?.message ?? started?.error) ?? 'no output'}; Docker must be running`, { file: dbTypesPath });
+    throw new DbTypesError(`\`${SUPABASE_CLI} start\` failed${started?.status != null ? ` (exit ${started.status})` : ''}: ${startDetail(started)} (the last ${START_TAIL_LINES} output lines at most; with no cause among them, Docker must be running)`, { file: dbTypesPath });
   }
   try {
     return emitDbTypesWithRunner({ root, run: execute });

package/lint/run.mjs

@@ -63,8 +63,8 @@ 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). */
-export const BOUND_ENV = 'STARCI_LINT_BOUND';
-export const linterBoundArgs = () => ['--require', fileURLToPath(new URL('./bound-sys.cjs', import.meta.url))];
+const BOUND_ENV = 'STARCI_LINT_BOUND';
+const linterBoundArgs = () => ['--require', fileURLToPath(new URL('./bound-sys.cjs', import.meta.url))];
 
 /** 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) {
@@ -94,7 +94,7 @@ async function runLinter({ cwd, pkg, bin, args, bound = null }) {
   // 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;
-  try { results = JSON.parse(run.stdout.trim() || run.stderr); } catch { return { error: `${pkg} produced no json report in ${path.basename(cwd)}/ (exit ${run.status}): ${String(run.stderr || run.stdout).trim().split('\n')[0]}` }; }
+  try { results = JSON.parse(run.stdout.trim() || run.stderr); } catch { return { error: `${pkg} produced no json report in ${path.basename(cwd)}/ (exit ${run.status}): ${String(run.stderr || run.stdout).trim().split('\n').slice(0, 8).join(' | ')}` }; }
   if (!Array.isArray(results)) return { error: `${pkg} produced a report that is not a result list` };
   const completed = !run.error && !run.signal && [0, 1].includes(run.status)
     && (run.status === 0 || results.some((result) => result?.messages?.length || result?.warnings?.length));