@starci/hfs 4.7.32 → 4.7.33

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;
+}

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

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
+import { propertyValue } from './function-spec-providers.mjs';
 
 /**
  * R50 `transport-owner` (FE_TRANSPORT_OWNER), the machine half of the eslint transport rules. ESLint judges one file at a time by
@@ -14,14 +15,16 @@ import { machineKit } from './machine-ast.mjs';
  *   - two or more client folders, or two or more unions, in the repository (two apps each keeping one, or a package one plus an
  *     app one) are findings on every copy;
  *   - an app client or app union in a repository where more than one app calls the back end is a finding (it belongs to the package);
- *   - no file outside the client folder references the global `fetch`: a call, `globalThis.fetch`, `window.fetch`, or a
+ *   - no file outside the client folder and the stream reader folder (`fe.transport.stream`, `modules/api/sse/clients/`) references the global `fetch`: a call, `globalThis.fetch`, `window.fetch`, or a
  *     reference passed as a value (`useSWR(key, fetch)`, `const send = fetch`), all of which a spelling-based rule misses; with no
  *     client at all every such reference is a finding that says the repository has no client;
  *   - axios is imported only by the api owner (modules/api, the api package) for its rest calls; every other HTTP library is a
  *     second transport wherever it is imported, by static import, `import()` or `require()`;
  *   - an `ApolloClient` is constructed only inside the client folder;
- *   - every GraphQL operation (`graphql/queries/query-*.ts`, `graphql/mutations/mutation-*.ts`) imports the client (or the api
+ *   - every GraphQL operation (`graphql/queries/query-*.ts`, `graphql/mutations/mutation-*.ts`, `graphql/subscriptions/subscription-*.ts`) imports the client (or the api
  *     package that holds it), so an operation is a caller of the one transport and not a second one.
+ *   - every stream operation (`sse/<area>/stream-*.ts`) imports the stream reader, so a server-sent-events stream is read by the
+ *     transport client layer and not by a fetch of its own.
  */
 export const TRANSPORT_OWNER_RULE_IDS = ['FE_TRANSPORT_OWNER'];
 
@@ -34,11 +37,14 @@ const APP_CLIENT_SLOT = 'fe.transport.client';
 const APP_OUTCOME_SLOT = 'fe.transport.outcome';
 const PACKAGE_API_SLOT = 'fe.package.api';
 const CLIENT_SLOTS = new Set([APP_CLIENT_SLOT, 'fe.package.api.client']);
+/** The stream reader (server-sent events) is the second half of the transport client layer: it may call `fetch`, and it is no second Apollo client folder. */
+const STREAM_SLOT = 'fe.transport.stream';
 /** The api owner: the slots whose files may import axios (the rest calls and the client's own links). */
 const API_OWNER_SLOTS = new Set(['fe.modules.api', PACKAGE_API_SLOT, ...CLIENT_SLOTS]);
 /** The slots that hold the GraphQL operations of an app or of the api package. */
 const OPERATION_SLOTS = new Set(['fe.modules.api', PACKAGE_API_SLOT]);
-const OPERATION_FILE = /^(?:query|mutation)-[^/]+\.ts$/u;
+const OPERATION_FILE = /^(?:query|mutation|subscription)-[^/]+\.ts$/u;
+const STREAM_OPERATION_FILE = /^stream-[^/]+\.ts$/u;
 const NO_CLIENT = "the repository has no transport client. Create the one Apollo client folder (packages/<family>-api/src/graphql/clients/, or the only app's modules/api/graphql/clients/) and call the back end through it.";
 
 /** True when `node` names the global fetch: no import, and no declaration outside a lib declaration file. */
@@ -108,11 +114,25 @@ function inspectLibraryImport({ ts, file, node, transport, report }) {
   report(file, node, `${specifier.text} is a second HTTP transport in ${file.rel}; ${where}.`, { library: specifier.text });
 }
 
