@starci/hfs 4.3.0 → 4.4.1

package/runtime/scripts/hfs/check.mjs

@@ -56,11 +56,14 @@
 // findings fail the check.
 import fs from 'node:fs';
 import path from 'node:path';
+import { appWiring, BOOT_PROOF_CODE } from './app-wiring.mjs';
+import { coverageFrom as coverageFromReport } from './coverage-from.mjs';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { ARCHITECTURE_RULE_IDS, checkArchitecture } from './architecture/index.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { readCatalogOnce } from './catalog-once.mjs';
-import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadRuleCatalog, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './slots.mjs';
+import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './slots.mjs';
+import { judgedFindings, summarize, withWhy } from './check-results.mjs';
 import { RUNTIME_KIND } from './manifest-shape.mjs';
 import { lsFiles } from '../api/git/ls-files.mjs';
 import { diff as gitDiff } from '../api/git/diff.mjs';
@@ -82,22 +85,18 @@ import { testTopologyFindings } from './rules/test-topology.mjs';
 import { feNoTestsFindings } from './rules/fe-no-tests.mjs';
 import { editionFindings } from './rules/edition.mjs';
 import { feStackFindings } from './rules/fe-stack.mjs';
+import { A15_CODES, a15Findings } from './rules/a15-findings.mjs';
+import { trackedStacksGateFindings } from './stacks-gate.mjs';
 import { byCodeUnit } from '../lib/list.mjs';
 import { pinFindings } from './pin-findings.mjs';
 import { requiredFileApplies } from './slot-required.mjs';
+import { REFUSAL_CODES } from './refusal-codes.mjs';
+export { REFUSAL_CODES } from './refusal-codes.mjs';
 // The database rules (R213-R216) read SQL through a WASM parser, so they are async: `starci app check` calls them beside the other emitters and passes the findings in as `extraFindings`.
 export { checkDatabase } from './rules/database.mjs';
 
 const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 export const FAILURE_CODES_FILE = 'modules/kernel/failure-codes.yaml';
-/**
- * The codes `starci app check` reports when it cannot judge (an unreadable repository, a refused declaration or manifest, a missing
- * formatter): infrastructure refusals, never obligations, so no rule of knowledge/hfs/rules.yaml owns them.
- */
-export const REFUSAL_CODES = Object.freeze([
-  'HFS_REPO_UNREADABLE',
-  'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID', 'HFS_FORMAT_TOOL_MISSING', 'HFS_EDITION_INVALID',
-]);
 /** The codes this module emits that are not the slot loader's own: the why bundle of packages/hfs ships exactly these plus the loader's. */
 export const CHECK_CODES = Object.freeze([
   'HFS_SLOT_UNDECLARED', 'HFS_SLOT_NOT_ENABLED', 'HFS_SLOT_AMBIGUOUS', 'HFS_TRACKED_MUST_BE_IGNORED', 'HFS_FORBIDDEN_PRESENT',
@@ -107,8 +106,11 @@ export const CHECK_CODES = Object.freeze([
   'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'BE_INTEGRATION_SPEC_MISSING', 'FE_GRAPHQL_CONTRACT', 'FE_NO_TESTS', 'HFS_MONO_WORKSPACES', 'HFS_MONO_FE_WORKSPACE', 'HFS_MONO_NEST_PROJECTS', 'HFS_MONO_WORKSPACE_DEP', 'BE_CLI_REQUIRED', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG', 'HFS_SERVICE_PLACEMENT', 'HFS_IMAGE_UNPINNED', 'HFS_SERVICE_STACK_DECLARATION', 'HFS_EVENT_CONTRACT', 'BE_ASYNC_SPEC_MISSING', 'BE_SAGA_STEP_COMPENSATION', 'BE_SAGA_STATE_VERSIONED', 'BE_SAGA_EVENT_CONTRACT', 'BE_SAGA_CONSUMER_DEDUPE', 'BE_EVENT_CLASS_CONTRACT', 'BE_PATTERN_SPEC_MISSING', 'BE_CONTRACT_BREAKING', 'BE_KIND_DECLARATION', 'BE_KIND_EMPTY', 'HFS_DOCKER_BUILD_CONTEXT', 'HFS_DOCKER_STAGES', 'HFS_DOCKER_ENTRY', 'HFS_DOCKER_BASE_PIN', 'HFS_DOCKER_SECRETS', 'BE_SAGA_E2E_MISSING',
   'FE_STACK_FORBIDDEN', 'HFS_EDITION_FORBIDDEN_PRESENT', 'HFS_LITE_SECRET_CUSTODY', 'HFS_STARCIWORK_LITE_FORBIDDEN',
   'DB_MIGRATION_SHAPE', 'DB_RLS_REQUIRED', 'DB_DYNAMIC_DDL', 'DB_POLICY_SHAPE', 'DB_DEFINER_SAFE', 'DB_STORAGE_POLICY', 'DB_CONFIG_POLICY', 'DB_TYPES_DRIFT',
+  'HFS_DOCKER_HEALTHCHECK_FAKE', 'DB_BE_ONLY_ACCESS', 'DB_REALTIME_UNLISTED', 'DB_APP_ROLE', 'DB_FORCE_RLS_DEFAULT',
+  'DB_POLICY_TAUTOLOGY', 'DB_VIEW_UNSAFE', 'DB_STORAGE_PREFIX', 'DB_DEFINER_REVOKE',
   'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_COVERAGE_SCOPE_DRIFT', 'HFS_FORMAT',
   'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
+  ...A15_CODES,
   ...REFUSAL_CODES,
 ]);
 /** Every code `starci app check` can report: its own and every code the architecture machine can emit (derived from the machine's rule id lists). */
@@ -172,34 +174,6 @@ const requiredOf = (slot, instance) => (slot.requires ?? []).map((entry) => {
 
 const appOf = (p) => /^apps\/([^/]+)\//.exec(p)?.[1];
 
-function withWhy(findings, why) {
-  return findings.map((f) => ({ ...f, title: why[f.code].title, titleVi: why[f.code].titleVi, whyVi: why[f.code].whyVi, nextStepVi: why[f.code].nextStepVi }));
-}
-
-function summarize(findings) {
-  const byCode = {};
-  for (const f of findings) {
-    byCode[f.code] ??= { level: f.level, count: 0 };
-    byCode[f.code].count += 1;
-  }
-  return {
-    error: findings.filter((f) => f.level === 'error').length,
-    warning: findings.filter((f) => f.level === 'warning').length,
-    info: findings.filter((f) => f.level === 'info').length,
-    byCode,
-  };
-}
-
-/**
- * THE edition filter of findings: a finding whose code belongs, through the rule catalog, to a rule the app's edition does not
- * judge (rules.yaml `editions`) is dropped. Codes outside the catalog (refusals, machine codes without a rule) stay. This is the
- * only place the edition touches a finding; no check below it knows the edition.
- */
-function judgedFindings(findings, edition, root) {
-  const catalog = loadRuleCatalog({ root });
-  return findings.filter((finding) => catalog.judgedIn(finding.code, edition));
-}
-
 /** A side-relative path (or null) as an app-relative one. */
 const onSide = (side, p) => (p ? path.posix.normalize(`${side}/${p}`) : p);
 
@@ -229,7 +203,7 @@ function minimumInstanceFindings(resolver, required, instances) {
   return findings;
 }
 
-function contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, editionDeclaration, manifest }) {
+function contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, appSide, editionDeclaration, manifest, phase }) {
   const findings = [
     ...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }),
     ...supabaseSecretFindings({ repoRoot, files: files.filter((file) => inScope(file)), resolver, repo }),
@@ -237,10 +211,12 @@ function contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pin
     ...feStackFindings({ repoRoot, files: files.filter((file) => inScope(file)), repo, manifest }),
     ...repoLocalCheckFindings({ repoRoot, files }),
     ...lintSuppressionFindings({ repoRoot, files }),
+    ...a15Findings({ repoRoot, files, all, repo, resolver, manifest, isRoot, appSide, inScope }),
   ];
