@starci/hfs 4.7.31 → 4.7.33

package/runtime/scripts/guards/supervisor-seat.mjs

@@ -0,0 +1,80 @@
+// supervisor-seat.mjs — what the Supervisor seat (a bound caller of role supervisor) may run, from the `supervisor` table of
+// modules/kernel/command-policy.yaml. The PreToolUse guard and the PATH shims evaluate it (command-policy.mjs policyVerdict): the
+// seat reads, answers the items of its menu with `starci supervisor decide`, records a runtime defect for Debug and runs the
+// collectors it owns. Every refusal names the status and decision verbs without running them.
+import { plainWords } from '../lib/menu-parts.mjs';
+import { refusal } from './rights.mjs';
+import { runtimeChangeRefusal, RUNTIME_CHANGE_CODE } from '../machine/runtime-change.mjs';
+
+const OPTION = /^--?([A-Za-z][\w-]*)(?:=(.*))?$/;
+
+/** The option names and the values of the options that carry one (`--item x` or `--item=x`) of a call. */
+function optionsOf(args) {
+  const names = new Set();
+  const values = new Map();
+  args.map(String).forEach((word, index, all) => {
+    const hit = OPTION.exec(word);
+    if (!hit) return;
+    names.add(hit[1]);
+    const next = all[index + 1];
+    const value = hit[2] ?? (next?.startsWith('-') === false ? next : undefined);
+    if (value !== undefined) values.set(hit[1], value);
+  });
+  return { names, values };
+}
+
+/** The first three non-option words of a starci call: its group, verb and action. */
+const listed = (table, group, verb) => (table?.verbs?.[group] ?? []).includes(verb);
+
+/** The reason a listed verb is still refused for its action or options, or null. */
+function narrowReason(table, { group, verb, action }, options) {
+  const actions = table.actions?.[verb];
+  if (actions?.includes(action) === false) return `starci ${[group, verb, action].filter(Boolean).join(' ')} is not an action of the Supervisor seat (${actions.join(', ')})`;
+  const blocked = (table['read-flags']?.[verb] ?? []).find((flag) => options.names.has(flag));
+  if (blocked) return `starci ${group} ${verb} --${blocked} changes state: the menu's decision verb does it`;
+  if (verb === 'actions' && action === 'record' && !new RegExp(table['record-items']).test(options.values.get('item') ?? '')) {
+    return 'starci supervisor actions record is allowed for a runtime defect only: --item runtime-defect:<cause>';
+  }
+  return null;
+}
+
+/** Whether the seat may run `starci <group> <verb> [action]` with these options: {allowed, reason?}. */
+function supervisorSeatAllows(table, words, args = []) {
+  const [group, verb, action] = words;
+  if (!listed(table, group, verb)) return { allowed: false, reason: `starci ${group} ${verb} is not a verb of the Supervisor seat` };
+  const reason = narrowReason(table, { group, verb, action }, optionsOf(args));
+  return reason ? { allowed: false, reason } : { allowed: true };
+}
+
+const useOf = (table) => table.use;
+
+/** A runtime-change verb the seat tried (land, a fix worker): the Debug code, with the menu as the way on. */
+function runtimeChangeVerdict({ table, words, text }) {
+  const change = runtimeChangeRefusal(words);
+  if (!change) return null;
+  const use = useOf(table);
+  return refusal(RUNTIME_CHANGE_CODE, text, change.reason, `${change.remedy}\n${use}`, use);
+}
+
+/**
+ * The refusal of a call the Supervisor seat may not make, or null when it may run it. A program other than starci passes only as a
+ * pure read or as a program whose read forms the general policy judges (orca lifecycle, git, npm); the rest is refused.
+ */
+export function supervisorSeatVerdict({ policy, program, args, text }) {
+  const table = policy?.supervisor;
+  if (!table) return null;
+  if (program === 'starci') {
+    const words = plainWords(args, 3);
+    const changed = runtimeChangeVerdict({ table, words, text });
+    if (changed) return changed;
+    const verdict = supervisorSeatAllows(table, words, args);
+    if (verdict.allowed) return null;
+    const use = useOf(table);
+    return refusal('SUPERVISOR_USE_DECIDE', text, `${verdict.reason}: the runtime runs it, and the Supervisor answers the items of its menu`, use, use);
+  }
+  const reads = new Set([...(policy.read ?? []), ...Object.keys(policy['guarded-read'] ?? {}), ...(table.defer ?? [])].map(String));
+  const denied = new Set((table['deny-programs'] ?? []).map(String));
+  if (reads.has(program) && !denied.has(program)) return null;
+  const use = useOf(table);
+  return refusal('SUPERVISOR_STARCI_ONLY', text, `the Supervisor seat runs starci verbs and pure reads: ${program} is neither`, use, use);
+}

