@starci/hfs 4.3.0 → 4.4.0

package/runtime/scripts/hfs/rules/database-access.mjs

@@ -0,0 +1,343 @@
+// R254-R256 inspect the final database access state, so later revokes and policy drops retire old browser doors.
+import { found } from './read.mjs';
+import { parseSql } from '../sql/pg-parse.mjs';
+import { eachInOrder } from '../../lib/in-order.mjs';
+
+export const DB_BE_ONLY_ACCESS = 'DB_BE_ONLY_ACCESS';
+export const DB_REALTIME_UNLISTED = 'DB_REALTIME_UNLISTED';
+export const DB_APP_ROLE = 'DB_APP_ROLE';
+export const DB_FORCE_RLS_DEFAULT = 'DB_FORCE_RLS_DEFAULT';
+export const DB_POLICY_TAUTOLOGY = 'DB_POLICY_TAUTOLOGY';
+export const DB_VIEW_UNSAFE = 'DB_VIEW_UNSAFE';
+export const DB_STORAGE_PREFIX = 'DB_STORAGE_PREFIX';
+
+const sval = (value) => value?.String?.sval;
+const names = (values) => (values ?? []).map(sval).filter(Boolean).join('.');
+const qualify = (name) => name.includes('.') ? name : `public.${name}`;
+const relationName = (relation, schema = 'public') => `${relation.schemaname ?? schema}.${relation.relname}`;
+const roleName = (role) => role?.rolename ?? (role?.roletype === 'ROLESPEC_PUBLIC' ? 'public' : null);
+const unwrap = (node) => node?.TypeCast ? unwrap(node.TypeCast.arg) : node;
+const stringValue = (node) => unwrap(node)?.A_Const?.sval?.sval;
+const operator = (node) => names(node.name);
+const publicRead = (policy) => policy.cmd === 'select' && policy.name.endsWith('_public_read');
+const anonymous = (role) => role === 'anon' || role === 'public';
+const browserRole = (role) => anonymous(role) || role === 'authenticated';
+const AND = ['AND', 'EXPR'].join('_');
+const OR = ['OR', 'EXPR'].join('_');
+const NOT = ['NOT', 'EXPR'].join('_');
+const SEQUENCE = ['OBJECT', 'SEQUENCE'].join('_');
+const MATVIEW = ['OBJECT', 'MATVIEW'].join('_');
+const note = (code, source, message, extra = {}) => found(code, source.file, `${source.file}:${source.line} ${message}`, { line: source.line, ...extra });
+
+function someNode(node, predicate) {
+  if (!node || typeof node !== 'object') return false;
+  if (predicate(node)) return true;
+  return Object.values(node).some((child) => someNode(child, predicate));
+}
+
+function structural(node) {
+  if (Array.isArray(node)) return node.map(structural);
+  if (!node || typeof node !== 'object') return node;
+  return Object.fromEntries(Object.entries(node).filter(([key]) => key !== 'location').map(([key, value]) => [key, structural(value)]));
+}
+
+function principalCall(call, helpers) {
+  const name = names(call.funcname);
+  if (['auth.uid', 'auth.jwt'].includes(name) || helpers.has(name)) return true;
+  return ['current_setting', 'pg_catalog.current_setting'].includes(name)
+    && ['request.jwt.claims', 'request.jwt.claim.sub'].includes(stringValue(call.args?.[0]));
+}
+
+const hasPrincipal = (node, helpers) => someNode(node, (item) => Boolean(item.FuncCall && principalCall(item.FuncCall, helpers)));
+const literalFalse = (node) => unwrap(node)?.A_Const?.boolval?.boolval === false;
+
+function principalPredicate(expression, helpers) {
+  const node = unwrap(expression);
+  if (!node) return false;
+  if (literalFalse(node)) return true;
+  if (node.NullTest || node.BooleanTest) return false;
+  const bool = node.BoolExpr;
+  if (bool?.boolop === AND) return bool.args.some((arg) => principalPredicate(arg, helpers));
+  if (bool?.boolop === OR) return bool.args.every((arg) => principalPredicate(arg, helpers));
+  if (bool?.boolop === NOT) return false;
+  const expr = node.A_Expr;
+  if (expr && JSON.stringify(structural(expr.lexpr)) === JSON.stringify(structural(expr.rexpr))) return false;
+  return hasPrincipal(node, helpers);
+}
+
+async function principalHelpers(analyses) {
+  const functions = analyses.flatMap(({ facts }) => facts.functions);
+  const bodies = [];
+  await eachInOrder(functions, async (fn) => {
+    const body = (fn.node.options ?? []).find((option) => option.DefElem?.defname === 'as')?.DefElem?.arg?.List?.items?.[0]?.String?.sval;
+    if (!body) return;
+    try { bodies.push({ name: fn.name, ast: await parseSql(body) }); } catch { /* PL/pgSQL safety is checked separately. */ }
+  });
+  const helpers = new Set();
+  for (let pass = 0; pass < bodies.length; pass += 1) {
+    for (const body of bodies) if (hasPrincipal(body.ast, helpers)) helpers.add(body.name);
+  }
+  return helpers;
+}
+
+function applyPolicies(policies, events, file) {
+  for (const event of events) {
+    const item = event.kind === 'create' ? event.policy : event;
+    const key = `${item.schema}.${item.table}/${item.name}`;
+    if (event.kind === 'drop') policies.delete(key);
+    else if (event.kind === 'create') policies.set(key, { ...item, file });
+    else policies.set(key, { ...policies.get(key), ...item, file, cmd: policies.get(key)?.cmd ?? 'all' });
+  }
+}
+
+function grantTargets(grant) {
+  if (!['OBJECT_TABLE', SEQUENCE].includes(grant.objtype)) return [];
+  if (grant.targtype === 'ACL_TARGET_ALL_IN_SCHEMA') return grant.objects.map((object) => `${sval(object)}.*`);
+  return grant.objects.filter((object) => object.RangeVar).map((object) => relationName(object.RangeVar, grant.defaultSchema));
+}
+
+function applyGrant(grants, grant, file) {
+  for (const target of grantTargets(grant)) {
+    for (const role of grant.grantees) {
+      const key = `${target}/${role}`;
+      const state = grants.get(key) ?? { target, role, privileges: new Set(), revokedRead: false, objtype: grant.objtype };
+      const privileges = grant.all || !grant.privileges.length ? ['all'] : grant.privileges;
+      updatePrivileges(state, grant.grant, privileges);
+      grants.set(key, { ...state, file, line: grant.line });
+    }
+  }
+}
+
+function updatePrivileges(state, granting, privileges) {
+  if (granting) {
+    for (const privilege of privileges) state.privileges.add(privilege);
+    if (privileges.some((privilege) => ['select', 'all'].includes(privilege))) state.revokedRead = false;
+    return;
+  }
+  if (privileges.includes('all')) state.privileges.clear();
+  else for (const privilege of privileges) state.privileges.delete(privilege);
+  if (privileges.some((privilege) => ['select', 'all'].includes(privilege))) state.revokedRead = true;
+}
+
+function grantAccessFindings(grants, policies, exposed, directAccess) {
+  const findings = [];
+  for (const state of grants.values()) {
+    if (!state.privileges.size || !browserRole(state.role)) continue;
+    if (!exposed.has(state.target.split('.')[0]) || directAccess.has(state.target)) continue;
+    const readOnly = state.privileges.size === 1 && state.privileges.has('select');
+    const policy = policies.some((item) => `${item.schema}.${item.table}` === state.target && publicRead(item)
+      && item.roles.some((role) => role === state.role || role === 'public'));
+    if (anonymous(state.role) && state.objtype === 'OBJECT_TABLE' && readOnly && policy) continue;
+    findings.push(note(DB_BE_ONLY_ACCESS, state, `grants ${state.role} data privileges on ${state.target}; browser data access requires supabase.directAccess, or anonymous SELECT beside *_public_read`, { table: state.target }));
+  }
+  return findings;
+}
+
+function defaultAccessFindings(analyses, exposed) {
+  const findings = [];
+  for (const { file, facts } of analyses) {
+    for (const defaults of facts.defaultPrivileges) {
+      if (!defaults.grant || !['OBJECT_TABLE', SEQUENCE].includes(defaults.objtype)) continue;
+      if (defaults.schemas?.length && !defaults.schemas.some((schema) => exposed.has(schema))) continue;
+      if (defaults.grantees.some(browserRole)) findings.push(note(DB_BE_ONLY_ACCESS, { ...defaults, file }, 'grants default browser data privileges; exposed data grants must be explicit per table'));
+    }
+  }
+  return findings;
+}
+
+function policyFindings(policies, exposed, directAccess, appRole, helpers) {
+  const findings = [];
+  for (const policy of policies) {
+    const table = `${policy.schema}.${policy.table}`;
+    const listed = directAccess.has(table);
+    if (exposed.has(policy.schema) && !listed && policy.roles.some((role) => browserRole(role) && !(anonymous(role) && publicRead(policy)))) {
+      findings.push(note(DB_BE_ONLY_ACCESS, policy, `policy ${policy.name} opens ${table} to browser roles; list intentional access in supabase.directAccess`, { table, policy: policy.name }));
+    }
+    if (policy.roles.every((role) => role === appRole) || publicRead(policy)) continue;
+    const predicates = [policy.qual, policy.withCheck].filter((expression) => expression !== undefined);
+    if (!predicates.length || predicates.some((expression) => !principalPredicate(expression, helpers))) {
+      findings.push(note(DB_POLICY_TAUTOLOGY, policy, `policy ${policy.name} must constrain a principal; constants, IS NOT NULL and self comparisons grant no ownership boundary`, { table, policy: policy.name }));
+    }
+  }
+  return findings;
+}
+
+function roleFindings(analyses, appRole) {
+  const findings = [];
+  for (const { file, facts } of analyses) {
+    for (const statement of facts.statements) findings.push(...roleStatementFindings({ ...statement, file }, appRole));
+    for (const grant of facts.grants) {
+      if (grant.grant && grant.grantees.includes(appRole) && (grant.all || !grant.privileges.length)) {
+        findings.push(note(DB_APP_ROLE, { ...grant, file }, `${appRole} receives ALL privileges; grant the capabilities it uses explicitly`));
+      }
+    }
+  }
+  return findings;
+}
+
+function roleStatementFindings(statement, appRole) {
+  const { type, node } = statement;
+  if (!['CreateRoleStmt', 'AlterRoleStmt'].includes(type)) return [];
+  const role = type === 'CreateRoleStmt' ? node.role : roleName(node.role);
+  if (role !== appRole) return [];
+  const options = new Map((node.options ?? []).map(({ DefElem: option }) => [option.defname, option.arg?.Boolean?.boolval]));
+  const unsafe = ['superuser', 'bypassrls', 'createdb', 'createrole', 'replication', 'inherit'].some((option) => options.get(option) === true);
+  const creationInvalid = type === 'CreateRoleStmt' && (options.get('canlogin') !== true || options.get('inherit') !== false);
+  if (!unsafe && !creationInvalid) return [];
+  return [note(DB_APP_ROLE, statement, `${appRole} must LOGIN NOINHERIT without SUPERUSER, BYPASSRLS or administrative role attributes`)];
+}
+
+function publicationTargets(node, defaultSchema) {
+  if (node.for_all_tables) return ['*'];
+  return (node.pubobjects ?? []).map(({ PublicationObjSpec: spec }) => {
+    if (spec.pubtable?.relation) return relationName(spec.pubtable.relation, defaultSchema);
+    return `${spec.name ?? defaultSchema}.*`;
+  });
+}
+
+function publicationFindings(analyses, directAccess) {
+  const tables = new Map();
+  for (const { file, facts } of analyses) {
+    for (const statement of facts.statements) {
+      applyPublication(tables, { ...statement, file });
+    }
+  }
+  return [...tables].filter(([table]) => !directAccess.has(table)).map(([table, source]) => note(DB_REALTIME_UNLISTED, source, `supabase_realtime publishes unlisted ${table}; every browser data table must be in supabase.directAccess`, { table }));
+}
+
+function applyPublication(tables, statement) {
+  const { type, node, defaultSchema } = statement;
+  if (!['CreatePublicationStmt', 'AlterPublicationStmt'].includes(type) || node.pubname !== 'supabase_realtime') return;
+  if (type === 'CreatePublicationStmt' || node.action === 'AP_SetObjects') tables.clear();
+  for (const table of publicationTargets(node, defaultSchema)) {
+    if (node.action === 'AP_DropObjects') tables.delete(table);
+    else tables.set(table, statement);
+  }
+}
+
+function tableStates(analyses) {
+  const tables = new Map();
+  let owner = null;
+  for (const { file, facts } of analyses) {
+    owner = null;
+    for (const statement of facts.statements) {
+      const { type, node, defaultSchema } = statement;
+      if (type === 'VariableSetStmt' && ['role', 'session_authorization'].includes(node.name)) owner = stringValue(node.args?.[0]) ?? null;
+      const relation = type === 'CreateTableAsStmt' ? node.into?.rel : node.relation;
+      if (['CreateStmt', 'CreateTableAsStmt'].includes(type) && relation && node.objtype !== MATVIEW && relation.relpersistence !== 't') {
+        tables.set(relationName(relation, defaultSchema), { owner, forced: false, ...statement, file });
+      }
+      applyTableAlter(tables, { ...statement, file });
+    }
+  }
+  return tables;
+}
+
+function applyTableAlter(tables, statement) {
+  const { type, node, defaultSchema } = statement;
+  if (!node.relation) return;
+  const key = relationName(node.relation, defaultSchema);
+  const table = tables.get(key) ?? { forced: false };
+  if (type === 'AlterObjectSchemaStmt' && node.objectType === 'OBJECT_TABLE') {
+    tables.delete(key);
+    tables.set(`${node.newschema}.${node.relation.relname}`, { ...table, ...statement });
+  }
+  if (type !== 'AlterTableStmt' || node.objtype !== 'OBJECT_TABLE') return;
+  for (const { AlterTableCmd: cmd } of node.cmds ?? []) {
+    if (cmd.subtype === 'AT_ChangeOwner') Object.assign(table, statement, { owner: roleName(cmd.newowner) });
+    if (cmd.subtype === 'AT_ForceRowSecurity') table.forced = true;
+    if (cmd.subtype === 'AT_NoForceRowSecurity') Object.assign(table, statement, { forced: false });
+  }
+  tables.set(key, table);
+}
+
+function forceFindings(analyses, supabase, appRole) {
+  const exemptions = new Set((supabase.forceRlsExemptions ?? []).filter((item) => typeof item?.table === 'string' && typeof item.reason === 'string' && item.reason.trim()).map((item) => qualify(item.table)));
+  return [...tableStates(analyses)].filter(([name, table]) => table.owner === appRole && !table.forced && !exemptions.has(name))
+    .map(([table, source]) => note(DB_FORCE_RLS_DEFAULT, source, `${appRole} owns ${table} without FORCE ROW LEVEL SECURITY; an exemption needs supabase.forceRlsExemptions with a table and reason`, { table }));
+}
+
+function viewFindings(analyses, grants, exposed) {
+  const views = new Map();
+  for (const { file, facts } of analyses) for (const view of facts.views) views.set(`${view.schema}.${view.name}`, { ...view, file });
+  const findings = [];
+  for (const [table, view] of views) {
+    if (!exposed.has(view.schema) || view.securityInvoker) continue;
+    if (['anon', 'authenticated'].every((role) => grants.get(`${table}/${role}`)?.revokedRead)) continue;
+    findings.push(note(DB_VIEW_UNSAFE, view, `exposed ${view.kind} ${table} needs security_invoker = true (ordinary views), or SELECT revoked from anon and authenticated`, { table }));
+  }
+  return findings;
+}
+
+function folderPrefix(node) {
+  const value = unwrap(node);
+  const subscript = value?.A_Indirection;
+  const call = subscript?.arg?.FuncCall;
+  return names(call?.funcname) === 'storage.foldername'
+    && names(unwrap(call?.args?.[0])?.ColumnRef?.fields) === 'name'
+    && subscript.indirection?.[0]?.A_Indices?.uidx?.A_Const?.ival?.ival === 1;
+}
+
+function ownershipExpression(expression, helpers) {
+  const node = unwrap(expression);
+  if (!node) return false;
+  const op = node.A_Expr;
+  if (!op || operator(op) !== '=') return false;
+  return (folderPrefix(op.lexpr) && hasPrincipal(op.rexpr, helpers)) || (folderPrefix(op.rexpr) && hasPrincipal(op.lexpr, helpers));
+}
+
+function publicBucketExpression(expression) {
+  const node = unwrap(expression);
+  if (!node) return false;
+  const op = node.A_Expr;
+  if (!op || operator(op) !== '=') return false;
+  const leftColumn = names(unwrap(op.lexpr)?.ColumnRef?.fields);
+  const rightColumn = names(unwrap(op.rexpr)?.ColumnRef?.fields);
+  return (leftColumn === 'bucket_id' && stringValue(op.rexpr)?.endsWith('_public'))
+    || (rightColumn === 'bucket_id' && stringValue(op.lexpr)?.endsWith('_public'));
+}
+
+function storageBoundaryExpression(expression, helpers) {
+  const node = unwrap(expression);
+  if (!node) return false;
+  const bool = node.BoolExpr;
+  if (bool?.boolop === AND) return bool.args.some((arg) => storageBoundaryExpression(arg, helpers));
+  if (bool?.boolop === OR) return bool.args.every((arg) => storageBoundaryExpression(arg, helpers));
+  return publicBucketExpression(node) || ownershipExpression(node, helpers);
+}
+
+function storagePrefixFindings(policies, helpers) {
+  const findings = [];
+  for (const policy of policies) {
+    if (policy.schema !== 'storage' || policy.table !== 'objects') continue;
+    const expressions = [policy.qual, policy.withCheck].filter((expression) => expression !== undefined);
+    if (expressions.length && expressions.every((expression) => storageBoundaryExpression(expression, helpers))) continue;
+    findings.push(note(DB_STORAGE_PREFIX, policy, `storage.objects policy ${policy.name} must compare storage.foldername(name)[1] with the principal, unless scoped to an *_public bucket`, { policy: policy.name }));
+  }
+  return findings;
+}
+
+/** All new access checks run on the ordered active migrations in either edition, through checkDatabase. */
+export async function databaseAccessFindings({ analyses, exposed, supabase = {} }) {
+  const declared = supabase ?? {};
+  const appRole = declared.appRole ?? 'app_be';
+  const directAccess = new Set((declared.directAccess ?? []).filter((table) => typeof table === 'string').map(qualify));
+  const policyMap = new Map();
+  const grants = new Map();
+  for (const { file, facts } of analyses) {
+    applyPolicies(policyMap, facts.policyEvents, file);
+    for (const grant of facts.grants) applyGrant(grants, grant, file);
+  }
+  const policies = [...policyMap.values()];
+  const helpers = await principalHelpers(analyses);
+  return [
+    ...grantAccessFindings(grants, policies, exposed, directAccess),
+    ...defaultAccessFindings(analyses, exposed),
+    ...policyFindings(policies, exposed, directAccess, appRole, helpers),
+    ...publicationFindings(analyses, directAccess),
+    ...roleFindings(analyses, appRole),
+    ...forceFindings(analyses, declared, appRole),
+    ...viewFindings(analyses, grants, exposed),
+    ...storagePrefixFindings(policies, helpers),
+  ];
+}

