@starci/hfs 4.0.5 → 4.0.6

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 4.0.6 - 2026-10-01
+
+- Changed: R112 integration specs, the runtime api layer, the examples-root CI scope and the new pins.
+
 ## 4.0.5 - 2026-10-01
 
 - Changed: workflow worktree runtime copies, the services coverage scope for Sonar and codecov.yml, sonar-gate, canon-pins.

package/README.md

@@ -63,6 +63,7 @@ Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rende
 | `HFS_REPO_LOCAL_CHECK` | error | a `check-*` file in `scripts/` or `tools/`, an `eslint-local-rules*` file or local eslint plugin, or a script that runs a local check (R103) |
 | `HFS_LINT_SUPPRESSION_FILE` | error | an `eslint.suppressions*` file, a `lint:suppressions` script, an eslint suppress flag or a suppressions config (R104) |
 | `HFS_PROOF_COMMAND_FILE_MISSING` | error | a `.starciwork` `requiresProof.<kind>.command` that runs a file the repository does not hold (R105) |
+| `BE_INTEGRATION_SPEC_MISSING` | error | an integration (`src/modules/integrations/<provider>/` with `<provider>.config.ts`) without a `src/tests/integration/<provider>/*.integration-spec.ts` that registers its module through `useTestWorld({ modules })`, references its ErrorCode enum and drives an outage through the world (R112) |
 | `HFS_PEER_INTEGRATION_MISSING` | error | the app root `package.json` depends on a driver integration (a pair of `knowledge/hfs/peer-integrations.yaml`) without its runtime peer, e.g. `@nestjs/apollo` on `@nestjs/platform-express` 11 without `@as-integrations/express5` (R111) |
 | `FE_WIRE_GENERATED` | error | a contract copy with no `codegen` script wired before `build` and `typecheck`, or generated types older than the copy (R52) |
 | `FE_I18N_PLACEMENT` | error | no `next-intl`, no `src/proxy.ts`, a `middleware.ts`, a route file outside `[locale]`, no `vi.json` catalog (R59) |
@@ -121,7 +122,7 @@ properties file is not its render or the stack declaration names another gate. R
 
 Coverage is the services' alone, from one scope. The managed `test` script is `jest --selectProjects unit --coverage`: it fails below the per-file 100 threshold on `src/**/*.service.ts` and writes `be/coverage/lcov.info` (the jest preset's lcov reporter). The managed `sonar-project.properties` imports that report (`sonar.javascript.lcov.reportPaths=be/coverage/lcov.info`) with `sonar.coverage.inclusions=be/src/**/*.service.ts` and no other coverage key, so a handler, resolver, controller, module, config file or test is not a coverage target and `fe/` is outside coverage. The managed `codecov.yml` holds the same paths at 100 on the project and the patch and ignores `fe/**`; the managed CI workflow uploads the lcov with `codecov/codecov-action` after the unit run. `hfs sync` renders the scope into both files from the installed jest preset's `COVERAGE_SOURCES` (`coverageScope` in `sync/index.mjs`), so they can never drift. The runtime judges the coverage per file: `sonar-local.mjs scan` holds every service a slice touched at 100, and `sonar-local.mjs dashboard` fails a project unless every service is at 100.
 
