@starci/eslint-canon-be 3.4.39 → 3.4.41

package/runtime/scripts/hfs/architecture/function-spec-providers.mjs

@@ -51,7 +51,7 @@ export function valueObjectSubjects(ts, sourceFile) {
 }
 
 /** The value of one literal object property. */
-const propertyValue = (ts, object, key) => {
+export const propertyValue = (ts, object, key) => {
   const property = object.properties.find(item => keyOf(ts, item) === key);
   return property && ts.isPropertyAssignment(property) ? property.initializer : null;
 };

package/runtime/scripts/hfs/architecture/operation-contract-roots.mjs

@@ -0,0 +1,53 @@
+/** The app emitter consumes the API app's declared operation table without importing it from app.module.ts. */
+import path from 'node:path';
+import { hasAnyFlag } from '../../lib/ts-ast.mjs';
+
+const actualSymbol = (ts, checker, symbol) => symbol && hasAnyFlag(symbol.flags, ts.SymbolFlags.Alias) ? checker.getAliasedSymbol(symbol) : symbol;
+
+/** Follow declaration aliases while retaining the actual expression rather than an asserted type. */
+const initializerOf = (ts, checker, node, seen = new Set()) => {
+  if (!node || seen.has(node)) return null;
+  seen.add(node);
+  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)
+    || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node)) return initializerOf(ts, checker, node.expression, seen);
+  if (!ts.isIdentifier(node) && !ts.isPropertyAccessExpression(node)) return node;
+  const declaration = actualSymbol(ts, checker, checker.getSymbolAtLocation(node))?.valueDeclaration;
+  return declaration?.initializer ? initializerOf(ts, checker, declaration.initializer, seen) : node;
+};
+
+/** A same-named local function cannot declare the platform operation contract. */
+const isOperationDefiner = (ts, checker, graph, config, expression, seen = new Set()) => {
+  const symbol = actualSymbol(ts, checker, checker.getSymbolAtLocation(expression));
+  if (!symbol || seen.has(symbol)) return false;
+  seen.add(symbol);
+  return (symbol?.declarations ?? []).some(declaration => {
+    const relative = path.relative(config.root, declaration.getSourceFile().fileName).split(path.sep).join('/');
+    const owner = graph.resolver.ownerOf(relative);
+    if (declaration.name?.text === 'defineOperations' && owner?.slot === 'be.platform' && path.posix.basename(owner.root) === 'operations') return true;
+    const alias = declaration.initializer;
+    return Boolean(alias && (ts.isIdentifier(alias) || ts.isPropertyAccessExpression(alias)) && isOperationDefiner(ts, checker, graph, config, alias, seen));
+  });
+};
+
+/** True only for an exported, nonempty registration by the canon platform capability. */
+const declaresOperations = (context, graph, config, sourceFile) => {
+  const { ts } = context;
+  const checker = context.checkerFor?.(sourceFile.fileName);
+  const moduleSymbol = checker?.getSymbolAtLocation(sourceFile);
+  if (!moduleSymbol) return false;
+  const exported = checker.getExportsOfModule(moduleSymbol).find(symbol => symbol.getName() === 'OPERATIONS');
+  const declaration = actualSymbol(ts, checker, exported)?.valueDeclaration;
+  const registration = initializerOf(ts, checker, declaration?.initializer);
+  if (!registration || !ts.isCallExpression(registration) || !isOperationDefiner(ts, checker, graph, config, registration.expression)) return false;
+  const entries = initializerOf(ts, checker, registration.arguments[0]);
+  return entries !== null && ts.isObjectLiteralExpression(entries) && checker.getPropertiesOfType(checker.getTypeAtLocation(entries)).length > 0;
+};
+
+/** Only the emitter's exact entry of a declared API app is a contract root; workers and arbitrary app files remain judged. */
+export function operationContractRoots(context, graph, config) {
+  return (config.apps ?? []).filter(app => app.kind === 'api').flatMap(app => {
+    const relative = `apps/${app.name}/src/operations.ts`;
+    const node = graph.files.get(relative);
+    return node?.tier === 'app' && node.slot === 'be.app.api' && declaresOperations(context, graph, config, node.sourceFile) ? [relative] : [];
+  });
+}

package/runtime/scripts/hfs/architecture/reachability.mjs

@@ -13,7 +13,7 @@ import { byCodeUnit } from '../../lib/list.mjs';
 
 export const REACHABILITY_RULE_IDS = ['BE_FEATURE_NOT_COMPOSED', 'FE_OWNER_REACHABLE', 'FE_HREF_RESOLVES'];
 