package/runtime/scripts/guards/verdict-process.mjs

@@ -0,0 +1,81 @@
+import { fileURLToPath } from 'node:url';
+import { spawnNode } from '../api/node/spawn-node.mjs';
+import { killTree } from '../api/process/kill-tree.mjs';
+import { HOOK_INPUT_LIMITS } from './hook-io.mjs';
+
+const entry = fileURLToPath(new URL('./command-guard.mjs', import.meta.url));
+
+/** Request forced teardown of this call's verifier tree; a failed tree stop is reported after the direct child is stopped. */
+function stopVerifier(child, teardownTimeoutMs) {
+  if (!Number.isInteger(child?.pid) || child.pid <= 0 || child.exitCode !== null) return;
+  let failure;
+  if (process.platform === 'win32') {
+    const stopped = killTree(child.pid, { timeoutMs: teardownTimeoutMs });
+    if (!stopped.ok) {
+      child.kill('SIGKILL');
+      const detail = stopped.output || `exit ${stopped.status}`;
+      failure = new Error(`verifier tree stop failed (${detail})`);
+    }
+  } else {
+    try { process.kill(-child.pid, 'SIGKILL'); }
+    catch (error) {
+      if (error.code !== 'ESRCH') {
+        child.kill('SIGKILL');
+        failure = error;
+      }
+    }
+  }
+  if (child.connected) child.disconnect();
+  child.unref();
+  if (failure) throw failure;
+}
+
+/**
+ * Evaluate a hook in an owned child so synchronous policy work cannot block its caller's deadline.
+ * The promise resolves only after the child sends a decision and exits; startup, IPC and deadline failures reject.
+ * A deadline requests bounded forced teardown of that child's tree and never accepts a late decision.
+ */
+export function runHookVerdict({ input, root, bindings, env = process.env, start = spawnNode,
+  timeoutMs = HOOK_INPUT_LIMITS.verdictTimeoutMs, teardownTimeoutMs = HOOK_INPUT_LIMITS.teardownTimeoutMs } = {}) {
+  return new Promise((resolve, reject) => {
+    const deadline = performance.now() + timeoutMs;
+    let child;
+    let settled = false;
+    let response;
+    const finish = (error, decision) => {
+      if (settled) return;
+      // Event-loop delays can deliver close before the expired timer; elapsed time still owns admission.
+      if (!error && performance.now() >= deadline) error = new Error(`hook verdict deadline exceeded (${timeoutMs} ms)`);
+      settled = true;
+      clearTimeout(timer);
+      if (error) {
+        try { stopVerifier(child, teardownTimeoutMs); }
+        catch (cleanupError) {
+          child?.channel?.unref();
+          child?.unref();
+          reject(new Error(`${error.message}; verifier cleanup failed (${cleanupError.message})`));
+          return;
+        }
+        reject(error);
+      } else resolve(decision);
+    };
+    const timer = setTimeout(() => finish(new Error(`hook verdict deadline exceeded (${timeoutMs} ms)`)), timeoutMs);
+    try {
+      child = start([entry], { env, detached: process.platform !== 'win32', stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });
+      child.once('error', (error) => finish(error));
+      child.on('message', (message) => {
+        if (settled || response) return;
+        if (message?.ok !== true || !Object.hasOwn(message, 'decision')) {
+          finish(new Error(String(message?.error ?? 'hook verifier returned an invalid decision')));
+          return;
+        }
+        response = message;
+      });
+      child.once('close', (code, signal) => {
+        if (response && code === 0 && !signal) finish(null, response.decision);
+        else finish(new Error(`hook verifier exited before its decision (exit ${code}, signal ${signal ?? 'none'})`));
+      });
+      child.send({ input, root, bindings }, (error) => { if (error) finish(error); });
+    } catch (error) { finish(error); }
+  });
+}

package/runtime/scripts/hfs/architecture/dead-exports.mjs

@@ -3,7 +3,7 @@
  *   HFS_UNUSED_EXPORT  an export of an owner's public entry that no production file outside the owner imports is dead.
  *   HFS_UNUSED_FILE    a production source file that no root reaches is dead. Roots: the files an app slot requires
  *                      (main.ts, app.module.ts), every route file (slot tier `route`), the public entry of every package,
- *                      and an api app operation table `operations.ts` (the contract emit reads it by path),
+ *                      the declared API app's registered operation contract consumed by app emit,
  *                      and a source file a framework config of the app names by a relative string literal
  *                      (next.config.ts pointing next-intl at its request config). Specs and tests are not in the graph,
  *                      so a file only a spec imports is dead, on purpose. Type-only imports reach a file.
