@starci/hfs 4.0.8 → 4.0.10

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

@@ -6,7 +6,8 @@ import { machineKit } from './machine-ast.mjs';
  * `client-fetch-has-signal`. ESLint judges one file at a time by the spelling of a call; the machine judges the repository by
  * what the checker resolves. A repository has exactly ONE transport client and ONE Outcome union, both named by slot (never
  * by a path spelled here): the api package's (`fe.package.api.client`, `fe.package.api.outcome`) when the repository shares
- * it, or the only app's (`fe.transport.client`, `fe.transport.outcome`) when the repository declares exactly one app.
+ * it, or the only app's (`fe.transport.client`, `fe.transport.outcome`) when the repository declares exactly one app. The
+ * Outcome homes are the slots the manifest marks `outcomeHome` (the lite edition adds `fe.modules.db.outcome`), not a list kept here.
  *
  *   - two or more clients, or two or more Outcome unions, in the repository (two apps each keeping one, or a package one plus
  *     an app one) are findings on every copy;
@@ -30,7 +31,6 @@ 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']);
-const OUTCOME_SLOTS = new Set([APP_OUTCOME_SLOT, 'fe.package.api.outcome']);
 const NO_CLIENT = "the repository has no transport client. Create the one client (packages/<family>-api/src/client.ts, or the only app's modules/api/client.ts) and call it.";
 
 export function checkTransportOwner(input) {
@@ -60,7 +60,7 @@ export function checkTransportOwner(input) {
 
   const files = [...graph.files.values()].filter(file => file.slot && file.tier !== 'e2e');
   const clients = files.filter(file => CLIENT_SLOTS.has(file.slot));
-  const outcomes = files.filter(file => OUTCOME_SLOTS.has(file.slot));
+  const outcomes = files.filter(file => resolver.slot(file.slot)?.outcomeHome === true);
   const clientRels = new Set(clients.map(file => file.rel));
   const list = items => items.map(item => item.rel).join(', ');
   const owned = clients.length ? `the repository has one transport (${list(clients)}). Call the client and take its Outcome.` : NO_CLIENT;

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

@@ -2,9 +2,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { canonical, isInside, slash } from './config.mjs';
+import { crossesSide } from './side-boundary.mjs';
 import { sameOrUnder } from '../../lib/path-key.mjs';
 import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule, sharedInProgramRun, typeScriptProjectReferencePath } from '../typescript-programs.mjs';
 import { readJsonFile } from '../../lib/json.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 import { locateDeclaration } from '../slots.mjs';
 
 const CODE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
@@ -12,21 +14,11 @@ const TEST_FILE = /(?:^|[.-])(?:spec|test)\.[cm]?[jt]sx?$/i;
 const ASSET_EXTENSION = /\.(?:css|scss|sass|less|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|eot|ya?ml|json)$/i;
 // Framework build output a tsconfig may include (Next writes `.next/types/**/*.ts` back into tsconfig.json on
 // every build) is compiled for type resolution but is never source: it is gitignored, regenerated, and no
-// canon or architecture rule applies to it (starci-next inc-2260b3754afa, nivo inc-ffe60c49f502).
-export const GENERATED_SEGMENTS = new Set(['.next', '.turbo', '.vercel', '.output', '.nuxt', '.svelte-kit', '.expo', '.docusaurus', '.swc', '.cache']);
-export function isGeneratedPath(root, fileName) {
+// canon or architecture rule applies to it (inc-ffe60c49f502).
+const GENERATED_SEGMENTS = new Set(['.next', '.turbo', '.vercel', '.output', '.nuxt', '.svelte-kit', '.expo', '.docusaurus', '.swc', '.cache']);
+function isGeneratedPath(root, fileName) {
   return slash(path.relative(root, fileName)).split('/').slice(0, -1).some(segment => GENERATED_SEGMENTS.has(segment));
 }
-// A `<tool>.config.*` or `<tool>.setup.*` module at the root of a project (beside a package manifest or a tsconfig.json:
-// next.config.ts and postcss.config.mjs of an app, which has no package.json of its own) is build tooling a broad `**/*.ts`
-// include pulls in; a `*.config.ts` inside a source tree (src/config/database.config.ts) has neither beside it and stays source.
-// The architecture program still reads tooling modules (a profile may declare one as source); the lint (hfs lint) judges one only
-// through the repository's own eslint.config.
-const TOOLING_MODULE = /^[^/]+\.(?:config|setup)\.[cm]?[jt]sx?$/i;
-export function isToolingModule(fileName) {
-  return TOOLING_MODULE.test(path.basename(fileName)) && ['package.json', 'tsconfig.json'].some((manifest) => fs.existsSync(path.join(path.dirname(fileName), manifest)));
-}
-
 function diagnosticMessage(ts, diagnostic) {
   return ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
 }
@@ -53,7 +45,7 @@ function compilerError(ts, root, diagnostic, project, ruleId = 'ARCH_TSCONFIG_IN
  * Load TypeScript through the target package boundary, never through StarCi's own dependency graph. A side folder of an app has no
  * package.json of its own: the app root's one manifest is the boundary its TypeScript is installed under.
  */
-export function loadTargetTypeScript(repositoryRoot) {
+function loadTargetTypeScript(repositoryRoot) {
   const packageFile = path.join(locateDeclaration(repositoryRoot).appRoot, 'package.json');
   if (!fs.existsSync(packageFile)) throw Error('ARCH_TYPESCRIPT_MISSING: target package.json is required to resolve target-installed TypeScript.');
   const targetRequire = createRequire(packageFile);
@@ -98,7 +90,7 @@ function runtimeImport(ts, node) {
   return true;
 }
 
-function isUnshadowedCommonJsRequire(ts, checker, expression) {
+export function isUnshadowedCommonJsRequire(ts, checker, expression) {
   if (!ts.isIdentifier(expression) || expression.text !== 'require') return false;
   const symbol = checker?.getSymbolAtLocation(expression);
   if (!symbol) return true;
@@ -113,7 +105,7 @@ function isUnshadowedCommonJsRequire(ts, checker, expression) {
  * existing directory and a data-asset extension tail qualify; code never does, since a context of code would
  * be an import graph nobody wrote down. Returns the specifiers, or null when the import stays unproven.
  */
-export function assetContextSpecifiers(ts, sourceFile, argument) {
+function assetContextSpecifiers(ts, sourceFile, argument) {
   if (!argument || !ts.isTemplateExpression(argument)) return null;
   const head = argument.head.text;
   const spans = argument.templateSpans;
@@ -168,11 +160,6 @@ function moduleReferences(ts, sourceFile, checker) {
   return { found, unproven };
 }
 
-function sourceLocation(sourceFile, node) {
-  const point = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
-  return { line: point.line + 1, column: point.character + 1 };
-}
-
 function isProductionSource(root, sourceFile) {
   return isInside(root, sourceFile.fileName)
     && CODE_EXTENSIONS.test(sourceFile.fileName)
@@ -210,7 +197,7 @@ function exportPatternCapture(pattern, request) {
   return request.startsWith(before) && request.endsWith(after) ? request.slice(before.length, request.length - after.length) : null;
 }
 
-function exportTargetStrings(value) {
+export function exportTargetStrings(value) {
   if (typeof value === 'string') return [value];
   if (Array.isArray(value)) return value.flatMap(exportTargetStrings);
   if (value && typeof value === 'object' && !Object.keys(value).some(key => key.startsWith('.'))) return Object.values(value).flatMap(exportTargetStrings);
@@ -497,9 +484,7 @@ function typeScriptContext(config, loaded, paths) {
         || (config.repository && isInside(config.repository, actualTarget) && !slash(actualTarget).includes('/node_modules/'));
       // A side of an app (config.root is be/ or fe/) imports nothing of the app outside itself: the root holds no source, the other
       // side is another program, and a declared read (sides.fe.reads, be/contracts/) is codegen input, never an import.
-      const crossesSide = config.packageRoot !== undefined && config.packageRoot !== config.root
-        && isInside(config.packageRoot, actualTarget) && !isInside(config.root, actualTarget) && !slash(actualTarget).includes('/node_modules/');
-      if (internal && crossesSide) {
+      if (internal && crossesSide(config, actualTarget)) {
         errors.push({
           ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
           project: project.relative,
@@ -581,6 +566,8 @@ export function unwrapExpression(ts, expression) {
   return expression;
 }
 
+/* ---- the AST walks every architecture checker shares ---- */
+
 /** The names of `expected` an import or re-export statement binds (all of them for a namespace or star form). */
 export function referencedExports(ts, statement, expected) {
   if (ts.isImportDeclaration(statement)) {
@@ -595,4 +582,3 @@ export function referencedExports(ts, statement, expected) {
   return [...expected];
 }
 
-export { isUnshadowedCommonJsRequire, sourceLocation };

package/runtime/scripts/hfs/architecture.mjs

@@ -1,6 +1,6 @@
-// architecture.mjs — the architecture check (docs/architecture-check.md).
+// architecture.mjs — the architecture check (docs/architecture.md).
 //
-//   node scripts/hfs/architecture.mjs <repo-root> [--base <commit>]
+//   starci runtime architecture <repo-root> [--base <commit>]
 //
 // Prints one starci/architecture-check@1 record. Exit 0: ok. Exit 1: violations or errors (a check that
 // cannot run is an error, never a pass). Exit 2: bad arguments.
@@ -11,9 +11,9 @@ import { isMain } from '../lib/is-main.mjs';
 
 export {checkArchitecture};
 
-const USAGE = 'usage: architecture.mjs <repo-root> [--base <commit>]';
+const USAGE = 'usage: starci runtime architecture <repo-root> [--base <commit>]';
 
-export function parseArchitectureArgs(argv) {
+function parseArchitectureArgs(argv) {
   let root = null, base;
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];

package/runtime/scripts/hfs/check.mjs

@@ -1,4 +1,4 @@
-// hfs-check.mjs - the HFS app check, behind `hfs check | explain` (packages/hfs) and reusable by any
+// hfs-check.mjs - the HFS app check, behind `starci app check | explain` (packages/hfs) and reusable by any
 // runtime check. It reads three things and nothing else: the app's hfs.json, the slot manifest
 // (knowledge/hfs/slots.yaml through scripts/hfs/slots.mjs) and the pins (knowledge/hfs/canon-pins.yaml). It never
 // writes to the repository it inspects.
@@ -15,22 +15,29 @@
 //                                 and passed in as `extraFindings` (this module does not read the templates)
 //   HFS_SLOT_REQUIRED_MISSING     a file or directory a required slot (or an instance of one) must contain
 //   HFS_MIN_INSTANCES             fewer instances of a slot than minInstances
-//   HFS_PLAINTEXT_SECRET          (R06, hfs-rules/secrets.mjs) a plaintext secret file or value in a tracked file; a `.enc` that is no sops envelope
-//   HFS_STACKS_SHAPE              (R10, hfs-rules/stacks.mjs) a `.starcistacks` path outside the standard shape, or a Sonar owner that is not the host
-//   HFS_CI_MISSING_CANON          (R13, hfs-rules/pipeline.mjs) CI without the pinned `hfs check`, pre-push without typecheck or lint
-//   HFS_DEP_VERSION_SKEW          (R14, hfs-rules/deps.mjs) a dependency at two versions in the workspace, or a nested copy in the lockfile
-//   HFS_CONTRACT_SNAPSHOT_DRIFT   (R23, hfs-rules/contract.mjs) an uncommitted back-end snapshot, or a front-end copy that differs from it
-//   BE_TEST_TOPOLOGY              (R47, hfs-rules/test-topology.mjs) a `.test` file, a testing/ folder, a second jest configuration
-//   FE_NO_TESTS                   (R97, hfs-rules/fe-no-tests.mjs) a front end holds a spec, e2e or test-tool file, a test script or a test dependency; no exception
-//   BE_SPEC_PLACEMENT             (R102, hfs-rules/spec-placement.mjs) a spec or test file outside the four test layers, scripts/ and tools/ included
-//   HFS_REPO_LOCAL_CHECK          (R103, hfs-rules/repo-local-checks.mjs) a local eslint rule or plugin, a `check-*` script, a relative import in eslint.config
-//   HFS_LINT_SUPPRESSION_FILE     (R104, hfs-rules/lint-suppression.mjs) an eslint suppressions file, script or option
-//   HFS_PROOF_COMMAND_FILE_MISSING (R105, hfs-rules/proof-commands.mjs) a .starciwork proof command that runs a file the repository does not hold
-//   HFS_PEER_INTEGRATION_MISSING  (R111, hfs-rules/peer-integrations.mjs) the app root package.json lacks the runtime peer a driver integration needs
-//   BE_INTEGRATION_SPEC_MISSING   (R112, hfs-rules/integration-specs.mjs) an integration with no integration spec that registers its module, maps its refusals and drives an outage
-//   FE_GRAPHQL_CONTRACT           (R113, hfs-rules/fe-contract-documents.mjs) a front-end GraphQL document the back end's contract snapshot does not serve
-//   FE_WIRE_GENERATED, FE_I18N_PLACEMENT, FE_I18N_CATALOG   (R52, R59, R60, hfs-rules/frontend.mjs) the front-end tree of each app
-//   HFS_GITIGNORE_BLOCK_DRIFT, HFS_SONAR_CONFIG   (R04, R11) produced by packages/hfs/sync/managed.mjs, which renders the templates
+//   HFS_PLAINTEXT_SECRET          (R06, rules/secrets.mjs) a plaintext secret file or value in a tracked file; a `.enc` that is no sops envelope
+//   HFS_STACKS_SHAPE              (R10, rules/stacks.mjs) a `.starcistacks` path outside the standard shape, or a Sonar owner that is not the host
+//   HFS_CI_MISSING_CANON          (R13, rules/pipeline.mjs) CI without the pinned `starci app check`, pre-push without typecheck or lint
+//   HFS_DEP_VERSION_SKEW          (R14, rules/deps.mjs) a dependency at two versions in the workspace, or a nested copy in the lockfile
+//   HFS_CONTRACT_SNAPSHOT_DRIFT   (R23, rules/contract.mjs) an uncommitted back-end snapshot, or a front-end copy that differs from it
+//   BE_TEST_TOPOLOGY              (R47, rules/test-topology.mjs) a `.test` file, a testing/ folder, a second jest configuration
+//   FE_NO_TESTS                   (R97, rules/fe-no-tests.mjs) a front end holds a spec, e2e or test-tool file, a test script or a test dependency; no exception
+//   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: a test script, dependency or tool config in a
+//                                 package.json or the tree, or a declared worker app, event pattern or trigger kind lite does not have
+//   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
+//   HFS_LINT_SUPPRESSION_FILE     (R104, rules/lint-suppression.mjs) an eslint suppressions file, script or option
+//   HFS_PROOF_COMMAND_FILE_MISSING (R105, rules/proof-commands.mjs) a .starciwork proof command that runs a file the repository does not hold
+//   HFS_PEER_INTEGRATION_MISSING  (R111, rules/peer-integrations.mjs) the app root package.json lacks the runtime peer a driver integration needs
+//   BE_INTEGRATION_SPEC_MISSING   (R112, rules/integration-specs.mjs) an integration with no integration spec that registers its module, maps its refusals and drives an outage
+//   FE_GRAPHQL_CONTRACT           (R113, rules/fe-contract-documents.mjs) a front-end GraphQL document the back end's contract snapshot does not serve
+//   HFS_MONO_* (R143-R146, rules/monorepo.mjs) the monorepo shape; BE_CLI_REQUIRED (R147, rules/cli.mjs) the one cli app
+//   HFS_SERVICE_PLACEMENT, HFS_IMAGE_UNPINNED, HFS_SERVICE_STACK_DECLARATION, HFS_EVENT_CONTRACT, BE_ASYNC_SPEC_MISSING   (R163-R167, rules/services.mjs) the microservice policy of a product with more than one service
+//   BE_EVENT_CLASS_CONTRACT, BE_PATTERN_SPEC_MISSING, BE_KIND_DECLARATION, BE_KIND_EMPTY   (rules/app-root.mjs: event-bus.mjs and kinds.mjs) a typed event class the vendored contract does not list, a declared pattern whose proof scenarios have no test, and the trigger kinds of the features (declared, whole, never empty)
+//   FE_WIRE_GENERATED, FE_I18N_PLACEMENT, FE_I18N_CATALOG   (R52, R59, R60, rules/frontend.mjs) the front-end tree of each app
+//   HFS_GITIGNORE_BLOCK_DRIFT, HFS_SONAR_CONFIG, HFS_COVERAGE_SCOPE_DRIFT   (R04, R11, R204) produced by packages/hfs/sync/managed.mjs, which renders the templates
 //   HFS_FORMAT                    (R19) produced by packages/hfs/sync/format.mjs, which runs the repository's own prettier
 //                                 both are passed in as `extraFindings`: this module reads no template and starts no tool
 //   HFS_CANON_PIN_DRIFT           a dependency whose declared version is not the pinned one
@@ -41,7 +48,7 @@
 //   HFS_UNTRACKED_ROOT_ENTRY      an entry git neither tracks nor ignores, outside an `ignored` slot (R03)
 // A runtime repository (hfs.json kind runtime, judged with knowledge/hfs/runtime-slots.yaml) gets the per-path slot findings,
 // the required files and minimum instances and the tree findings only; scripts/hfs/runtime-check.mjs adds the runtime rules.
-// checkRepository() is the whole `hfs check`: checkRepo() plus the architecture machine (scripts/hfs/architecture.mjs, one
+// checkRepository() is the whole `starci app check`: checkRepo() plus the architecture machine (scripts/hfs/architecture.mjs, one
 // implementation; the published bundle carries a byte copy), its violations and errors reported as findings under their own
 // codes; `fast` limits both to the owners changed since the merge-base. Every finding carries its code and the Vietnamese why text of modules/kernel/failure-codes.yaml. Only `error`
 // findings fail the check.
@@ -50,40 +57,40 @@ import path from 'node:path';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { ARCHITECTURE_RULE_IDS, checkArchitecture } from './architecture/index.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './slots.mjs';
+import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadRuleCatalog, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './slots.mjs';
 import { allowsFile } from './allows.mjs';
 import { RUNTIME_KIND } from './manifest-shape.mjs';
-import { gitOutput } from '../api/git/lib.mjs';
+import { lsFiles } from '../api/git/ls-files.mjs';
+import { diff as gitDiff } from '../api/git/diff.mjs';
+import { mergeBase } from '../api/git/merge-base.mjs';
+import { gitOutputOf } from '../lib/git.mjs';
 import { posixPath } from '../lib/path-key.mjs';
 import { readTree, treeFacts, untrackedEntries } from './tree.mjs';
 import { contractFindings } from './rules/contract.mjs';
-import { depFindings } from './rules/deps.mjs';
-import { appFrontendFindings, frontendFindings } from './rules/frontend-tree.mjs';
-import { feContractFindings } from './rules/fe-contract-documents.mjs';
-import { integrationSpecFindings } from './rules/integration-specs.mjs';
+import { appRootFindings } from './rules/app-root.mjs';
+import { frontendFindings } from './rules/frontend-tree.mjs';
 import { lintSuppressionFindings } from './rules/lint-suppression.mjs';
-import { peerIntegrationFindings } from './rules/peer-integrations.mjs';
-import { pipelineFindings } from './rules/pipeline.mjs';
-import { proofCommandFindings } from './rules/proof-commands.mjs';
 import { repoLocalCheckFindings } from './rules/repo-local-checks.mjs';
 import { readJson } from './rules/read.mjs';
-import { secretFindings } from './rules/secrets.mjs';
+import { supabaseSecretFindings } from './rules/supabase-secrets.mjs';
 import { pathFindings } from './path-findings.mjs';
 import { onLintSurface } from './architecture/surface.mjs';
 import { checkAppRoot, trackedTreeView } from './architecture/hfs.mjs';
-import { stacksFindings } from './rules/stacks.mjs';
 import { testTopologyFindings } from './rules/test-topology.mjs';
 import { feNoTestsFindings, isFeTestPath } from './rules/fe-no-tests.mjs';
+import { editionFindings } from './rules/edition.mjs';
+// The database rules (R213-R216) read SQL through a WASM parser, so they are async: `starci app check` calls them beside the other emitters and passes the findings in as `extraFindings`.
+export { checkDatabase } from './rules/database.mjs';
 
-export const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
+const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 export const FAILURE_CODES_FILE = 'modules/kernel/failure-codes.yaml';
 /**
- * The codes `hfs check` reports when it cannot judge (an unreadable repository, a refused declaration or manifest, a missing
+ * The codes `starci app check` reports when it cannot judge (an unreadable repository, a refused declaration or manifest, a missing
  * formatter): infrastructure refusals, never obligations, so no rule of knowledge/hfs/rules.yaml owns them.
  */
 export const REFUSAL_CODES = Object.freeze([
   'HFS_REPO_UNREADABLE',
-  'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID', 'HFS_FORMAT_TOOL_MISSING',
+  'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID', 'HFS_FORMAT_TOOL_MISSING', 'HFS_EDITION_INVALID',
 ]);
 /** The codes this module emits that are not the slot loader's own: the why bundle of packages/hfs ships exactly these plus the loader's. */
 export const CHECK_CODES = Object.freeze([
@@ -91,12 +98,14 @@ export const CHECK_CODES = Object.freeze([
   'HFS_SLOT_REQUIRED_MISSING', 'HFS_MIN_INSTANCES', 'HFS_CANON_PIN_DRIFT', 'HFS_SIZE_SOFT_BACKLOG', 'BE_SOURCE_FORM',
   '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',
-  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'BE_INTEGRATION_SPEC_MISSING', 'FE_GRAPHQL_CONTRACT', 'FE_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
-  'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_FORMAT',
+  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', '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',
+  'HFS_EDITION_FORBIDDEN_PRESENT', 'HFS_LITE_SECRET_CUSTODY',
+  '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_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_COVERAGE_SCOPE_DRIFT', 'HFS_FORMAT',
   'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
   ...REFUSAL_CODES,
 ]);
-/** Every code `hfs check` can report: its own and every code the architecture machine can emit (derived from the machine's rule id lists). */
+/** Every code `starci app check` can report: its own and every code the architecture machine can emit (derived from the machine's rule id lists). */
 export const ALL_CHECK_CODES = Object.freeze([...new Set([...CHECK_CODES, ...ARCHITECTURE_RULE_IDS])].sort());
 const SOURCE_EXT = /\.(?:[cm]?[jt]sx?)$/;
 const VAR = /<([a-z][a-z0-9-]*)>/g;
@@ -120,7 +129,7 @@ export function readWhy(root = skillRoot, codes = CHECK_CODES) {
 export function trackedFiles(repoRoot) {
   let out;
   try {
-    out = gitOutput(['ls-files', '-z', '--cached', '--exclude-standard'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 });
+    out = gitOutputOf(lsFiles(['-z', '--cached', '--exclude-standard'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files');
   } catch (error) {
     refuse('HFS_REPO_UNREADABLE', `${repoRoot} is not a readable Git work tree (${String(error?.stderr ?? error?.message ?? error).trim().split('\n')[0]})`, { repoRoot });
   }
@@ -129,12 +138,6 @@ export function trackedFiles(repoRoot) {
 
 const fill = (text, bindings) => String(text).replace(VAR, (whole, name) => bindings[name] ?? whole);
 
-/** hfs.json of `repoRoot` resolved against the manifest, or the single refusal finding when it is absent or invalid. */
-export function openRepo({ repoRoot, root = skillRoot, manifest = loadSlotManifest({ root }) }) {
-  const repo = readRepoDeclaration(manifest, repoRoot);
-  return { manifest, repo, resolver: createSlotResolver(manifest, repo) };
-}
-
 const pinnedSpec = (spec, pin) => (spec === pin.version ? null : `declared ${spec}, pinned ${pin.version}`);
 
 /** The pin map of knowledge/hfs/canon-pins.yaml under `root`. */
@@ -202,6 +205,16 @@ function summarize(findings) {
   };
 }
 
+/**
+ * THE edition filter of findings: a finding whose code belongs, through the rule catalog, to a rule the app's edition does not
+ * judge (rules.yaml `editions`) is dropped. Codes outside the catalog (refusals, machine codes without a rule) stay. This is the
+ * only place the edition touches a finding; no check below it knows the edition.
+ */
+function judgedFindings(findings, edition, root) {
+  const catalog = loadRuleCatalog({ root });
+  return findings.filter((finding) => catalog.judgedIn(finding.code, edition));
+}
+
 /** The tree findings of R03: empty directories, ghost siblings, untracked entries outside an ignored slot. */
 function treeFindings({ repoRoot, resolver }) {
   const inIgnoredSlot = (rel) => resolver.classifyPath(`${rel}/.probe`).tracking === 'ignored';
@@ -230,7 +243,7 @@ const onSide = (side, p) => (p ? path.posix.normalize(`${side}/${p}`) : p);
  * relative to it, exactly as the standalone repository root was). `files` are the scope's tracked paths; `all` (root only) every
  * tracked path of the app, for the rules that read across it (dependency skew, proof commands).
  */
-function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, scoped }) {
+function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, scoped, manifest, editionDeclaration = true }) {
   const inScope = (file) => !scoped || scoped.has(file);
   // A required directory of the root (be/, fe/) is present through the files below it, which are the sides' own.
   const trackedSet = new Set(all);
@@ -264,28 +277,21 @@ function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, sco
   const pins = readPins(root);
   findings.push(...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }));
 
-  // The tree checks of the rules that read file content or configuration (hfs-rules/*): whole-scope, cheap, no tool run.
+  // The tree checks of the rules that read file content or configuration (rules/*): whole-scope, cheap, no tool run.
   findings.push(
-    ...secretFindings({ repoRoot, files: files.filter(inScope), resolver }),
+    ...supabaseSecretFindings({ repoRoot, files: files.filter(inScope), resolver, repo }),
+    ...editionFindings({ repoRoot, files: files.filter(inScope), repo, resolver, withDeclaration: editionDeclaration }),
     ...repoLocalCheckFindings({ repoRoot, files }),
     ...lintSuppressionFindings({ repoRoot, files }),
   );
   if (isRoot) {
     findings.push(
-      ...depFindings({ repoRoot, files: all }),
-      ...peerIntegrationFindings({ repoRoot, files: all }),
-      ...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 }),
+      ...appRootFindings({ repoRoot, files, all, repo, resolver, pins }),
       // The tree check of the app root the machine runs per side for a side folder: README, root entries, automatic gates, hooks path.
       ...checkAppRoot({ root: repoRoot, resolver, tree: trackedTreeView(all) }).violations.map((item) => ({ code: item.ruleId, level: 'error', path: item.path, line: item.line, column: item.column, source: 'machine', message: `${item.path}: ${item.message}` })),
     );
   } else if (repo.profile === 'be') {
-    findings.push(...contractFindings({ files, repo, resolver }), ...testTopologyFindings({ repoRoot, files }));
+    findings.push(...contractFindings({ repoRoot, files, repo, resolver }), ...testTopologyFindings({ repoRoot, files }));
   } else {
     findings.push(...frontendFindings({ repoRoot, files, repo }), ...feNoTestsFindings({ repoRoot, files: files.filter(inScope) }));
   }
@@ -319,7 +325,7 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only
   try {
     repo = declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration);
   } catch (error) {
-    if (!(error instanceof HfsSlotsError) || !['HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH'].includes(error.code)) throw error;
+    if (!(error instanceof HfsSlotsError) || !['HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_EDITION_INVALID'].includes(error.code)) throw error;
     const findings = withWhy([{ code: error.code, level: 'error', path: HFS_DECLARATION_FILE, message: error.message.replace(/^[A-Z_]+: /, ''), problems: error.details.problems }], why);
     return { ok: false, repoRoot, manifest: manifest.version, profile: null, apps: [], tracked: 0, findings, counts: summarize(findings) };
   }
@@ -327,28 +333,29 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only
   const tracked = files ?? trackedFiles(repoRoot);
   const scoped = only ? new Set(only) : null;
   const findings = [];
-  // `hfs check` leaves to the lint canon the per-path findings that sit on an existing TypeScript file (hfs-path-findings.mjs).
+  // `starci app check` leaves to the lint canon the per-path findings that sit on an existing TypeScript file (hfs-path-findings.mjs).
   const keep = (list, scopeRoot) => (surface === 'check' ? list.filter((finding) => !(finding.origin === 'repo' && onLintSurface(scopeRoot, finding))) : list);
   if (repo.profile === APP_SCOPE) {
     const own = tracked.filter((file) => resolver.sideOf(file) === null);
-    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: own, all: tracked, scoped }), repoRoot));
+    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: own, all: tracked, scoped, manifest }), repoRoot));
     for (const side of SIDES) {
       const prefix = `${side}/`;
       const sideRoot = path.join(repoRoot, side);
       const sideFiles = tracked.filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length));
       const sideScoped = scoped ? new Set([...scoped].filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length))) : null;
-      const sideFindings = scopeFindings({ repoRoot: sideRoot, root, repo: repo.sides[side], resolver: resolver.sides[side], files: sideFiles, scoped: sideScoped });
+      const sideFindings = scopeFindings({ repoRoot: sideRoot, root, repo: repo.sides[side], resolver: resolver.sides[side], files: sideFiles, scoped: sideScoped, manifest, editionDeclaration: false });
       const message = appRelativeMessages(side, sideRoot);
       findings.push(...keep(sideFindings, sideRoot).map((finding) => ({ ...finding, side, path: onSide(side, finding.path), message: message(finding.message) })));
     }
   } else {
-    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: tracked, scoped }), repoRoot));
+    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: tracked, scoped, manifest }), repoRoot));
   }
   findings.push(...extraFindings);
   if (tree) findings.push(...treeFindings({ repoRoot, resolver }));
 
   // The app-root tree check reports machine codes: their why is read with the check's own.
-  const finished = withWhy(findings, { ...why, ...readWhy(root, [...new Set(findings.map((f) => f.code).filter((code) => !why[code]))]) });
+  const judged = judgedFindings(findings, repo.edition ?? 'full', root);
+  const finished = withWhy(judged, { ...why, ...readWhy(root, [...new Set(judged.map((f) => f.code).filter((code) => !why[code]))]) });
   const counts = summarize(finished);
   const apps = repo.profile === APP_SCOPE ? SIDES.flatMap((side) => repo.sides[side].apps.map((app) => ({ ...app, side }))) : repo.apps;
   return { ok: counts.error === 0, repoRoot, manifest: manifest.version, profile: repo.profile, apps, tracked: tracked.length, findings: finished, counts };
@@ -356,28 +363,24 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only
 
 // ------------------------------------------------------------------------------------------ the whole check
 
-const gitOut = (repoRoot, args) => gitOutput(args, { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 });
-
 /** The merge-base of HEAD with `base`, else with origin/main, else with main; null when none resolves. */
 function mergeBaseOf(repoRoot, base) {
   for (const ref of base ? [base] : ['origin/main', 'main']) {
-    try {
-      const sha = gitOut(repoRoot, ['merge-base', 'HEAD', ref]).trim();
-      if (sha) return sha;
-    } catch { /* this ref has no merge-base with HEAD; try the next */ }
+    const sha = mergeBase(repoRoot, 'HEAD', ref); // null: this ref has no merge-base with HEAD; try the next
+    if (sha) return sha;
   }
   return null;
 }
 
 /** Tracked paths that differ from the merge-base (commits, staged and unstaged edits; deletions are not paths to judge). */
-export function changedSince(repoRoot, base) {
+function changedSince(repoRoot, base) {
   const sha = mergeBaseOf(repoRoot, base);
   if (!sha) {
     throw new Error(base
       ? `--base ${base} has no merge-base with HEAD; pass a ref this branch descends from`
       : '--fast needs a merge-base with origin/main or main and found none; run `git fetch origin main` or pass --base <ref>');
   }
-  const files = gitOut(repoRoot, ['diff', '--name-only', '--diff-filter=ACMRT', '-z', sha]).split('\0').filter(Boolean).map(posixPath);
+  const files = gitOutputOf(gitDiff(['--name-only', '--diff-filter=ACMRT', '-z', sha], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git diff').split('\0').filter(Boolean).map(posixPath);
   return { base: sha, files };
 }
 
@@ -388,7 +391,7 @@ function machineFindings(report) {
 }
 
 /**
- * The whole `hfs check` of one app: checkRepo() (the root and both sides: slots, pins, size, tree) and then the architecture machine
+ * The whole `starci app check` of one app: checkRepo() (the root and both sides: slots, pins, size, tree) and then the architecture machine
  * over each side folder (the side as the repository root it judges), its violations and errors merged in as findings with the
  * Vietnamese why of their codes and the side prefixed onto their paths. `fast` judges only what changed since the merge-base (`base`
  * names another ref): the per-path slot and pin checks on the changed paths, the machine on the owners of the changed source files
@@ -412,7 +415,7 @@ export function checkRepository({ repoRoot, root = skillRoot, fast = false, base
     found.push(...run.findings);
   }
   const why = readWhy(root, [...new Set(found.map((f) => f.code))]);
-  const findings = [...slotResult.findings, ...withWhy(found, why)];
+  const findings = [...slotResult.findings, ...withWhy(judgedFindings(found, repo.edition ?? 'full', root), why)];
   const counts = summarize(findings);
   const ran = runs.filter((info) => info.status === 'ran');
   return {
@@ -451,7 +454,7 @@ function machineOver({ scope, manifest, machine, changed }) {
 // --------------------------------------------------------------------------------------------------- explain
 
 const TEST_KIND = {
-  'unit-beside': 'a <name>.service.spec.ts beside each <name>.service.ts in this slot (only services are unit-tested)',
+  'unit-beside': 'a <name>.service.spec.ts beside each <name>.service.ts in this slot (only services are unit-tested; a webhook or realtime door has its own spec beside it)',
   e2e: 'an integration, e2e or contract spec covering the flow; no unit spec is required',
   none: 'no test is required for files in this slot',
 };