-const BE_CAPABILITY_SLOTS = new Set(['be.domain', 'be.integrations', 'be.platform']);
+const BE_CAPABILITY_SLOTS = new Set(['be.domain', 'be.integrations', 'be.platform', 'be.platform.logging']);
 const TEST_FILE = /(?:\.(?:spec|test|stories|e2e-spec)\.[cm]?[jt]sx?$)|(?:(?:^|\/)__tests__\/)/;
 const ROUTE_FILE = /^(?:page|route)\.(?:tsx|ts|jsx|js)$/;
 const PLACEHOLDER = '\u0000';

package/runtime/scripts/hfs/architecture/sql-owner.mjs

@@ -3,6 +3,7 @@ import { analyzeSql, HOLE } from './sql-tokens.mjs';
 import { machineKit } from './machine-ast.mjs';
 import { contextModelOf } from './context-map.mjs';
 import { supabaseTablesOf } from './supabase-tables.mjs';
+import { supabaseUniqueSetsOf } from './supabase-keys.mjs';
 
 /**
  * R86 `sql-owner` (BE_SQL_TABLE_OWNER). Every `sql` tagged template (the tag declared in platform/database) of a
@@ -14,10 +15,10 @@ import { supabaseTablesOf } from './supabase-tables.mjs';
  *     to the table owner's public entry); a table of another context is refused (cross-context data comes only by events);
  *   - every table it names is declared by some entity under TypeORM authority, or by the generated
  *     `Database['public']['Tables']` contract under Supabase authority;
- *   - a SELECT carries LIMIT, or constrains the primary key or a unique key of its first table with `=`, or selects only
- *     aggregates without GROUP BY.
+ *   - a SELECT carries LIMIT, or reads a single relation under a complete primary/unique-key equality to scalar values,
+ *     or selects only proven scalar aggregates without GROUP BY. Inferred bounds reject multiplying projections and set operations.
  * Table positions that hold a `${...}` substitution (SqlIdent) are dynamic; they are counted in the coverage and judged by
- * nobody. Joined tables are not part of the bound: a to-many join under a key-constrained first table is a review point.
+ * nobody. A join needs an explicit result bound because key constraints on its first relation do not bound joined rows.
  */
 export const SQL_OWNER_RULE_IDS = ['BE_SQL_TABLE_OWNER'];
 