@@ -42,14 +42,13 @@ import { treeOf } from './required-files.mjs';
 import { globExpression } from '../../lib/glob.mjs';
 import { stagedConsumerSources } from './staged-consumers.mjs';
 import { bindingsOf } from './dead-exports-bindings.mjs';
+import { operationContractRoots } from './operation-contract-roots.mjs';
 
 export const DEAD_EXPORT_RULE_IDS = ['HFS_UNUSED_EXPORT', 'HFS_UNUSED_FILE'];
 
 const PACKAGE_ENTRIES = ['src/index.ts', 'src/index.tsx', 'index.ts', 'index.tsx'];
 const OWNER_ENTRIES = ['index.ts', 'index.tsx'];
 const CHAIN_DEPTH = 6;
-/** The file of an api app that the contract emit reads by path for the typed operation table (BE-OPERATIONS-1): no import reaches it, the emit does. */
-const OPERATION_TABLE_FILE = "operations.ts";
 /** Tiers whose files are not production source that an app serves: judged by no dead-file rule. */
 const UNJUDGED_TIERS = new Set(['none', 'e2e', 'fixtures']);
 const CONFIG_EXTENSIONS = ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '/index.ts', '/index.tsx', '/index.js'];
@@ -139,15 +138,15 @@ const addFrameworkConfigRoots = (graph, config, roots) => {
   for (const app of config.apps ?? []) addAppConfigRoots(graph, config, app, roots);
 };
 
-/** The files the graph serves from: what an app slot requires, every route file, every package entry, every config-named file. */
-function rootFiles(graph, config) {
+/** Roots are required app files, registered operation contracts, routes, package entries and config-named files. */
+function rootFiles(graph, config, context) {
   const roots = new Set();
   for (const [rel, node] of graph.files) {
     if (node.tier === 'route') { roots.add(rel); continue; }
     if (!node.owner || node.tier !== 'app') continue;
     const slot = graph.resolver.slot(node.owner.slot);
     const inside = rel.slice(withoutSlash(node.owner.root).length + 1);
-    if ((slot?.requires ?? []).includes(inside) || inside === OPERATION_TABLE_FILE) roots.add(rel);
+    if ((slot?.requires ?? []).includes(inside)) roots.add(rel);
   }
   for (const [key, owner] of graph.ownerRoots) {
     if (owner.tier !== 'package') continue;
@@ -156,6 +155,7 @@ function rootFiles(graph, config) {
   }
   // A framework config of an app (slot fe.app.next) names sources by string, never by import.
   addFrameworkConfigRoots(graph, config, roots);
+  for (const entry of operationContractRoots(context, graph, config)) roots.add(entry);
   return roots;
 }
 
@@ -163,12 +163,12 @@ const unusedFileViolation = (rel, node) => ({
   ruleId: 'HFS_UNUSED_FILE',
   path: rel, line: 1, column: 1,
   slot: node.slot, owner: node.owner?.root ?? null,
-  message: `${rel} is not reached from any root (an app main.ts or app.module.ts, a route file, a package entry): nothing imports it, so no process runs it. Delete the file, or import it where it is used (a spec alone does not count).`,
+  message: `${rel} is not reached from any root (an app main.ts or app.module.ts, a registered operation contract, a route file, a package entry): nothing consumes it. Delete the file, or import it where it is used (a spec alone does not count).`,
 });
 
 /** HFS_UNUSED_FILE: production files no root reaches through runtime or type-only imports and re-exports. */
-function deadFiles(graph, config) {
-  const roots = rootFiles(graph, config);
+function deadFiles(graph, config, context) {
+  const roots = rootFiles(graph, config, context);
   const forward = Map.groupBy(graph.edges, edge => edge.from);
   const reached = new Set(roots);
   const queue = [...roots];
@@ -355,7 +355,7 @@ export function checkDeadExports({ context, graph, config }) {
   const edgesTo = edgeIndex([...graph.edges, ...testConsumerEdges({ context, graph, config })]);
   const analysis = { ...context, graph, edgesTo, namespaceCheckers: new WeakMap(), namespaceUses: new WeakMap() };
   const exports = ownerExportFindings(analysis, config);
-  const files = deadFiles(graph, config);
+  const files = deadFiles(graph, config, context);
   const dead = exports.violations.length;
   exports.violations.push(...files.violations);
   return { violations: exports.violations, coverage: { status: 'checked', owners: exports.owners, exports: exports.exports, dead, files: files.judged, roots: files.roots, unusedFiles: files.violations.length } };

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 } = {}) {