+  findings.push(...trackedStacksGateFindings({ repoRoot, files, all, repo, resolver, manifest, isRoot, inScope, existingFindings: findings }));
   if (isRoot) {
     findings.push(
-      ...appRootFindings({ repoRoot, files, all, repo, resolver, pins }),
+      ...appRootFindings({ repoRoot, files, all, repo, resolver, pins, phase }),
       ...checkAppRoot({ root: repoRoot, resolver, tree: trackedTreeView(all) }).violations.map((item) => ({ code: item.ruleId, level: 'error', path: item.path, line: item.line, column: item.column, source: 'machine', message: `${item.path}: ${item.message}` })),
     );
   } else if (repo.profile === 'be') {
@@ -269,7 +245,7 @@ function sizeSoftFindings({ repoRoot, resolver, files, inScope }) {
  * relative to it, exactly as the standalone repository root was). `files` are the scope's tracked paths; `all` (root only) every
  * tracked path of the app, for the rules that read across it (dependency skew, proof commands).
  */
-function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, scoped, manifest, editionDeclaration = true }) {
+function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, scoped, manifest, appSide = false, editionDeclaration = true, phase }) {
   const inScope = (file) => !scoped || scoped.has(file);
   // A required directory of the root (be/, fe/) is present through the files below it, which are the sides' own.
   const trackedSet = new Set(all);
@@ -283,7 +259,7 @@ function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, sco
   if (repo.kind === RUNTIME_KIND) return findings;
 
   const pins = readPins(root);
-  findings.push(...contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, editionDeclaration, manifest }));
+  findings.push(...contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, appSide, editionDeclaration, manifest, phase }));
   if (!isRoot) findings.push(...sizeSoftFindings({ repoRoot, resolver, files, inScope }));
   return findings;
 }
@@ -298,8 +274,11 @@ function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, sco
  * The root scope and each side run their own rules over their own files (hfs checks per side, the side folder as the old repository
  * root, plus the root checks); every finding path is app-relative. Returns {ok, profile, apps, manifest, tracked, findings, counts};
  * a missing or invalid hfs.json is one HFS_DECLARATION_INVALID / HFS_MANIFEST_MAJOR_MISMATCH error finding, never an exception.
