@starci/hfs 4.0.4 → 4.0.6

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.
+
+## Unreleased (alpha.4, bumped in C0's batch)
+
+- Changed (contract change `sonar-services-coverage`): Sonar and Codecov judge the services' coverage. The managed `sonar-project.properties` adds `sonar.javascript.lcov.reportPaths=be/coverage/lcov.info` and `sonar.coverage.inclusions=be/src/**/*.service.ts`; a new managed `codecov.yml` (slot `app.quality-config`, now `{sonar-project.properties,codecov.yml}`) holds the same paths at 100 on the project and the patch and ignores `fe/**`; the managed CI workflow uploads the be lcov with `codecov/codecov-action@v5` and the `CODECOV_TOKEN` secret after the unit run. Both files are rendered from one scope, `coverageScope(presets)`: the installed jest preset's `COVERAGE_SOURCES` on the be side (`loadPresets` now returns `coverageSources`). An app re-renders with `hfs sync --write`.
+- Changed: the bundled runtime copies of `knowledge/sonar-gate.yaml` (coverage 100 overall and on new code, per file; every hotspot reviewed), `knowledge/hfs/slots.yaml` (the quality-config slot) and `modules/kernel/failure-codes.yaml` (the R11 law and HFS_SONAR_CONFIG text).
+
 ## 4.0.4 - 2026-10-01
 
 - Changed: the bundled runtime copy of knowledge/hfs/canon-pins.yaml pins @starci/test-world 1.0.3. No rule or command changed.

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) |
@@ -70,7 +71,7 @@ Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rende
 | `FE_I18N_KEYS` | error | a literal key read through `next-intl` that a locale lacks, or a catalog key no source reads (R106; the architecture machine) |
 | `FE_NO_TESTS` | error | a front end holds a `*.spec.*`, `*.test.*` or `*-spec.*` file, an `e2e/`, `__tests__/`, `__mocks__/` or `test-support/` directory, a vitest, Playwright, jest or Cypress file, a test script, or a test dependency in a `package.json`; no exception (R97; `scripts/lib/hfs-rules/fe-no-tests.mjs`) |
 | `HFS_GITIGNORE_BLOCK_DRIFT` | error | the managed `.gitignore` block differs from its render (R04; `sync/managed.mjs`) |
-| `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render: no `sonar.host.url`, the `sonar.exclusions` of the installed jest preset, no coverage import (R11; `sync/managed.mjs`) |
+| `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render: no `sonar.host.url`, the `sonar.exclusions` of the installed jest preset, the be lcov import with the services as the only coverage scope (R11; `sync/managed.mjs`) |
 | `HFS_FORMAT` | error | a tracked file the repository's own prettier would change (R19; `sync/format.mjs`, not under `--fast`) |
 | `HFS_FORMAT_TOOL_MISSING` | refusal (exit 2) | prettier is not installed in the repository; the format check is never skipped |
 
@@ -114,12 +115,14 @@ The managed `sonar-project.properties` carries `sonar.externalIssuesReportPaths`
 reaches Sonar while the job stays failed. There is no `continue-on-error`. CI runs `npm run lint -- --sonar reports/lint.sonar.json` once at the app root, before the scan. The duplicate-block threshold (`ruleParams.<side>.duplicateBlock`) has no Sonar property for TypeScript (SonarJS detects
 clones with its own token rule), so the machine enforces it (R21) and its findings are imported like every other.
 