+/** True when a call of fetch declares, in its init object literal, the request header accept: "text/event-stream". */
+function asksForEventStream(ts, node) {
+  const call = node.parent && ts.isCallExpression(node.parent) && node.parent.expression === node ? node.parent : null;
+  const init = call?.arguments[1];
+  if (!init || !ts.isObjectLiteralExpression(init)) return false;
+  const headers = propertyValue(ts, init, 'headers');
+  const accept = headers && ts.isObjectLiteralExpression(headers) ? propertyValue(ts, headers, 'accept') : null;
+  return Boolean(accept && ts.isStringLiteralLike(accept) && accept.text === 'text/event-stream');
+}
+
 function inspectTransportNode(scope, node) {
   const { ts, kit, checker, file, isClient, owned, report } = scope;
   const fetchUse = globalFetchUse(ts, kit, checker, node);
   if (fetchUse !== null) {
     if (isClient) return false;
+    if (file.slot === STREAM_SLOT) {
+      if (!asksForEventStream(ts, node)) report(file, node, `${file.rel} fetches something other than an event stream; the stream reader folder reads server-sent events only (accept: "text/event-stream"), every other request is an operation of modules/api run by Apollo or axios.`);
+      return false;
+    }
     if (fetchUse === 'property') report(file, node, `${node.getText(file.sourceFile)} reaches the global fetch outside the transport client; ${owned}`);
     else report(file, node, `fetch is used outside the transport client (called, aliased or passed as a value); ${owned}`);
     return false;
@@ -131,6 +151,27 @@ function reachesClient(graph, file, clientRels) {
   });
 }
 
+/** True for a stream operation of the app's api layer: `modules/api/sse/<area>/stream-<channel>.ts`. */
+function isStreamOperation(file) {
+  return file.slot === 'fe.modules.api' && STREAM_OPERATION_FILE.test(path.posix.basename(file.rel)) && path.posix.basename(path.posix.dirname(path.posix.dirname(file.rel))) === 'sse';
+}
+
+/** True when the stream operation imports a file of the stream reader folder. */
+function reachesStreamReader(graph, file) {
+  return graph.edges.some(edge => edge.from === file.rel && edge.runtime && graph.files.get(edge.to)?.slot === STREAM_SLOT);
+}
+
+/** Only a stream operation (or the reader folder itself) imports the stream reader: a REST call, a GraphQL operation or a hook never does. */
+function inspectReaderImporters({ files, graph, report }) {
+  const byRel = new Map(files.map(file => [file.rel, file]));
+  for (const edge of graph.edges) {
+    if (!edge.runtime || graph.files.get(edge.to)?.slot !== STREAM_SLOT) continue;
+    const from = byRel.get(edge.from);
+    if (!from || from.slot === STREAM_SLOT || isStreamOperation(from)) continue;
+    report(from, from.sourceFile, `${from.rel} imports the stream reader (modules/api/sse/clients); only a stream operation (sse/<area>/stream-<channel>.ts) reads a server-sent-events stream.`);
+  }
+}
+
 function inspectTransportFiles({ files, graph, kit, ts, clientRels, transport, owned, report }) {
   const appsWithFiles = new Set();
   let operations = 0;
@@ -142,7 +183,12 @@ function inspectTransportFiles({ files, graph, kit, ts, clientRels, transport, o
       operations += 1;
       if (!reachesClient(graph, file, clientRels)) report(file, file.sourceFile, `${file.rel} is a GraphQL operation that does not import the transport client; an operation runs through the repository's one Apollo client, never through its own transport.`);
     }
+    if (isStreamOperation(file)) {
+      operations += 1;
+      if (!reachesStreamReader(graph, file)) report(file, file.sourceFile, `${file.rel} is a stream operation that does not import the stream reader (modules/api/sse/clients); a stream operation runs on the transport client layer's reader, never on a fetch of its own.`);
+    }
   }
+  inspectReaderImporters({ files, graph, report });
   return { appsWithFiles, operations };
 }
 

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

@@ -311,7 +311,7 @@ const packageIndexSource = workspace => {
 };
 
 /** The source entry a workspace import resolves to without a build: its export targets mapped back to source, `src/index.ts` for the package root. */
