@starci/hfs 4.0.8 → 4.0.10

package/runtime/scripts/hfs/path-findings.mjs

@@ -1,4 +1,4 @@
-// hfs-path-findings.mjs - the per-path judgements of the slot manifest: what a tracked path is. One function, two surfaces: `hfs check`
+// hfs-path-findings.mjs - the per-path judgements of the slot manifest: what a tracked path is. One function, two surfaces: `starci app check`
 // (checkRepo) runs it over the tracked tree and keeps the findings that have no TypeScript file to sit on; the lint canon's project graph
 // (scripts/hfs/project-graph.mjs) runs it over the same tree and serves the findings on a TypeScript file as ESLint reports.
 //   HFS_SLOT_UNDECLARED / HFS_SLOT_AMBIGUOUS / HFS_SLOT_NOT_ENABLED / HFS_FORBIDDEN_PRESENT / HFS_TOOL_CONFIG_LOCAL / HFS_TRACKED_MUST_BE_IGNORED (R01, R16)

package/runtime/scripts/hfs/repo-identity.mjs

@@ -1,11 +1,14 @@
 // repo-identity.mjs - who a repository is, independent of the folder it is checked out in.
-// A git worktree (D:/starci-lanes/<lane>/<name>) and the main checkout of the same repository are ONE repository:
+// A git worktree (<lanes root>/<lane>/<name>) and the main checkout of the same repository are ONE repository:
 // they carry the same README title, the same stack-declaration project name and the same sibling repositories.
 import fs from 'node:fs';
 import path from 'node:path';
-import { gitOutput } from '../api/git/lib.mjs';
+import { revParseQuery } from '../api/git/rev-parse-query.mjs';
+import { remote as gitRemote } from '../api/git/remote.mjs';
+import { gitOutputOf } from '../lib/git.mjs';
 
-const git = (root, args) => gitOutput(args, { cwd: root }).trim();
+/** One git call (a scripts/api/git call file) in `root`: its trimmed stdout; throws unless git exits 0. */
+const git = (call, root, args) => gitOutputOf(call(args, { cwd: root })).trim();
 const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
 
 /** { repositoryRoot, inWorkTree, home } for `root`: home is the main checkout folder when root is a repository top level. */
