@starci/hfs 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.5.0 - 2026-10-17
+- Added: consumer-class CI declarations, `app ci` custody verbs and R296-R298; manifest-driven quality files and split cached CI with immutable action pins.
+- Added: release audit/local Sonar and main-CI protection; encrypted outside-repository DB dump and armed linked reset with backup/auth/storage validation.
+- Fixed: DB types refuse stale migration history.
+
+## 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({})`.

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/ci/cli.mjs

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { readCiDeclaration, sealedKeyNames } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { github, refuse } from './github.mjs';
+import { setSecret } from './secret.mjs';
+import { setVariable, syncVariables } from './vars.mjs';
+import { verifyCi } from './verify.mjs';
+
+const COMMANDS = {
+  'secret set': ['env', 'dependabot', 'repo'],
+  'var set': ['env', 'value', 'repo'],
+  'var sync': ['execute', 'repo'],
+  verify: ['json', 'repo'],
+};
+const BOOLEAN = new Set(['dependabot', 'execute', 'json']);
+
+/** Invalid options never echo argv, because an extra argument may itself contain a secret. */
+function parse(argv) {
+  const command = argv[0] === 'verify' ? 'verify' : argv.slice(0, 2).join(' ');
+  const allowed = COMMANDS[command];
+  if (!allowed) throw refuse('CI_USAGE', 'use secret set, var set, var sync or verify');
+  const positional = [], options = {};
+  for (let i = command === 'verify' ? 1 : 2; i < argv.length; i += 1) {
+    const arg = argv[i], match = /^--([^=]+)(?:=(.*))?$/s.exec(arg);
+    if (!match && !arg.startsWith('-')) { positional.push(arg); continue; }
+    const key = match?.[1];
+    if (!allowed.includes(key) || Object.hasOwn(options, key)) throw refuse(command === 'secret set' ? 'CI_VALUE_ARGV' : 'CI_USAGE', 'unsupported or repeated option');
+    if (BOOLEAN.has(key)) {
+      if (match[2] !== undefined) throw refuse('CI_USAGE', 'boolean flags take no value');
+      options[key] = true;
+    } else {
+      const value = match[2] ?? argv[++i];
+      if (value === undefined || value.startsWith('--') || (key !== 'value' && !value.length)) throw refuse('CI_USAGE', 'an option value is required');
+      options[key] = value;
+    }
+  }
+  const named = command.endsWith(' set');
+  if (positional.length !== (named ? 1 : 0)) throw refuse(command === 'secret set' && positional.length > 1 ? 'CI_VALUE_ARGV' : 'CI_USAGE', 'provide the declared name only for set');
+  if (named && (!/^[A-Z][A-Z0-9_]*$/.test(positional[0]) || positional[0].startsWith('GITHUB_'))) throw refuse('CI_NAME_UNDECLARED', 'a declared uppercase CI name is required');
+  if (options.dependabot && options.env) throw refuse('CI_SCOPE_MISMATCH', 'Dependabot secrets have repository scope');
+  return { command, options, name: positional[0] };
+}
+
+/** Manifest and sealed key reads remain offline; only github.mjs may invoke the GitHub CLI. */
+export async function ciMain(argv, { cwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), stdin, env = process.env, tools = {} } = {}) {
+  try {
+    const parsed = parse(argv);
+    let declaration, sealed;
+    try {
+      declaration = readCiDeclaration(parseYaml(fs.readFileSync(path.join(cwd, '.starcistacks/application-stacks.yaml'), 'utf8')));
+      sealed = sealedKeyNames(cwd, { fs });
+    } catch { throw refuse('CI_DECLARATION_INVALID', 'the manifest or sealed key names could not be read'); }
+    if (declaration.problems.length) throw refuse('CI_DECLARATION_INVALID', 'correct the CI declaration before using GitHub');
+    const context = { ...parsed, declaration, sealed, gh: github({ cwd, env, spawn: tools.spawn }), stdin, stdout };
+    if (parsed.command === 'secret set') return await setSecret(context);
+    if (parsed.command === 'var set') return setVariable(context);
+    if (parsed.command === 'var sync') return syncVariables(context);
+    return verifyCi(context);
+  } catch (error) {
+    stderr(`${error.code ? error.message : 'CI_USAGE: CI command could not complete'}\n`);
+    return 2;
+  }
+}