package/runtime/scripts/hfs/rules/database-baseline.mjs

@@ -0,0 +1,142 @@
+// R257: an archive is immutable history retired by one explicit active baseline.
+import { lsTree } from '../../api/git/ls-tree.mjs';
+import { show } from '../../api/git/show.mjs';
+import { mergeBase } from '../../api/git/merge-base.mjs';
+import { withoutGitLocalEnv } from '../../lib/git.mjs';
+import { sameText } from '../../lib/same-text.mjs';
+import { found, readText } from './read.mjs';
+import { migrationStamp } from './database-migrations.mjs';
+import { DB_BASELINE_SHAPE, DB_ARCHIVE_MUTATED, MIGRATIONS_DIR, MIGRATIONS_ARCHIVE_DIR } from './database-constants.mjs';
+
+const ACTIVE = /^supabase\/migrations\/\d{14}_[^/]+\.sql$/;
+const ARCHIVED = /^supabase\/migrations\/_archive\/\d{14}_[^/]+\.sql$/;
+const stampOf = (file) => /(?:^|\/)(\d{14})_/.exec(file)?.[1] ?? null;
+
+/** Header comments only: SQL literals and later comments cannot impersonate a baseline marker. */
+export function baselineMarkers(text) {
+  const lines = String(text ?? '').replace(/^\uFEFF/, '').split(/\r?\n/);
+  const header = [];
+  for (const line of lines) {
+    if (line.trim() && !/^\s*--/.test(line)) break;
+    header.push(line);
+  }
+  return header.flatMap((line) => {
+    const marker = /^\s*--\s*starci:baseline\s+(\d{14})\s*$/.exec(line);
+    return marker ? [marker[1]] : [];
+  });
+}
+
+function explicitRestamp(text, archiveBoundary, newStamp) {
+  const header = String(text ?? '').split(/\r?\n/).findIndex((line) => line.trim() && !/^\s*--/.test(line));
+  const lines = String(text ?? '').split(/\r?\n/).slice(0, header < 0 ? undefined : header);
+  return lines.some((line) => {
+    const marker = /^\s*--\s*starci:restamp\s+(\d{14})\s+(\d{14})\s*$/.exec(line);
+    return marker && migrationStamp(marker[1]) !== null && marker[1] >= archiveBoundary && marker[2] === newStamp;
+  });
+}
+
+/** Synchronous git seam: (args, {cwd}) -> {ok, stdout}; no diff or blob containing SQL is printed. */
+function baselineGit(args, { cwd }) {
+  const [verb, ...rest] = args;
+  if (verb === 'merge-base') {
+    const sha = mergeBase(cwd, rest[0], rest[1]);
+    return { ok: sha !== null, stdout: sha ?? '' };
+  }
+  const result = (verb === 'ls-tree' ? lsTree : show)(rest, { cwd, env: withoutGitLocalEnv(process.env), maxBuffer: 64 * 1024 * 1024 });
+  return { ok: !result.error && result.status === 0, stdout: String(result.stdout ?? '') };
+}
+
+function snapshot(repoRoot, git, base) {
+  let revision = null;
+  for (const ref of base ? [base] : ['origin/main', 'main']) {
+    const result = git(['merge-base', 'HEAD', ref], { cwd: repoRoot });
+    if (result?.ok && result.stdout.trim()) { revision = result.stdout.trim(); break; }
+  }
+  // An unconfigured repository still has a committed archive that must remain immutable.
+  revision ??= 'HEAD';
+  const result = git(['ls-tree', '-r', '--name-only', '-z', revision, '--', MIGRATIONS_DIR], { cwd: repoRoot });
+  return result?.ok ? { revision, files: result.stdout.split('\0').filter(Boolean) } : null;
+}
+
+const oldText = (repoRoot, git, revision, file) => {
+  const result = git(['show', `${revision}:./${file}`], { cwd: repoRoot });
+  return result?.ok ? String(result.stdout) : null;
+};
+
+function shapeFindings(repoRoot, active, archived) {
+  const marked = active.flatMap((file) => baselineMarkers(readText(repoRoot, file)).map((stamp) => ({ file, stamp })));
+  if (!archived.length) return { findings: [], marked };
+  const findings = [];
+  if (marked.length !== 1) {
+    findings.push(found(DB_BASELINE_SHAPE, MIGRATIONS_DIR, 'a nonempty _archive requires exactly one active -- starci:baseline <archived-last-stamp> header marker'));
+    return { findings, marked };
+  }
+  const latest = archived.map(stampOf).filter((stamp) => stamp && migrationStamp(stamp) !== null).sort((left, right) => left.localeCompare(right)).at(-1);
+  const marker = marked[0];
+  const current = stampOf(marker.file);
+  if (!latest || marker.stamp !== latest || migrationStamp(marker.stamp) === null) {
+    findings.push(found(DB_BASELINE_SHAPE, marker.file, 'the baseline header must identify the last valid archived migration stamp'));
+  }
+  if (!current || migrationStamp(current) === null || (latest && current <= latest && !explicitRestamp(readText(repoRoot, marker.file), latest, current))) {
+    findings.push(found(DB_BASELINE_SHAPE, marker.file, 'the baseline stamp must follow the archive boundary, or document the exact boundary and replacement in a -- starci:restamp <old> <new> header'));
+  }
+  for (const file of archived) {
+    // Archived files are immutable history and never applied: only the name shape is checked, not stamp validity.
+    if (!ARCHIVED.test(file)) findings.push(found(DB_BASELINE_SHAPE, file, 'archived migrations retain their original timestamped SQL filename'));
+  }
+  return { findings, marked };
+}
+
+function archiveFindings(repoRoot, current, archived, marked, prior, git) {
+  if (!prior) return [];
+  const findings = [];
+  const oldFiles = new Set(prior.files);
+  const newBaseline = marked.length === 1 && !oldFiles.has(marked[0].file);
+  for (const file of prior.files.filter((entry) => entry.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`))) {
+    if (!current.has(file) || !sameText(readText(repoRoot, file), oldText(repoRoot, git, prior.revision, file))) {
+      findings.push(found(DB_ARCHIVE_MUTATED, file, 'an archived migration is immutable: restore its committed path and content'));
+    }
+  }
+  for (const file of archived.filter((entry) => !oldFiles.has(entry))) {
+    const source = `${MIGRATIONS_DIR}/${file.slice(MIGRATIONS_ARCHIVE_DIR.length + 1)}`;
+    const moved = oldFiles.has(source) && !current.has(source);
+    const unchanged = moved && sameText(readText(repoRoot, file), oldText(repoRoot, git, prior.revision, source));
+    if (!newBaseline || !unchanged) {
+      findings.push(found(DB_ARCHIVE_MUTATED, file, 'a new archive entry must move an existing active migration unchanged in the same diff that adds the marked baseline'));
+    }
+  }
+  return findings;
+}
+
+/** A cutover may archive only unchanged, committed source files from the same history the finder judges. */
+export function baselineSourceFindings({ repoRoot, files = [], all = files, git = baselineGit, base }) {
+  const active = all.filter((file) => ACTIVE.test(file));
+  const archived = all.filter((file) => file.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`));
+  const prior = snapshot(repoRoot, git, base);
+  if (!prior) return [found(DB_BASELINE_SHAPE, MIGRATIONS_DIR, 'a baseline cutover requires readable committed migration history')];
+  const { findings, marked } = shapeFindings(repoRoot, active, archived);
+  const current = new Set(all);
+  findings.push(...archiveFindings(repoRoot, current, archived, marked, prior, git));
+  const oldFiles = new Set(prior.files);
+  for (const file of active) {
+    if (!oldFiles.has(file) || !sameText(readText(repoRoot, file), oldText(repoRoot, git, prior.revision, file))) {
+      findings.push(found(DB_ARCHIVE_MUTATED, file, 'baseline sources must be committed unchanged before they enter the archive'));
+    }
+  }
+  for (const file of prior.files.filter((entry) => ACTIVE.test(entry))) {
+    const retired = `${MIGRATIONS_ARCHIVE_DIR}/${file.slice(MIGRATIONS_DIR.length + 1)}`;
+    if (!current.has(file) && !current.has(retired)) findings.push(found(DB_ARCHIVE_MUTATED, file, 'restore removed migration history before creating a baseline'));
+  }
+  return findings;
+}
+
+/** R257 content finder, synchronous in both editions; all paths judge cross-file cutovers even under --fast. */
+export function databaseBaselineFindings({ repoRoot, files = [], all, repo, isRoot, inScope, base, git = baselineGit }) {
+  if (isRoot === false || (repo?.edition && !['lite', 'full'].includes(repo.edition))) return [];
+  const inventory = Array.isArray(all) ? all : files;
+  const active = inventory.filter((file) => ACTIVE.test(file));
+  const archived = inventory.filter((file) => file.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`));
+  const { findings, marked } = shapeFindings(repoRoot, active, archived);
+  findings.push(...archiveFindings(repoRoot, new Set(inventory), archived, marked, snapshot(repoRoot, git, base), git));
+  return typeof inScope === 'function' ? findings.filter((finding) => inScope(finding.path) || finding.path === MIGRATIONS_DIR || inventory.some((file) => file.startsWith(`${MIGRATIONS_DIR}/`) && inScope(file))) : findings;
+}