@@ -13,9 +16,9 @@ function identityOf(root) {
   let inWorkTree = false, repositoryRoot = false, home = null;
   try {
     // Identity comes from Git only when root IS a repository (or worktree) top level, never a folder inside one.
-    repositoryRoot = real(git(root, ['rev-parse', '--show-toplevel'])) === real(root);
+    repositoryRoot = real(git(revParseQuery, root, ['--show-toplevel'])) === real(root);
     inWorkTree = true;
-    const common = path.resolve(root, git(root, ['rev-parse', '--git-common-dir']));
+    const common = path.resolve(root, git(revParseQuery, root, ['--git-common-dir']));
     if (repositoryRoot && path.basename(common) === '.git') home = path.dirname(common);
   } catch { /* Not a Git work tree; the caller falls back to the folder and package name. */ }
   return { inWorkTree, repositoryRoot, home };
@@ -31,7 +34,7 @@ export function repositoryName(root) {
   if (home) return path.basename(home);
   if (repositoryRoot) {
     try {
-      const remote = git(root, ['remote', 'get-url', 'origin']).replace(/[\/]+$/u, '').replace(/\.git$/iu, '');
+      const remote = git(gitRemote, root, ['get-url', 'origin']).replace(/[\/]+$/u, '').replace(/\.git$/iu, '');
       const name = remote.split(/[\/:]/u).pop();
       if (name) return name;
     } catch { /* No origin remote. */ }

package/runtime/scripts/hfs/rule-params-shape.mjs

@@ -0,0 +1,50 @@
+// rule-params-shape.mjs - the shape of `ruleParams` of an app slot manifest (knowledge/hfs/slots.yaml): the parameters both sides
+// share (`common`), the back end's own (`be`) and the front end's overrides (`fe`). Pure: a parsed manifest in, a list of
+// problems out, in the words of modules/schemas/hfs-slots.schema.yaml. scripts/hfs/slots.mjs (loadSlotManifest) is the reader.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { paramNamesOk } from './param-names.mjs';
+import { kindParamProblems, scenarioProblem } from './declaration-slots.mjs';
+import { roleListProblems, SCHEMA_AUTHORITIES, unitRolesProblems } from './manifest-shape.mjs';
+
+const PROFILES = ['be', 'fe'];
+
+/** The shape problems of `m.ruleParams`. */
+export function ruleParamsProblems(m) {
+  const bad = [];
+  const blockOk = (v) => isPlainObject(v) && Number.isInteger(v.lines) && v.lines >= 2 && Number.isInteger(v.tokens) && v.tokens >= 1 && Object.keys(v).length === 2;
+  const fileLinesOk = (v) => isPlainObject(v) && Number.isInteger(v.soft) && v.soft >= 1 && typeof v.hardGrowth === 'boolean' && Object.keys(v).length === 2;
+  const rp = m.ruleParams;
+  if (!isPlainObject(rp) || Object.keys(rp).some((k) => ![...PROFILES, 'common'].includes(k)) || !isPlainObject(rp.common) || !isPlainObject(rp.be) || (rp.fe !== undefined && !isPlainObject(rp.fe))) bad.push('ruleParams must be a map with common, be and optionally fe');
+  else {
+    // common holds the parameters both sides share; a side may restate one of them (a valid value) as an override, nothing else.
+    const sharedParam = (key, v) => (key === 'fileLines' ? fileLinesOk(v) : blockOk(v));
+    const sideOk = (side, own, extra = []) => own.every((k) => side[k] !== undefined) && Object.entries(side).every(([k, v]) => own.includes(k) || extra.includes(k) || (['fileLines', 'duplicateBlock'].includes(k) && sharedParam(k, v)));
+    // Edition lite: a side's optional `lite` map overrides keys of the same side (never `lite` itself) when the app declares edition lite.
+    const liteOk = (lite, keys) => lite === undefined || (isPlainObject(lite) && Object.keys(lite).length > 0 && Object.keys(lite).every((k) => k !== 'lite' && keys.includes(k)));
+    const BE_OWN = ['infraOwners', 'eventBus', 'specDoubles', 'paramNames', 'suffixes', 'bannedSuffixes', 'contractShape', 'unitRoles', 'logicRoles', 'thinRoles', 'patternScenarios', 'kindPatterns', 'addKinds'];
+    if (Object.keys(rp.common).length !== 2 || !fileLinesOk(rp.common.fileLines) || !blockOk(rp.common.duplicateBlock)) bad.push('ruleParams.common needs exactly fileLines {soft, hardGrowth} and duplicateBlock {lines >= 2, tokens >= 1}');
+    if (!sideOk(rp.be, BE_OWN, ['schemaAuthority', 'lite']) || (rp.be.schemaAuthority !== undefined && !SCHEMA_AUTHORITIES.includes(rp.be.schemaAuthority)) || !liteOk(rp.be.lite, [...BE_OWN, 'fileLines', 'duplicateBlock', 'schemaAuthority'])) bad.push('ruleParams.be needs infraOwners, eventBus, specDoubles, paramNames, suffixes, bannedSuffixes, contractShape {helper}, unitRoles, logicRoles, thinRoles, patternScenarios, kindPatterns and addKinds (fileLines and duplicateBlock live in ruleParams.common, a side may override them); optional: schemaAuthority (' + SCHEMA_AUTHORITIES.join(' | ') + ') and lite (overrides of the same keys)'); else bad.push(...unitRolesProblems(rp.be), ...roleListProblems(rp.be));
+    bad.push(...scenarioProblem(rp.be.patternScenarios), ...kindParamProblems(rp.be, m.triggerKinds));
+    if (!isPlainObject(rp.be.contractShape) || Object.keys(rp.be.contractShape).length !== 1 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(String(rp.be.contractShape.helper))) bad.push('ruleParams.be.contractShape must be {helper: <identifier>}');
+    const owners = rp.be.infraOwners;
+    const ownerId = /^(platform|integrations)\/[a-z][a-z0-9-]*$/;
+    if (!isPlainObject(owners) || !Object.keys(owners).length || !Object.entries(owners).every(([key, list]) => key && Array.isArray(list) && list.every((o) => ownerId.test(String(o))) && new Set(list).size === list.length)) bad.push('ruleParams.be.infraOwners must map a non-empty specifier to a list of unique platform/<capability> or integrations/<provider> owners ([] means nowhere)');
+    const className = /^[A-Z][A-Za-z0-9]*$/;
+    const memberMap = (v, allowEmpty) => isPlainObject(v) && Object.keys(v).length > 0 && Object.values(v).every((list) => Array.isArray(list) && (allowEmpty || list.length > 0) && list.every((x) => className.test(String(x))) && new Set(list).size === list.length);
+    const eventBus = rp.be.eventBus;
+    if (!isPlainObject(eventBus) || Object.keys(eventBus).sort().join() !== 'classes,imports' || !memberMap(eventBus.imports, true) || !memberMap(eventBus.classes, false)) bad.push('ruleParams.be.eventBus must be {imports: {<module>: [unique PascalCase members]}, classes: {<module>: [non-empty unique PascalCase classes]}}');
+    if (!paramNamesOk(rp.be.paramNames)) bad.push('ruleParams.be.paramNames must be a non-empty list of unique {type | typeSuffix, names, nameSuffix?} entries');
+    const roleList = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => /^[a-z][a-z0-9-]*$/.test(String(x))) && new Set(v).size === v.length;
+    if (!roleList(rp.be.suffixes)) bad.push('ruleParams.be.suffixes must be a non-empty list of unique kebab-case role suffixes');
+    if (!roleList(rp.be.bannedSuffixes)) bad.push('ruleParams.be.bannedSuffixes must be a non-empty list of unique kebab-case suffixes');
+    else if (roleList(rp.be.suffixes) && rp.be.suffixes.some((x) => rp.be.bannedSuffixes.includes(x))) bad.push('ruleParams.be.suffixes and bannedSuffixes must be disjoint');
+    const formNames = ['call', 'new', 'curried', 'object', 'primitive', 'array'];
+    const formsOk = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => formNames.includes(x)) && new Set(v).size === v.length;
+    const doubleOk = (v) => isPlainObject(v) && /^[A-Za-z][A-Za-z0-9]*$/.test(String(v.double)) && formsOk(v.forms);
+    const regexOk = (v) => { try { return typeof v === 'string' && v.length > 0 && Boolean(new RegExp(v)); } catch { return false; } };
+    const sd = rp.be.specDoubles;
+    if (!isPlainObject(sd) || Object.keys(sd).sort().join() !== 'doubles,fallback,kit' || typeof sd.kit !== 'string' || !sd.kit || !Array.isArray(sd.doubles) || !sd.doubles.length || !sd.doubles.every((e) => doubleOk(e) && regexOk(e.token) && Object.keys(e).length === 3) || !doubleOk(sd.fallback) || Object.keys(sd.fallback).length !== 2) bad.push('ruleParams.be.specDoubles must be {kit, doubles: [{token: regex, double, forms}], fallback: {double, forms}} with forms drawn from call, new, curried, object, primitive, array');
+    if (rp.fe !== undefined && (!sideOk(rp.fe, [], ['lite']) || !liteOk(rp.fe.lite, ['fileLines', 'duplicateBlock']))) bad.push('ruleParams.fe may only restate fileLines and duplicateBlock of ruleParams.common, and carry a lite override of them');
+  }
+  return bad;
+}

package/runtime/scripts/hfs/rules/app-root.mjs

@@ -0,0 +1,51 @@
+// app-root.mjs - the tree checks of `starci app check` that read the WHOLE app from its root (app-relative paths over every tracked
+// file of both sides): one list of the rule modules of the app root, so scripts/hfs/check.mjs runs them as one step.
+//   HFS_DEP_VERSION_SKEW (R14, deps.mjs), HFS_PEER_INTEGRATION_MISSING (R111, peer-integrations.mjs), the monorepo shape
+//   (HFS_MONO_*, monorepo.mjs), the one cli app (BE_CLI_REQUIRED, cli.mjs), BE_INTEGRATION_SPEC_MISSING (R112,
+//   integration-specs.mjs), FE_GRAPHQL_CONTRACT (R113, fe-contract-documents.mjs), HFS_CI_MISSING_CANON (R13, pipeline.mjs),
+//   BE_TEST_TOPOLOGY (R47, test-topology.mjs), HFS_PROOF_COMMAND_FILE_MISSING (R105, proof-commands.mjs), the app front-end
+//   tree (FE_WIRE_GENERATED, FE_I18N_PLACEMENT, frontend-tree.mjs) and HFS_STACKS_SHAPE (R10, stacks.mjs).
+import { cliFindings } from './cli.mjs';
+import { contractCompatFindings } from './contract-compat.mjs';
+import { depFindings } from './deps.mjs';
+import { dockerFindings } from './docker.mjs';
+import { eventClassContractFindings, patternSpecFindings } from './event-bus.mjs';
+import { feContractFindings } from './fe-contract-documents.mjs';
+import { appFrontendFindings } from './frontend-tree.mjs';
+import { integrationSpecFindings } from './integration-specs.mjs';
+import { kindFindings } from './kinds.mjs';
+import { monorepoFindings } from './monorepo.mjs';
+import { peerIntegrationFindings } from './peer-integrations.mjs';
+import { pipelineFindings } from './pipeline.mjs';
+import { proofCommandFindings } from './proof-commands.mjs';
+import { sagaFindings } from './saga.mjs';
+import { serviceFindings } from './services.mjs';
+import { stacksFindings } from './stacks.mjs';
+import { testTopologyFindings } from './test-topology.mjs';
+
+/**
+ * The findings of the app-root rules: `files` are the root's own tracked paths, `all` every tracked path of the app, `repo` the
+ * resolved app declaration, `resolver` its slot resolver and `pins` the canon pins.
+ */
+export function appRootFindings({ repoRoot, files, all, repo, resolver, pins }) {
+  return [
+    ...depFindings({ repoRoot, files: all }),
+    ...peerIntegrationFindings({ repoRoot, files: all }),
+    ...monorepoFindings({ repoRoot, files: all, repo }),
+    ...dockerFindings({ repoRoot, files: all, repo }),
+    ...cliFindings({ files: all, repo, resolver }),
+    ...contractCompatFindings({ repoRoot, files: all }),
+    ...eventClassContractFindings({ repoRoot, files: all, repo }),
+    ...patternSpecFindings({ repoRoot, files: all, repo }),
+    ...serviceFindings({ repoRoot, files: all, repo }),
+    ...sagaFindings({ repoRoot, files: all }),
+    ...kindFindings({ files: all, repo }),
+    ...integrationSpecFindings({ repoRoot, files: all }),
+    ...feContractFindings({ repoRoot, files: all }),
+    ...pipelineFindings({ repoRoot, files, pins }),
+    ...testTopologyFindings({ repoRoot, files }),
+    ...proofCommandFindings({ repoRoot, files: all, resolver, sides: Object.keys(repo.sides ?? {}) }),
+    ...appFrontendFindings({ repoRoot, files: all, repo }),
+    ...stacksFindings({ repoRoot, files, resolver }),
+  ];
+}

package/runtime/scripts/hfs/rules/cli.mjs

@@ -0,0 +1,37 @@
+// cli.mjs - the one command line of a back end (R147 BE_CLI_REQUIRED).
+//   BE_CLI_REQUIRED       a back end that declares a connection (it has migrations to run) or tracks a command (src/features/cli/)
+//                         declares exactly one app of kind cli, named cli (be/apps/cli), and tracks its image be/apps/cli/Dockerfile:
+//                         one image, run as `cli <group> <command>`. A cli app with another name, or a second one, is refused.
+// Where a command is declared and that every command has its unit spec beside it are eslint-be's (cli-command-shape, and
+// unit-test-colocated over ruleParams.be.unitRoles).
+// Paths are app-relative; the cli app and the cli feature root are read from the slot manifest through the resolver.
+import { found } from './read.mjs';
+
+const CLI_REQUIRED = 'BE_CLI_REQUIRED';
+
+/** The one name of the cli app, its kind, and what its image is called below it. */
+export const CLI_APP = 'cli';
+const CLI_KIND = 'cli';
+const IMAGE = 'Dockerfile';
+const CLI_FEATURE_SLOT = 'be.cli';
+const CLI_APP_SLOT = 'be.app.cli';
+
+/** The findings of R147 over the tracked paths `files` (app-relative) of the app `repo`; `resolver` is the app's. */
+export function cliFindings({ files, repo, resolver }) {
+  if (!repo?.sides) return [];
+  const be = repo.sides.be;
+  const beResolver = resolver.sides?.be ?? resolver;
+  const onBe = files.filter((file) => file.startsWith('be/')).map((file) => file.slice('be/'.length));
+  const tracked = new Set(onBe);
+  const commandFiles = onBe.filter((file) => beResolver.classifyPath(file).slot === CLI_FEATURE_SLOT);
+  const findings = [];
+  const cliApps = be.apps.filter((app) => app.kind === CLI_KIND);
+  // Where the cli app is only optional (litePresence: schema migration is the Supabase CLI's job) a connection no longer forces it; a tracked command still does.
+  const migrates = (be.connections ?? []).length > 0 && beResolver.slot(CLI_APP_SLOT)?.presence !== 'optional';
+  const needs = migrates || commandFiles.length > 0;
+  const why = migrates ? `it declares the connection${be.connections.length === 1 ? '' : 's'} ${be.connections.map((c) => c.name).join(', ')} (their migrations run as \`cli migrate run\`)` : 'it tracks commands under be/src/features/cli/';
+  if (needs && cliApps.length === 0) findings.push(found(CLI_REQUIRED, 'hfs.json', `the back end declares no cli app, but ${why}; declare { "name": "${CLI_APP}", "kind": "${CLI_KIND}" } in sides.be.apps and build be/apps/${CLI_APP} on nest-commander: every one-off action of the back end is one of its commands.`, { needs: why }));
+  for (const app of cliApps.filter((entry) => entry.name !== CLI_APP)) findings.push(found(CLI_REQUIRED, 'hfs.json', `the cli app is named ${app.name}; the back end has ONE cli app, be/apps/${CLI_APP}, so its image and its command line are the same in every app.`, { app: app.name }));
+  if (cliApps.length > 0 && !tracked.has(`apps/${CLI_APP}/${IMAGE}`) && cliApps.some((app) => app.name === CLI_APP)) findings.push(found(CLI_REQUIRED, `be/apps/${CLI_APP}/${IMAGE}`, `be/apps/${CLI_APP} has no image: track be/apps/${CLI_APP}/${IMAGE}, the one cli image every one-off action runs from (\`cli <group> <command>\`).`, { app: CLI_APP }));
+  return findings;
+}

package/runtime/scripts/hfs/rules/contract-compat.mjs

@@ -0,0 +1,71 @@
+// contract-compat.mjs - event contracts evolve only additively (BE_CONTRACT_BREAKING, R177).
+//
+// A service publishes its events in `be/contracts/<service>/events.json` (the vendored snapshot hfs emits from the service's event table).
+// The previous published contract is pinned beside it as `be/contracts/<service>/events.pin.json` (the same format, copied when a contract is
+// published). The current snapshot is compared with its pin, event by event:
+//   - every pinned event still exists under the same key, with the same `stream` and `version`;
+//   - every pinned payload field still exists with the same type and the same optionality (`<type>` or `<type>?`);
+//   - a field that is new is optional (events already on the wire do not carry it);
+//   - any other member the pinned event declared (for example `compensates`) is unchanged.
+// Anything else is a breaking change: it needs a NEW event key `<event>.v2` next to the old one, which stays until its consumers have moved.
+// A new event, and a new optional field, are additive and pass. A service with no pin is not judged (the pin is opt-in per service).
+import path from 'node:path';
+import { isPlainObject } from '../../../engine/plain-object.mjs';
+import { found, readJson } from './read.mjs';
+
+export const CONTRACT_BREAKING = 'BE_CONTRACT_BREAKING';
+
+const CONTRACTS = /^be\/contracts\/([^/]+)\/events\.pin\.json$/;
+
+const same = (a, b) => JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b));
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortKeys(value[key])]));
+}
+/** {type, optional} of a payload field spelling (`string`, `number?`, `string[]`). */
+const fieldOf = (spelling) => (typeof spelling === 'string' && spelling.endsWith('?') ? { type: spelling.slice(0, -1), optional: true } : { type: spelling, optional: false });
+
+/** The breaking changes of `current` against `pinned`: [{event, message}]. */
+export function breakingChanges(pinned, current) {
+  const problems = [];
+  const pinnedEvents = isPlainObject(pinned?.events) ? pinned.events : {};
+  const currentEvents = isPlainObject(current?.events) ? current.events : {};
+  for (const [name, before] of Object.entries(pinnedEvents)) {
+    const after = currentEvents[name];
+    if (!isPlainObject(after)) { problems.push({ event: name, message: `event ${name} was removed; a published event is never deleted while it can still be on the wire. Keep it, and add ${name}.v2 for the new shape.` }); continue; }
+    for (const key of Object.keys(before)) {
+      if (key === 'payload') continue;
+      if (!same(before[key], after[key])) problems.push({ event: name, message: `event ${name} changed its ${key} from ${JSON.stringify(before[key])} to ${JSON.stringify(after[key] ?? null)}; a published event keeps its ${key}. Add ${name}.v2 for the new shape.` });
+    }
+    const was = isPlainObject(before.payload) ? before.payload : {};
+    const now = isPlainObject(after.payload) ? after.payload : {};
+    for (const [field, spelling] of Object.entries(was)) {
+      if (!(field in now)) { problems.push({ event: name, message: `event ${name} lost payload field ${field}; fields are only ever added. Keep it, and add ${name}.v2 for the new shape.` }); continue; }
+      const a = fieldOf(spelling);
+      const b = fieldOf(now[field]);
+      if (a.type !== b.type) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.type} to ${b.type}; a field keeps its type. Add ${name}.v2 for the new shape.` });
+      else if (a.optional !== b.optional) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.optional ? 'optional' : 'required'} to ${b.optional ? 'optional' : 'required'}; a field keeps its optionality. Add ${name}.v2 for the new shape.` });
+    }
+    for (const [field, spelling] of Object.entries(now)) {
+      if (!(field in was) && !fieldOf(spelling).optional) problems.push({ event: name, message: `event ${name} gained required payload field ${field}; events already on the wire do not carry it, so a new field is optional (${field}?). Make it optional, or add ${name}.v2.` });
+    }
+  }
+  return problems;
+}
+
+/** R177: the findings of every service whose contract is pinned. `files` are the repository-relative tracked paths. */
+export function contractCompatFindings({ repoRoot, files }) {
+  const findings = [];
+  for (const rel of [...files].sort()) {
+    const match = CONTRACTS.exec(rel);
+    if (!match) continue;
+    const current = `be/contracts/${match[1]}/events.json`;
+    const pinned = readJson(repoRoot, rel);
+    const snapshot = readJson(repoRoot, current);
+    if (!isPlainObject(pinned) || !isPlainObject(pinned.events)) { findings.push(found(CONTRACT_BREAKING, rel, `${rel} is not a readable event contract (an object with an events table); copy a published ${path.posix.basename(current)} over it.`)); continue; }
+    if (!isPlainObject(snapshot) || !isPlainObject(snapshot.events)) { findings.push(found(CONTRACT_BREAKING, current, `${current} is missing or unreadable while ${rel} pins the contract of service ${match[1]}; the contract of a published service is never dropped. Emit it again.`)); continue; }
+    for (const { event, message } of breakingChanges(pinned, snapshot)) findings.push(found(CONTRACT_BREAKING, current, `${current}: ${message}`, { event, service: match[1] }));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/contract.mjs

@@ -2,7 +2,7 @@
 //   a be side with a GraphQL transport commits `contracts/<app>/schema.graphql` for each api app, and an api app with an operation table
 //   commits `contracts/<app>/openapi.json`. The fe side of the same app reads those snapshots where they are (`be/contracts/`, the one
 //   cross-side read of hfs.json sides.fe.reads) for its codegen: there is no copy to keep equal.
-// The snapshots are generated by `npm run contract:emit` (`hfs emit-contracts`, packages/hfs/emit/contracts.mjs): printSchema of the
+// The snapshots are generated by `npm run contract:emit` (`starci app emit`, packages/hfs/emit/contracts.mjs): printSchema of the
 // resolvers the app root composes, and the OpenAPI 3.1 document of the typed operation table `apps/<app>/src/operations.ts`.
 // That the committed snapshot equals what the app emits now is contractEmitFindings (full pass only, never --fast): it emits every
 // api app into a temp directory through the injected `emit` (packages/hfs/emit) and compares hashes; an emit that cannot run is a finding.
@@ -10,20 +10,20 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { found } from './read.mjs';
-import { safeRemoveTree } from '../../api/fs/safe-remove.mjs';
+import { found, readText } from './read.mjs';
+import { safeRemove } from '../../api/fs/safe-remove.mjs';
 
 export const CONTRACT_SNAPSHOT_DRIFT = 'HFS_CONTRACT_SNAPSHOT_DRIFT';
-export const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
+const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
 const SNAPSHOT_OF = { graphql: 'schema.graphql', json: 'openapi.json' };
 
 /** sha256 of a file's text with line endings folded, or null when it cannot be read. */
-export function contractHash(file) {
+function contractHash(file) {
   try { return createHash('sha256').update(fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n')).digest('hex'); } catch { return null; }
 }
 
 /** The findings of R23 for the be side at `repoRoot` (a side of another profile has none). */
-export function contractFindings({ files, repo, resolver }) {
+export function contractFindings({ repoRoot, files, repo, resolver }) {
   const findings = [];
   if (repo.profile !== 'be') return findings;
   const serves = files.some((file) => resolver.classifyPath(file).slot === GRAPHQL_TRANSPORT_SLOT);
@@ -31,7 +31,8 @@ export function contractFindings({ files, repo, resolver }) {
   for (const app of repo.apps.filter((a) => a.kind === 'api')) {
     const operations = `contracts/${app.name}/${SNAPSHOT_OF.json}`;
     if (tracked.has(`apps/${app.name}/src/operations.ts`) && !tracked.has(operations)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, operations, `${app.name} declares an operation table (apps/${app.name}/src/operations.ts) but ${operations} is not committed; declare be.contract.openapi in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
-    if (!serves) continue;
+    // An app serves GraphQL when its root module composes the platform graphql capability; a repository with a GraphQL transport slot does not make every api app one.
+    if (!serves || !(readText(repoRoot, `apps/${app.name}/src/app.module.ts`) ?? '').includes('platform/graphql')) continue;
     const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
     if (!tracked.has(snapshot)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${app.name} serves GraphQL but ${snapshot} is not committed; declare be.contract.graphql in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
   }
@@ -65,7 +66,7 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
       } catch (error) {
         for (const { artifact } of artifacts) apps.push({ app: app.name, artifact, status: 'emit-failed' });
         const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
-        findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `contracts/${app.name} cannot be verified: \`hfs emit-contracts\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
+        findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `contracts/${app.name} cannot be verified: \`starci app emit\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
         continue;
       }
       for (const { artifact, what } of artifacts) {
@@ -94,7 +95,7 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
     }
   } finally {
     // A temp directory this rule made itself, in no ledger's repository: no indexed job artifact can live in it.
-    safeRemoveTree(scratch, { hold: () => null });
+    safeRemove(scratch, { hold: () => null });
   }
   return { findings, apps };
 }

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

@@ -0,0 +1,102 @@
+// database-config.mjs - L08 Supabase TOML policy and L09 generated-type drift checks. Parsing and type emission stay
+// lazy/injected so applications without Supabase do not load either tool and this rule starts no Docker process.
+import { sameText } from '../../lib/same-text.mjs';
+import { found, readText } from './read.mjs';
+import { DB_CONFIG_POLICY, DB_TYPES_DRIFT, TYPES_FILE } from './database-constants.mjs';
+const ENV_REF = /^env\([A-Za-z_][A-Za-z0-9_]*\)$/;
+const PUBLIC_KEYS = new Set(['anon_key', 'publishable_key', 'public_key']);
+
+
+function tomlEntries(value, path = []) {
+  if (!value || typeof value !== 'object') return [];
+  if (Array.isArray(value)) return value.flatMap((item) => tomlEntries(item, path));
+  return Object.entries(value).flatMap(([key, child]) => {
+    const at = [...path, key];
+    if (child && typeof child === 'object') {
+      if (Array.isArray(child)) {
+        if (child.every((item) => item && typeof item === 'object' && !Array.isArray(item))) return child.flatMap((item) => tomlEntries(item, at));
+      } else return tomlEntries(child, at);
+    }
+    return [[at.join('.'), key, child]];
+  });
+}
+
+const isCredentialKey = (key) => {
+  const leaf = key.toLowerCase();
+  return ['secret', 'client_id', 'key', 'pass', 'password', 'token'].includes(leaf)
+    || /_(secret|password|token|client_id|api_key)$/.test(leaf)
+    || (leaf.endsWith('_key') && !PUBLIC_KEYS.has(leaf));
+};
+
+const tomlLine = (text, key) => {
+  const expression = new RegExp(`^\\s*["']?${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']?\\s*=`, 'm');
+  const match = expression.exec(text);
+  return match ? text.slice(0, match.index).split('\n').length : undefined;
+};
+
+/** The parsed TOML of `text`, or null when it does not parse. */
+export async function parseToml(text) {
+  try {
+    const module = await import('smol-toml');
+    return (module.default?.parse ?? module.parse)(text);
+  } catch {
+    return null;
+  }
+}
+
+/** L08 policy findings in one already-parsed supabase/config.toml. */
+export function configFindings({ file, text, toml, supabase }) {
+  const findings = [];
+  for (const [at, key, value] of tomlEntries(toml)) {
+    if (!isCredentialKey(key)) continue;
+    const line = tomlLine(text, key);
+    if (typeof value !== 'string' || !ENV_REF.test(value)) {
+      findings.push(found(DB_CONFIG_POLICY, file, `${file}${line ? `:${line}` : ''} ${at} holds a literal credential; a secret in config.toml is written env(NAME), never a value`, { ...(line ? { line } : {}), key: at }));
+    }
+  }
+  const auth = toml?.auth ?? {};
+  if (auth.jwt_expiry !== undefined && (typeof auth.jwt_expiry !== 'number' || auth.jwt_expiry > 3600)) {
+    findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.jwt_expiry is ${JSON.stringify(auth.jwt_expiry)}; the access token lives at most 3600 seconds`, { key: 'auth.jwt_expiry' }));
+  }
+  if (!supabase) return findings;
+  const declared = {
+    enableSignup: supabase.enableSignup, jwtExpiry: supabase.jwtExpiry, siteUrl: supabase.siteUrl,
+    redirectUrls: Array.isArray(supabase.redirectUrls) ? supabase.redirectUrls : undefined,
+  };
+  if (declared.jwtExpiry !== undefined && auth.jwt_expiry !== declared.jwtExpiry) {
+    findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.jwt_expiry is ${JSON.stringify(auth.jwt_expiry ?? 'absent')}; hfs.json supabase.jwtExpiry declares ${declared.jwtExpiry}`, { key: 'auth.jwt_expiry', declared: declared.jwtExpiry }));
+  }
+  if (declared.enableSignup !== undefined) {
+    if (auth.enable_signup !== declared.enableSignup) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.enable_signup is ${JSON.stringify(auth.enable_signup ?? 'absent')}; hfs.json supabase.enableSignup declares ${declared.enableSignup} - the invite posture is a checked fact, not a doc claim`, { key: 'auth.enable_signup', declared: declared.enableSignup }));
+    if (auth.email?.enable_signup !== undefined && auth.email.enable_signup !== declared.enableSignup) {
+      findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.email.enable_signup is ${JSON.stringify(auth.email.enable_signup)}; hfs.json supabase.enableSignup declares ${declared.enableSignup}`, { key: 'auth.email.enable_signup', declared: declared.enableSignup }));
+    }
+  }
+  if (declared.siteUrl !== undefined && auth.site_url !== declared.siteUrl) {
+    findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.site_url is ${JSON.stringify(auth.site_url ?? 'absent')}; hfs.json supabase.siteUrl declares ${declared.siteUrl}`, { key: 'auth.site_url', declared: declared.siteUrl }));
+  }
+  if (declared.redirectUrls !== undefined) {
+    const configured = Array.isArray(auth.additional_redirect_urls) ? auth.additional_redirect_urls : [];
+    for (const url of configured) {
+      if (!declared.redirectUrls.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls holds ${url}, which hfs.json supabase.redirectUrls does not declare; the config states nothing the app did not declare`, { key: 'auth.additional_redirect_urls', url }));
+    }
+    for (const url of declared.redirectUrls) {
+      if (!configured.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls omits ${url}, which hfs.json supabase.redirectUrls declares; the config and declaration must carry the same redirect set`, { key: 'auth.additional_redirect_urls', url }));
+    }
+  }
+  return findings;
+}
+
+/** L09 drift findings for the committed generated database type file. */
+export async function typesFindings({ repoRoot, files, emitTypes, declaration }) {
+  if (typeof emitTypes !== 'function') return [];
+  const tracked = new Set(files);
+  let emitted;
+  try { emitted = await emitTypes({ repoRoot, declaration }); } catch (error) {
+    return [found(DB_TYPES_DRIFT, TYPES_FILE, `${TYPES_FILE} cannot be verified: the types emit failed (${String(error?.message ?? error).split('\n').filter(Boolean).slice(0, 3).join(' | ')})`, { drift: 'emit-failed' })];
+  }
+  const committed = tracked.has(TYPES_FILE) ? readText(repoRoot, TYPES_FILE) : null;
+  if (committed === null) return [found(DB_TYPES_DRIFT, TYPES_FILE, `${TYPES_FILE} is not committed; run \`npm run contract:emit\` and commit the generated types`, { drift: 'not-committed' })];
+  if (!sameText(committed, String(emitted))) return [found(DB_TYPES_DRIFT, TYPES_FILE, `${TYPES_FILE} differs from what \`contract:emit\` generates from the migrations now; run \`npm run contract:emit\` and commit the result`, { drift: 'stale' })];
+  return [];
+}

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

@@ -0,0 +1,13 @@
+// Single source of database-rule finding codes and owned Supabase paths.
+export const DB_MIGRATION_SHAPE = 'DB_MIGRATION_SHAPE';
+export const DB_RLS_REQUIRED = 'DB_RLS_REQUIRED';
+export const DB_DYNAMIC_DDL = 'DB_DYNAMIC_DDL';
+export const DB_POLICY_SHAPE = 'DB_POLICY_SHAPE';
+export const DB_DEFINER_SAFE = 'DB_DEFINER_SAFE';
+export const DB_STORAGE_POLICY = 'DB_STORAGE_POLICY';
+export const DB_CONFIG_POLICY = 'DB_CONFIG_POLICY';
+export const DB_TYPES_DRIFT = 'DB_TYPES_DRIFT';
+
+export const MIGRATIONS_DIR = 'supabase/migrations';
+export const CONFIG_FILE = 'supabase/config.toml';
+export const TYPES_FILE = 'supabase/types/database.types.ts';

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

@@ -0,0 +1,111 @@
+// database-migrations.mjs - L02 migration name, UTC ordering and base-branch immutability checks. Git reads go
+// through the runtime API call files, and specs may inject the same small runner contract used by database.mjs.
+import { lsTree } from '../../api/git/ls-tree.mjs';
+import { log } from '../../api/git/log.mjs';
+import { mergeBase } from '../../api/git/merge-base.mjs';
+import { show } from '../../api/git/show.mjs';
+import { withoutGitLocalEnv } from '../../lib/git.mjs';
+import { sameText } from '../../lib/same-text.mjs';
+import { found, readText } from './read.mjs';
+import { DB_MIGRATION_SHAPE, MIGRATIONS_DIR } from './database-constants.mjs';
+const MIGRATION_NAME = /^(\d{14})_([a-z0-9]+(?:-[a-z0-9]+)*)\.sql$/;
+
+/** `<ts14>` -> the UTC instant it names, or null when the digits are no real time (month 13, day 32, ...). */
+export function migrationStamp(text) {
+  const [year, month, day, hour, minute, second] = [Number(text.slice(0, 4)), ...[4, 6, 8, 10, 12].map((at) => Number(text.slice(at, at + 2)))];
+  const stamp = Date.UTC(year, month - 1, day, hour, minute, second);
+  const date = new Date(stamp);
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
+    && date.getUTCHours() === hour && date.getUTCMinutes() === minute && date.getUTCSeconds() === second ? stamp : null;
+}
+
+/** The three git reads L02 makes: (args, {cwd}) -> {ok, stdout}. */
+export function defaultGit(args, { cwd }) {
+  const [verb, ...rest] = args;
+  const env = withoutGitLocalEnv(process.env);
+  if (verb === 'merge-base') { const sha = mergeBase(cwd, rest[0], rest[1]); return { ok: sha !== null, stdout: sha ?? '' }; }
+  const call = verb === 'ls-tree' ? lsTree : verb === 'log' ? log : show;
+  const result = call(rest, { cwd, env, maxBuffer: 64 * 1024 * 1024 });
+  return { ok: !result.error && result.status === 0, stdout: result.stdout };
+}
+
+const runGit = (git, repoRoot, args) => Promise.resolve(git(args, { cwd: repoRoot }))
+  .then((result) => ({ ok: result?.ok === true, stdout: String(result?.stdout ?? '') }));
+
+async function baseShaOf(git, repoRoot, base) {
+  for (const ref of base ? [base] : ['origin/main', 'main']) {
+    const result = await runGit(git, repoRoot, ['merge-base', 'HEAD', ref]);
+    if (result.ok && result.stdout.trim()) return { ref, sha: result.stdout.trim() };
+  }
+  return null;
+}
+
+async function baseMigrationNames(git, repoRoot, sha) {
+  const result = await runGit(git, repoRoot, ['ls-tree', '-r', '--name-only', '-z', sha, '--', MIGRATIONS_DIR]);
+  if (!result.ok) return [];
+  const prefix = `${MIGRATIONS_DIR}/`;
+  return result.stdout.split('\0').filter(Boolean).map((entry) => (entry.startsWith(prefix) ? entry.slice(prefix.length) : entry));
+}
+
+async function baseFileText(git, repoRoot, sha, file) {
+  const result = await runGit(git, repoRoot, ['show', `${sha}:${file}`]);
+  return result.ok ? result.stdout : null;
+}
+
+async function migrationTimeLimit(git, repoRoot, file, now) {
+  const result = await runGit(git, repoRoot, ['log', '-1', '--format=%ct', '--', file]);
+  const seconds = Number(result.stdout.trim());
+  if (result.ok && Number.isFinite(seconds) && seconds > 0) return { at: seconds * 1000, tracked: true };
+  return { at: now(), tracked: false };
+}
+
+
+/** L02 findings for names, stamps, ordering and immutability of supabase/migrations/*.sql. */
+export async function migrationShapeFindings({ repoRoot, migrations, git, base, now }) {
+  const findings = [];
+  const prefix = `${MIGRATIONS_DIR}/`;
+  const local = migrations.map((file) => {
+    const name = file.startsWith(prefix) ? file.slice(prefix.length) : file;
+    return { file, name, match: MIGRATION_NAME.exec(name) };
+  });
+  const stamps = new Map();
+  for (const entry of local) {
+    if (!entry.match) {
+      findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is not named <ts14>_<kebab>.sql; a migration is created by \`npm run db:new\` (supabase migration new), never renamed by hand`, { expected: '<ts14>_<kebab>.sql' }));
+      continue;
+    }
+    const stamp = migrationStamp(entry.match[1]);
+    if (stamp === null) {
+      findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} carries ${entry.match[1]}, which is no valid UTC time; the stamp is the real creation time`, { stamp: entry.match[1] }));
+      continue;
+    }
+    const limit = await migrationTimeLimit(git, repoRoot, entry.file, now);
+    if (stamp > limit.at) {
+      const boundary = limit.tracked ? `the file's commit time ${new Date(limit.at).toISOString()}` : `the current time ${new Date(limit.at).toISOString()}`;
+      findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, in the future relative to ${boundary}; a migration stamp is its real creation time, never a hand-picked date`, { stamp: entry.match[1], tracked: limit.tracked }));
+    }
+    if (stamps.has(stamp)) findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} shares stamp ${entry.match[1]} with ${stamps.get(stamp)}; stamps are strictly increasing`, { stamp: entry.match[1], other: stamps.get(stamp) }));
+    stamps.set(stamp, entry.file);
+  }
+  const baseSha = await baseShaOf(git, repoRoot, base);
+  if (!baseSha) return findings;
+  const baseNames = await baseMigrationNames(git, repoRoot, baseSha.sha);
+  const onBase = new Set(baseNames);
+  const baseStamps = baseNames.map((name) => MIGRATION_NAME.exec(name)?.[1]).filter(Boolean).map(migrationStamp).filter((stamp) => stamp !== null);
+  const baseMax = baseStamps.length ? Math.max(...baseStamps) : null;
+  for (const entry of local) {
+    if (!entry.match) continue;
+    const stamp = migrationStamp(entry.match[1]);
+    if (onBase.has(entry.name)) {
+      const committed = await baseFileText(git, repoRoot, baseSha.sha, entry.file);
+      const current = readText(repoRoot, entry.file);
+      if (!sameText(current, committed)) findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} differs from its content on ${baseSha.ref}; a migration on the base branch is immutable - write a new migration`, { base: baseSha.ref }));
+    } else if (baseMax !== null && stamp !== null && stamp <= baseMax) {
+      findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, not after every migration on ${baseSha.ref} (latest ${String(new Date(baseMax).toISOString())}); a new migration sorts after the base ones`, { stamp: entry.match[1], base: baseSha.ref }));
+    }
+  }
+  for (const name of baseNames) {
+    if (!local.some((entry) => entry.name === name)) findings.push(found(DB_MIGRATION_SHAPE, `${MIGRATIONS_DIR}/${name}`, `${MIGRATIONS_DIR}/${name} exists on ${baseSha.ref} but is gone here; a migration on the base branch is immutable - restore it`, { base: baseSha.ref }));
+  }
+  return findings;
+}