-The upload needs the repository secret `CODECOV_TOKEN` (the owner adds it once per repository: Codecov, the repository's settings, then GitHub Settings > Secrets and variables > Actions > New repository secret `CODECOV_TOKEN`). Without it the step is skipped like the Sonar steps without `SONAR_TOKEN`.
+The upload needs the repository secret `CODECOV_TOKEN` (each product monorepo gets its own; the runtime repository's root `.github/workflows/examples.yml` uses the runtime repository's one for the example apps; the owner adds it once per repository: Codecov, the repository's settings, then GitHub Settings > Secrets and variables > Actions > New repository secret `CODECOV_TOKEN`). Without it the step is skipped like the Sonar steps without `SONAR_TOKEN`.
 
 ## Maintaining the bundle
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.0.5",
+  "version": "4.0.6",
   "description": "The HFS command line of a StarCi app (one repository: the root, be/ and fe/): hfs lint, check, scaffold app, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
   "type": "module",
   "license": "UNLICENSED",

package/runtime/engine/machine-db.mjs

@@ -35,7 +35,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 import { pathToFileURL, fileURLToPath } from 'node:url';
-import { runGit } from '../scripts/lib/git.mjs';
+import { runGit } from '../scripts/api/git/lib.mjs';
 import { sleepSync as scaledSleepSync } from '../scripts/lib/sleep-sync.mjs';
 import { putBlob as storeBlob, blobPath, artifactRoot, getBlob } from '../scripts/lib/artifact-store.mjs';
 import { redactBytes, redactData, redactText } from '../scripts/lib/redact.mjs';
@@ -1303,7 +1303,7 @@ const upsertWorktree = (m, wt) => upsertRow(m.db, 'worktrees', { created_at: m.n
 const removedWorktree = (m, wtPath, { error = null, archivedRef = null } = {}) => m.db.prepare('UPDATE worktrees SET removed_at=CASE WHEN ? IS NULL THEN ? ELSE removed_at END, remove_error=?, archived_ref=COALESCE(?,archived_ref) WHERE path=?')
   .run(error, m.now(), error, archivedRef, path.resolve(wtPath)).changes > 0;
 /**
- * The worktree registry (scripts/lib/worktrees.mjs is its one caller): reserve a row for a worktree about to be created,
+ * The worktree registry (scripts/lib/worktree-registry.mjs and the worktree api files are its callers): reserve a row for a worktree about to be created,
  * atomically against the per-repo cap. BEGIN IMMEDIATE: two dispatches never both take the last slot. `cap` null: no cap.
  * {ok, live} | {ok:false, reason:'worktree-cap', live, cap}
  */

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,14 +31,14 @@ pins:
     source: packages/grammar/package.json
     why: nivo-fe pins 0.4.11 and 0.5.0 in one workspace, starci-next-fe 0.5.1, miamia-fe 0.5.0; the runtime source is 0.8.0 (the brand layer sets `--font-sans` and `--font-mono`; the grammar reads them; 0.7.2 added the Input tel kind and IconButton disclosure props).
   '@starci/eslint-canon-be':
-    version: 3.0.5
+    version: 3.0.6
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: '3.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2 and hfs 4.0.3; no rule changed. 3.0.2: its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root (app.starcistacks, app.sops) and pin hfs 4.0.2. 3.0.1: its bundled canon-pins copy pins hfs 4.0.1. 3.0.0: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side; the project graph is built per side. 2.0.0 (C0 release): starciBeConfig({ hfs: loadHfs(import.meta.url) }) typed factory and the BE-CONVENTION laws.'
   '@starci/eslint-canon-fe':
-    version: 8.0.5
+    version: 8.0.6
     group: starci
     install: registry
     side: fe
@@ -71,14 +71,14 @@ pins:
     source: packages/jest-preset/package.json
     why: '2.2.2: the unit run writes the lcov Sonar and Codecov import (services only); 2.2.0: the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; 2.1.0: four projects on the test world, the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
   '@starci/test-world':
-    version: 1.0.3
+    version: 1.0.5
     group: starci
     install: registry
     side: be
     source: packages/test-world/package.json
-    why: '1.0.3: the globalSetup registers the path aliases as TypeScript resolves them (the extends chain, paths from the config that declares them, the effective baseUrl), so a tests tsconfig that only extends the side config loads the declaration. 1.0.2: every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json), where .starcistacks lives, never from the be side. The shared e2e library of every back end (R47, R48): the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs, the outage lock and the starci-test-stack bin behind the managed test:stack script; a devDependency of every back end. 1.0.1: world.keycloak.events/sessions (the user events of the realm and live sessions through the admin API) and world.infra.postgresql.connection(name) (the database of one connection down while the others serve, under the outage lock).'
+    why: '1.0.5: a modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, and w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client. 1.0.4: world.resolve and scope.resolve take any Nest token (class, string or symbol). 1.0.3: the globalSetup registers the path aliases as TypeScript resolves them (the extends chain, paths from the config that declares them, the effective baseUrl), so a tests tsconfig that only extends the side config loads the declaration. 1.0.2: every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json), where .starcistacks lives, never from the be side. The shared e2e library of every back end (R47, R48): the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs, the outage lock and the starci-test-stack bin behind the managed test:stack script; a devDependency of every back end. 1.0.1: world.keycloak.events/sessions (the user events of the realm and live sessions through the admin API) and world.infra.postgresql.connection(name) (the database of one connection down while the others serve, under the outage lock).'
   '@starci/hfs':
-    version: 4.0.5
+    version: 4.0.6
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/slots.yaml

@@ -818,9 +818,9 @@ slots:
     tier: integrations
     owner: true
     requires: [index.ts, "<provider>.config.ts"]
-    tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts, nothing else
+    tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts; plus src/tests/integration/<provider>/ (R112)
     budget: {indexExports: 60}
-    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT]
+    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING]
   - id: be.integrations.model
     profiles: [be]
     path: "src/modules/integrations/<provider>/model/"
@@ -897,8 +897,8 @@ slots:
     tracked: tracked
     tier: e2e
     tests: e2e
-    why: one capability module on the real database, no HTTP (SQL, transactions, concurrency, inbox claims) through useTestWorld({ modules }); run by test:integration
-    rules: [BE_TEST_TOPOLOGY]
+    why: one capability module through useTestWorld({ modules }), no HTTP door of ours (SQL, transactions, concurrency, inbox claims on the real database; and every integration client, `<capability>` being its provider folder, against our real infra, a real peer app or the library fake at the network edge, with its success, its ErrorCode refusal mapping and an outage through the world, R112); run by test:integration
+    rules: [BE_TEST_TOPOLOGY, BE_INTEGRATION_SPEC_MISSING]
   - id: be.tests.e2e
     profiles: [be]
     path: "src/tests/e2e/<area>/*.e2e-spec.ts"

package/runtime/modules/kernel/failure-codes.yaml

@@ -384,6 +384,16 @@ BE_FEATURE_SHAPE:
   owner: op-retry
   kind: check-finding
 
+BE_INTEGRATION_SPEC_MISSING:
+  title: "Every integration has an integration spec that proves its client through the test world"
+  title_vi: "Tích hợp thiếu spec integration chứng minh client qua test world"
+  meaning_vi: "Thư mục `src/modules/integrations/<provider>/` (có `<provider>.config.ts`) không có `src/tests/integration/<provider>/*.integration-spec.ts` nào vừa gọi `useTestWorld({ modules })` với factory đăng ký module của chính tích hợp đó (`<Provider>Module.register`, import từ thư mục tích hợp), vừa tham chiếu enum ErrorCode của tích hợp, vừa gây một sự cố qua world (`world.infra.<service>`, `world.fake.<name>.failNext`, `world.apps.<peer>.during`, `world.interruptDatabase`)."
+  causes_vi:
+    - "Vi phạm luật R112: client của tích hợp chỉ được kiểm bằng unit spec với double, nên ánh xạ lỗi và đường sự cố của nhà cung cấp thật (hoặc fake ở biên mạng) chưa bao giờ chạy; lỗi phân loại timeout của FetchHttpClient chỉ lộ ra khi spec integration đầu tiên chạy."
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: thêm hoặc bổ sung spec integration của đúng thư mục provider cho phần còn thiếu (đăng ký module, enum ErrorCode, sự cố qua world); không thêm ngoại lệ."
+  owner: op-retry
+  kind: check-finding
+
 BE_MODULE_HANDLER_REGISTRATION:
   title: "Handler not registered exactly once"
   title_vi: "Handler chưa đăng ký đúng một lần"

package/runtime/scripts/api/fs/rmdir-link.mjs

@@ -0,0 +1,12 @@
+// rmdir-link.mjs — the link-safe removal primitive: `cmd /d /c rmdir <link>` (no /s) removes a Windows junction or
+// directory symlink as a link and never touches its target. scripts/lib/safe-remove.mjs removeLink is its one caller and
+// checks afterwards that the link is gone (unlinkOnly); this file only issues the call.
+
+import { spawnSync } from 'node:child_process';
+
+/** Issue `cmd /d /c rmdir <p>` on Windows; elsewhere nothing (a POSIX link is unlinked by the caller). {status, error}. */
+export function rmdirLink(p, { platform = process.platform } = {}) {
+  if (platform !== 'win32') return { status: null, error: null };
+  const r = spawnSync('cmd', ['/d', '/c', 'rmdir', p], { windowsHide: true, encoding: 'utf8' });
+  return { status: r.status, error: r.error?.message ?? null };
+}

package/runtime/scripts/{lib/git.mjs → api/git/lib.mjs}

@@ -1,11 +1,11 @@
-// git.mjs — the one spawn the runtime's guard/kernel scripts run git through.
+// scripts/api/git/lib.mjs — the one place the runtime spawns git (scripts/checks/check-layers.mjs enforces it).
 //
-// Every copy spelt the same options by hand - encoding:'utf8', windowsHide:true, sometimes a
-// timeout - with two shapes: `git args` in a cwd (shim's pathspec scans, footprint-scan,
-// safe-remove's prune) and `git -C dir args` (settle-landed, install, terminal-dedupe's worktree
-// list). gitOutput is the throwing shape (stdout text, or an Error on a non-zero exit). gitSpawn keeps the spawnSync(file, args, options) signature so an injected runner or a
-// spec's fake takes the same three arguments; runGit is the `-C` convenience; gitResult folds the
-// result into settle-landed's {ok, stdout, error} envelope.
+// Every caller spelt the same options by hand - encoding:'utf8', windowsHide:true, sometimes a timeout - with two shapes:
+// `git args` in a cwd and `git -C dir args`. gitOutput is the throwing shape (stdout text, or an Error on a non-zero exit).
+// gitSpawn keeps the spawnSync(file, args, options) signature so an injected runner or a spec's fake takes the same three
+// arguments; runGit is the `-C` convenience; gitResult folds the result into the {ok, stdout, error} envelope; gitRunner
+// folds any caller's runner into {ok, stdout, stderr}. The call files beside this one (worktree-*.mjs, rev-parse.mjs, ...)
+// each name one git verb.
 import { spawnSync } from 'node:child_process';
 
 /**
@@ -43,11 +43,10 @@ export function gitResult(args, options = {}) {
 }
 
 /**
- * git's C-quoted diff path decoded - `"b\303\251"` a `+++ ` header line prints when core.quotePath
- * covers the name. Octal escapes become \u00XX for JSON.parse (which answers \n, \t, \" and \\);
- * a value not wrapped in quotes passes through unchanged.
+ * A caller's git runner folded to (args, opts) -> {ok, stdout, stderr}. `git`: the caller's runner (args, {cwd}) ->
+ * {ok|status, stdout|out, stderr|err} (a spec's fake); null: runGit with a 5-minute timeout and a 64 MB buffer.
  */
-export const unquoteDiffPath = (value) =>
-  /^".*"$/.test(value)
-    ? JSON.parse(value.replace(/\\([0-7]{3})/g, (_, octal) => `\\u00${Number.parseInt(octal, 8).toString(16).padStart(2, '0')}`))
-    : value;
+export const gitRunner = (git = null) => (args, opts = {}) => {
+  const r = git ? git(args, opts) : runGit(args, { timeout: 300_000, maxBuffer: 64 * 1024 * 1024, ...opts });
+  return { ok: r?.ok ?? (!r?.error && r?.status === 0), stdout: String(r?.stdout ?? r?.out ?? '').trim(), stderr: String(r?.stderr ?? r?.err ?? r?.error?.message ?? r?.error ?? '').trim() };
+};

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

@@ -18,8 +18,12 @@
  * used by the importers of that file; a re-exporting file nobody imports is a framework entry (a route file) and uses it.
  * Specs and tests are not in the graph, so an export used only by a spec is dead, on purpose, with one exception (unit test
  * standard): a `<name>.service.spec.ts` (the only unit spec kind) and a `*.builder.ts` under src/tests/fixtures/builders read from
- * disk count as consumers, because a spec can only provide an Inject*() token or a param type the entry exports. Specs of any
- * other kind, e2e specs and world files still do not count. A consumer inside the owner is skipped like any inside consumer.
+ * disk count as consumers, because a spec can only provide an Inject*() token or a param type the entry exports. An integration
+ * spec (slot be.tests.integration, `src/tests/integration/<capability>/*.integration-spec.ts`) counts as a consumer of exactly one
+ * owner: the integration (slot be.integrations, `src/modules/integrations/<provider>/`) whose provider folder is its capability
+ * folder, because R112 makes that spec register the integration module and reference its ErrorCode enum. Specs of any other kind,
+ * an integration spec importing another owner, e2e specs and world files still do not count. A consumer inside the owner is
+ * skipped like any inside consumer.
  */
 import fs from 'node:fs';
 import { canonical } from './config.mjs';
@@ -168,13 +172,35 @@ function deadFiles(graph, config) {
 }
 
 const TEST_CONSUMER = /^(?:(?:src|apps)\/.+\.service\.spec\.ts|src\/tests\/fixtures\/builders\/.+\.builder\.ts)$/u;
+/** The slot of integration specs and the slot of the integrations they pair with by folder (knowledge/hfs/slots.yaml). */
+const INTEGRATION_SPEC_SLOT = 'be.tests.integration';
+const INTEGRATION_SLOT = 'be.integrations';
 
-/** Pseudo edges from the unit specs of services and the fixture builders (read from disk, outside the production program) to graph files. */
+/** The provider an integration spec pairs with (its `<capability>` folder), or null when `rel` is no integration spec. */
+function integrationSpecProvider(graph, rel) {
+  const classified = graph.resolver.classifyPath(rel);
+  return classified.slot === INTEGRATION_SPEC_SLOT && classified.status !== 'forbidden' ? classified.bindings?.capability ?? null : null;
+}
+
+/** Whether `to` belongs to the integration of `provider` (slot be.integrations, its `<provider>` binding). */
+function inIntegrationOf(graph, to, provider) {
+  const owner = graph.resolver.ownerOf(to);
+  return owner?.slot === INTEGRATION_SLOT && owner.bindings?.provider === provider;
+}
+
+/**
+ * Pseudo edges (read from disk, outside the production program) to graph files: from the unit specs of services and the fixture
+ * builders to anything, and from an integration spec only to the integration of its own provider folder.
+ */
 function testConsumerEdges({ context, graph, config }) {
   const { ts } = context;
   const options = context.projects?.[0]?.options ?? {};
   const edges = [];
-  for (const rel of [...treeOf(config.root).files].filter(file => TEST_CONSUMER.test(file)).sort()) {
+  const consumers = [...treeOf(config.root).files]
+    .map(file => ({ file, provider: TEST_CONSUMER.test(file) ? null : integrationSpecProvider(graph, file) }))
+    .filter(({ file, provider }) => provider !== null || TEST_CONSUMER.test(file))
+    .sort((a, b) => a.file.localeCompare(b.file));
+  for (const { file: rel, provider } of consumers) {
     const abs = path.join(config.root, ...rel.split('/'));
     let text;
     try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
@@ -183,7 +209,7 @@ function testConsumerEdges({ context, graph, config }) {
       if (!(ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) || !statement.moduleSpecifier || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue;
       const resolved = ts.resolveModuleName(statement.moduleSpecifier.text, abs, options, ts.sys).resolvedModule?.resolvedFileName;
       const to = resolved ? graph.abs(canonical(resolved)) : null;
-      if (to) edges.push({ from: rel, to, edge: { declaration: statement }, reexport: false });
+      if (to && (provider === null || inIntegrationOf(graph, to, provider))) edges.push({ from: rel, to, edge: { declaration: statement }, reexport: false });
     }
   }
   return edges;
@@ -254,7 +280,7 @@ export function checkDeadExports({ context, graph, config }) {
         ruleId: 'HFS_UNUSED_EXPORT',
         path: entry, line, column: 1,
         name, owner: owner.root, slot: owner.slot,
-        message: `${entry} exports ${name}, but no production file outside ${owner.root || 'the repository root'} imports it; remove the export (only a service unit spec or a fixture builder counts besides production files).`,
+        message: `${entry} exports ${name}, but no production file outside ${owner.root || 'the repository root'} imports it; remove the export (only a service unit spec, a fixture builder, or an integration spec of this integration's own provider folder counts besides production files).`,
       });
     }
   }

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

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { isIP } from 'node:net';
-import { gitOutput } from '../../lib/git.mjs';
+import { gitOutput } from '../../api/git/lib.mjs';
 import { repositoryName } from '../../lib/repo-identity.mjs';
 import { braceVariants } from '../../lib/glob.mjs';
 import { createSlotResolver, loadSlotManifest, openHfs } from '../../lib/hfs-slots.mjs';

package/runtime/scripts/checks/architecture/required-files.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { gitOutput } from '../../lib/git.mjs';
+import { gitOutput } from '../../api/git/lib.mjs';
 
 /**
  * HFS check 5: the files and directories the slot manifest requires (knowledge/hfs/slots.yaml `requires`,

package/runtime/scripts/lib/hfs-check.mjs

@@ -27,6 +27,7 @@
 //   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_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_FORMAT                    (R19) produced by packages/hfs/sync/format.mjs, which runs the repository's own prettier
@@ -48,12 +49,13 @@ import { ARCHITECTURE_RULE_IDS, checkArchitecture } from '../checks/architecture
 import { parseYaml } from '../../engine/yaml.mjs';
 import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './hfs-slots.mjs';
 import { allowsFile } from './hfs-allows.mjs';
-import { gitOutput } from './git.mjs';
+import { gitOutput } from '../api/git/lib.mjs';
 import { posixPath } from './path-key.mjs';
 import { readTree, treeFacts, untrackedEntries } from './hfs-tree.mjs';
 import { contractFindings } from './hfs-rules/contract.mjs';
 import { depFindings } from './hfs-rules/deps.mjs';
 import { appFrontendFindings, frontendFindings } from './hfs-rules/frontend.mjs';
+import { integrationSpecFindings } from './hfs-rules/integration-specs.mjs';
 import { lintSuppressionFindings } from './hfs-rules/lint-suppression.mjs';
 import { peerIntegrationFindings } from './hfs-rules/peer-integrations.mjs';
 import { pipelineFindings } from './hfs-rules/pipeline.mjs';
@@ -84,7 +86,7 @@ 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', 'FE_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
+  '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_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
   'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_FORMAT',
   'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
   ...REFUSAL_CODES,
@@ -265,6 +267,7 @@ function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, sco
     findings.push(
       ...depFindings({ repoRoot, files: all }),
       ...peerIntegrationFindings({ repoRoot, files: all }),
+      ...integrationSpecFindings({ repoRoot, files: all }),
       ...pipelineFindings({ repoRoot, files, pins }),
       ...testTopologyFindings({ repoRoot, files }),
       ...proofCommandFindings({ repoRoot, files: all, resolver, sides: Object.keys(repo.sides ?? {}) }),

package/runtime/scripts/lib/hfs-rules/integration-specs.mjs

@@ -0,0 +1,222 @@
+// integration-specs.mjs - BE_INTEGRATION_SPEC_MISSING (R112): every integration of a back end has an integration spec that proves
+// its client through the test world. An integration is the slot be.integrations: `src/modules/integrations/<provider>/` holding
+// `<provider>.config.ts` (its required config boundary). Its spec is the slot be.tests.integration of the same folder name:
+// `src/tests/integration/<provider>/*.integration-spec.ts`. At least one of those specs, read as a TypeScript syntax tree (never
+// matched by name), must
+//   1. call `useTestWorld({ modules })` where `modules` is an array (inline, a local const, or an exported const of another file,
+//      spreads followed) holding a factory whose body calls `<X>.register(...)` with `<X>` imported from that integration;
+//   2. reference an enum the integration exports (its ErrorCode enum): an identifier imported from the integration whose export
+//      resolves to an `enum` declaration, used outside the import;
+//   3. drive an outage through the world handle the call answers: `<world>.infra.<service>.cut|latency|during|connection(...)`, `<world>.fake.<name>.failNext(...)`,
+//      `<world>.apps.<name>.during(...)` or `<world>.interruptDatabase(...)`.
+// The finding sits on the integration folder. Imports resolve through the side's tsconfig (paths included) with the app's own
+// TypeScript, the one every back end installs; the runtime's TypeScript is the fallback.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findPackage, requirePackage } from '../package-at.mjs';
+import { found, readText } from './read.mjs';
+
+export const INTEGRATION_SPEC_MISSING = 'BE_INTEGRATION_SPEC_MISSING';
+
+const CONFIG_FILE = /^((?:[^/]+\/)*?)src\/modules\/integrations\/([^/]+)\/\2\.config\.ts$/;
+const SPEC_SUFFIX = '.integration-spec.ts';
+const OUTAGE_CALLS = Object.freeze({ fake: 'failNext', apps: 'during' });
+/** The outage verbs of `world.infra.<service>` (`connection` leads to one connection's cut/restore/during). */
+const INFRA_OUTAGES = new Set(['cut', 'latency', 'during', 'connection']);
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** The TypeScript compiler of the app (else of the runtime), or null. */
+function typescriptFor(repoRoot) {
+  const located = findPackage([repoRoot, HERE], ['typescript']);
+  return located ? requirePackage(located) : null;
+}
+
+/** The compiler options of the side (its tsconfig.json, `extends` and `paths` resolved by TypeScript itself). */
+function optionsOf(ts, sideRoot) {
+  const file = path.join(sideRoot, 'tsconfig.json');
+  if (!fs.existsSync(file)) return {};
+  const read = ts.readConfigFile(file, ts.sys.readFile);
+  if (read.error) return {};
+  return ts.parseJsonConfigFileContent(read.config, ts.sys, sideRoot).options;
+}
+
+/** One parsed file: its syntax tree and its imports (local name -> { source, imported }). */
+function parse(ts, repoRoot, rel) {
+  const text = readText(repoRoot, rel);
+  if (text === null) return null;
+  const sourceFile = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const imports = new Map();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const named = statement.importClause?.namedBindings;
+    if (!named || !ts.isNamedImports(named)) continue;
+    for (const element of named.elements) imports.set(element.name.text, { source: statement.moduleSpecifier.text, imported: (element.propertyName ?? element.name).text, node: element });
+  }
+  return { rel, sourceFile, imports };
+}
+
+/** Walks every node under `node`. */
+function walk(ts, node, visit) {
+  visit(node);
+  ts.forEachChild(node, (child) => walk(ts, child, visit));
+}
+
+/** The names of a property chain `a.b.c` from its root identifier, or null when the chain does not start at an identifier. */
+function chainOf(ts, expression) {
+  const names = [];
+  let current = expression;
+  while (ts.isPropertyAccessExpression(current)) {
+    names.unshift(current.name.text);
+    current = current.expression;
+  }
+  return ts.isIdentifier(current) ? [current.text, ...names] : null;
+}
+
+/**
+ * The judge of one app: resolves an import of a parsed file to a repository-relative path, finds the top-level const of a file,
+ * and reads files once.
+ */
+function judgeOf(ts, repoRoot, side) {
+  const options = optionsOf(ts, path.join(repoRoot, side));
+  const cache = new Map();
+  const parsed = (rel) => {
+    if (!cache.has(rel)) cache.set(rel, parse(ts, repoRoot, rel));
+    return cache.get(rel);
+  };
+  const resolve = (fromRel, source) => {
+    const resolved = ts.resolveModuleName(source, path.join(repoRoot, fromRel), options, ts.sys).resolvedModule?.resolvedFileName;
+    if (!resolved) return null;
+    const rel = path.relative(repoRoot, resolved).split(path.sep).join('/');
+    return rel.startsWith('..') ? null : rel;
+  };
+  /** The initializer of `const <name> = ...` at the top level of `file`. */
+  const constOf = (file, name) => {
+    for (const statement of file.sourceFile.statements) {
+      if (!ts.isVariableStatement(statement)) continue;
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name) && declaration.name.text === name && declaration.initializer) return declaration.initializer;
+      }
+    }
+    return null;
+  };
+  return { parsed, resolve, constOf };
+}
+
+/** Whether `rel` lies in the integration folder `folder` (its index or any file of it). */
+const insideFolder = (rel, folder) => rel !== null && (rel === `${folder}/index.ts` || rel.startsWith(`${folder}/`));
+
+/** The array elements `expression` evaluates to in `file`, each with the file it is written in (identifiers, spreads and imports followed). */
+function elementsOf(ts, judge, file, expression, depth = 0) {
+  if (!expression || depth > 6) return [];
+  let node = expression;
+  while (ts.isAsExpression(node) || ts.isSatisfiesExpression?.(node) || ts.isParenthesizedExpression(node)) node = node.expression;
+  if (ts.isArrayLiteralExpression(node)) {
+    return node.elements.flatMap((element) => (ts.isSpreadElement(element) ? elementsOf(ts, judge, file, element.expression, depth + 1) : [{ file, node: element }]));
+  }
+  if (!ts.isIdentifier(node)) return [];
+  const local = judge.constOf(file, node.text);
+  if (local) return elementsOf(ts, judge, file, local, depth + 1);
+  const imported = file.imports.get(node.text);
+  if (!imported) return [];
+  const target = judge.resolve(file.rel, imported.source);
+  const other = target ? judge.parsed(target) : null;
+  return other ? elementsOf(ts, judge, other, judge.constOf(other, imported.imported), depth + 1) : [];
+}
+
+/** Whether a factory element calls `<X>.register(...)` with `<X>` imported (in the element's file) from the integration folder. */
+function registersIntegration(ts, judge, element, folder) {
+  let registers = false;
+  walk(ts, element.node, (node) => {
+    if (registers || !ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return;
+    if (node.expression.name.text !== 'register' || !ts.isIdentifier(node.expression.expression)) return;
+    const binding = element.file.imports.get(node.expression.expression.text);
+    if (binding && insideFolder(judge.resolve(element.file.rel, binding.source), folder)) registers = true;
+  });
+  return registers;
+}
+
+/** Whether `name`, exported by the module `rel`, is declared as an enum there or in the file it is re-exported from. */
+function exportsEnum(ts, judge, rel, name, depth = 0) {
+  const file = rel ? judge.parsed(rel) : null;
+  if (!file || depth > 4) return false;
+  for (const statement of file.sourceFile.statements) {
+    if (ts.isEnumDeclaration(statement) && statement.name.text === name) return true;
+    if (!ts.isExportDeclaration(statement) || !statement.exportClause || !ts.isNamedExports(statement.exportClause)) continue;
+    for (const element of statement.exportClause.elements) {
+      if (element.name.text !== name) continue;
+      const original = (element.propertyName ?? element.name).text;
+      if (statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) return exportsEnum(ts, judge, judge.resolve(rel, statement.moduleSpecifier.text), original, depth + 1);
+      return exportsEnum(ts, judge, rel, original, depth + 1);
+    }
+  }
+  return false;
+}
+
+/** What one spec proves about the integration in `folder`: { modules, errorCode, outage }. */
+function judgeSpec(ts, judge, rel, folder) {
+  const spec = judge.parsed(rel);
+  const result = { modules: false, errorCode: false, outage: false };
+  if (!spec) return result;
+  const worlds = new Set();
+  walk(ts, spec.sourceFile, (node) => {
+    if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression) || node.expression.text !== 'useTestWorld' || !spec.imports.has('useTestWorld')) return;
+    const [argument] = node.arguments;
+    if (!argument || !ts.isObjectLiteralExpression(argument)) return;
+    const modules = argument.properties.find((property) => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === 'modules');
+    if (!modules) return;
+    if (ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)) worlds.add(node.parent.name.text);
+    if (elementsOf(ts, judge, spec, modules.initializer).some((element) => registersIntegration(ts, judge, element, folder))) result.modules = true;
+  });
+  const enumBindings = new Set(
+    [...spec.imports].filter(([, binding]) => {
+      const target = judge.resolve(rel, binding.source);
+      return insideFolder(target, folder) && exportsEnum(ts, judge, target, binding.imported);
+    }).map(([local]) => local),
+  );
+  walk(ts, spec.sourceFile, (node) => {
+    if (ts.isIdentifier(node) && enumBindings.has(node.text) && !ts.isImportSpecifier(node.parent)) result.errorCode = true;
+    if (!ts.isPropertyAccessExpression(node)) return;
+    const chain = chainOf(ts, node);
+    if (!chain || !worlds.has(chain[0])) return;
+    const [, area, name, call] = chain;
+    const called = ts.isCallExpression(node.parent) && node.parent.expression === node;
+    if (area === 'infra' && name !== undefined && INFRA_OUTAGES.has(call) && called) result.outage = true;
+    else if (area === 'interruptDatabase' && called) result.outage = true;
+    else if (OUTAGE_CALLS[area] !== undefined && name !== undefined && call === OUTAGE_CALLS[area] && called) result.outage = true;
+  });
+  return result;
+}
+
+const MISSING_PARTS = Object.freeze({
+  modules: 'call useTestWorld({ modules }) with a factory that registers the integration module (<Provider>Module.register) imported from the integration',
+  errorCode: "reference the integration's ErrorCode enum (its refusal mapping)",
+  outage: 'drive an outage through the world: world.infra.<service>, world.fake.<name>.failNext(...), world.apps.<peer>.during(...) or world.interruptDatabase(...)',
+});
+
+/** The findings of R112 over the tracked paths `files` of the app at `repoRoot`. */
+export function integrationSpecFindings({ repoRoot, files }) {
+  const integrations = files.map((file) => CONFIG_FILE.exec(file)).filter(Boolean).map(([, side, provider]) => ({ side, provider, folder: `${side}src/modules/integrations/${provider}` }));
+  if (integrations.length === 0) return [];
+  const ts = typescriptFor(repoRoot);
+  const findings = [];
+  for (const { side, provider, folder } of integrations) {
+    const specDir = `${side}src/tests/integration/${provider}/`;
+    const specs = files.filter((file) => file.startsWith(specDir) && file.endsWith(SPEC_SUFFIX) && !file.slice(specDir.length).includes('/')).sort();
+    if (specs.length === 0) {
+      findings.push(found(INTEGRATION_SPEC_MISSING, `${folder}/`, `${folder}/ is an integration with no integration spec: add ${specDir}<name>${SPEC_SUFFIX} that ${MISSING_PARTS.modules}, ${MISSING_PARTS.errorCode}, and ${MISSING_PARTS.outage}.`, { provider, missing: ['spec'] }));
+      continue;
+    }
+    if (ts === null) {
+      findings.push(found(INTEGRATION_SPEC_MISSING, `${folder}/`, `${folder}/ cannot be judged: no TypeScript resolves from the app; install the app's dependencies.`, { provider, missing: ['typescript'] }));
+      continue;
+    }
+    const judge = judgeOf(ts, repoRoot, side);
+    const verdicts = specs.map((spec) => ({ spec, ...judgeSpec(ts, judge, spec, folder) }));
+    if (verdicts.some((verdict) => verdict.modules && verdict.errorCode && verdict.outage)) continue;
+    const best = [...verdicts].sort((a, b) => Number(b.modules) + Number(b.errorCode) + Number(b.outage) - (Number(a.modules) + Number(a.errorCode) + Number(a.outage)))[0];
+    const missing = Object.keys(MISSING_PARTS).filter((part) => !best[part]);
+    findings.push(found(INTEGRATION_SPEC_MISSING, `${folder}/`, `${folder}/ has integration specs (${specs.join(', ')}), but none proves the integration: ${best.spec} must also ${missing.map((part) => MISSING_PARTS[part]).join('; and ')}.`, { provider, missing }));
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-tree.mjs

@@ -4,7 +4,7 @@
 // Read-only: it walks the file system and asks git, nothing else.
 import fs from 'node:fs';
 import path from 'node:path';
-import { gitOutput } from './git.mjs';
+import { gitOutput } from '../api/git/lib.mjs';
 import { posixPath } from './path-key.mjs';
 
 /** Directory names no tree check enters: git's own store and installed packages. */

package/runtime/scripts/lib/package-at.mjs

@@ -0,0 +1,25 @@
+// scripts/lib/package-at.mjs — a package the runtime does not ship (playwright, esbuild, tailwindcss) comes from the
+// project that owns it: node resolution from that project's directory, walking up its node_modules.
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+/** The package.json of `name` as resolved from `dir`, or null. */
+export const packageAt = (dir, name) => {
+  try { return createRequire(path.join(dir, 'package.json')).resolve(`${name}/package.json`); } catch { return null; }
+};
+
+/** The first of `names` resolvable from the first of `dirs` that has one: {name, root, packageFile, version} or null. */
+export function findPackage(dirs, names) {
+  for (const dir of dirs.filter(Boolean)) {
+    for (const name of names) {
+      const packageFile = packageAt(dir, name);
+      if (!packageFile) continue;
+      const require = createRequire(packageFile);
+      return { name, root: path.dirname(packageFile), packageFile, version: require(packageFile).version };
+    }
+  }
+  return null;
+}
+
+/** The CommonJS entry of a package found by findPackage. */
+export const requirePackage = (found) => createRequire(found.packageFile)(found.name);

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

@@ -3,7 +3,7 @@
 // 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 './git.mjs';
+import { gitOutput } from '../api/git/lib.mjs';
 
 const git = (root, args) => gitOutput(args, { cwd: root }).trim();
 const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };

package/runtime/scripts/lib/safe-remove.mjs

@@ -18,11 +18,11 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { sleepSync } from './sleep-sync.mjs';
 import { samePath } from './path-key.mjs';
-import { gitSpawn } from './git.mjs';
+import { gitSpawn } from '../api/git/lib.mjs';
+import { rmdirLink } from '../api/fs/rmdir-link.mjs';
 import { artifactHoldReason } from './artifact-hold.mjs';
 import { realpathOr } from './fs-kind.mjs';
 
@@ -186,7 +186,7 @@ export function removeLink(p) {
   if (WIN) {
     let st = null;
     try { st = fs.lstatSync(p); } catch { return true; }
-    if (st.isDirectory() || st.isSymbolicLink()) spawnSync('cmd', ['/d', '/c', 'rmdir', p], { windowsHide: true, encoding: 'utf8' });
+    if (st.isDirectory() || st.isSymbolicLink()) rmdirLink(p);
   }
   return unlinkOnly(p);
 }
@@ -213,7 +213,7 @@ export function mainCheckoutDamage(before, after) {
 }
 
 /**
- * The link step of every worktree removal (git's here, Orca's in scripts/lib/worktrees.mjs removeOrcaWorktree): every link
+ * The link step of every worktree removal (git's here, Orca's in scripts/api/orca/worktree-remove.mjs removeOrcaWorktree): every link
  * under `target` found WITHOUT following one (linksUnder), each removed as a link (removeLink: `cmd /c rmdir <link>`, never
  * /s), outermost first, then a re-scan that must find ZERO. {ok, links, errors: [{path, code, message}]}; ok false: a link
  * is stuck and the caller removes nothing.