package/ci/github.mjs

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+
+/** Refusals carry only fixed public diagnostics, never child output or secret input. */
+export function refuse(code, message) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  return error;
+}
+
+/** All GitHub access uses argument arrays and captured output; secret bodies travel only on stdin. */
+export function github({ cwd, spawn = spawnSync, env = process.env }) {
+  function run(args, input) {
+    let result;
+    try { result = spawn('gh', args, { cwd, env, encoding: 'utf8', shell: false, stdio: ['pipe', 'pipe', 'pipe'], ...(input === undefined ? {} : { input }) }); }
+    catch { throw refuse('CI_GITHUB_UNREADABLE', 'GitHub CLI could not run; check installation and authentication'); }
+    if (result.error || result.status !== 0) throw refuse('CI_GITHUB_UNREADABLE', 'GitHub CLI failed; check authentication and repository access');
+    return result.stdout;
+  }
+  function json(args) {
+    try { return JSON.parse(run(args)); }
+    catch (error) {
+      if (error.code) throw error;
+      throw refuse('CI_GITHUB_UNREADABLE', 'GitHub CLI returned invalid JSON');
+    }
+  }
+  function repository(explicit) {
+    const repo = explicit ?? json(['repo', 'view', '--json', 'nameWithOwner'])?.nameWithOwner;
+    if (typeof repo !== 'string' || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw refuse('CI_GITHUB_UNREADABLE', 'a repository owner/name is required');
+    return repo;
+  }
+  return { run, json, repository };
+}
+
+/** Repository, environment and Dependabot stores are distinct even when their names coincide. */
+export function scopeArgs(options) {
+  return options.dependabot ? ['--app', 'dependabot'] : options.env ? ['--env', options.env] : [];
+}
+
+export function scopeName(options) {
+  return options.dependabot ? 'dependabot' : options.env ? `environment:${options.env}` : 'repository';
+}

package/ci/secret.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import { refuse, scopeArgs, scopeName } from './github.mjs';
+
+/** A declared name must belong to the requested store before a secret body is read. */
+export function declaredEntry(entries, name, options) {
+  const entry = entries.find((item) => item.name === name);
+  if (!entry) throw refuse('CI_NAME_UNDECLARED', 'the name is not declared for this CI class');
+  const environment = entry.scope === 'environment' ? entry.environment : undefined;
+  if (environment !== options.env || (options.dependabot && options.env)) throw refuse('CI_SCOPE_MISMATCH', 'the requested scope differs from the declaration');
+  return entry;
+}
+
+/** Secret input is read once, stripped of one trailing newline, and passed only to the child stdin. */
+export async function setSecret({ declaration, sealed, gh, options, name, stdin, stdout }) {
+  if (sealed.some((item) => item.key === name)) throw refuse('CI_SECRET_SEALED', 'the name belongs to a sealed app secret');
+  declaredEntry(options.dependabot ? declaration.dependabotSecrets : declaration.secrets, name, options);
+  let value;
+  if (stdin === undefined) {
+    if (process.stdin.isTTY) throw refuse('CI_VALUE_EMPTY', 'a secret value is required on stdin');
+    value = fs.readFileSync(0, 'utf8');
+  } else value = typeof stdin === 'function' ? await stdin() : stdin;
+  value = String(value ?? '').replace(/\r?\n$/, '');
+  if (!value.length) throw refuse('CI_VALUE_EMPTY', 'a secret value is required on stdin');
+  const repo = gh.repository(options.repo);
+  gh.run(['secret', 'set', name, ...scopeArgs(options), '--repo', repo], value);
+  stdout(`set secret ${name} (${scopeName(options)})\n`);
+  return 0;
+}

package/ci/vars.mjs

@@ -0,0 +1,33 @@
+import { refuse, scopeArgs, scopeName } from './github.mjs';
+import { declaredEntry } from './secret.mjs';
+
+/** Public CI values may come from argv or the manifest, but two supplied values must agree. */
+function valueOf(entry, supplied) {
+  const declared = entry.value === undefined ? undefined : String(entry.value);
+  if (supplied !== undefined && declared !== undefined && supplied !== declared) throw refuse('CI_VAR_DRIFT', 'the supplied value differs from the manifest');
+  const value = supplied ?? declared;
+  if (value === undefined) throw refuse('CI_VALUE_EMPTY', 'a public variable value is required');
+  return value;
+}
+
+function writeVariable(gh, repo, entry, value, options, stdout) {
+  gh.run(['variable', 'set', entry.name, '--body', value, ...scopeArgs(options), '--repo', repo]);
+  stdout(`set variable ${entry.name} (${scopeName(options)})\n`);
+}
+
+export function setVariable({ declaration, gh, options, name, stdout }) {
+  const entry = declaredEntry(declaration.vars, name, options), value = valueOf(entry, options.value);
+  writeVariable(gh, gh.repository(options.repo), entry, value, options, stdout);
+  return 0;
+}
+
+/** Sync validates the whole plan first and performs no GitHub access until execution is requested. */
+export function syncVariables({ declaration, gh, options, stdout }) {
+  const plan = declaration.vars.map((entry) => ({ entry, value: valueOf(entry), options: { env: entry.scope === 'environment' ? entry.environment : undefined } }));
+  const repo = options.execute && plan.length ? gh.repository(options.repo) : undefined;
+  for (const item of plan) {
+    if (options.execute) writeVariable(gh, repo, item.entry, item.value, item.options, stdout);
+    else stdout(`would set variable ${item.entry.name} (${scopeName(item.options)})\n`);
+  }
+  return 0;
+}

package/ci/verify.mjs

@@ -0,0 +1,36 @@
+import { refuse, scopeArgs, scopeName } from './github.mjs';
+
+/** Verification reports names and scopes only; values are compared in memory and excluded from findings. */
+export function verifyCi({ declaration, sealed, gh, options, stdout }) {
+  const repo = gh.repository(options.repo), stores = [];
+  const environments = [...new Set([...declaration.secrets, ...declaration.vars].filter((item) => item.scope === 'environment').map((item) => item.environment))].sort();
+  for (const scope of [{}, ...environments.map((env) => ({ env })), { dependabot: true }]) {
+    for (const kind of scope.dependabot ? ['secret'] : ['secret', 'variable']) {
+      const rows = gh.json([kind, 'list', '--json', kind === 'secret' ? 'name' : 'name,value', ...scopeArgs(scope), '--repo', repo]);
+      if (!Array.isArray(rows) || rows.some((row) => typeof row?.name !== 'string' || (kind === 'variable' && typeof row.value !== 'string'))) throw refuse('CI_GITHUB_UNREADABLE', 'GitHub CLI returned an invalid name list');
+      stores.push({ scope, kind, rows });
+    }
+  }
+  const findings = [], sealedNames = new Set(sealed.map((item) => item.key));
+  const declarations = (store) => store.scope.dependabot ? declaration.dependabotSecrets : store.kind === 'secret' ? declaration.secrets : declaration.vars;
+  const matches = (entry, scope) => (entry.scope === 'environment' ? entry.environment : undefined) === scope.env;
+  const add = (code, name, scope) => findings.push({ code, name, scope: scopeName(scope) });
+  for (const store of stores) {
+    const entries = declarations(store), actual = new Map(store.rows.map((row) => [row.name, row]));
+    for (const entry of entries.filter((item) => matches(item, store.scope))) {
+      const row = actual.get(entry.name);
+      if (!row && !(store.kind === 'secret' && entry.optional)) add(store.kind === 'secret' ? 'CI_SECRET_MISSING' : 'CI_VAR_MISSING', entry.name, store.scope);
+      else if (row && store.kind === 'variable' && entry.value !== undefined && row.value !== String(entry.value)) add('CI_VAR_DRIFT', entry.name, store.scope);
+    }
+    for (const row of store.rows) {
+      if (store.kind === 'secret' && sealedNames.has(row.name)) add('APP_SECRET_IN_CI', row.name, store.scope);
+      if (entries.some((entry) => entry.name === row.name && matches(entry, store.scope))) continue;
+      const sameKind = store.kind === 'secret' ? [...declaration.secrets, ...declaration.dependabotSecrets] : declaration.vars;
+      add(sameKind.some((entry) => entry.name === row.name) ? 'CI_SCOPE_MISMATCH' : store.kind === 'secret' ? 'CI_SECRET_UNDECLARED' : 'CI_VAR_UNDECLARED', row.name, store.scope);
+    }
+  }
+  if (options.json) stdout(`${JSON.stringify({ ok: findings.length === 0, findings }, null, 2)}\n`);
+  else if (!findings.length) stdout('CI verification passed\n');
+  else for (const finding of findings) stdout(`${finding.code}: ${finding.name} (${finding.scope})\n`);
+  return findings.length ? 1 : 0;
+}

package/db/backup-receipt.mjs

@@ -0,0 +1,129 @@
+// backup-receipt.mjs - encrypted database backup custody, shared by dump and reset; 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';
+
+export const RECEIPT_SCHEMA = 'starci/db-backup@1';
+export function sha256(file) {
+  const hash = createHash('sha256');
+  const fd = fs.openSync(file, 'r');
+  const chunk = Buffer.alloc(1024 * 1024);
+  try {
+    let bytes;
+    while ((bytes = fs.readSync(fd, chunk, 0, chunk.length, null)) > 0) hash.update(chunk.subarray(0, bytes));
+  } finally { fs.closeSync(fd); }
+  return hash.digest('hex');
+}
+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`); }
+}
+
+/** Resolves existing ancestors before checking containment, including symlinked output directories and Git worktree marker files. */
+export function outsideRepository(root, output) {
+  let ancestor = path.resolve(output);
+  const tail = [];
+  while (!fs.existsSync(ancestor)) { tail.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor); }
+  const resolved = path.join(fs.realpathSync(ancestor), ...tail);
+  if (inside(fs.realpathSync(root), resolved)) throw refusal('DB_DUMP_INSIDE_REPO', '--out must be outside the app repository and every Git worktree');
+  for (let dir = resolved; ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.git'))) throw refusal('DB_DUMP_INSIDE_REPO', '--out must be outside every Git worktree');
+    if (dir === path.dirname(dir)) break;
+  }
+  return resolved;
+}
+
+/** Uses migrate's linked/password/URL resolution; local is explicitly selected and never silently defaults to linked. */
+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 project = path.basename(ctx.cwd).replace(/[^A-Za-z0-9_-]/gu, '-') || 'database';
+  return { ctx, target, database, 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. */
+export function queryRows(session, sql) {
+  let rows;
+  try { rows = JSON.parse(runCli(session, ['db', 'query', sql, '--output', 'json', '--agent', 'no', ...backupArgs(session)]).stdout); }
+  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. */
+export function backupTool(ctx, command, args, options = {}) {
+  const result = ctx.spawn(command, args, { cwd: ctx.cwd, env: ctx.env, ...options });
+  if (result.error || result.status !== 0) throw failure('DB_BACKUP_TOOL_FAILED', `${command} failed; output withheld`);
+  return result;
+}
+
+/** Reads public recipients only from creation_rules age fields, including nested SOPS key_groups. */
+export function backupRecipients(root) {
+  let rules;
+  try { rules = parseYaml(fs.readFileSync(path.join(root, '.sops.yaml'), 'utf8')).creation_rules; } catch { rules = []; }
+  const found = [];
+  const visit = (value) => {
+    if (!value || typeof value !== 'object') return;
+    for (const [key, item] of Object.entries(value)) {
+      if (key === 'age') found.push(...(JSON.stringify(item).match(/age1[0-9a-z]{50,}/gu) ?? []));
+      else if (typeof item === 'object') visit(item);
+    }
+  };
+  visit(rules);
+  if (!found.length) throw refusal('DB_BACKUP_NO_RECIPIENT', 'no age recipient in .sops.yaml creation_rules');
+  return [...new Set(found)];
+}
+
+/** Header and size checks prove an age envelope exists; proving decryption requires the owner's identity separately. */
+function checkArchive(file) {
+  const size = fs.statSync(file).size;
+  const fd = fs.openSync(file, 'r');
+  const header = Buffer.alloc(22);
+  try { fs.readSync(fd, header, 0, header.length, 0); } finally { fs.closeSync(fd); }
+  if (size < 100 || !header.toString('ascii').startsWith('age-encryption.org/v1\n')) throw failure('DB_BACKUP_ARCHIVE_INVALID', 'encrypted archive has no valid age header or payload');
+  return size;
+}
+
+export function encryptFile(ctx, input, output, recipients) {
+  backupTool(ctx, 'age', [...recipients.flatMap((recipient) => ['-r', recipient]), '-o', output, input]);
+  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/dump.mjs

@@ -0,0 +1,66 @@
+// dump.mjs - full Supabase backup, 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';
+
+/** Counts every ordinary table with quoted identifiers in a read-only transaction, including auth and storage. */
+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;`);
+    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) };
+  });
+}
+
+/** Writes only ciphertext and its receipt permanently; a receipt is published only after header, size and hash checks. */
+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);
+  const recipients = backupRecipients(ctx.cwd);
+  fs.mkdirSync(out, { recursive: true, mode: 0o700 });
+  const at = new Date(ctx.now()).toISOString();
+  const stamp = at.replace(/[-:.]/gu, '');
+  const name = `${session.project}-${stamp}`;
+  const dir = path.join(out, name);
+  fs.mkdirSync(dir, { mode: 0o700 });
+  const scratch = path.join(dir, '.plaintext');
+  const archive = path.join(dir, `${name}.tar.age`);
+  const receiptPath = path.join(dir, `${name}.receipt.json`);
+  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 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 = path.join(scratch, 'backup.tar');
+    backupTool(ctx, 'tar', ['-cf', tar, '-C', 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,
+      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 });
+    complete = true;
+    return { ok: true, lines: [JSON.stringify(receipt, null, 2), `receipt: ${receiptPath}`, 'age header, size and sha256 verified; decryption requires the owner identity'], data: { receipt, receiptPath } };
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+    if (!complete) { fs.rmSync(archive, { force: true }); fs.rmSync(receiptPath, { force: true }); }
+  }
+}
+
+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'] },
+    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'] });
+    } });
+}