+ * `phase: 'source'` is the runtime's no-install example-render pass: tracked obligations still run, while ignored generated
+ * artifact presence/freshness belongs to the default `workspace` phase after codegen. Ordinary app check/lint always use it.
  */
-export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }), surface = 'all' }) {
+export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }), surface = 'all', phase = 'workspace' }) {
+  if (!['source', 'workspace'].includes(phase)) throw new Error(`unknown HFS inspection phase ${phase}`);
   const why = readWhy(root);
   let repo;
   try {
@@ -317,18 +296,18 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only
   const keep = (list, scopeRoot) => (surface === 'check' ? list.filter((finding) => !(finding.origin === 'repo' && onLintSurface(scopeRoot, finding))) : list);
   if (repo.profile === APP_SCOPE) {
     const own = tracked.filter((file) => resolver.sideOf(file) === null);
-    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: own, all: tracked, scoped, manifest }), repoRoot));
+    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: own, all: tracked, scoped, manifest, phase }), repoRoot));
     for (const side of SIDES) {
       const prefix = `${side}/`;
       const sideRoot = path.join(repoRoot, side);
       const sideFiles = tracked.filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length));
       const sideScoped = scoped ? new Set([...scoped].filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length))) : null;
-      const sideFindings = scopeFindings({ repoRoot: sideRoot, root, repo: repo.sides[side], resolver: resolver.sides[side], files: sideFiles, scoped: sideScoped, manifest, editionDeclaration: false });
+      const sideFindings = scopeFindings({ repoRoot: sideRoot, root, repo: repo.sides[side], resolver: resolver.sides[side], files: sideFiles, scoped: sideScoped, manifest, appSide: true, editionDeclaration: false, phase });
       const message = appRelativeMessages(side, sideRoot);
       findings.push(...keep(sideFindings, sideRoot).map((finding) => ({ ...finding, side, path: onSide(side, finding.path), message: message(finding.message) })));
     }
   } else {
-    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: tracked, scoped, manifest }), repoRoot));
+    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: tracked, scoped, manifest, phase }), repoRoot));
   }
   findings.push(...extraFindings);
   const untrackedSecrets = untrackedSecretFindings({ repoRoot, files: tracked, repo });