-function workspaceSourceEntry(ts, workspace, specifier) {
+export function workspaceSourceEntry(ts, workspace, specifier) {
   if (!workspace.workspace || !workspace.name || !sameOrUnder(specifier, workspace.name)) return null;
   const isRoot = specifier === workspace.name;
   const candidates = isRoot && !workspace.exports ? manifestEntryTargets(workspace.manifest) : exportCandidates(workspace, specifier);

package/runtime/scripts/hfs/check.mjs

@@ -27,7 +27,9 @@
 //                                 declares a package knowledge/hfs/fe-stack.yaml forbids
 //   HFS_LITE_SECRET_CUSTODY       (R220, rules/supabase-secrets.mjs) under edition lite: secret material or a forbidden custody path; the R06 scan itself runs for every edition
 //   HFS_EDITION_FORBIDDEN_PRESENT (R212, rules/edition.mjs) under edition lite: an e2e, contract, test-stack or browser script, or a
-//                                 dependency of self-hosted infrastructure (test containers, fault proxy, BullMQ, Kafka, Redis)
+//                                 dependency of infrastructure lite does not run (test containers, fault proxy, Kafka)
+//   HFS_BACKING_UNDECLARED, HFS_BACKING_UNUSED (R212, rules/edition.mjs) under edition lite: a client library or a pattern of a backing
+//                                 service hfs.json sides.be.backing does not declare or the edition does not admit, or a declared service no dependency consumes
 //   DB_MIGRATION_SHAPE ... DB_TYPES_DRIFT (R213-R216, rules/database.mjs, async: passed in as extraFindings) the Supabase migrations, policies, definer functions, buckets, config.toml and generated types
 //   BE_SPEC_PLACEMENT             (R102, rules/spec-placement.mjs) a spec or test file outside the four test layers, scripts/ and tools/ included
 //   HFS_REPO_LOCAL_CHECK          (R103, rules/repo-local-checks.mjs) a local eslint rule or plugin, a `check-*` script, a relative import in eslint.config
@@ -108,7 +110,7 @@ export const CHECK_CODES = Object.freeze([
   'HFS_MANAGED_FILE_DRIFT', 'HFS_TOOL_CONFIG_LOCAL', 'HFS_RULE_OFF_WITHOUT_REPLACEMENT', 'HFS_TS_STRICT',
   'HFS_PLAINTEXT_SECRET', 'HFS_STACKS_SHAPE', 'HFS_CI_MISSING_CANON', 'HFS_DEP_VERSION_SKEW', 'HFS_CONTRACT_SNAPSHOT_DRIFT', 'HFS_MCP_TOOLS_SNAPSHOT',
   'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_BYPASS_MARKER', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'BE_INTEGRATION_SPEC_MISSING', 'FE_GRAPHQL_CONTRACT', 'FE_NO_TESTS', 'HFS_MONO_WORKSPACES', 'HFS_MONO_FE_WORKSPACE', 'HFS_MONO_NEST_PROJECTS', 'HFS_MONO_WORKSPACE_DEP', 'BE_CLI_REQUIRED', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG', 'HFS_SERVICE_PLACEMENT', 'HFS_IMAGE_UNPINNED', 'HFS_SERVICE_STACK_DECLARATION', 'HFS_EVENT_CONTRACT', 'BE_ASYNC_SPEC_MISSING', 'BE_SAGA_STEP_COMPENSATION', 'BE_SAGA_STATE_VERSIONED', 'BE_SAGA_EVENT_CONTRACT', 'BE_SAGA_CONSUMER_DEDUPE', 'BE_EVENT_CLASS_CONTRACT', 'BE_PATTERN_SPEC_MISSING', 'BE_CONTRACT_BREAKING', 'BE_KIND_DECLARATION', 'BE_KIND_EMPTY', 'HFS_DOCKER_BUILD_CONTEXT', 'HFS_DOCKER_STAGES', 'HFS_DOCKER_ENTRY', 'HFS_DOCKER_BASE_PIN', 'HFS_DOCKER_SECRETS', 'BE_SAGA_E2E_MISSING',
-  'FE_STACK_FORBIDDEN', 'HFS_EDITION_FORBIDDEN_PRESENT', 'HFS_LITE_SECRET_CUSTODY', 'HFS_STARCIWORK_LITE_FORBIDDEN',
+  'FE_STACK_FORBIDDEN', 'HFS_EDITION_FORBIDDEN_PRESENT', 'HFS_BACKING_UNDECLARED', 'HFS_BACKING_UNUSED', 'HFS_LITE_SECRET_CUSTODY', 'HFS_STARCIWORK_LITE_FORBIDDEN',
   'DB_MIGRATION_SHAPE', 'DB_RLS_REQUIRED', 'DB_DYNAMIC_DDL', 'DB_POLICY_SHAPE', 'DB_DEFINER_SAFE', 'DB_STORAGE_POLICY', 'DB_CONFIG_POLICY', 'DB_TYPES_DRIFT',
   'HFS_DOCKER_HEALTHCHECK_FAKE', 'DB_BE_ONLY_ACCESS', 'DB_REALTIME_UNLISTED', 'DB_APP_ROLE', 'DB_FORCE_RLS_DEFAULT',
   'DB_POLICY_TAUTOLOGY', 'DB_VIEW_UNSAFE', 'DB_STORAGE_PREFIX', 'DB_DEFINER_REVOKE',
@@ -397,11 +399,11 @@ export function checkRepository({ repoRoot, root = skillRoot, fast = false, base
   return withCheckProofs(result, { repoRoot, root, manifest, wiring, coverageFrom });
 }
 
-/** Optional CLI proofs run over the whole tracked tree, including after a dry edition override. */
+/** Optional CLI proofs run over the whole tracked tree. */
 export function withCheckProofs(result, { repoRoot, root = skillRoot, manifest = loadSlotManifest({ root }), wiring = false, coverageFrom, edition } = {}) {
   if ((!wiring && coverageFrom === undefined) || result.profile === null) return result;
   const declared = readRepoDeclaration(manifest, repoRoot);
-  const repo = { ...declared, edition: result.editionOverride?.judged ?? edition ?? declared.edition };
+  const repo = { ...declared, edition: edition ?? declared.edition };
   if (repo.sides) repo.sides = Object.fromEntries(Object.entries(repo.sides).map(([side, declaration]) => [side, { ...declaration, edition: repo.edition }]));
   const context = { repoRoot, repo, manifest, files: trackedFiles(repoRoot) };
   const reports = {};

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

@@ -75,6 +75,33 @@ function addEntryPatterns(sonar, slot, entry, isRole) {
   }
 }
 
+/** Whether `text` fits `pattern`, where each `*` stands for any run of characters. */
+function wildcardMatches(pattern, text) {
+  const parts = pattern.split('*');
+  if (!text.startsWith(parts[0])) return false;
+  let at = parts[0].length;
+  for (const part of parts.slice(1, -1)) {
+    const found = text.indexOf(part, at);
+    if (found < 0) return false;
+    at = found + part.length;
+  }
+  const last = parts.at(-1);
+  return parts.length === 1 ? text === pattern : text.length - last.length >= at && text.endsWith(last);
+}
+
+/** Whether glob segments `glob` match path-or-glob segments `entry` (`**` crosses directories, `*` stays inside one segment). */
+function segmentsCover(glob, entry) {
+  if (glob.length === 0) return entry.length === 0;
+  const [head, ...rest] = glob;
+  if (head === '**') return Array.from({ length: entry.length + 1 }, (_, skipped) => skipped).some((skipped) => segmentsCover(rest, entry.slice(skipped)));
+  if (entry.length === 0 || entry[0].includes('**')) return false;
+  const matches = head.includes('*') ? wildcardMatches(head, entry[0]) : head === entry[0];
+  return matches && segmentsCover(rest, entry.slice(1));
+}
+
+/** The exclusion entries that no other entry already matches: a glob covered by a broader one adds nothing to the scope. */
+export const withoutCovered = (entries) => entries.filter((entry) => !entries.some((other) => other !== entry && segmentsCover(other.split('/'), entry.split('/'))));
+
 /** The directory a path pattern lives in (itself when it is one). */
 const dirOf = (path) => (isDir(path) ? path : path.slice(0, path.lastIndexOf('/') + 1));
 
@@ -114,7 +141,7 @@ export function coverageScope(manifest, providers = []) {
   addRequiredPatterns(sonar, required, suffixes);
   sonar.add('fe/**');
   noneMinimal.sort(byCodeUnit);
-  return { roles, roots, excludes, none: noneMinimal, sonar: [...sonar].sort(byCodeUnit), codecovPaths: roots.map((root) => `be/${root}**`) };
+  return { roles, roots, excludes, none: noneMinimal, sonar: withoutCovered([...sonar]).sort(byCodeUnit), codecovPaths: roots.map((root) => `be/${root}**`) };
 }
 
 /** The glob a root measures: every file of a logic role below it (`src/modules/domain/*\/**\/*.{service,policy}.ts`). */

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

@@ -7,8 +7,48 @@ import { migrationStamp } from './rules/database-migrations.mjs';
 import { MIGRATIONS_DIR, MIGRATIONS_ARCHIVE_DIR } from './rules/database-constants.mjs';
 import { DbVerbError, dbOptions, dbAppRoot, dbSqlFiles, runDbSupabase, repairArgs, dbFailure } from './db-baseline-verb.mjs';
 
-/** YAML maps use quoted UTC stamps as keys and values (or a versions: mapping). */
-function restampPlan(root, mapFile) {
+/** The map value of one old version: a new version, or { file, to, applied } for the colliding-versions case. */
+function mapEntry(old, raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { old, file: null, to: String(raw), applied: undefined };
+  const known = Object.keys(raw).every((key) => ['file', 'to', 'applied'].includes(key));
+  if (!known || (raw.applied !== undefined && typeof raw.applied !== 'boolean') || (raw.file !== undefined && typeof raw.file !== 'string')) throw new DbVerbError('a restamp entry is a new version or { file, to, applied } with a string file and a boolean applied');
+  return { old, file: raw.file ?? null, to: raw.to === undefined ? null : String(raw.to), applied: raw.applied };
+}
+
+/** The first unoccupied version after `old`, one second at a time. */
+function nextFreeVersion(old, occupied) {
+  let moment = migrationStamp(old);
+  for (;;) {
+    moment += 1000;
+    const candidate = new Date(moment).toISOString().replace(/\D/g, '').slice(0, 14);
+    if (!occupied.has(candidate)) return candidate;
+  }
+}
+
+/** The active migration that moves: the only file of its version, or the one an entry names among files that share it. */
+function sourceOf(entry, active) {
+  const sharing = active.filter((file) => file.stamp === entry.old);
+  const named = entry.file === null ? sharing : sharing.filter((file) => [file.name, file.name.slice(15), file.name.slice(15).replace(/\.sql$/, '')].includes(entry.file));
+  if (named.length === 1 && (sharing.length === 1 || entry.file !== null)) return named[0];
+  if (sharing.length > 1) throw new DbVerbError(`version ${entry.old} is shared by ${sharing.map((file) => file.name).join(', ')}; name the file to move: "${entry.old}": { file: <name> }`);
+  throw new DbVerbError('each restamp source must identify exactly one active migration; archives never change');
+}
+
+/**
+ * Whether the history records the file that moves under the shared version `old` (SELECT only: supabase_migrations.schema_migrations keeps the name
+ * of the file that ran). No row means nothing ran; a row named for the other file means the one that stays ran. A history that cannot be read is
+ * not guessed: the entry has to say `applied`.
+ */
+function recordedAsApplied(root, source, old, local, ports) {
+  const unreadable = new DbVerbError(`version ${old} is shared by several migrations and the history could not be read; say which one ran with "${old}": { file: <name>, applied: true|false }`);
+  let rows;
+  try { rows = JSON.parse(runDbSupabase(root, ['db', 'query', `select name from supabase_migrations.schema_migrations where version = '${old}'`, local ? '--local' : '--linked', '--output', 'json', '--agent', 'no'], ports)); } catch { throw unreadable; }
+  if (!Array.isArray(rows) || (rows.length > 0 && typeof rows[0]?.name !== 'string')) throw unreadable;
+  return rows.length > 0 && rows[0].name === source.name.slice(15).replace(/\.sql$/, '');
+}
+
+/** YAML maps use quoted UTC stamps as keys and a new version, or { file, to?, applied? }, as values (or a versions: mapping). */
+function restampPlan(root, mapFile, { local = false, ports = {} } = {}) {
   if (!mapFile) throw new DbVerbError('restamp requires --map <restamp.yaml>');
   let document;
   try { document = parseYaml(fs.readFileSync(path.resolve(root, mapFile), 'utf8')); }
@@ -16,22 +56,22 @@ function restampPlan(root, mapFile) {
   const mapping = document?.versions ?? document;
   if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping) || !Object.keys(mapping).length) throw new DbVerbError('restamp map must contain old-to-new version pairs');
   const active = dbSqlFiles(root);
-  const archived = dbSqlFiles(root, MIGRATIONS_ARCHIVE_DIR);
-  const occupied = new Set([...active, ...archived].map((entry) => entry.stamp));
+  const occupied = new Set([...active, ...dbSqlFiles(root, MIGRATIONS_ARCHIVE_DIR)].map((entry) => entry.stamp));
   const targets = new Set();
   const steps = Object.entries(mapping).map(([old, raw]) => {
-    const next = String(raw);
+    const entry = mapEntry(old, raw);
+    const source = sourceOf(entry, active);
+    const shared = active.filter((file) => file.stamp === old).length > 1;
+    const next = entry.to ?? nextFreeVersion(old, new Set([...occupied, ...targets]));
     if (![old, next].every((stamp) => /^\d{14}$/.test(stamp) && migrationStamp(stamp) !== null) || old === next) throw new DbVerbError('restamp pairs require distinct valid UTC versions');
-    const sources = active.filter((entry) => entry.stamp === old);
-    if (sources.length !== 1) throw new DbVerbError('each restamp source must identify exactly one active migration; archives never change');
     if (occupied.has(next) || targets.has(next)) throw new DbVerbError('restamp targets must be unique unoccupied versions');
     targets.add(next);
-    const source = sources[0];
-    const name = source.name.replace(old, next);
-    return { old, next, source: source.file, target: `${MIGRATIONS_DIR}/${name}` };
+    // a version two files share ran for at most one of them: the history says which, unless the entry does
+    const applied = entry.applied ?? (shared ? recordedAsApplied(root, source, old, local, ports) : true);
+    return { old, next, source: source.file, target: `${MIGRATIONS_DIR}/${source.name.replace(old, next)}`, applied };
   });
-  const replacements = new Map(steps.map((step) => [step.old, step.next]));
-  const resulting = active.map((entry) => replacements.get(entry.stamp) ?? entry.stamp);
+  const moved = new Map(steps.map((step) => [step.source, step.next]));
+  const resulting = active.map((entry) => moved.get(entry.file) ?? entry.stamp);
   if (resulting.some((stamp, index) => index > 0 && stamp <= resulting[index - 1])) throw new DbVerbError('the map must cover every version needed to preserve migration order');
   return steps.sort((left, right) => left.old < right.old ? -1 : 1);
 }
@@ -41,8 +81,8 @@ export function dbRestampMain(argv, { cwd = invocationDir(), stdout = (text) =>
   try {
     const opts = dbOptions(argv, ['cwd', 'map', 'apply', 'local']);
     const root = dbAppRoot(cwd, opts);
-    const steps = restampPlan(root, opts.map);
-    const repairs = steps.flatMap((step) => [repairArgs(step.old, 'reverted', opts.local), repairArgs(step.next, 'applied', opts.local)]);
+    const steps = restampPlan(root, opts.map, { local: opts.local, ports });
+    const repairs = steps.filter((step) => step.applied).flatMap((step) => [repairArgs(step.old, 'reverted', opts.local), repairArgs(step.next, 'applied', opts.local)]);
     stdout(`${opts.apply ? 'apply' : 'preview'} restamp ${steps.length} migrations\n`);
     for (const step of steps) stdout(`${step.source} -> ${step.target}\n`);
     for (const args of repairs) stdout(`supabase ${args.join(' ')}\n`);

package/runtime/scripts/hfs/declaration-shape.mjs

@@ -1,7 +1,7 @@
 // declaration-shape.mjs - the dependency-free hfs.json shape validation used by the HFS slot loader. Semantic checks
 // against a loaded manifest remain in slots.mjs; this module mirrors modules/schemas/hfs-repo.schema.yaml only.
 import { isPlainObject } from '../../engine/plain-object.mjs';
-import { APP_KIND, connectionShapeProblems, NAME, RUNTIME_KIND, SLOT_ID } from './manifest-shape.mjs';
+import { APP_KIND, connectionShapeProblems, NAME, PACKAGE_NAME, RUNTIME_KIND, SLOT_ID } from './manifest-shape.mjs';
 import { kindShapeProblems, patternShapeProblems } from './declaration-slots.mjs';
 import { byCodeUnit } from '../lib/list.mjs';
 
@@ -60,8 +60,6 @@ function connectionProblems(side, value) {
 /** Whether a declared list is present but not a list of distinct entries that all satisfy `valid`. */
 const isBadUniqueList = (list, valid) => list !== undefined && (!Array.isArray(list) || !list.every((entry) => valid(entry)) || new Set(list).size !== list.length);
 
-const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
-
 function validExtraPackage(entry) {
   return isPlainObject(entry) && Object.keys(entry).every(key => key === 'name' || key === 'reason')
     && typeof entry.name === 'string' && entry.name.length <= 214 && PACKAGE_NAME.test(entry.name)
@@ -79,9 +77,11 @@ function declarationSideProblems(side, value, names) {
   const bad = [];
   const at = `sides.${side}`;
   if (!isPlainObject(value)) return [`${at} must be an object`];
-  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages'].includes(key)) bad.push(`${at} has unknown key ${key}`);
+  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'backing'].includes(key)) bad.push(`${at} has unknown key ${key}`);
   bad.push(...appShapeProblems(value.apps, at, side, names));
   if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot)))) bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
+  if (value.backing !== undefined && side !== 'be') bad.push('backing belongs to the be side');
+  else if (isBadUniqueList(value.backing, (name) => NAME.test(String(name)))) bad.push(`${at}.backing must be a unique list of backing service names`);
   bad.push(...patternShapeProblems(value, at, NAME), ...kindShapeProblems(value, at, NAME));
   if (isBadUniqueList(value.reads, (read) => typeof read === 'string' && read.length > 0)) bad.push(`${at}.reads must be a unique list of paths`);
   if (value.connections !== undefined) bad.push(...connectionProblems(side, value));

package/runtime/scripts/hfs/declaration-slots.mjs

@@ -1,7 +1,8 @@
 // declaration-slots.mjs - how an app declaration (hfs.json) switches on the opt-in slots of a side: by name (`optionalSlots`), by app kind
 // (a slot with `appKind`) and by declared pattern (a slot with `pattern: <name>` is enabled by `sides.<side>.patterns: [<name>]`, one
-// mechanism for every pattern: saga, event-bus, fenced-job, ...). slots.mjs asks this file to judge a side's lists and to say whether a
-// slot is enabled for a repository.
+// mechanism for pattern slots). A cross-cutting pattern can instead be owned by the side's canonical proof scenario catalog.
+// slots.mjs asks this file to judge a side's lists and to say whether a slot is enabled for a repository.
+import { judgedInEdition } from './edition-slots.mjs';
 
 /** The problems of a side's `optionalSlots` and `patterns` against the manifest. */
 export function optionalSlotProblems(manifest, side, s) {
@@ -13,7 +14,9 @@ export function optionalSlotProblems(manifest, side, s) {
     else if (slot.appKind !== undefined) bad.push(`sides.${side}.optionalSlots names ${id}; an app of kind ${slot.appKind} enables it`);
   }
   for (const name of s.patterns ?? []) {
-    if (!manifest.slots.some((slot) => slot.profiles.includes(side) && slot.pattern === name)) bad.push(`sides.${side}.patterns names ${name}, which no ${side} slot declares as its pattern`);
+    const ownsSlot = manifest.slots.some((slot) => slot.profiles.includes(side) && slot.pattern === name);
+    const ownsProof = Object.hasOwn(manifest.ruleParams?.[side]?.patternScenarios ?? {}, name);
+    if (!ownsSlot && !ownsProof) bad.push(`sides.${side}.patterns names ${name}, which neither a ${side} slot nor its proof scenario catalog declares`);
   }
   if (s.kinds !== undefined && side !== 'be') bad.push(`sides.${side}.kinds belongs to the be side`);
   for (const kind of s.kinds ?? []) {
@@ -22,6 +25,14 @@ export function optionalSlotProblems(manifest, side, s) {
   return bad;
 }
 
+/** The problems of a side's `backing` list: every name is admitted by ruleParams.be.backing in this edition. */
+export function backingProblems(manifest, side, s, edition = 'full') {
+  const services = Object.entries(manifest.ruleParams?.be?.backing ?? {})
+    .filter(([, entry]) => judgedInEdition(entry, edition)).map(([name]) => name);
+  return (s.backing ?? []).filter((name) => !services.includes(name))
+    .map((name) => `sides.${side}.backing names ${name}, which is not admitted in edition ${edition} by ruleParams.be.backing (${services.join(', ')})`);
+}
+
 /** The problems of the shape of a side's `patterns` list (a unique list of pattern names). */
 export function patternShapeProblems(s, at, namePattern) {
   const list = s.patterns;