package/db/migrate.mjs

@@ -43,6 +43,8 @@ const POST_CHECKS = {
 };
 const postOk = (value) => plain(value) && Object.keys(value).every((key) => POST_FIELDS.includes(key) && POST_CHECKS[key](value[key]));
 
+const resetOk = (value) => plain(value) && Object.keys(value).every((key) => key === 'backupMaxAgeHours' && Number.isFinite(value[key]) && value[key] > 0);
+
 const CHECKS = {
   migrationsDir: [dirOk, 'must be a relative directory inside the app'],
   archiveDir: [dirOk, 'must be a relative directory inside the app'],
@@ -53,10 +55,11 @@ const CHECKS = {
   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`],
+  reset: [resetOk, 'must be a mapping with only optional finite positive backupMaxAgeHours'],
 };
 
 /** Judges the `database:` block. Returns { config } or { problems }; `baseline` is the one required field. */
-export function normalizeDatabase(block) {
+function normalizeDatabase(block) {
   if (!plain(block)) return { problems: ['database: must be a mapping'] };
   const problems = [];
   for (const [key, value] of Object.entries(block)) {
@@ -66,7 +69,7 @@ export function normalizeDatabase(block) {
   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,
+    migrationsDir: 'supabase/migrations', archiveDir: null, standard: null, heldBack: [], projectRef: null, restamp: [], password: null, postCutover: null, reset: null, ...block,
   };
   return { config };
 }
@@ -159,7 +162,7 @@ function tableVersions(text) {
 }
 
 /** Remote (and local) versions from `supabase migration list`: the JSON form, or the older table. */
-export const parseMigrationList = (text) => jsonVersions(text) ?? tableVersions(text);
+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]))];
@@ -245,7 +248,7 @@ export const listRemote = (session) => parseMigrationList(runCli(session, ['migr
 /* ---- the plan */
 
 /** Pure: what to do given the remote history. `done` means baseline + forward are present and nothing else is. */
-export function planMigration(model, remote) {
+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));
@@ -329,7 +332,7 @@ function applyPlan(session, plan) {
  * `starci app db migrate`. options: { execute, linked, urlEnv }. Dry run reads the remote history once and prints the plan; --execute (with
  * STARCI_DB_ARMED=1) applies it. Already baseline + forward: `nothing to do`, no mutating call, ok.
  */
-export async function migrateDatabase(ctx, decl, options = {}) {
+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);

package/db/post-cutover.mjs

@@ -19,7 +19,7 @@ const MS_PER_HOUR = 3.6e6;
 const DEFAULT_MIN_AGE_HOURS = 48;
 
 /** Makes a DROP signature comparable with pg_proc's regprocedure text. */
-export function normalizeSignature(signature, schema) {
+function normalizeSignature(signature, schema) {
   const lowered = signature.trim().toLowerCase();
   const bare = lowered.startsWith(`${schema}.`) ? lowered.slice(schema.length + 1) : lowered;
   const words = bare
@@ -36,7 +36,7 @@ function droppedSignature(statement) {
 }
 
 /** The signatures a migration drops: every `DROP FUNCTION [IF EXISTS] <signature>;` statement. */
-export function dropSignatures(sql, schema) {
+function dropSignatures(sql, schema) {
   return sql.replace(/--[^\n]*/gu, '').split(';').flatMap((statement) => {
     const signature = droppedSignature(statement.trim());
     return signature === null ? [] : [normalizeSignature(signature, schema)];
@@ -48,7 +48,7 @@ const settingsOf = (post) => ({
 });
 
 /** The read-only pg_proc query of the declared function families (identifiers are validated, so nothing free-form reaches the SQL). */
-export function preflightSql({ schema, prefixes, names }) {
+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 ')})`;
@@ -104,7 +104,7 @@ function applyHeld(session, remote) {
  * `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.
  */
-export async function postCutoverDatabase(ctx, decl, options = {}) {
+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)');