@@ -132,7 +133,8 @@ const capabilityTable = root => path.posix.basename(root).replaceAll('-', '_').t
 /** Supabase declarations, with an owner when the generated table name matches a capability's persistence folder. */
 function supabaseDeclarations(graph, appRoot, ts) {
   const generated = supabaseTablesOf(appRoot, ts);
-  const tables = new Map([...generated].map(table => [table, { table, owner: null, rel: null, uniqueSets: [] }]));
+  const keys = supabaseUniqueSetsOf(appRoot);
+  const tables = new Map([...generated].map(table => [table, { table, owner: null, rel: null, uniqueSets: keys.get(table) ?? [] }]));
   for (const file of graph.files.values()) {
     if (file.slot !== 'be.persistence' || !file.owner) continue;
     const key = capabilityTable(file.owner.root);
@@ -142,6 +144,12 @@ function supabaseDeclarations(graph, appRoot, ts) {
   return tables;
 }
 
+/** A capability owns the table named for it and the tables that start with its name and an underscore (`realtime`, `realtime_events`). */
+const isOwnTable = (table, ownTable) => {
+  const name = table.toLowerCase();
+  return name === ownTable || name.startsWith(`${ownTable}_`);
+};
+
 function reportSqlWrite({ tables, supabase, file, ownTable, report }, write) {
   const declaration = tables.get(write.table.toLowerCase());
   if (!declaration) {
@@ -149,7 +157,7 @@ function reportSqlWrite({ tables, supabase, file, ownTable, report }, write) {
       ? `SQL writes table ${write.table}, which Database['public']['Tables'] does not declare; regenerate supabase/types/database.types.ts from the migrations.`
       : `SQL writes table ${write.table}, which no @Entity declares; declare the entity in the owning capability's persistence/entities.`, { table: write.table });
   } else if (supabase) {
-    if (write.table.toLowerCase() === ownTable) return;
+    if (isOwnTable(write.table, ownTable) && (declaration.owner === null || declaration.owner === file.owner.root)) return;
     const ownerNote = declaration.owner ? `, owned by ${declaration.owner}` : '';
     report(`SQL in ${file.owner.root} writes table ${write.table}${ownerNote}; under Supabase schema authority a capability writes only its own table (${ownTable}), named for that capability.`, { table: write.table, ...(declaration.owner ? { tableOwner: declaration.owner } : {}) });
   } else if (declaration.owner !== file.owner.root) {
@@ -208,7 +216,10 @@ function inspectSqlTag(input, state, file, checker, node) {
     seen.add(key);
     state.violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
   };
-  const result = analyzeSql(text, { uniqueSetsOf: table => tables.get(table.toLowerCase())?.uniqueSets ?? null });
+  const result = analyzeSql(text, { uniqueSetsOf: (table, schema) => {
+    if (supabase && ((schema && schema !== 'public') || table !== table.toLowerCase())) return null;
+    return tables.get(table.toLowerCase())?.uniqueSets ?? null;
+  } });
   state.dynamic += result.dynamic;
   const ownTable = capabilityTable(file.owner.root);
   reportSqlWrites({ result, tables, supabase, file, ownTable, report });

package/runtime/scripts/hfs/architecture/sql-token-forms.mjs

@@ -0,0 +1,105 @@
+/** Token forms shared by SQL relation scanning and conservative singleton-value proofs. */
+
+/** Whether a token can spell an SQL identifier. */
+export const isName = token => token && (token.t === 'word' || token.t === 'ident');
+/** The identifier spelling after SQL word folding. */
+export const nameOf = token => (token.t === 'word' ? token.v.toLowerCase() : token.v);
+/** Whether a token is the named SQL keyword. */
+export const isWord = (token, up) => token?.t === 'word' && token.up === up;
+
+// The scalar-cast grammar proves only these builtin targets, unqualified or explicitly under pg_catalog.
+const SCALAR_CAST_TYPES = new Set(['uuid', 'text']);
+
+/** Depth of each token (the depth before it when it is `(`, after it when it is `)`). */
+export function depths(tokens) {
+  let depth = 0;
+  return tokens.map(token => {
+    if (token.v === ')' && token.t === 'punct') depth -= 1;
+    const here = depth;
+    if (token.v === '(' && token.t === 'punct') depth += 1;
+    return here;
+  });
+}
+
+/** The closing parenthesis of a token group, or the final token when unmatched. */
+export function matching(tokens, open) {
+  let depth = 0;
+  for (let i = open; i < tokens.length; i += 1) {
+    if (tokens[i].t !== 'punct') continue;
+    if (tokens[i].v === '(') depth += 1;
+    else if (tokens[i].v === ')') { depth -= 1; if (depth === 0) return i; }
+  }
+  return tokens.length - 1;
+}
+
+function unparenthesized(tokens) {
+  let part = tokens;
+  while (part[0]?.v === '(' && part.at(-1)?.v === ')' && matching(part, 0) === part.length - 1) part = part.slice(1, -1);
+  return part;
+}
+
+function keyColumn(tokens, qualifiers) {
+  const part = unparenthesized(tokens);
+  if (singletonValue(part)) return null;
+  if (part.length === 1 && isName(part[0])) return nameOf(part[0]);
+  if (part.length === 3 && isName(part[0]) && part[1].v === '.' && isName(part[2]) && qualifiers.has(nameOf(part[0]))) return nameOf(part[2]);
+  return null;
+}
+
+function scalarCastType(tokens) {
+  if (tokens.length === 1 && isName(tokens[0])) return SCALAR_CAST_TYPES.has(nameOf(tokens[0]));
+  return tokens.length === 3 && isName(tokens[0]) && nameOf(tokens[0]) === 'pg_catalog' && tokens[1].v === '.'
+    && isName(tokens[2]) && SCALAR_CAST_TYPES.has(nameOf(tokens[2]));
+}
+
+/** SQL CAST is a scalar wrapper; its operand is still inspected separately for row dependence or set-returning calls. */
+function castParts(tokens, start = 0) {
+  if (!isWord(tokens[start], 'CAST') || tokens[start + 1]?.v !== '(') return null;
+  const end = matching(tokens, start + 1);
+  if (tokens[end]?.v !== ')') return null;
+  const inside = tokens.slice(start + 2, end);
+  const level = depths(inside);
+  const separator = inside.findIndex((token, index) => level[index] === 0 && isWord(token, 'AS'));
+  if (separator < 1 || separator === inside.length - 1) return null;
+  return { value: inside.slice(0, separator), type: inside.slice(separator + 1), next: end + 1 };
+}
+
+/** A scalar atom, optionally cast through the supported builtin grammar, proves a row-independent equality value. */
+function singletonValue(tokens) {
+  const part = unparenthesized(tokens);
+  if (part.length === 2 && ['+', '-'].includes(part[0].v) && part[1].t === 'number') return true;
+  if (part.length === 1) {
+    const [token] = part;
+    return ['param', 'string', 'number'].includes(token.t) || isWord(token, 'NULL') || isWord(token, 'TRUE') || isWord(token, 'FALSE');
+  }
+  const cast = castParts(part);
+  if (cast?.next === part.length && scalarCastType(cast.type)) return singletonValue(cast.value);
+  const level = depths(part);
+  for (let index = part.length - 1; index > 0; index -= 1) {
+    if (level[index] === 0 && part[index].v === '::') return scalarCastType(part.slice(index + 1)) && singletonValue(part.slice(0, index));
+  }
+  return false;
+}
+
+/** Key columns equated to proven row-independent singleton values in either operand order. */
+export function equalityColumns(conjunct, qualifiers) {
+  const found = new Set();
+  const part = unparenthesized(conjunct);
+  const level = depths(part);
+  const equals = part.findIndex((token, index) => level[index] === 0 && token.t === 'punct' && token.v === '=');
+  if (equals < 0) return found;
+  const left = part.slice(0, equals);
+  const right = part.slice(equals + 1);
+  const leftColumn = keyColumn(left, qualifiers);
+  const rightColumn = keyColumn(right, qualifiers);
+  if (leftColumn && singletonValue(right)) found.add(leftColumn);
+  if (rightColumn && singletonValue(left)) found.add(rightColumn);
+  return found;
+}
+
+/** Whether a call position is SQL CAST through the supported scalar type grammar. */
+export function scalarCastAt(tokens, index) {
+  if (tokens[index - 1]?.v === '.') return false;
+  const cast = castParts(tokens, index);
+  return Boolean(cast && scalarCastType(cast.type));
+}

package/runtime/scripts/hfs/architecture/sql-tokens.mjs

@@ -5,6 +5,8 @@
  * A substitution of the `sql` tag (a `${...}` hole, the SqlIdent form) is an opaque token: a table position that holds
  * one is counted as dynamic and judged by nobody.
  */
+import { depths, equalityColumns, isName, isWord, matching, nameOf, scalarCastAt } from './sql-token-forms.mjs';
+
 export const HOLE = '';
 
 const isSpace = char => /\s/u.test(char);
@@ -129,10 +131,6 @@ const NOT_A_WRITE_BEFORE_UPDATE = new Set(['FOR', 'DO', 'ON', 'KEY', 'SHARE', 'O
 const WHERE_END = new Set(['GROUP', 'ORDER', 'HAVING', 'LIMIT', 'OFFSET', 'UNION', 'INTERSECT', 'EXCEPT', 'FOR', 'WINDOW', 'RETURNING', 'FETCH']);
 const SYSTEM_SCHEMAS = new Set(['pg_catalog', 'information_schema']);
 
-const isName = token => token && (token.t === 'word' || token.t === 'ident');
-const nameOf = token => (token.t === 'word' ? token.v.toLowerCase() : token.v);
-const isWord = (token, up) => token?.t === 'word' && token.up === up;
-
 /**
  * The table reference at `start`: {parts, table, alias, next}, {dynamic: true}, or null (a subquery, a function, nothing).
  * `next` is the index after the reference and its alias.
@@ -223,27 +221,6 @@ function cteNames(tokens) {
   return names;
 }
 
-/** Depth of each token (the depth before it when it is `(`, after it when it is `)`). */
-function depths(tokens) {
-  let depth = 0;
-  return tokens.map(token => {
-    if (token.v === ')' && token.t === 'punct') depth -= 1;
-    const here = depth;
-    if (token.v === '(' && token.t === 'punct') depth += 1;
-    return here;
-  });
-}
-
-function matching(tokens, open) {
-  let depth = 0;
-  for (let i = open; i < tokens.length; i += 1) {
-    if (tokens[i].t !== 'punct') continue;
-    if (tokens[i].v === '(') depth += 1;
-    else if (tokens[i].v === ')') { depth -= 1; if (depth === 0) return i; }
-  }
-  return tokens.length - 1;
-}
-
 function isAggregateItem(item) {
   for (let i = 0; i < item.length; i += 1) {
     if (item[i].t === 'word' && AGGREGATES.has(item[i].up) && item[i + 1]?.v === '(') {
@@ -257,28 +234,11 @@ function isAggregateItem(item) {
 /** The unique-key columns `columns` (lowercase Set of `=`-constrained column names) satisfy for one of `uniqueSets`. */
 const covers = (uniqueSets, columns) => uniqueSets.some(set => set.length > 0 && set.every(column => columns.has(column)));
 
-function equalityColumns(conjunct, qualifiers) {
-  const found = new Set();
-  const name = (from, to) => {
-    const part = conjunct.slice(from, to);
-    if (part.length === 1 && isName(part[0])) return nameOf(part[0]);
-    if (part.length === 3 && isName(part[0]) && part[1].v === '.' && isName(part[2]) && qualifiers.has(nameOf(part[0]))) return nameOf(part[2]);
-    return null;
-  };
-  const equals = conjunct.findIndex(token => token.t === 'punct' && token.v === '=');
-  if (equals < 0) return found;
-  const left = name(0, equals);
-  const rightStart = conjunct[equals + 1];
-  if (left && !(rightStart?.t === 'word' && ['ANY', 'ALL', 'SOME'].includes(rightStart.up))) found.add(left);
-  const right = name(equals + 1, conjunct.length);
-  if (right) found.add(right);
-  return found;
-}
-
 /**
  * Judge one statement that reads rows (no INSERT/UPDATE/DELETE/MERGE at its own depth): `{bounded, basis}`. Bounded is
  * a LIMIT/FETCH at the statement depth, no FROM at all (one row), only aggregates without GROUP BY, or an equality on
- * every column of the primary key or of one unique key of the first table of FROM.
+ * every column of the primary key or of one unique key of a single FROM relation. Unknown projection calls can
+ * multiply rows even when that relation contributes at most one, so they need an explicit statement bound.
  */
 function aggregateSelectItems(tokens, level, select, from) {
   const items = [];
@@ -338,16 +298,42 @@ function isUniqueBounded(tokens, level, from, primary, uniqueSets) {
   return Boolean(columns) && covers(uniqueSets, columns);
 }
 
+function singleFromRelation(tokens, level, from) {
+  for (let index = from + 1; index < tokens.length; index += 1) {
+    if (level[index] !== 0) continue;
+    if (isWord(tokens[index], 'WHERE') || (tokens[index].t === 'word' && WHERE_END.has(tokens[index].up))) break;
+    if (isWord(tokens[index], 'JOIN') || (tokens[index].t === 'punct' && tokens[index].v === ',')) return false;
+  }
+  return true;
+}
+
+/** Plain known aggregate calls are scalar; other calls, including wrappers around aggregates, may return sets. */
+function unprovenProjectionCall(tokens, level, select, from) {
+  const end = from < 0 ? tokens.length : from;
+  for (let index = select + 1; index < end; index += 1) {
+    const token = tokens[index];
+    if (level[index] === 0 && (isWord(token, 'WHERE') || (token.t === 'word' && WHERE_END.has(token.up)))) break;
+    if (!isName(token) || tokens[index + 1]?.v !== '(') continue;
+    if (scalarCastAt(tokens, index)) continue;
+    if (token.t !== 'word' || !AGGREGATES.has(token.up) || tokens[index - 1]?.v === '.') return true;
+  }
+  return false;
+}
+
 function selectBound(tokens, level, uniqueSetsOf, cte) {
   if (findTopWord(tokens, level, 'LIMIT') >= 0 || findTopWord(tokens, level, 'FETCH') >= 0) return { bounded: true, basis: 'limit' };
   const select = findTopWord(tokens, level, 'SELECT');
   const from = findTopWord(tokens, level, 'FROM', select);
-  if (from < 0) return { bounded: true, basis: 'no from' };
-  if (!hasTopGroupBy(tokens, level) && aggregateSelectItems(tokens, level, select, from).every(isAggregateItem)) return { bounded: true, basis: 'aggregate' };
-  const primary = tableRef(tokens, from + 1);
-  if (!primary || primary.dynamic || cte.has(primary.table)) return { bounded: false, basis: 'unbounded', table: primary?.table ?? null };
-  if (isUniqueBounded(tokens, level, from, primary, uniqueSetsOf(primary.table))) return { bounded: true, basis: 'unique' };
-  return { bounded: false, basis: 'unbounded', table: primary.table };
+  const primary = from < 0 ? null : tableRef(tokens, from + 1);
+  const unbounded = { bounded: false, basis: 'unbounded', table: primary?.table ?? null };
+  const grouped = hasTopGroupBy(tokens, level);
+  if (tokens.some((token, index) => level[index] === 0 && (isWord(token, 'UNION') || isWord(token, 'INTERSECT') || isWord(token, 'EXCEPT')))) return unbounded;
+  if (unprovenProjectionCall(tokens, level, select, from)) return unbounded;
+  if (from < 0) return grouped ? unbounded : { bounded: true, basis: 'no from' };
+  if (!grouped && aggregateSelectItems(tokens, level, select, from).every(isAggregateItem)) return { bounded: true, basis: 'aggregate' };
+  if (grouped || !primary || primary.dynamic || cte.has(primary.table) || !singleFromRelation(tokens, level, from)) return unbounded;
+  if (isUniqueBounded(tokens, level, from, primary, uniqueSetsOf(primary.table, primary.schema))) return { bounded: true, basis: 'unique' };
+  return unbounded;
 }
 
 function recordSqlReference(list, ref, reads, cte, state) {
@@ -437,8 +423,8 @@ function statementAnalysis(tokens, uniqueSetsOf) {
 }
 
 /**
- * Read one SQL text. `uniqueSetsOf(table)` returns the unique-key column sets (each a lowercase column list) of the entity
- * of `table`, or null when no entity declares it.
+ * Read one SQL text. `uniqueSetsOf(table, schema)` returns the unique-key column sets (each a lowercase column list)
+ * proven for that relation by its declared schema authority, or null when no key is known.
  * Returns {writes: [{table, schema}], reads: [{table, schema}], selects: [{bounded, basis, table}], dynamic}.
  */
 export function analyzeSql(text, { uniqueSetsOf = () => null } = {}) {

package/runtime/scripts/hfs/architecture/supabase-keys.mjs

@@ -0,0 +1,261 @@
+import path from 'node:path';
+import { lsFiles } from '../../api/git/ls-files.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+import { MIGRATIONS_DIR } from '../rules/database-constants.mjs';
+import { databaseSqlStatements, databaseSqlTokens, isMigrationName, migrationStamp } from '../rules/database-migrations.mjs';
+import { readText } from '../rules/read.mjs';
+
+const word = (token, value) => token?.t === 'word' && token.v === value;
+const identifier = (token) => ['word', 'ident'].includes(token?.t) && token.v === token.v.toLowerCase() ? token.v : null;
+const OPAQUE_STATEMENTS = new Set(['do', 'call', 'select', 'with', 'insert', 'update', 'delete', 'merge', 'truncate', 'execute', 'rollback', 'abort', 'prepare', 'discard', 'refresh', 'copy']);
+const settingName = (token, value) => ['word', 'ident'].includes(token?.t) && token.v.toLowerCase() === value;
+
+/** A migration relation is public only when its qualification or the current search path proves it. */
+function relationAt(tokens, start, schema) {
+  const first = identifier(tokens[start]);
+  if (first === null) return null;
+  if (tokens[start + 1]?.v !== '.') return { schema, table: first, next: start + 1 };
+  const table = identifier(tokens[start + 2]);
+  if (table === null || tokens[start + 3]?.v === '.') return null;
+  return { schema: first, table, next: start + 3 };
+}
+
+/** Split declarations at their own commas, keeping type arguments and constraint column lists together. */
+function clausesOf(tokens) {
+  const clauses = [[]];
+  let depth = 0;
+  for (const token of tokens) {
+    if (token.v === '(') depth += 1;
+    if (token.v === ')') depth -= 1;
+    if (depth < 0) return null;
+    if (token.v === ',' && depth === 0) clauses.push([]);
+    else clauses.at(-1).push(token);
+  }
+  return depth === 0 ? clauses : null;
+}
+
+function parenthesized(tokens, start) {
+  if (tokens[start]?.v !== '(') return null;
+  let depth = 1;
+  for (let index = start + 1; index < tokens.length; index += 1) {
+    if (tokens[index].v === '(') depth += 1;
+    if (tokens[index].v === ')') depth -= 1;
+    if (depth === 0) return { body: tokens.slice(start + 1, index), next: index + 1 };
+  }
+  return null;
+}
+
+const isDeferred = (tokens) => tokens.some((token, index) => word(token, 'deferrable') && !word(tokens[index - 1], 'not'));
+
+/** A declared key proves only its complete, plain column list; index expressions are never column names. */
+function tableKey(tokens) {
+  if (isDeferred(tokens)) return null;
+  let start = word(tokens[0], 'constraint') ? 2 : 0;
+  if (word(tokens[start], 'primary') && word(tokens[start + 1], 'key')) start += 2;
+  else if (word(tokens[start], 'unique')) start += 1;
+  else return null;
+  const enclosed = parenthesized(tokens, start);
+  const clauses = enclosed && clausesOf(enclosed.body);
+  if (!clauses?.length || clauses.some((clause) => clause.length !== 1 || identifier(clause[0]) === null)) return null;
+  return clauses.map((clause) => identifier(clause[0]));
+}
+
+/** Inline key clauses are read at column depth, outside defaults, generated expressions and type parameters. */
+function columnKey(tokens) {
+  const column = identifier(tokens[0]);
+  if (column === null || isDeferred(tokens)) return null;
+  let depth = 0;
+  for (let index = 1; index < tokens.length; index += 1) {
+    if (tokens[index].v === '(') depth += 1;
+    if (tokens[index].v === ')') depth -= 1;
+    if (depth === 0 && (word(tokens[index], 'unique') || (word(tokens[index], 'primary') && word(tokens[index + 1], 'key')))) return [column];
+  }
+  return null;
+}
+
+function declarationKey(tokens) {
+  const tableConstraint = ['constraint', 'primary', 'unique', 'check', 'foreign', 'exclude'].some((value) => word(tokens[0], value));
+  return tableConstraint ? tableKey(tokens) : columnKey(tokens);
+}
+
+function addKey(keys, columns) {
+  if (columns && !keys.some((key) => key.length === columns.length && key.every((column, index) => column === columns[index]))) keys.push(columns);
+}
+
+function clearKeys(state, uncertain = false) {
+  for (const table of state.tables.keys()) state.tables.set(table, []);
+  if (uncertain) state.safe.clear();
+}
+
+function opaqueExecution(state) {
+  clearKeys(state, true);
+  state.schema = null;
+}
+
+function forgetRelation(state, relation) {
+  if (!relation || relation.schema === null) clearKeys(state, true);
+  else if (relation.schema === 'public') {
+    state.tables.set(relation.table, []);
+    state.safe.delete(relation.table);
+  }
+}
+
+/** Conditional table creation cannot establish what an unknown pre-existing table actually constrains. */
+function createTable(state, tokens, start) {
+  const conditional = word(tokens[start], 'if') && word(tokens[start + 1], 'not') && word(tokens[start + 2], 'exists');
+  if (conditional) start += 3;
+  const relation = relationAt(tokens, start, state.schema);
+  if (!relation || relation.schema !== 'public') return;
+  if (conditional) {
+    if (!state.tables.has(relation.table)) state.tables.set(relation.table, []);
+    return;
+  }
+  const enclosed = parenthesized(tokens, relation.next);
+  const clauses = enclosed && clausesOf(enclosed.body);
+  const keys = [];
+  state.safe.delete(relation.table);
+  state.tables.set(relation.table, keys);
+  if (!clauses) return;
+  state.safe.add(relation.table);
+  for (const clause of clauses) addKey(keys, declarationKey(clause));
+}
+
+function safeAlter(tokens) {
+  if (word(tokens[0], 'owner') || word(tokens[0], 'cluster')) return true;
+  const security = tokens.some((token) => word(token, 'security'));
+  if (security && ['enable', 'disable', 'force', 'no'].some((value) => word(tokens[0], value))) return true;
+  return (word(tokens[0], 'set') || word(tokens[0], 'reset')) && tokens[1]?.v === '(';
+}
+
+/** ADD can establish a new key; drops, renames and unreadable alterations discard the affected proof. */
+function alterClause(state, relation, tokens) {
+  if (tokens.some((token) => word(token, 'inherit') || word(token, 'partition'))) { clearKeys(state, true); return; }
+  if (word(tokens[0], 'validate') || tokens.some((token) => word(token, 'default') || word(token, 'check') || word(token, 'generated') || word(token, 'using'))) {
+    opaqueExecution(state);
+    return;
+  }
+  if (safeAlter(tokens)) return;
+  if (word(tokens[0], 'drop') && (word(tokens[1], 'column') || word(tokens[1], 'constraint'))) {
+    if (relation.schema === 'public') state.tables.set(relation.table, []);
+    return;
+  }
+  if (!word(tokens[0], 'add')) { forgetRelation(state, relation); return; }
+  let start = word(tokens[1], 'column') ? 2 : 1;
+  if (word(tokens[start], 'if')) return;
+  if (relation.schema !== 'public' || !state.safe.has(relation.table)) return;
+  const keys = state.tables.get(relation.table) ?? [];
+  state.tables.set(relation.table, keys);
+  addKey(keys, declarationKey(tokens.slice(start)));
+}
+
+function alterTable(state, tokens, start) {
+  if (word(tokens[start], 'if') && word(tokens[start + 1], 'exists')) start += 2;
+  if (word(tokens[start], 'only')) start += 1;
+  const relation = relationAt(tokens, start, state.schema);
+  if (!relation || relation.schema === null) { clearKeys(state, true); return; }
+  const clauses = clausesOf(tokens.slice(relation.next));
+  if (!clauses) { forgetRelation(state, relation); return; }
+  for (const clause of clauses) alterClause(state, relation, clause);
+}
+
+function dropTable(state, tokens, start) {
+  if (word(tokens[start], 'if') && word(tokens[start + 1], 'exists')) start += 2;
+  for (const clause of clausesOf(tokens.slice(start)) ?? []) forgetRelation(state, relationAt(clause, 0, state.schema));
+}
+
+function searchPath(state, tokens) {
+  const local = word(tokens[1], 'local');
+  const start = local || word(tokens[1], 'session') ? 2 : 1;
+  if (word(tokens[start], 'schema')) {
+    state.schema = !local && tokens[start + 1]?.t === 'string' ? tokens[start + 1].v : null;
+    return;
+  }
+  if (!settingName(tokens[start], 'search_path')) {
+    if (tokens.some((token) => settingName(token, 'search_path')) || word(tokens[start], 'all')) state.schema = null;
+    return;
+  }
+  if (word(tokens[0], 'reset')) { state.schema = 'public'; return; }
+  if (!word(tokens[start + 1], 'to') && tokens[start + 1]?.v !== '=') { state.schema = null; return; }
+  const value = tokens[start + 2];
+  const declared = identifier(value) ?? (value?.t === 'string' ? value.v : null);
+  state.schema = local ? null : declared;
+}
+
+function createObject(tokens) {
+  let start = 1;
+  if (word(tokens[start], 'or') && word(tokens[start + 1], 'replace')) start += 2;
+  if (word(tokens[start], 'global') || word(tokens[start], 'local')) start += 1;
+  const temporary = word(tokens[start], 'temp') || word(tokens[start], 'temporary');
+  if (temporary || word(tokens[start], 'unlogged')) start += 1;
+  if (word(tokens[start], 'unique')) start += 1;
+  return { start, temporary };
+}
+
+/** CTAS, materialization and index building can call user code; event triggers also affect later DDL. */
+function executingCreate(state, tokens, start) {
+  if (word(tokens[start], 'event') && word(tokens[start + 1], 'trigger')) {
+    state.tainted = true;
+    opaqueExecution(state);
+    return true;
+  }
+  if (word(tokens[start], 'index') || (word(tokens[start], 'materialized') && word(tokens[start + 1], 'view'))) {
+    opaqueExecution(state);
+    return true;
+  }
+  if (!word(tokens[start], 'table')) return false;
+  let depth = 0;
+  for (const token of tokens.slice(start + 1)) {
+    if (token.v === '(') depth += 1;
+    if (token.v === ')') depth -= 1;
+    if (depth === 0 && word(token, 'as')) { opaqueExecution(state); return true; }
+  }
+  return false;
+}
+
+function applyCreate(state, tokens) {
+  // A private or temporary child also contributes rows to a public parent's ordinary SELECT.
+  if (tokens.some((token) => word(token, 'inherits'))) { clearKeys(state, true); return; }
+  const { start, temporary } = createObject(tokens);
+  if (executingCreate(state, tokens, start)) return;
+  if (temporary) { opaqueExecution(state); return; }
+  if (word(tokens[start], 'table')) createTable(state, tokens, start + 1);
+}
+
+function applyTableCommand(state, tokens, command) {
+  if (word(tokens[1], 'table')) command(state, tokens, 2);
+  else clearKeys(state, true);
+}
+
+/** Reduce only unconditional schema declarations; executable bodies may remove facts but never manufacture them. */
+function applyStatement(state, tokens) {
+  if (state.tainted) return;
+  if (word(tokens[0], 'set') || word(tokens[0], 'reset')) { searchPath(state, tokens); return; }
+  if (tokens[0]?.t === 'word' && OPAQUE_STATEMENTS.has(tokens[0].v)) { opaqueExecution(state); return; }
+  if (word(tokens[0], 'commit') && word(tokens[1], 'prepared')) { opaqueExecution(state); return; }
+  if (word(tokens[0], 'create')) { applyCreate(state, tokens); return; }
+  if (word(tokens[0], 'alter')) { applyTableCommand(state, tokens, alterTable); return; }
+  if (word(tokens[0], 'drop')) applyTableCommand(state, tokens, dropTable);
+}
+
+function activeMigrations(root) {
+  const listed = lsFiles(['-z', '--cached', '--exclude-standard', '--', MIGRATIONS_DIR], { dir: root, maxBuffer: 256 * 1024 * 1024 });
+  if (listed.error || listed.status !== 0) return null;
+  return listed.stdout.split('\0').filter((file) => path.posix.dirname(file) === MIGRATIONS_DIR
+    && isMigrationName(path.posix.basename(file)) && migrationStamp(path.posix.basename(file).slice(0, 14)) !== null).sort(byCodeUnit);
+}
+
+/**
+ * Public-table key sets proven by ordered, tracked active migrations. Direct event triggers taint later DDL proof.
+ * Opaque bodies discard current facts; persistent schema machinery hidden inside them is outside static authority.
+ */
+export function supabaseUniqueSetsOf(appRoot) {
+  const root = path.resolve(appRoot);
+  const files = activeMigrations(root);
+  const state = { tables: new Map(), safe: new Set(), schema: 'public', tainted: false };
+  for (const file of files ?? []) {
+    const text = readText(root, file);
+    if (text === null) { clearKeys(state, true); state.schema = null; continue; }
+    for (const statement of databaseSqlStatements(databaseSqlTokens(text))) applyStatement(state, statement);
+  }
+  return state.tainted ? new Map() : state.tables;
+}