-The gate is `knowledge/sonar-gate.yaml`, the one declaration: the new-code conditions (duplication, blocker and critical issues, hotspots; no coverage condition) and an `overall` part (0 open issues on the whole code,
-duplicated lines density, cognitive complexity through the S3776 rule). A SonarQube gate condition cannot filter by engine, so the condition counts every
+The gate is `knowledge/sonar-gate.yaml`, the one declaration: the new-code conditions (coverage 100, duplication, blocker and critical issues, hotspots) and an `overall` part (coverage 100, 0 open issues on the whole code,
+every hotspot reviewed, duplicated lines density, cognitive complexity through the S3776 rule). A SonarQube gate condition cannot filter by engine, so the condition counts every
 open issue, imported or native; that is stricter than the three imports alone and is intended. `hfs check` reports `HFS_SONAR_CONFIG` (R11) when the
 properties file is not its render or the stack declaration names another gate. R20 and R21 have their Sonar enforcers as conditions of that file.
 
-Sonar does not depend on coverage: the managed properties file has no `sonar.*.lcov.reportPaths` and no `sonar.coverage.*`, the gate has no coverage condition, and the managed CI workflow uploads no coverage anywhere (no Codecov). The back end's unit coverage is the runner's: the managed `test` script is `jest --selectProjects unit --coverage`, which fails below the per-file 100 threshold on `src/**/*.service.ts`.
+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` (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.4",
+  "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';
@@ -43,9 +43,9 @@ import { redactBytes, redactData, redactText } from '../scripts/lib/redact.mjs';
 const require = createRequire(import.meta.url);
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 export const MACHINE_SCHEMA = 'starci/machine@1';
-export const MACHINE_VERSION = 2;
+export const MACHINE_VERSION = 3;
 /** Forward migrations after 0001-init, in order; each bumps user_version to its `version` (migrateMachine). */
-export const MACHINE_MIGRATIONS = Object.freeze([{ version: 2, name: '0002-worktrees-no-workflow-kind' }]);
+export const MACHINE_MIGRATIONS = Object.freeze([{ version: 2, name: '0002-worktrees-no-workflow-kind' }, { version: 3, name: '0003-worktrees-workflow-orca' }]);
 export const MACHINE_BUSY_TIMEOUT_MS = 15000;
 /** Test seam: STARCI_MACHINE_BUSY_TIMEOUT_MS (a positive integer) replaces the writer's busy_timeout; unset in production. */
 export const busyTimeoutOf = (env = process.env) => { const n = Number(env?.STARCI_MACHINE_BUSY_TIMEOUT_MS); return Number.isInteger(n) && n > 0 ? n : MACHINE_BUSY_TIMEOUT_MS; };
@@ -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/engine/migrations/machine/0003-worktrees-workflow-orca.sql

@@ -0,0 +1,21 @@
+-- 0003-worktrees-workflow-orca (starci/machine@1, user_version 2 -> 3). Applied by engine/machine-db.mjs migrateMachine on
+-- the first writer open of an older machine.sqlite (after an integrity_check and a VACUUM INTO backup, with foreign_key_check
+-- + quick_check before COMMIT); a fresh machine.sqlite runs 0001 then the forward files.
+--
+-- One worktree per Kernel workflow replaces the per-op worktree (owner decision WFWT, final). Orca creates and owns it (the
+-- Kernel launch), so the registry keys it by Orca's worktree id (orca_id, unique among the rows that have one), records
+-- the workflow's last checkpoint (checkpoint_sha) and the moment its finish asked for its release (release_pending_at: the
+-- host-side GC removes it once the Kernel's and the ops' terminals are released; never from inside itself). The draw
+-- critic's placement is an Orca worktree too (kind critic). worktrees.kind no longer accepts 'op': a row of that kind
+-- describes the removed mechanism and is deleted (a directory it named, if any is left, is an unregistered worktree the
+-- worktree GC and the footprint scan report); then the table's CHECK is rewritten in place (writable_schema: the views over worktrees stay as they are).
+DELETE FROM worktrees WHERE kind='op';
+ALTER TABLE worktrees ADD COLUMN orca_id TEXT;
+ALTER TABLE worktrees ADD COLUMN checkpoint_sha TEXT;
+ALTER TABLE worktrees ADD COLUMN release_pending_at INTEGER;
+CREATE UNIQUE INDEX IF NOT EXISTS ux_worktrees_orca_id ON worktrees(orca_id) WHERE orca_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS ix_worktrees_workflow ON worktrees(workflow_id,kind,removed_at);
+PRAGMA writable_schema=ON;
+UPDATE sqlite_master
+   SET sql=replace(sql, 'CHECK(kind IN (''op'',''land-scratch'',', 'CHECK(kind IN (''workflow'',''critic'',''land-scratch'',')
+ WHERE type='table' AND name='worktrees';

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

@@ -16,6 +16,13 @@ purpose: >-
 pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
+  '@starci/heroicons':
+    version: 0.3.1
+    group: starci
+    install: registry
+    side: fe
+    source: packages/heroicons/package.json
+    why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
     version: 0.8.1
     group: starci
@@ -24,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.4
+    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.4
+    version: 8.0.6
     group: starci
     install: registry
     side: fe
@@ -57,21 +64,21 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.2.1
+    version: 2.2.2
     group: starci
     install: registry
     side: be
     source: packages/jest-preset/package.json
-    why: '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.'
+    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.4
+    version: 4.0.6
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/slots.yaml

@@ -246,7 +246,7 @@ slots:
     rules: [HFS_TOOL_CONFIG_LOCAL]
   - id: app.quality-config
     profiles: [app]
-    path: sonar-project.properties
+    path: "{sonar-project.properties,codecov.yml}"
     presence: required
     tracked: tracked
     tier: none
@@ -373,7 +373,7 @@ slots:
     tracked: external
     tier: none
     tests: none
-    goesTo: "D:/starci-lanes/<project>/<lane>/ (outside every repository) for a lane; a runtime op worktree (.starciwork/worktrees/<op>) is git-excluded, never tracked, and removed when its op settles"
+    goesTo: "D:/starci-lanes/<project>/<lane>/ (outside every repository) for a lane; a Kernel workflow's worktree is created and owned by Orca outside the app checkout, never tracked, and removed by the runtime's host-side controller once the workflow's finish marked it release-pending"
   - id: app.plaintext-env
     profiles: [app]
     path: "{.env,.env.*,.secrets/,**/*.pem,**/*.key}"
@@ -387,12 +387,12 @@ slots:
   # ----- side root (both sides): what the old standalone repository root held, less the app-root files ----------
   - id: repo.side-root-forbidden
     profiles: [be, fe]
-    path: "{package.json,package-lock.json,hfs.json,README.md,.gitignore,.gitattributes,.husky/,.github/,.starciwork/,.starcistacks/,.sops.yaml,sonar-project.properties,.prettierrc,.prettierignore,scripts/}"
+    path: "{package.json,package-lock.json,hfs.json,README.md,.gitignore,.gitattributes,.husky/,.github/,.starciwork/,.starcistacks/,.sops.yaml,sonar-project.properties,codecov.yml,.prettierrc,.prettierignore,scripts/}"
     presence: forbidden
     tracked: external
     tier: none
     tests: none
-    goesTo: "the app root: one package.json, lockfile, hfs.json, README, git and CI files, hooks, formatter, Sonar configuration, scripts/, .starciwork, .starcistacks and .sops.yaml per app"
+    goesTo: "the app root: one package.json, lockfile, hfs.json, README, git and CI files, hooks, formatter, Sonar and Codecov configuration, scripts/, .starciwork, .starcistacks and .sops.yaml per app"
   - id: be.tool-config
     profiles: [be]
     # Managed files (hfs sync renders them, hfs check compares them): the whole tool configuration of a back end. Each is
@@ -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/knowledge/sonar-gate.yaml

@@ -8,16 +8,24 @@ purpose: |
   conditions and selects it for the project, and (2) judges an op's slice - the lines it changed - against
   the same numbers. Code-writing ops cannot settle done while the slice is red
   (scripts/kernel/sonar-settle.mjs). Changing a number here changes every repository on the next scan.
-  The gate has two parts: `newCode` (the recent work: duplication, blocker/critical issues, hotspots) and
-  `overall` (the whole code: no imported HFS, ESLint or stylelint finding, no duplicated-lines excess, no cognitive-
-  complexity issue). The one Sonar mechanism of the HFS canon is packages/hfs/README.md section "Sonar".
+  The gate has two parts: `newCode` (the recent work: coverage, duplication, blocker/critical issues, hotspots) and
+  `overall` (the whole code: coverage, no imported HFS, ESLint or stylelint finding, no bug, code smell or
+  vulnerability, every hotspot reviewed, no duplicated-lines excess, no cognitive-complexity issue). The one Sonar
+  mechanism of the HFS canon is packages/hfs/README.md section "Sonar".
 gate:
   name: starci-new-code
   # A project with no new-code baseline judges the whole project as new code (nivo inc-f92febebbb64); a fixed
   # window keeps "new code" the recent work on main, so the server gate is passable on a healthy main.
   newCodePeriod: {type: NUMBER_OF_DAYS, value: 30}
 newCode:
-  # Sonar holds NO coverage condition: unit coverage is the runner's job (jest per-file 100 on `*.service.ts`), never an lcov import.
+  # Coverage of the services only. The be unit run writes coverage/lcov.info (@starci/jest-preset coverageReporters lcov) and the
+  # managed sonar-project.properties imports it (sonar.javascript.lcov.reportPaths=be/coverage/lcov.info) with
+  # sonar.coverage.inclusions=be/src/**/*.service.ts, the one scope rendered by hfs sync from the preset's COVERAGE_SOURCES (codecov.yml
+  # is rendered from the same constant). A handler, resolver, controller, module, config file or test is not a coverage target and
+  # fe/ is outside coverage entirely, so coverage on these conditions is the services' coverage alone.
+  coverage:
+    metric: new_coverage
+    minPercent: 100
   # SonarQube's ignoreSmallChanges: fewer changed lines than this are not held to duplication.
   ignoreBelowChangedLines: 20
   duplication:
@@ -49,6 +57,19 @@ overall:
     metric: violations
     max: 0
     engines: [starci-hfs, eslint, stylelint]
+    # The dashboard counts (`sonar-local dashboard`): each type of open issue, each held at `max`.
+    types: {bugs: BUG, code_smells: CODE_SMELL, vulnerabilities: VULNERABILITY}
+  # Every security hotspot of the whole code is reviewed (the dashboard's "hotspots reviewed").
+  hotspots:
+    metric: security_hotspots_reviewed
+    minReviewedPercent: 100
+  # The services' coverage (see newCode.coverage), overall and per file: with the inclusions in place each `*.service.ts` is its
+  # own measure, so one service below 100 fails the slice verdict (sonar-local evaluateSlice) and the dashboard verdict
+  # (sonar-local dashboard) although the project average may round to 100. A file outside the inclusions is never read.
+  coverage:
+    metric: coverage
+    minPercent: 100
+    perFile: true
   # HFS_DUPLICATE_CODE (R21): duplicated lines density of the whole project, the Sonar enforcer of the machine's clone check.
   # SonarJS runs its own token-based detection (sonar.cpd.* minimums are not read for TypeScript), so ruleParams.<profile>.duplicateBlock
   # is enforced by the machine and imported as starci-hfs issues, and this density is the Sonar-side backstop.
@@ -70,8 +91,10 @@ enforcedOps: [backend.implement, interface.implement, code.refactor]
 reasoning: |
   Chosen against the four projects the local server holds on 2026-09-29 (whole-project duplicated lines
   1.6 / 2.1 / 1.7 / 0.0 percent), so new code that meets them is at or below what main already carries.
-  no coverage condition: the unit project fails below its per-file 100 threshold on `*.service.ts`, so Sonar never
-  imports an lcov report and never judges coverage.
+  coverage 100 on services, overall and new code (owner 2026-10-01): the unit project already fails below its per-file
+  100 threshold on `*.service.ts`; Sonar imports the same run's lcov with the same scope, so the dashboard, the slice
+  verdict and the server gate show the number the runner enforces, file by file. Only services count: business logic
+  lives there, the thin layers are covered through them, and the front end has no unit tests.
   duplication 3: the Sonar way value; the worst project today is 2.1, so 3 rejects a real copy-paste block and
   passes ordinary work.
   blocker/critical 0: the two severities that are defects, not style. main carries old debt of both kinds

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"
@@ -1482,11 +1492,11 @@ HFS_SLOT_UNDECLARED:
   kind: check-finding
 
 HFS_SONAR_CONFIG:
-  title: "Sonar config is generated, with no host URL and no coverage import"
+  title: "Sonar config is generated, with no host URL, importing the be lcov with the services as the only coverage scope"
   title_vi: "Cấu hình Sonar lệch"
-  meaning_vi: "Cấu hình Sonar lệch: `<detail>`. Sonar phải đọc đúng cấu hình sinh ra, không nhập báo cáo độ phủ."
+  meaning_vi: "Cấu hình Sonar lệch: `<detail>`. Sonar phải đọc đúng cấu hình sinh ra và nhập báo cáo độ phủ lcov của be, chỉ tính các service."
   causes_vi:
-    - "Vi phạm luật R11: `sonar-project.properties` do template sinh: không `sonar.host.url`, `sources`/`tests` không chồng, `sonar.exclusions` = đúng danh sách loại trừ của jest, không nhập lcov hay `sonar.coverage.*`, không nhắc kiểu spec đã bỏ, và nhận báo cáo ESLint cùng tệp nhập lỗi HFS (`sonar.eslint.reportPaths`, `sonar.externalIssuesReportPaths`) để mọi lỗi canon hiện trong Sonar."
+    - "Vi phạm luật R11: `sonar-project.properties` do template sinh: không `sonar.host.url`, `sources`/`tests` không chồng, `sonar.exclusions` = đúng danh sách loại trừ của jest, nhập lcov của be (`sonar.javascript.lcov.reportPaths=be/coverage/lcov.info`) với `sonar.coverage.inclusions=be/src/**/*.service.ts` và không khóa độ phủ nào khác, không nhắc kiểu spec đã bỏ, và nhận báo cáo ESLint cùng tệp nhập lỗi HFS (`sonar.eslint.reportPaths`, `sonar.externalIssuesReportPaths`) để mọi lỗi canon hiện trong Sonar."
     - "Khối `services.sonar.qualityGate` của khai báo stack phải gọi đúng cổng chất lượng duy nhất của `knowledge/sonar-gate.yaml`; repo không tự ghi ngưỡng."
   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 (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
   owner: op-retry

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);
 }
@@ -212,6 +212,21 @@ export function mainCheckoutDamage(before, after) {
   return out;
 }
 
+/**
+ * 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.
+ */
+export function removeLinksUnder(target) {
+  const out = { ok: false, links: 0, errors: [] };
+  if (!fs.existsSync(target)) { out.ok = true; return out; }
+  for (const link of linksUnder(target)) { if (removeLink(link)) out.links += 1; else out.errors.push({ path: link, code: 'LINK_STUCK', message: 'a link could not be removed' }); }
+  for (const l of linksUnder(target)) if (!out.errors.some((e) => e.path === l)) out.errors.push({ path: l, code: 'LINK_STUCK', message: 'a link is still there after removal' });
+  out.ok = out.errors.length === 0;
+  return out;
+}
+
 /**
  * Remove a git worktree (the one algorithm; the 490-file .claude incident and nivo-fe inc-c8fbf76aa499):
  *   1. enumerate every link in it WITHOUT following one (linksUnder);
@@ -236,13 +251,9 @@ export function safeRemoveWorktree(worktree, { repo, git = null, retries = 5 } =
   if (refused) { out.errors.push({ path: target, code: 'REFUSED', message: `refusing to remove ${refused}` }); return out; }
   const before = mainRoot ? mainCheckoutGuard(mainRoot, { git: run }) : null;
   if (fs.existsSync(target)) {
-    for (const link of linksUnder(target)) { if (removeLink(link)) out.links += 1; else out.errors.push({ path: link, code: 'LINK_STUCK', message: 'a link could not be removed' }); }
-    const left = linksUnder(target);
-    if (left.length) {
-      for (const l of left) if (!out.errors.some((e) => e.path === l)) out.errors.push({ path: l, code: 'LINK_STUCK', message: 'a link is still there after removal' });
-      out.reason = 'link-stuck';
-      return out;
-    }
+    const unlinked = removeLinksUnder(target);
+    out.links = unlinked.links;
+    if (!unlinked.ok) { out.errors.push(...unlinked.errors); out.reason = 'link-stuck'; return out; }
     out.removed.links = out.links;
     const registered = trees.some((t) => same(t, target));
     if (registered && repo) run(['worktree', 'remove', '--force', target], { cwd: repo });

package/sync/index.mjs

@@ -8,7 +8,8 @@
 // side (be, fe) for a side slot, whose files land under that side's folder. Two targets are not whole files of a managedBy slot
 // and are listed in this module: the marked block of the root .gitignore, and .starciwork/.gitignore, which lives inside the
 // .starciwork directory slot. Every file is rendered with the app's hfs.json (both sides and their apps) and, for the Sonar
-// exclusions, the jest preset the app installs for its be side. `--check` compares the sha256 of the rendered content with the
+// exclusions and the one coverage scope (sonar.coverage.inclusions and codecov.yml alike), the jest preset the app installs for
+// its be side. `--check` compares the sha256 of the rendered content with the
 // file on disk and fails on any drift; `--write` rewrites the drifted files. `.gitignore` is the one shared file: only the marked
 // block is managed and the app's own lines around it are left alone. The root package.json is managed by its `scripts` block
 // only (mode scripts, compared as parsed JSON): the rest of the file (dependencies, npm workspaces of fe/packages/*) is the app's.
@@ -98,7 +99,10 @@ export function render(text, vars, readTemplate = readBundled) {
   });
 }
 
-/** The Sonar exclusions from the jest preset the app installs for its be side: { sonarExclusions }. */
+/**
+ * What the app's sync reads from the jest preset it installs for its be side: the Sonar exclusions and the coverage sources
+ * (`COVERAGE_SOURCES`, the globs jest collects coverage from): { sonarExclusions, coverageSources }.
+ */
 export async function loadPresets(root) {
   const name = '@starci/jest-preset';
   const require = createRequire(path.join(root, 'package.json'));
@@ -109,7 +113,21 @@ export async function loadPresets(root) {
     throw new SyncError('HFS_SYNC_PRESET_MISSING', `${name} is not installed under ${root}; set it to the exact version in knowledge/hfs/canon-pins.yaml and reinstall`);
   }
   const preset = require(resolved);
-  return { sonarExclusions: preset.sonarExclusions() };
+  return { sonarExclusions: preset.sonarExclusions(), coverageSources: [...preset.COVERAGE_SOURCES] };
+}
+
+/** Where the be unit run writes the lcov report (jest `coverageDirectory` coverage under be/, reporter lcov), from the app root. */
+export const LCOV_REPORT = 'be/coverage/lcov.info';
+
+/**
+ * THE coverage scope of an app, from the app root: the preset's coverage sources on the be side (`be/src/**` + `/*.service.ts`).
+ * It is the one source of sonar.coverage.inclusions and of the codecov.yml status paths, so the two can never drift; fe/ is
+ * outside it (a front end has no tests).
+ */
+export function coverageScope(presets) {
+  const sources = presets?.coverageSources;
+  if (!Array.isArray(sources) || !sources.length) throw new SyncError('HFS_SYNC_PRESET_MISSING', '@starci/jest-preset gives no COVERAGE_SOURCES: the coverage scope cannot be rendered');
+  return sources.map(glob => `be/${glob}`);
 }
 
 /**
@@ -156,6 +174,9 @@ export function variables(app, scope, presets, sonarKey) {
     sonarKey: sonarKey ?? app.project,
     sonarExclusions: [presets?.sonarExclusions, '**/.next/**', '**/node_modules/**', '**/src/messages/**'].filter(Boolean).join(','),
     sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
+    lcovReport: LCOV_REPORT,
+    coverageInclusions: scope === APP_SCOPE ? coverageScope(presets).join(',') : '',
+    codecovPaths: scope === APP_SCOPE ? coverageScope(presets).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
     tsconfigPaths: ['be/tsconfig.json', ...feTsconfigs].join(','),
     styleGlob: STYLE_GLOB,
   };

package/sync/managed.mjs

@@ -20,7 +20,7 @@
 //                                 `prettier`, `lint-staged`, `jest`). Forbidden tool-config files (.eslintrc*, .eslintignore, a second
 //                                 eslint.config.*) are refused by hfs-check through the slot manifest under the same code.
 //   HFS_SONAR_CONFIG (R11)        sonar-project.properties differs from its render (the render names no host URL, sources and tests that
-//                                 do not overlap, the `sonar.exclusions` of the jest preset (a back end), no coverage import, the ESLint report and the
+//                                 do not overlap, the `sonar.exclusions` of the jest preset (a back end), the be lcov with the services as the coverage scope, the ESLint report and the
 //                                 HFS import files Sonar reads), or the stack declaration names a quality gate other than the one
 //                                 gate of knowledge/sonar-gate.yaml (bundled in the runtime copy). One edit is one finding.
 //   HFS_TS_STRICT (R22)           the root tsconfig.json drift (either profile), named by flag (ts-strict.mjs) instead of by hash.

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -14,6 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -29,6 +30,14 @@ jobs:
         run: npm run typecheck
       - name: unit
         run: npm test -- --ci
+      - name: coverage upload
+        uses: codecov/codecov-action@v5
+        if: ${{ !cancelled() && env.CODECOV_TOKEN != '' }}
+        with:
+          token: ${{ env.CODECOV_TOKEN }}
+          files: {{lcovReport}}
+          disable_search: true
+          fail_ci_if_error: true
       - name: build be
         run: npm run build:be
       - name: build fe

package/templates/app/quality-config/codecov.yml

@@ -0,0 +1,22 @@
+{{header}}
+# The be unit run's lcov ({{lcovReport}}), uploaded by the managed CI workflow. Coverage is the services' alone: the status
+# paths are the one coverage scope hfs sync renders into sonar.coverage.inclusions too, held at 100 on the project and on
+# the patch. fe/ is outside coverage (a front end has no tests).
+codecov:
+  require_ci_to_pass: true
+coverage:
+  status:
+    project:
+      default:
+        target: 100%
+        threshold: 0%
+        paths:
+{{codecovPaths}}
+    patch:
+      default:
+        target: 100%
+        threshold: 0%
+        paths:
+{{codecovPaths}}
+ignore:
+  - "fe/**"

package/templates/app/quality-config/sonar-project.properties

@@ -7,4 +7,6 @@ sonar.exclusions={{sonarExclusions}}
 sonar.test.inclusions=**/*.spec.ts
 sonar.typescript.tsconfigPaths={{tsconfigPaths}}
 sonar.externalIssuesReportPaths=reports/lint.sonar.json
+sonar.javascript.lcov.reportPaths={{lcovReport}}
+sonar.coverage.inclusions={{coverageInclusions}}
 sonar.nodejs.maxspace=8192