@@ -381,7 +360,7 @@ function machineFindings(report) {
  * templates or run the formatter (packages/hfs/sync), judged with checkRepo's own. `machine` is injectable for specs. A missing
  * merge-base under `fast` is an Error, never a silent full pass. `repoRoot` may also be a side folder: that side alone is checked.
  */
-export function checkRepository({ repoRoot, root = skillRoot, fast = false, base, extraFindings = [], manifest = loadSlotManifest({ root }), machine = checkArchitecture }) {
+export function checkRepository({ repoRoot, root = skillRoot, fast = false, base, extraFindings = [], manifest = loadSlotManifest({ root }), machine = checkArchitecture, wiring = false, coverageFrom }) {
   const changed = fast ? changedSince(repoRoot, base) : null;
   const slotResult = checkRepo({ repoRoot, root, manifest, extraFindings, surface: 'check', ...(changed ? { only: changed.files, tree: false } : {}) });
   if (slotResult.profile === null) return { ...slotResult, machine: { status: 'skipped', reason: 'hfs.json is not valid' } };
@@ -400,7 +379,7 @@ export function checkRepository({ repoRoot, root = skillRoot, fast = false, base
   const findings = [...slotResult.findings, ...withWhy(judgedFindings(found, repo.edition ?? 'full', root), why)];
   const counts = summarize(findings);
   const ran = runs.filter((info) => info.status === 'ran');
-  return {
+  const result = {
     ...slotResult,
     ok: counts.error === 0,
     findings,
@@ -410,6 +389,26 @@ export function checkRepository({ repoRoot, root = skillRoot, fast = false, base
       : { status: 'skipped', reason: runs.map((info) => info.reason).join('; '), sides: runs, ...(changed ? { base: changed.base } : {}) },
     ...(changed ? { fast: { base: changed.base, changed: changed.files.length } } : {}),
   };
+  return withCheckProofs(result, { repoRoot, root, manifest, wiring, coverageFrom });
+}
+
+/** Optional CLI proofs run over the whole tracked tree, including after a dry edition override. */
+export function withCheckProofs(result, { repoRoot, root = skillRoot, manifest = loadSlotManifest({ root }), wiring = false, coverageFrom, edition } = {}) {
+  if ((!wiring && coverageFrom === undefined) || result.profile === null) return result;
+  const declared = readRepoDeclaration(manifest, repoRoot);
+  const repo = { ...declared, edition: result.editionOverride?.judged ?? edition ?? declared.edition };
+  if (repo.sides) repo.sides = Object.fromEntries(Object.entries(repo.sides).map(([side, declaration]) => [side, { ...declaration, edition: repo.edition }]));
+  const context = { repoRoot, repo, manifest, files: trackedFiles(repoRoot) };
+  const reports = {};
+  if (wiring) reports.wiring = appWiring(context);
+  if (coverageFrom !== undefined) reports.coverage = coverageFromReport({ ...context, coverageFrom });
+  const proofFindings = Object.values(reports).flatMap(report => report.findings);
+  const why = readWhy(root, [...new Set(proofFindings.map(finding => finding.code))]);
+  // The explicit whole-tree wiring proof supersedes the ordinary finder's scoped result.
+  const previous = result.findings.filter(finding => !wiring || finding.code !== BOOT_PROOF_CODE);
+  const findings = [...previous, ...withWhy(judgedFindings(proofFindings, repo.edition ?? 'full', root), why)];
+  const counts = summarize(findings);
+  return { ...result, ...reports, findings, counts, ok: counts.error === 0 };
 }
 
 /** The architecture machine over one scope (a side folder): `{ info, findings }`, finding paths app-relative. */

package/runtime/scripts/hfs/coverage-from.mjs

@@ -0,0 +1,70 @@
+// starci app check --coverage-from <lcov>: the optional, read-only coverage proof and its declared boundary (R273).
+import path from 'node:path';
+import { invocationDir } from '../lib/roots.mjs';
+import { isMain } from '../lib/is-main.mjs';
+import { gitOutputOf } from '../lib/git.mjs';
+import { lsFiles } from '../api/git/ls-files.mjs';
+import { loadSlotManifest, readRepoDeclaration } from './slots.mjs';
+import { coverageBelowReport } from './rules/coverage-below.mjs';
+
+/** Report for the coordinator's dispatcher; supply its findings as checkRepository's extraFindings. */
+export function coverageFrom({ repoRoot = invocationDir(), coverageFrom: reportPath, files, repo, manifest = loadSlotManifest(), lcov } = {}) {
+  const declaration = repo ?? readRepoDeclaration(manifest, repoRoot);
+  if (!['app', 'be'].includes(declaration.profile)) throw new Error('coverage proof requires an app root or its be side');
+  const tracked = files ?? gitOutputOf(lsFiles(['-z', '--cached', '--exclude-standard'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files').split('\0').filter(Boolean);
+  return coverageBelowReport({ repoRoot, files: tracked, repo: declaration, manifest, coverageFrom: reportPath, lcov });
+}
+
+function setValueOption(opts, flag, value) {
+  const key = flag === '--cwd' ? 'cwd' : 'coverageFrom';
+  if (value === undefined || !value || value.startsWith('--')) throw new Error(`${flag} needs a value`);
+  if (Object.hasOwn(opts, key)) throw new Error(`${flag} may be given only once`);
+  opts[key] = value;
+}
+
+function parse(argv) {
+  const opts = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const [flag, inline] = argv[index].split(/=(.*)/su);
+    if (flag === '--json' && inline === undefined) opts.json = true;
+    else if (['--coverage-from', '--cwd'].includes(flag)) {
+      const value = inline ?? argv[++index];
+      setValueOption(opts, flag, value);
+    } else throw new Error(`unknown argument ${argv[index]}`);
+  }
+  if (!opts.coverageFrom) throw new Error('usage: starci app check --coverage-from <lcov> [--cwd <app>] [--json]');
+  return opts;
+}
+
+/** Human-readable measured scope, excluded scope and every unmeasured source file; suitable for normal check output. */
+export function formatCoverageReport(report) {
+  const roles = report.scope?.roles ?? [];
+  const rolePattern = roles.length === 1 ? roles[0] : '{' + roles.join(',') + '}';
+  const lines = [
+    `coverage: ${report.ok ? 'passed' : 'refused'} (${report.measured.length} measured logic files; lines/functions/branches at 100% per file)`,
+    'statement coverage is enforced by the unit runner; lcov does not carry statement counts',
+    'measured scope:',
+    ...(report.scope?.roots ?? []).map((root) => `  ${report.prefix ?? ''}${root}**/*.${rolePattern}.ts`),
+    'unmeasured scope:',
+    ...report.unmeasuredScopes.map((entry) => `  ${entry}${entry.endsWith('/') ? '**' : ''}`),
+    'unmeasured source files:',
+    ...(report.unmeasured.length ? report.unmeasured.map((file) => `  ${file}`) : ['  (none)']),
+    ...report.findings.map((finding) => `${finding.code} ${finding.path}: ${finding.message}`),
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+/** Standalone coordinator entry point: exit 0 proof passed, 2 proof or invocation refused. */
+function coverageFromMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), run = coverageFrom } = {}) {
+  try {
+    const opts = parse(argv);
+    const report = run({ repoRoot: path.resolve(cwd, opts.cwd ?? '.'), coverageFrom: opts.coverageFrom });
+    stdout(opts.json ? `${JSON.stringify(report, null, 2)}\n` : formatCoverageReport(report));
+    return report.ok ? 0 : 2;
+  } catch (error) {
+    stderr(`starci app check --coverage-from: ${String(error.code ?? error.message).split('\n')[0]}\n`);
+    return 2;
+  }
+}
+
+if (isMain(import.meta.url)) process.exitCode = coverageFromMain(process.argv.slice(2));

package/runtime/scripts/hfs/coverage-scope.mjs

@@ -17,7 +17,7 @@ import { byCodeUnit } from '../lib/list.mjs';
 import { trimTrailingSlashes } from './trailing-slashes.mjs';
 
 /** The component that holds the shared infrastructure: the platform tier and every capability more than one service app composes. */
-export const PLATFORM_COMPONENT = 'platform';
+const PLATFORM_COMPONENT = 'platform';
 const SERVICE_APP_KINDS = new Set(['api', 'worker']);
 /** `text` with every `<placeholder>` (a `<`, at least one character, the next `>`) replaced by `*`; a `<` with no closing `>` stays. */
 export const star = (text) => {

package/runtime/scripts/hfs/db-baseline-verb.mjs

@@ -0,0 +1,276 @@
+// app db baseline: schema-only dump, explicit cutover and repair commands; preview writes nothing.
+import fs from 'node:fs';
+import path from 'node:path';
+import pg from 'libpg-query';
+import { invocationDir } from '../lib/roots.mjs';
+import { sqlStringParts as names, walkSqlAst as walk, sqlParser } from '../lib/sql-ast.mjs';
+import { databaseDump } from '../api/supabase/database-dump.mjs';
+import { databaseQuery } from '../api/supabase/database-query.mjs';
+import { migrationRepair } from '../api/supabase/migration-repair.mjs';
+import { migrationStamp, isMigrationName, databaseSqlTokens, databaseExecutableTokens } from './rules/database-migrations.mjs';
+import { baselineMarkers, baselineSourceFindings } from './rules/database-baseline.mjs';
+import { databaseQueueDeclarations } from './rules/database-queues.mjs';
+import { MIGRATIONS_DIR, MIGRATIONS_ARCHIVE_DIR } from './rules/database-constants.mjs';
+import { dbPlanMain } from './db-plan-verb.mjs';
+
+await pg.loadModule();
+
+export class DbVerbError extends Error {}
+const LINKED_PASSWORD_ENV = 'SUPABASE_DB_PASSWORD';
+const TELEMETRY_DISABLED_ENV = 'SUPABASE_TELEMETRY_DISABLED';
+const TELEMETRY_DEBUG_ENV = 'SUPABASE_TELEMETRY_DEBUG';
+const CLI_DEBUG_ENV = 'SUPABASE_DEBUG';
+
+/** Strict shared options; unknown flags never reach the database CLI. */
+export function dbOptions(argv, allowed) {
+  const opts = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const [flag, inline] = argv[index].split(/=(.*)/s);
+    const name = flag.slice(2);
+    if (!flag.startsWith('--') || !allowed.includes(name) || Object.hasOwn(opts, name)) throw new DbVerbError('unknown or duplicate database option');
+    if (['apply', 'local', 'json'].includes(name)) {
+      if (inline !== undefined && !['true', 'false'].includes(inline)) throw new DbVerbError(`${flag} expects true or false`);
+      opts[name] = inline !== 'false';
+    } else {
+      const value = inline ?? argv[++index];
+      if (!value || value.startsWith('--')) throw new DbVerbError(`${flag} requires a value`);
+      opts[name] = value;
+    }
+  }
+  return opts;
+}
+
+export function dbAppRoot(cwd, opts) {
+  const root = path.resolve(cwd, opts.cwd ?? '.');
+  let declaration;
+  try { declaration = JSON.parse(fs.readFileSync(path.join(root, 'hfs.json'), 'utf8')); } catch { throw new DbVerbError('run at an app root containing hfs.json'); }
+  if (declaration.kind !== 'app' || !['lite', 'full'].includes(declaration.edition ?? 'full')) throw new DbVerbError('database verbs require a lite or full app');
+  return root;
+}
+
+/** Immediate SQL files only, never secrets or Supabase's temporary credential files. */
+export function dbSqlFiles(root, directory = MIGRATIONS_DIR) {
+  const dir = path.join(root, directory);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith('.sql')).map((entry) => {
+    const match = /^(\d{14})_/.exec(entry.name);
+    if (!isMigrationName(entry.name) || !match || migrationStamp(match[1]) === null) throw new DbVerbError('migration filenames must carry valid UTC stamps');
+    return { file: `${directory}/${entry.name}`, name: entry.name, stamp: match[1] };
+  }).sort((left, right) => left.name < right.name ? -1 : Number(left.name > right.name));
+}
+
+/** Supabase adapter uses supabaseSpawn's (repoRoot, args, options) contract; raw failures are private. */
+const DB_CALLS = { 'db dump': databaseDump, 'db query': databaseQuery, 'migration repair': migrationRepair };
+
+function runDatabaseCommand(root, args, options) {
+  const call = DB_CALLS[args.slice(0, 2).join(' ')];
+  if (!call) throw new DbVerbError('unsupported database command');
+  return call(root, args.slice(2), options);
+}
+
+export function runDbSupabase(root, args, ports = {}) {
+  const env = ports.env ?? process.env;
+  // The linked CLI can mint a temporary remote login when no existing password is supplied.
+  // Check custody presence only; the value stays within the CLI environment.
+  if (args.includes('--linked') && !ports.runSupabase && !ports.run && (typeof env[LINKED_PASSWORD_ENV] !== 'string' || env[LINKED_PASSWORD_ENV].length === 0)) throw new DbVerbError('linked database operations require an existing SUPABASE_DB_PASSWORD in the CLI environment');
+  const cliEnv = { ...env, [TELEMETRY_DISABLED_ENV]: '1', [TELEMETRY_DEBUG_ENV]: '0', [CLI_DEBUG_ENV]: '0' };
+  const result = (ports.runSupabase ?? runDatabaseCommand)(root, args, { env: cliEnv, ...(ports.run ? { run: ports.run } : {}) });
+  if (result?.error || !(result?.ok === true || result?.status === 0)) throw new DbVerbError('Supabase command failed; inspect the CLI privately');
+  return String(result.stdout ?? '');
+}
+
+export const repairArgs = (stamp, status, local) => ['migration', 'repair', stamp, '--status', status, local ? '--local' : '--linked'];
+export const dbFailure = (verb, error, stderr) => { stderr(`starci app db ${verb}: ${error instanceof DbVerbError ? error.message : 'operation failed; database output was withheld'}\n`); return 2; };
+
+function baselinePlan(root, opts, now) {
+  const active = dbSqlFiles(root);
+  if (!active.length) throw new DbVerbError('baseline requires an existing active migration chain');
+  const archived = dbSqlFiles(root, MIGRATIONS_ARCHIVE_DIR);
+  const oldStamps = [...active, ...archived].map((entry) => entry.stamp);
+  const last = oldStamps.sort((left, right) => left.localeCompare(right)).at(-1);
+  const stamp = opts.stamp ?? now().toISOString().replace(/\D/g, '').slice(0, 14);
+  if (!/^\d{14}$/.test(stamp) || migrationStamp(stamp) === null || stamp <= last) throw new DbVerbError('--stamp must be a valid UTC version after the archive boundary');
+  const file = `${MIGRATIONS_DIR}/${stamp}_baseline.sql`;
+  if (fs.existsSync(path.join(root, file)) || active.some((entry) => fs.existsSync(path.join(root, MIGRATIONS_ARCHIVE_DIR, entry.name)))) throw new DbVerbError('baseline would overwrite an existing migration');
+  return { active, last, stamp, file };
+}
+
+const EXCLUDED_SCHEMAS = new Set(['information_schema', '_analytics', '_realtime', '_supavisor', 'auth', 'etl', 'extensions', 'pgbouncer', 'realtime', 'storage', 'supabase_functions', 'supabase_migrations', 'cron', 'dbdev', 'graphql', 'graphql_public', 'net', 'pgmq', 'pgmq_public', 'pgsodium', 'pgsodium_masks', 'pgtle', 'repack', 'tiger', 'tiger_data', 'topology', 'vault']);
+const ROLE_OPTIONS = new Set(['canlogin', 'inherit', 'superuser', 'createdb', 'createrole', 'isreplication', 'bypassrls', 'connectionlimit']);
+const identifier = (name) => `"${name.replaceAll('"', '""')}"`;
+const literal = (value) => `'${value.replaceAll("'", "''")}'`;
+const excludedSchema = (name) => EXCLUDED_SCHEMAS.has(name) || /^(?:pg_|timescaledb_|_timescaledb_)/.test(name ?? '');
+
+/** Inventory source paths only; no credential, generated or vendor tree is traversed. */
+function baselineFiles(root) {
+  const files = [];
+  const visit = (directory) => {
+    const full = path.join(root, directory);
+    if (!fs.existsSync(full)) return;
+    for (const entry of fs.readdirSync(full, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const file = `${directory}/${entry.name}`;
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile() && /\.(?:sql|[cm]?[jt]sx?)$/.test(entry.name)) files.push(file);
+    }
+  };
+  for (const directory of ['supabase', 'be/src', 'be/apps', 'src', 'apps']) visit(directory);
+  return files;
+}
+
+const parsed = sqlParser(pg, () => { throw new DbVerbError('migration SQL could not be prepared safely for a baseline'); });
+
+function statementSql(text, entry) {
+  const bytes = Buffer.from(text);
+  const start = entry.stmt_location ?? 0;
+  const statement = bytes.subarray(start, entry.stmt_len ? start + entry.stmt_len : bytes.length).toString('utf8');
+  return `${statement.slice(databaseSqlTokens(statement)[0]?.index ?? 0).trim().replace(/;\s*$/, '')};\n`;
+}
+
+function ownedSchemas(node) {
+  const schemas = [node.relation?.schemaname, node.table?.schemaname, node.schemaname, node.newschema];
+  for (const field of ['funcname', 'typeName', 'typename', 'type', 'object', 'domainname', 'collname', 'opfamilyname', 'opclassname']) {
+    const parts = names(Array.isArray(node[field]) ? node[field] : node[field]?.names ?? node[field]?.List?.items);
+    if (parts.length > 1) schemas.push(parts[0]);
+  }
+  for (const object of node.objects ?? []) {
+    const parts = names(object.List?.items ?? object.ObjectWithArgs?.objname);
+    schemas.push(object.RangeVar?.schemaname);
+    if (parts.length > 1 || /^OBJECT_SCHEMA$/.test(node.objtype ?? node.removeType ?? '')) schemas.push(parts[0]);
+  }
+  return schemas;
+}
+
+function excludedOwnership(stmt) {
+  if (ownedSchemas(stmt).some(excludedSchema)) return true;
+  let unsupported = false;
+  walk(stmt, (node) => {
+    if (node.DefElem?.defname === 'schemas' && names(node.DefElem.arg?.List?.items).some(excludedSchema)) unsupported = true;
+    if (node.FuncCall && names(node.FuncCall.funcname)[0] === 'vault') unsupported = true;
+  });
+  if (stmt.name === 'search_path') unsupported ||= (stmt.args ?? []).some((node) => excludedSchema(node.A_Const?.sval?.sval));
+  return unsupported;
+}
+
+function dataMutation(stmt) {
+  if (stmt.CreateFunctionStmt || stmt.CreateTrigStmt || stmt.CreatePolicyStmt || stmt.AlterPolicyStmt || stmt.CreateStmt || stmt.ViewStmt) return false;
+  let mutation = false;
+  walk(stmt, (node) => { if (['InsertStmt', 'UpdateStmt', 'DeleteStmt', 'MergeStmt', 'CopyStmt', 'TruncateStmt', 'IntoClause'].some((key) => node[key])) mutation = true; });
+  return mutation;
+}
+
+function unsupportedCall(call) {
+  const name = names(call.funcname).join('.');
+  const args = (call.args ?? []).map((arg) => arg.NamedArgExpr?.arg ?? arg);
+  if (name === 'pgmq.create' || name === 'pgmq.drop_queue') return args.length !== 1 || !args[0]?.A_Const?.sval;
+  if (name === 'cron.schedule' || name === 'cron.unschedule') return false;
+  if (name === 'pg_catalog.set_config') return args[0]?.A_Const?.sval?.sval !== 'search_path' || args[1]?.A_Const?.sval?.sval !== '';
+  return true;
+}
+
+function sourceExecution(stmt) {
+  if (stmt.CallStmt) return true;
+  if (!stmt.SelectStmt) return false;
+  let unsupported = false;
+  walk(stmt, (node) => { if (node.FuncCall && unsupportedCall(node.FuncCall)) unsupported = true; });
+  return unsupported;
+}
+
+function unsupportedDo(node) {
+  const body = (node.args ?? []).find((item) => item.DefElem?.defname === 'as')?.DefElem?.arg?.String?.sval ?? '';
+  const tokens = databaseExecutableTokens(body);
+  const unsupported = tokens.some((token, index) => {
+    const next = tokens[index + 1]?.v;
+    return (token.t === 'word' && ['execute', 'role', 'user', 'extension', 'insert', 'update', 'delete', 'merge', 'copy', 'truncate'].includes(token.v))
+      || (excludedSchema(token.v) && next === '.' && !['pgmq', 'cron'].includes(token.v));
+  });
+  if (unsupported) return true;
+  let tree;
+  try { tree = pg.parsePlPgSQLSync(`do ${literal(body)};`); } catch { return true; }
+  let effects = false;
+  walk(tree, (item) => {
+    if (item.PLpgSQL_expr?.parseMode !== 0) return;
+    const sql = parsed(item.PLpgSQL_expr.query);
+    if ((sql.stmts ?? []).some((entry) => dataMutation(entry.stmt) || sourceExecution(entry.stmt))) effects = true;
+  });
+  return effects;
+}
+
+function roleDeclaration(stmt, sql, roles) {
+  const create = stmt.CreateRoleStmt;
+  const alter = stmt.AlterRoleStmt;
+  const setting = stmt.AlterRoleSetStmt;
+  const declaration = create ?? alter ?? setting;
+  if (!declaration) return false;
+  const name = create?.role ?? declaration.role?.rolename;
+  if (!name || name.startsWith('pg_') || (declaration.options ?? []).some((option) => !ROLE_OPTIONS.has(option.DefElem?.defname))) throw new DbVerbError('baseline role declarations require static non-secret role attributes');
+  if (setting && setting.setstmt?.name !== 'search_path') throw new DbVerbError('baseline supports only non-secret search_path role settings');
+  if (create) roles.set(name, [sql]);
+  else {
+    if (!roles.has(name)) throw new DbVerbError('baseline cannot reconstruct alterations to a role it does not declare');
+    roles.get(name).push(sql);
+  }
+  return true;
+}
+
+function extensionDeclaration(stmt, sql, extensions) {
+  if (stmt.CreateExtensionStmt) {
+    extensions.set(stmt.CreateExtensionStmt.extname, sql.replace(/\bcreate\s+extension\s+(?!if\s+not\s+exists\b)/i, 'create extension if not exists '));
+    return true;
+  }
+  if (!/^OBJECT_EXTENSION$/.test(stmt.DropStmt?.removeType ?? '')) return false;
+  for (const object of stmt.DropStmt.objects ?? []) extensions.delete(names(object.List?.items)[0]);
+  return true;
+}
+
+function baselineStatement(state, stmt, sql) {
+  if (roleDeclaration(stmt, sql, state.roles) || extensionDeclaration(stmt, sql, state.extensions)) return;
+  if (stmt.DropRoleStmt) { for (const role of stmt.DropRoleStmt.roles ?? []) state.roles.delete(role.RoleSpec?.rolename); return; }
+  if (stmt.GrantRoleStmt || stmt.AlterExtensionStmt || stmt.AlterExtensionContentsStmt || /^OBJECT_ROLE$/.test(stmt.RenameStmt?.renameType ?? '')) throw new DbVerbError('baseline cannot reconstruct role membership, role renames or extension alterations');
+  if (dataMutation(stmt) || sourceExecution(stmt)) throw new DbVerbError('baseline cannot reconstruct migration-owned data changes or custom execution from a schema-only dump');
+  const node = Object.values(stmt)[0];
+  const queueGrant = stmt.GrantStmt && (node.objects ?? []).every((object) => object.RangeVar?.schemaname === 'pgmq');
+  if ((excludedOwnership(node) && !queueGrant) || (stmt.DoStmt && unsupportedDo(node))) throw new DbVerbError('baseline cannot reconstruct application changes to excluded managed schemas or dynamic operational declarations');
+}
+
+function baselineMetadata(root, plan, files) {
+  const queues = databaseQueueDeclarations({ repoRoot: root, files, all: files });
+  if (queues.findings.length) throw new DbVerbError('baseline requires valid migration-owned queues, grants and cron declarations');
+  const state = { roles: new Map(), extensions: new Map() };
+  for (const migration of plan.active) {
+    const text = fs.readFileSync(path.join(root, migration.file), 'utf8');
+    for (const entry of parsed(text).stmts ?? []) baselineStatement(state, entry.stmt, statementSql(text, entry));
+  }
+  return { ...queues, roles: [...state.roles.values()].flat().join(''), extensions: [...state.extensions.values()].join('') };
+}
+
+function metadataSql(metadata) {
+  const queueSql = metadata.queues.map((queue) => `select pgmq.create(${literal(queue)});\n`).join('');
+  const grants = (metadata.grants ?? []).map((grant) => `grant ${grant.privileges.join(', ')} on table ${grant.tables.map((table) => table.split('.').map(identifier).join('.')).join(', ')} to ${grant.roles.map(identifier).join(', ')}${grant.grantOption ? ' with grant option' : ''};\n`).join('');
+  const cron = metadata.cron.map((job) => `select cron.schedule(${literal(job.name)}, ${literal(job.schedule)}, ${literal(job.command)});\n`).join('');
+  return `${queueSql}${grants}${cron}`;
+}
+
+/** Numeric CLI exit code, injectable IO/clock/CLI; neither files nor history change without --apply. */
+export function dbBaselineMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), now = () => new Date(), ...ports } = {}) {
+  try {
+    const opts = dbOptions(argv, ['cwd', 'stamp', 'apply', 'local']);
+    const root = dbAppRoot(cwd, opts);
+    const plan = baselinePlan(root, opts, now);
+    const files = baselineFiles(root);
+    if (baselineSourceFindings({ repoRoot: root, files, all: files, git: ports.git }).length) throw new DbVerbError('baseline sources and archives must match committed migration history');
+    const metadata = baselineMetadata(root, plan, files);
+    if (dbPlanMain(['--json', ...(opts.local ? ['--local'] : [])], { ...ports, cwd: root, stdout: () => {}, stderr: () => {} }) !== 0) throw new DbVerbError('baseline requires a clean database plan with all local migrations already applied');
+    const schema = runDbSupabase(root, ['db', 'dump', opts.local ? '--local' : '--linked'], ports);
+    if (!schema.trim() || baselineMarkers(schema).length || /\bvault\.(?:create_secret|update_secret)\s*\(|\bpassword\s+'[^']+'/i.test(schema)) throw new DbVerbError('schema dump is empty or contains unsupported secret/baseline statements');
+    const repairs = [...plan.active.map((entry) => repairArgs(entry.stamp, 'reverted', opts.local)), repairArgs(plan.stamp, 'applied', opts.local)];
+    stdout(`${opts.apply ? 'apply' : 'preview'} baseline ${plan.file}; archive ${plan.active.length} migrations\n`);
+    for (const args of repairs) stdout(`supabase ${args.join(' ')}\n`);
+    if (!opts.apply) return 0;
+    for (const args of repairs) runDbSupabase(root, args, ports);
+    fs.mkdirSync(path.join(root, MIGRATIONS_ARCHIVE_DIR), { recursive: true });
+    fs.writeFileSync(path.join(root, plan.file), `-- starci:baseline ${plan.last}\n${metadata.extensions}${metadata.roles}${schema.replace(/^\s+/, '')}\n${metadataSql(metadata)}`, { flag: 'wx' });
+    for (const entry of plan.active) fs.renameSync(path.join(root, entry.file), path.join(root, MIGRATIONS_ARCHIVE_DIR, entry.name));
+    return 0;
+  } catch (error) { return dbFailure('baseline', error, stderr); }
+}