@starci/hfs 4.2.17 → 4.4.0

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

@@ -1,15 +1,22 @@
 // database-migrations.mjs - L02 migration name, UTC ordering and base-branch immutability checks. Git reads go
 // through the runtime API call files, and specs may inject the same small runner contract used by database.mjs.
 import { lsTree } from '../../api/git/ls-tree.mjs';
-import { log } from '../../api/git/log.mjs';
 import { mergeBase } from '../../api/git/merge-base.mjs';
 import { show } from '../../api/git/show.mjs';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
 import { eachInOrder, findInOrder } from '../../lib/in-order.mjs';
 import { sameText } from '../../lib/same-text.mjs';
 import { found, readText } from './read.mjs';
-import { DB_MIGRATION_SHAPE, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
-const MIGRATION_NAME = /^(\d{14})_([a-z0-9]+(?:-[a-z0-9]+)*)\.sql$/;
+import { DB_MIGRATION_DESTRUCTIVE, DB_MIGRATION_SHAPE, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const MIGRATION_NAME = /^(\d{14})_([a-z0-9]+(?:-[a-z0-9]+)*|contract_[a-z0-9]+(?:[-_][a-z0-9]+)*|[a-z0-9]+(?:-[a-z0-9]+)*_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*)\.sql$/;
+export const isMigrationName = (name) => MIGRATION_NAME.test(name);
+const RESTAMP_HEADER = /^-- starci:restamp (\d{14}) (\d{14})(?:\r?\n|$)/;
+const withoutRestampHeader = (text) => text?.replace(RESTAMP_HEADER, '') ?? null;
 
 /** `<ts14>` -> the UTC instant it names, or null when the digits are no real time (month 13, day 32, ...). */
 export function migrationStamp(text) {
@@ -27,7 +34,6 @@ export function defaultGit(args, { cwd }) {
   if (verb === 'merge-base') { const sha = mergeBase(cwd, rest[0], rest[1]); return { ok: sha !== null, stdout: sha ?? '' }; }
   let call = show;
   if (verb === 'ls-tree') call = lsTree;
-  else if (verb === 'log') call = log;
   const result = call(rest, { cwd, env, maxBuffer: 64 * 1024 * 1024 });
   return { ok: !result.error && result.status === 0, stdout: result.stdout };
 }
@@ -45,11 +51,11 @@ async function baseShaOf(git, repoRoot, base) {
   return found;
 }
 
-async function baseMigrationNames(git, repoRoot, sha) {
+async function migrationFilesAt(git, repoRoot, sha) {
   const result = await runGit(git, repoRoot, ['ls-tree', '-r', '--name-only', '-z', sha, '--', MIGRATIONS_DIR]);
   if (!result.ok) return [];
   const prefix = `${MIGRATIONS_DIR}/`;
-  return result.stdout.split('\0').filter(Boolean).filter(isActiveMigration).map((entry) => entry.slice(prefix.length));
+  return result.stdout.split('\0').filter((entry) => entry.startsWith(prefix));
 }
 
 async function baseFileText(git, repoRoot, sha, file) {
@@ -58,46 +64,67 @@ async function baseFileText(git, repoRoot, sha, file) {
   return result.ok ? result.stdout : null;
 }
 
-async function migrationTimeLimit(git, repoRoot, file, now) {
-  const result = await runGit(git, repoRoot, ['log', '-1', '--format=%ct', '--', file]);
-  const seconds = Number(result.stdout.trim());
-  if (result.ok && Number.isFinite(seconds) && seconds > 0) return { at: seconds * 1000, tracked: true };
-  return { at: now(), tracked: false };
-}
-
-async function localMigrationFindings(local, repoRoot, git, now) {
+function localMigrationFindings(local) {
   const findings = [];
   const stamps = new Map();
-  await eachInOrder(local, async (entry) => {
+  for (const entry of local) {
     if (!entry.match) {
       findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is not named <ts14>_<kebab>.sql; a migration is created by \`npm run db:new\` (supabase migration new), never renamed by hand`, { expected: '<ts14>_<kebab>.sql' }));
-      return;
+      continue;
     }
     const stamp = migrationStamp(entry.match[1]);
     if (stamp === null) {
-      findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} carries ${entry.match[1]}, which is no valid UTC time; the stamp is the real creation time`, { stamp: entry.match[1] }));
-      return;
-    }
-    const limit = await migrationTimeLimit(git, repoRoot, entry.file, now);
-    if (stamp > limit.at) {
-      const boundary = limit.tracked ? `the file's commit time ${new Date(limit.at).toISOString()}` : `the current time ${new Date(limit.at).toISOString()}`;
-      findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, in the future relative to ${boundary}; a migration stamp is its real creation time, never a hand-picked date`, { stamp: entry.match[1], tracked: limit.tracked }));
+      findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} carries ${entry.match[1]}, which is no valid UTC time; a migration stamp must name a valid UTC instant`, { stamp: entry.match[1] }));
+      continue;
     }
     if (stamps.has(stamp)) findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} shares stamp ${entry.match[1]} with ${stamps.get(stamp)}; stamps are strictly increasing`, { stamp: entry.match[1], other: stamps.get(stamp) }));
     stamps.set(stamp, entry.file);
-  });
+  }
   return findings;
 }
 
-async function baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase, baseMax) {
+/** HEAD owns the append boundary. Archived names retire the old chain, so a replacement baseline starts afresh. */
+function migrationHistory(files, retired, localNames) {
+  const prefix = `${MIGRATIONS_DIR}/`;
+  const onHead = new Set(files.filter(isActiveMigration).map((file) => file.slice(prefix.length)));
+  const retiredNames = new Set([...retired, ...files.filter((file) => file.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`)).map((file) => file.slice(MIGRATIONS_ARCHIVE_DIR.length + 1))].filter((name) => !localNames.has(name)));
+  const stamps = [...onHead].filter((name) => !retiredNames.has(name)).map((name) => MIGRATION_NAME.exec(name)?.[1]).filter(Boolean).map(migrationStamp).filter((stamp) => stamp !== null);
+  return { onHead, latest: stamps.length ? Math.max(...stamps) : null };
+}
+
+function migrationOrderingFindings(local, history, restamped = new Set()) {
+  return local.flatMap((entry) => {
+    const stamp = entry.match ? migrationStamp(entry.match[1]) : null;
+    if (history.onHead.has(entry.name) || restamped.has(entry.name) || stamp === null || history.latest === null || stamp > history.latest) return [];
+    return [found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, not after every migration already in repository history (latest active ${new Date(history.latest).toISOString()}); a new migration sorts after the committed active chain`, { stamp: entry.match[1], latest: new Date(history.latest).toISOString() })];
+  });
+}
+
+/** A restamp changes only the version, and its header proves the explicit old->new map against repository SQL. */
+async function verifiedRestamps(local, files, repoRoot, git, sha) {
+  const prefix = `${MIGRATIONS_DIR}/`;
+  const active = files.filter(isActiveMigration).map((file) => file.slice(prefix.length));
+  const claims = local.map((entry) => ({ ...entry, header: RESTAMP_HEADER.exec(readText(repoRoot, entry.file) ?? '') })).filter((entry) => entry.header);
+  const accepted = [];
+  await eachInOrder(claims, async (entry) => {
+    const [, oldStamp, newStamp] = entry.header;
+    if (!entry.match || entry.match[1] !== newStamp || migrationStamp(oldStamp) === null || oldStamp === newStamp) return;
+    if (claims.filter((claim) => claim.header[1] === oldStamp).length !== 1) return;
+    const names = active.filter((name) => name.startsWith(`${oldStamp}_`) && name.slice(14) === entry.name.slice(14));
+    if (names.length !== 1 || local.some((candidate) => candidate.name === names[0])) return;
+    const committed = await baseFileText(git, repoRoot, sha, `${prefix}${names[0]}`);
+    if (committed === null || !sameText(withoutRestampHeader(readText(repoRoot, entry.file)), withoutRestampHeader(committed))) return;
+    accepted.push({ source: names[0], destination: entry.name });
+  });
+  return accepted;
+}
+
+async function baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase) {
   if (!entry.match) return [];
-  const stamp = migrationStamp(entry.match[1]);
   if (onBase.has(entry.name)) {
     const committed = await baseFileText(git, repoRoot, baseSha.sha, entry.file);
     const current = readText(repoRoot, entry.file);
     if (!sameText(current, committed)) return [found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} differs from its content on ${baseSha.ref}; a migration on the base branch is immutable - write a new migration`, { base: baseSha.ref })];
-  } else if (baseMax !== null && stamp !== null && stamp <= baseMax) {
-    return [found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, not after every migration on ${baseSha.ref} (latest ${String(new Date(baseMax).toISOString())}); a new migration sorts after the base ones`, { stamp: entry.match[1], base: baseSha.ref })];
   }
   return [];
 }
@@ -112,26 +139,279 @@ function removedMigrationFindings(local, retired, baseNames, baseSha) {
 
 /**
  * L02 findings for names, stamps, ordering and immutability of supabase/migrations/*.sql. `archived` are the files of
- * supabase/migrations/_archive/ (app.supabase.migrations.archive): never judged, and a base migration moved there at a baseline
- * cutover is retired, not removed.
+ * supabase/migrations/_archive/ (app.supabase.migrations.archive): never judged, and a migration moved there at a baseline
+ * cutover is retired from the ordering chain, not removed. New files append after HEAD's active migrations; timestamps
+ * on archived migrations, remote branches and the wall clock do not constrain a replacement baseline.
  */
-export async function migrationShapeFindings({ repoRoot, migrations, archived = [], git, base, now }) {
+export async function migrationShapeFindings({ repoRoot, migrations, archived = [], git, base }) {
   const prefix = `${MIGRATIONS_DIR}/`;
   const local = migrations.map((file) => {
     const name = file.startsWith(prefix) ? file.slice(prefix.length) : file;
     return { file, name, match: MIGRATION_NAME.exec(name) };
   });
-  const findings = await localMigrationFindings(local, repoRoot, git, now);
+  const findings = localMigrationFindings(local);
+  const retired = new Set(archived.map((file) => file.slice(MIGRATIONS_ARCHIVE_DIR.length + 1)));
+  const headFiles = await migrationFilesAt(git, repoRoot, 'HEAD');
   const baseSha = await baseShaOf(git, repoRoot, base);
+  const baseFiles = baseSha ? await migrationFilesAt(git, repoRoot, baseSha.sha) : [];
+  const restamps = await verifiedRestamps(local, baseSha ? baseFiles : headFiles, repoRoot, git, baseSha?.sha ?? 'HEAD');
+  for (const restamp of restamps) retired.add(restamp.source);
+  const history = migrationHistory(headFiles, retired, new Set(local.map((entry) => entry.name)));
+  findings.push(...migrationOrderingFindings(local, history, new Set(restamps.map((entry) => entry.destination))));
   if (!baseSha) return findings;
-  const baseNames = await baseMigrationNames(git, repoRoot, baseSha.sha);
+  const baseNames = baseFiles.filter(isActiveMigration).map((file) => file.slice(prefix.length));
   const onBase = new Set(baseNames);
-  const baseStamps = baseNames.map((name) => MIGRATION_NAME.exec(name)?.[1]).filter(Boolean).map(migrationStamp).filter((stamp) => stamp !== null);
-  const baseMax = baseStamps.length ? Math.max(...baseStamps) : null;
   await eachInOrder(local, async (entry) => {
-    findings.push(...await baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase, baseMax));
+    findings.push(...await baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase));
   });
-  const retired = new Set(archived.map((file) => file.slice(MIGRATIONS_ARCHIVE_DIR.length + 1)));
   findings.push(...removedMigrationFindings(local, retired, baseNames, baseSha));
   return findings;
 }
+
+const sqlName = (token) => token && ['word', 'ident'].includes(token.t) ? token.v : null;
+const sqlWord = (token, value) => token?.t === 'word' && token.v === value;
+
+function commentEnd(text, start) {
+  if (text.startsWith('--', start)) {
+    const end = text.indexOf('\n', start + 2);
+    return end === -1 ? text.length : end;
+  }
+  if (!text.startsWith('/*', start)) return null;
+  let depth = 1;
+  let index = start + 2;
+  while (index < text.length && depth > 0) {
+    if (text.startsWith('/*', index)) { depth += 1; index += 2; }
+    else if (text.startsWith('*/', index)) { depth -= 1; index += 2; }
+    else index += 1;
+  }
+  return index;
+}
+
+function quotedToken(text, start, quote, escaped = false) {
+  let index = start + 1;
+  let value = '';
+  while (index < text.length) {
+    if (text[index] === quote && text[index + 1] === quote) { value += quote; index += 2; }
+    else if (text[index] === quote) return { value, end: index + 1 };
+    else if (escaped && text[index] === '\\') { value += text[index + 1] ?? ''; index += 2; }
+    else { value += text[index]; index += 1; }
+  }
+  return { value, end: index };
+}
+
+function sqlTokenAt(text, index) {
+  const char = text[index];
+  if (char === "'" || char === '"') {
+    const token = quotedToken(text, index, char);
+    return { t: char === '"' ? 'ident' : 'string', v: token.value, end: token.end };
+  }
+  if (/[eE]/.test(char) && text[index + 1] === "'") {
+    const token = quotedToken(text, index + 1, "'", true);
+    return { t: 'string', v: token.value, end: token.end };
+  }
+  const tag = char === '$' ? /^\$(?:[A-Za-z_]\w*)?\$/.exec(text.slice(index))?.[0] : null;
+  if (tag) {
+    const end = text.indexOf(tag, index + tag.length);
+    return { t: 'body', v: text.slice(index + tag.length, end === -1 ? text.length : end), end: end === -1 ? text.length : end + tag.length };
+  }
+  const word = /^[A-Za-z_][A-Za-z0-9_$]*/.exec(text.slice(index))?.[0];
+  if (word) return { t: 'word', v: word.toLowerCase(), end: index + word.length };
+  const number = /^\d+(?:\.\d+)?/.exec(text.slice(index))?.[0];
+  if (number) return { t: 'number', v: number, end: index + number.length };
+  return { t: 'punct', v: char, end: index + 1 };
+}
+
+/** Synchronous SQL tokens; literal values stay internal and must never be copied to a finding. */
+export function databaseSqlTokens(text) {
+  const tokens = [];
+  let index = 0;
+  let line = 1;
+  while (index < text.length) {
+    if (/\s/.test(text[index])) { if (text[index] === '\n') line += 1; index += 1; continue; }
+    const end = commentEnd(text, index);
+    if (end !== null) { line += text.slice(index, end).split('\n').length - 1; index = end; continue; }
+    const token = sqlTokenAt(text, index);
+    tokens.push({ t: token.t, v: token.v, line, index });
+    line += text.slice(index, token.end).split('\n').length - 1;
+    index = token.end;
+  }
+  return tokens;
+}
+
+/** Split executable SQL, retaining function bodies as opaque tokens until their language is known. */
+export function databaseSqlStatements(tokens) {
+  const statements = [];
+  let current = [];
+  for (const token of tokens) {
+    if (token.t === 'punct' && token.v === ';') { if (current.length) statements.push(current); current = []; }
+    else current.push(token);
+  }
+  if (current.length) statements.push(current);
+  return statements;
+}
+
+function executableStatementTokens(statement, depth) {
+  const isDo = sqlWord(statement[0], 'do');
+  const functionAt = statement.findIndex((token) => sqlWord(token, 'function') || sqlWord(token, 'procedure'));
+  const isFunction = sqlWord(statement[0], 'create') && functionAt > 0 && functionAt < 4;
+  if (!isDo && !isFunction) return statement;
+  const languageAt = statement.findIndex((token) => sqlWord(token, 'language'));
+  const language = statement[languageAt + 1]?.v ?? 'sql';
+  if (languageAt !== -1 && !['sql', 'plpgsql'].includes(language)) return statement;
+  return statement.flatMap((token, index) => {
+    const body = token.t === 'body' || (token.t === 'string' && (isDo || sqlWord(statement[index - 1], 'as')));
+    if (!body) return [token];
+    return databaseExecutableTokens(token.v, depth + 1).map((child) => ({ ...child, line: child.line + token.line - 1 }));
+  });
+}
+
+/** SQL and PL/pgSQL bodies are scanned; comments, data literals and other function languages are opaque. */
+export function databaseExecutableTokens(text, depth = 0) {
+  const tokens = databaseSqlTokens(text);
+  if (depth > 8) return tokens;
+  return databaseSqlStatements(tokens).flatMap((statement) => [...executableStatementTokens(statement, depth), { t: 'punct', v: ';' }]);
+}
+
+function nameAt(tokens, index) {
+  const first = sqlName(tokens[index]);
+  if (first === null) return null;
+  const parts = [first];
+  let next = index + 1;
+  while (tokens[next]?.v === '.' && sqlName(tokens[next + 1]) !== null) { parts.push(sqlName(tokens[next + 1])); next += 2; }
+  return { name: parts.join('.'), leaf: parts.at(-1), next };
+}
+
+const skipWords = (tokens, index, words) => {
+  let next = index;
+  while (words.some((word) => sqlWord(tokens[next], word))) next += 1;
+  return next;
+};
+
+function dropObjects(tokens, start) {
+  const kind = tokens[start + 1]?.v;
+  if (!['table', 'role', 'user', 'schema', 'type', 'view', 'materialized', 'sequence', 'function', 'procedure', 'index', 'policy', 'trigger'].includes(kind)) return [];
+  let index = skipWords(tokens, start + 2, ['view', 'if', 'exists', 'concurrently']);
+  const objects = [];
+  while (index < tokens.length) {
+    const object = nameAt(tokens, index);
+    if (!object) break;
+    objects.push({ ...object, kind, line: tokens[start].line });
+    if (tokens[object.next]?.v !== ',') break;
+    index = object.next + 1;
+  }
+  return objects;
+}
+
+function columnAlterObject(tokens, index, table, line) {
+  let next = index + 1;
+  if (sqlWord(tokens[next], 'column')) next += 1;
+  const column = nameAt(tokens, next);
+  if (!column) return null;
+  const tail = tokens.slice(column.next);
+  const type = sqlWord(tail[0], 'type') || (sqlWord(tail[0], 'set') && sqlWord(tail[1], 'data') && sqlWord(tail[2], 'type'));
+  const notNull = sqlWord(tail[0], 'set') && sqlWord(tail[1], 'not') && sqlWord(tail[2], 'null');
+  const defaultSet = tokens.some((token, at) => sqlWord(token, 'alter') && sqlName(tokens[at + 1 + Number(sqlWord(tokens[at + 1], 'column'))]) === column.leaf
+    && sqlWord(tokens[at + 2 + Number(sqlWord(tokens[at + 1], 'column'))], 'set') && sqlWord(tokens[at + 3 + Number(sqlWord(tokens[at + 1], 'column'))], 'default'));
+  if (!type && !(notNull && !defaultSet)) return null;
+  return { name: `${table.name}.${column.name}`, leaf: column.leaf, table: table.leaf, kind: 'column', line };
+}
+
+function alteredColumn(table, column, line) {
+  return { name: `${table.name}.${column.name}`, leaf: column.leaf, table: table.leaf, kind: 'column', line };
+}
+
+function tableActionObject(body, index, table, line) {
+  if (sqlWord(body[index], 'drop')) {
+    const at = skipWords(body, index + 1, ['column', 'constraint', 'if', 'exists']);
+    if (sqlWord(body[at], 'default') || sqlWord(body[at], 'not')) return null;
+    const column = nameAt(body, at);
+    return column ? alteredColumn(table, column, line) : null;
+  }
+  if (sqlWord(body[index], 'rename')) {
+    const column = sqlWord(body[index + 1], 'column') ? nameAt(body, index + 2) : null;
+    return column ? alteredColumn(table, column, line) : { ...table, kind: 'table', line };
+  }
+  return sqlWord(body[index], 'alter') ? columnAlterObject(body, index, table, line) : null;
+}
+
+function alterObjects(tokens, start) {
+  const table = nameAt(tokens, skipWords(tokens, start + 2, ['if', 'exists', 'only']));
+  if (!table) return [];
+  const body = tokens.slice(table.next);
+  return body.map((token, index) => tableActionObject(body, index, table, tokens[start].line)).filter(Boolean);
+}
+
+function truncatedObjects(tokens, start) {
+  const objects = [];
+  let index = skipWords(tokens, start + 1, ['table', 'only']);
+  while (index < tokens.length) {
+    const table = nameAt(tokens, index);
+    if (!table) break;
+    objects.push({ ...table, kind: 'table', line: tokens[start].line });
+    if (tokens[table.next]?.v !== ',') break;
+    index = skipWords(tokens, table.next + 1, ['only']);
+  }
+  return objects;
+}
+
+function destructiveObjects(statement) {
+  const objects = [];
+  for (let index = 0; index < statement.length; index += 1) {
+    if (sqlWord(statement[index], 'drop')) objects.push(...dropObjects(statement, index));
+    else if (sqlWord(statement[index], 'truncate')) objects.push(...truncatedObjects(statement, index));
+    else if (sqlWord(statement[index], 'alter') && sqlWord(statement[index + 1], 'table')) objects.push(...alterObjects(statement, index));
+    else if (sqlWord(statement[index], 'alter') && ['type', 'schema', 'view', 'sequence', 'function', 'procedure', 'index'].includes(statement[index + 1]?.v)) {
+      const object = nameAt(statement, index + 2);
+      if (object && statement.slice(object.next).some((token) => sqlWord(token, 'rename'))) objects.push({ ...object, kind: statement[index + 1].v, line: statement[index].line });
+    }
+  }
+  return objects;
+}
+
+function sourceNames(ts, text, file) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+  const names = new Set();
+  const addSql = (sql) => { for (const token of databaseSqlTokens(sql)) if (sqlName(token) !== null) names.add(token.v); };
+  const visit = (node) => {
+    if (ts.isStringLiteralLike(node)) addSql(node.text);
+    if (ts.isTemplateExpression(node)) { addSql(node.head.text); for (const span of node.templateSpans) addSql(span.literal.text); }
+    if (/\.entity\.[cm]?tsx?$/.test(file) && ts.isIdentifier(node)) names.add(node.text);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return names;
+}
+
+function destructiveObjectFinding(file, object, contract, references) {
+  const reference = references.find(({ names }) => names.has(object.leaf));
+  if (contract && !reference) return null;
+  const reason = reference && contract ? `${reference.file} still references this object; remove the reference before the contract migration`
+    : 'use a *_contract_* migration after the application stops using this object';
+  return found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destructively changes ${object.name}; ${reason}`,
+    { line: object.line, object: object.name, ...(reference ? { reference: reference.file } : {}) });
+}
+
+function destructiveFileFindings(file, text, references) {
+  const contract = /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/.test(file);
+  const seen = new Set();
+  const objects = databaseSqlStatements(databaseExecutableTokens(text)).flatMap(destructiveObjects);
+  return objects.flatMap((object) => {
+    const key = `${object.line}:${object.name}`;
+    if (seen.has(key)) return [];
+    seen.add(key);
+    const finding = destructiveObjectFinding(file, object, contract, references);
+    return finding ? [finding] : [];
+  });
+}
+
+/** Destructive changes require a contract migration and no remaining SQL/entity reference in be/src. */
+export function destructiveMigrationFindings({ repoRoot, migrations, files }) {
+  const sources = files.filter((file) => /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/.test(file));
+  const ts = sources.length ? loadTypescript(repoRoot, HERE) : null;
+  if (sources.length && !ts) return [found(DB_MIGRATION_DESTRUCTIVE, 'hfs.json', 'destructive migration checks require the TypeScript parser to read be/src references')];
+  const references = sources.map((file) => ({ file, names: sourceNames(ts, readText(repoRoot, file) ?? '', file) }));
+  return migrations.flatMap((file) => {
+    const text = readText(repoRoot, file);
+    return text === null ? [] : destructiveFileFindings(file, text, references);
+  });
+}

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

@@ -5,6 +5,7 @@ import { eachInOrder } from '../../lib/in-order.mjs';
 import { parsePlpgsqlBody, parseSql } from '../sql/pg-parse.mjs';
 import { DB_DEFINER_SAFE, DB_DYNAMIC_DDL } from './database-constants.mjs';
 
+const DB_DEFINER_REVOKE = 'DB_DEFINER_REVOKE';
 const sval = (node) => node?.String?.sval;
 const nameOf = (list, defaultSchema) => {
   const parts = (list ?? []).map(sval).filter((part) => part !== undefined);
@@ -183,17 +184,66 @@ async function definerDynamicFindings(file, fn, queries, baseLine) {
   return findings;
 }
 
+const OUTPUT_PARAMETER_MODES = new Set(['OUT', 'TABLE'].map((mode) => ['FUNC', 'PARAM', mode].join('_')));
+const RESET_ALL_KIND = ['VAR', 'RESET', 'ALL'].join('_');
+const inputParameters = (node) => (node.parameters ?? []).map((item) => item.FunctionParameter)
+  .filter((parameter) => !OUTPUT_PARAMETER_MODES.has(parameter?.mode));
+
+function typeIdentity(type) {
+  const node = type?.TypeName ?? type;
+  const parts = (node?.names ?? []).map(sval).filter(Boolean);
+  if (parts[0] === 'pg_catalog') parts.shift();
+  return `${parts.join('.')}${node?.arrayBounds?.length ? '[]' : ''}`;
+}
+
+const functionArguments = (fn) => fn.node.func?.objargs ?? inputParameters(fn.node).map((parameter) => parameter.argType);
+const argumentIdentity = (args) => args.map(typeIdentity).join(',');
+
+function matchesFunction(fn, object, defaultSchema) {
+  if (nameOf(object?.objname, defaultSchema) !== fn.name) return false;
+  return object?.args_unspecified === true || argumentIdentity(object?.objargs ?? []) === argumentIdentity(functionArguments(fn));
+}
+
+const matchesAlter = (fn, alter) => matchesFunction(fn, alter.node.func, alter.schema);
+
+function grantMatchesFunction(fn, grant) {
+  if (grant.objtype !== 'OBJECT_FUNCTION') return false;
+  if (grant.privileges.length && !grant.privileges.includes('execute') && !grant.privileges.includes('all')) return false;
+  if (grant.targtype === 'ACL_TARGET_ALL_IN_SCHEMA') return grant.objects.some((object) => sval(object) === fn.schema);
+  return grant.objects.some((object) => matchesFunction(fn, object?.ObjectWithArgs, grant.defaultSchema));
+}
+
 function revokedRolesFor(fn, grants) {
   const roles = new Set();
   for (const grant of grants) {
-    if (grant.grant || grant.objtype !== 'OBJECT_FUNCTION') continue;
-    if (!grant.privileges.includes('execute') && !grant.privileges.includes('all')) continue;
-    const matches = grant.objects.some((object) => nameOf(object?.ObjectWithArgs?.objname, grant.defaultSchema) === fn.name);
-    if (matches) for (const role of grant.grantees) roles.add(role);
+    if (grant.index <= (fn.originIndex ?? fn.index)) continue;
+    if (!grantMatchesFunction(fn, grant)) continue;
+    for (const role of grant.grantees) {
+      if (grant.grant) roles.delete(role);
+      else roles.add(role);
+    }
   }
   return roles;
 }
 
+function pathSetting(options, pinned, facts) {
+  for (const option of options) {
+    const setting = option?.DefElem?.arg?.VariableSetStmt;
+    if (setting?.name === 'search_path' || setting?.kind === RESET_ALL_KIND) pinned = facts.isSearchPathSet(option.DefElem);
+  }
+  return pinned;
+}
+
+function hasPinnedSearchPath(fn, facts) {
+  let pinned = pathSetting(fn.node.options ?? [], false, facts);
+  const originIndex = fn.originIndex ?? fn.index;
+  for (const alter of facts.alterFunctions) {
+    if (alter.index <= originIndex || !matchesAlter(fn, alter)) continue;
+    pinned = pathSetting(alter.node.actions ?? [], pinned, facts);
+  }
+  return pinned;
+}
+
 async function doBlockFindings(file, block) {
   if (block.body === undefined || block.language !== 'plpgsql') {
     return [found(DB_DYNAMIC_DDL, file, `${file}:${block.line} DO block in ${block.language} cannot be inspected; a DO block is plpgsql so a static pass sees its statements`, { line: block.line })];
@@ -206,14 +256,12 @@ async function doBlockFindings(file, block) {
 function definerDeclarationFindings(file, fn, facts, exposed, definer) {
   if (!definer) return [];
   const findings = [];
-  const pathSet = functionOption(fn.node, 'set').some((option) => facts.isSearchPathSet(option))
-    || facts.alterFunctions.some((alter) => alter.name === fn.name && alter.setsPath && alter.index > fn.index);
-  if (!pathSet) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} sets no search_path; add \`set search_path = ''\` (or a pinned schema list) on the create, or an alter function in the same migration`, { line: fn.line, function: fn.name }));
+  if (!hasPinnedSearchPath(fn, facts)) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} sets no search_path; add \`set search_path = ''\` (or a pinned schema list) on the create, or an alter function in the same migration`, { line: fn.line, function: fn.name }));
   if (exposed.has(fn.schema)) {
     const revoked = revokedRolesFor(fn, facts.grants);
     if (!revoked.has('public') || !revoked.has('anon')) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} lives in the exposed schema ${fn.schema}; keep it in a non-exposed schema or revoke execute from public and anon in the same migration`, { line: fn.line, function: fn.name }));
   }
-  if (!fn.node.is_procedure && !fn.node.returnType) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} declares no return type`, { line: fn.line, function: fn.name }));
+  if (!fn.altered && !fn.node.is_procedure && !fn.node.returnType) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} declares no return type`, { line: fn.line, function: fn.name }));
   return findings;
 }
 
@@ -235,14 +283,76 @@ async function functionBodyFindings(file, fn, definer) {
 async function functionFindings(file, fn, facts, exposed) {
   const definer = securityDefiner(fn.node);
   const findings = definerDeclarationFindings(file, fn, facts, exposed, definer);
-  findings.push(...await functionBodyFindings(file, fn, definer));
+  const becomesDefiner = facts.alterFunctions.some((alter) => alter.securityDefiner && alter.index > fn.index && matchesAlter(fn, alter));
+  findings.push(...await functionBodyFindings(file, fn, definer || becomesDefiner));
   return findings;
 }
 
+function alteredDefinerFindings(file, alter, facts, exposed) {
+  if (!alter.securityDefiner) return [];
+  const created = facts.functions.filter((fn) => fn.index < alter.index && matchesAlter(fn, alter)).at(-1);
+  const node = created?.node ?? { func: alter.node.func };
+  const fn = { ...alter, node, altered: true, originIndex: created?.index ?? -1 };
+  return definerDeclarationFindings(file, fn, facts, exposed, true);
+}
+
 /** All PL/pgSQL-backed L04/L06 findings for one migration's extracted facts. */
 export async function plpgsqlFindings(file, facts, exposed) {
   const findings = [];
   await eachInOrder(facts.doBlocks, async (block) => { findings.push(...await doBlockFindings(file, block)); });
   await eachInOrder(facts.functions, async (fn) => { findings.push(...await functionFindings(file, fn, facts, exposed)); });
+  for (const alter of facts.alterFunctions) findings.push(...alteredDefinerFindings(file, alter, facts, exposed));
   return findings;
 }
+
+const functionKey = (fn) => `${fn.name}/${argumentIdentity(functionArguments(fn))}`;
+
+function applyFunctionAlter(functions, alter) {
+  if (!functionOption({ options: alter.node.actions }, 'security').length) return;
+  const matching = [...functions.values()].filter((fn) => matchesAlter(fn, alter));
+  if (!matching.length) matching.push({ ...alter, node: { func: alter.node.func }, originIndex: -1 });
+  for (const fn of matching) {
+    functions.set(functionKey(fn), { ...fn, file: alter.file, line: alter.line, definer: alter.securityDefiner });
+  }
+}
+
+function applyFunctionDrop(functions, statement) {
+  if (statement.node.removeType !== 'OBJECT_FUNCTION') return;
+  for (const fn of functions.values()) {
+    if (statement.node.objects?.some((object) => matchesFunction(fn, object.ObjectWithArgs, statement.defaultSchema))) {
+      functions.delete(functionKey(fn));
+    }
+  }
+}
+
+function finalFunctionAccess(analyses) {
+  const functions = new Map();
+  const grants = [];
+  let offset = 0;
+  for (const { file, facts } of analyses) {
+    const ordered = (items) => items.map((item) => ({ ...item, file, index: offset + item.index }));
+    const created = new Map(ordered(facts.functions).map((fn) => [fn.index, fn]));
+    const altered = new Map(ordered(facts.alterFunctions).map((fn) => [fn.index, fn]));
+    grants.push(...ordered(facts.grants));
+    for (const statement of ordered(facts.statements)) {
+      const fn = created.get(statement.index);
+      if (fn) {
+        const key = functionKey(fn);
+        const originIndex = functions.get(key)?.originIndex ?? fn.index;
+        functions.set(key, { ...fn, originIndex, definer: securityDefiner(fn.node) });
+      }
+      const alter = altered.get(statement.index);
+      if (alter) applyFunctionAlter(functions, alter);
+      if (statement.type === 'DropStmt') applyFunctionDrop(functions, statement);
+    }
+    offset += facts.statements.length;
+  }
+  return { functions: [...functions.values()], grants };
+}
+
+/** Authenticated execution is judged after all active migrations, including later revokes and grants. */
+export function migrationSetDefinerFindings(analyses, exposed) {
+  const { functions, grants } = finalFunctionAccess(analyses);
+  return functions.filter((fn) => fn.definer && exposed.has(fn.schema) && !revokedRolesFor(fn, grants).has('authenticated'))
+    .map((fn) => found(DB_DEFINER_REVOKE, fn.file, `${fn.file}:${fn.line} security definer function ${fn.name} lives in the exposed schema ${fn.schema}; the migration set ends without revoking execute from authenticated; revoke execute from public, anon and authenticated`, { line: fn.line, function: fn.name }));
+}