@starci/hfs 4.12.2 → 4.13.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 4.13.0 - 2026-10-31
+
+The delivery pipeline of an app (contexts/project/cicd.md, ruling app-cicd-auto-deploy; owner approval 2026-10-31: every green release tag deploys by itself, STARCI_DEPLOY_PAUSED is the brake, agents deploy, the CI deploy key is sealed, pull requests get CI, contract migrations run after the accept, Sonar judges every full run, images are cached in GitHub Actions and built for amd64 unless declared).
+
+- Added: `starci app stack status --env <env>` (read-only) compares the live services of the stack with the accepted release and reports drift per service (`rolled back by swarm`, `updated outside a release`, `missing`, `not in the release`); `stack verify` fails on the same drift when the stack file pins its images by digest.
+- Added: every executing `stack deploy`, `rollback` and `accept` is one recorded attempt: it takes `/srv/<stack>/deploy.lock` on the manager (shared with the urgent deploy, a bounded wait, then `STACK_DEPLOY_LOCKED`), writes `deploys/<attempt>.json` at every phase boundary plus the append-only `deploys.jsonl`, and snapshots the live services after converge, after a rollback and on accept (`release.json` gains `observed`).
+- Added: `stack deploy --ci-run <id>` marks the attempt as a CI one and `--redeploy` deploys although the accepted release already runs the commit; without it a deploy of the commit the accepted release already runs, with matching services, ends green as `already-current`.
+- Changed: preflight pulls the images of the rollback target too and refuses (`STACK_DEPLOY_ROLLBACK_PULL`) before the services are touched when one no longer pulls.
+
+- Added: every deploy of an app that declares the `database:` block of application-stacks.yaml runs the database phases of `stack/db-phases.mts`. Before the stack deploy: `db-preview` (migrate preview of every pending migration; red refuses `STACK_DEPLOY_MIGRATE_PREVIEW_RED`), `backup` only when something is pending (a fresh dump made on the manager from the database container, age-encrypted to the `.sops.yaml` recipients and the server recipient, kept in `<deploy.backup.dir | /var/backups/<stack>>/db`, receipt written beside it and judged against a second reading of the archive, test decrypt on the manager with its own identity; codes `STACK_DEPLOY_BACKUP_FAILED`, `_UNVERIFIED`, `_DECRYPT_FAILED`; nothing pending means no backup and `data.migrations.backup` is null) and `migrate` (the expand migrations: every migration but `*_contract_*`; `STACK_DEPLOY_MIGRATE_FAILED`). Any refusal leaves the services untouched. After accept (in `stack deploy` and in `stack accept`): the `contract` pass applies the `*_contract_*` migrations; a red contract leaves the release accepted and the job red (`data.contractFailed`). A release that only carries a contract migration still gets its backup first. With no accepted release the deploy chooses the first start by itself (hold deploy, proof the database is empty, every migration inside the container, then the real deploy; `STACK_FIRST_START_NOT_EMPTY` refuses a database that holds data). `data.migrations` records pending files, backup receipt, applied versions and contract versions.
+- Added: `database.target` (`stack`, default, or `external`) and `database.service` (default `db`) in the `database:` block. A `stack` database is reached inside its own container with the credentials that container holds (`ownContainerTarget`: role and database from the container, password read inside it from `POSTGRES_PASSWORD_FILE`), so a deploy holds no `DATABASE_URL` and no password; `stack deploy --db-url-env` is refused for it (`STACK_DEPLOY_DB_URL_UNEXPECTED`). An `external` database keeps `--db-url-env` (also on `stack accept`) and dumps where the deploy runs (`--backup-out`).
+- Added: `db migrate` passes (`phase: all | expand | contract`) and `pushFiles` in its result data; `isContractMigration`.
+- Added: `DB_MIGRATION_DESTRUCTIVE` (R259) also judges a contract migration against the previous release: a contract migration that is new since the previous release tag (the newest `v*` tag HEAD contains, not on HEAD itself) and destroys an object that the be/src sources of that tag still reference is a hard blocker, because the deploy applies it right after the accept while that release is the rollback target. The code change goes in one release and its contract migration in the next. The check is git-based: no release tag, or an unreadable history, means no previous release and no finding.
+- Changed: the urgent floor shares these steps and their codes. `STACK_URGENT_BACKUP_FAILED`, `_BACKUP_UNVERIFIED`, `_DECRYPT_UNAVAILABLE`, `_DECRYPT_FAILED`, `_MIGRATE_PREVIEW_RED` and `_MIGRATE_FAILED` are now `STACK_DEPLOY_BACKUP_FAILED`, `STACK_DEPLOY_BACKUP_UNVERIFIED`, `STACK_DEPLOY_BACKUP_DECRYPT_UNAVAILABLE`, `STACK_DEPLOY_BACKUP_DECRYPT_FAILED`, `STACK_DEPLOY_MIGRATE_PREVIEW_RED` and `STACK_DEPLOY_MIGRATE_FAILED`. The urgent path keeps its operator-held `--db-url-env` and its always-on backup. `stack deploy` accepts `--db-url-env` and `--backup-out` without `--urgent` (for `database.target: external`). An app without a `database:` block deploys exactly as before.
+- Added: the urgent tag annotation carries the trailers `Starci-Urgent: <role>` and `Starci-Urgent-Reason: <text>` (`urgentTrailerBlock`, `parseUrgentTrailers` in release/records.mts; `release push --urgent` writes them), and the urgent record gains `trailers`. `stack deploy --ci-run <id>` is judged by the CLI (the jobs the CI standard requires, read from GitHub for the exact `--sha`); hfs takes the id only as the journal label of the attempt, after the CLI has accepted the run.
+- Added: the managed workflows render the pipeline. `ci.yml` runs on `pull_request` to main as well (read-only, no environment, no secret), and holds `plan` (full, defer or reuse from the event, the ref and a green candidate run of the same commit), the checks, `images` (the reusable images.yml, built once beside the checks), `verdict` (needs every job, runs always, the single required check) and one `deploy-<env>` call of the reusable stack-deploy.yml per environment with `deploy.auto`, in declared order, after the verdict. Sonar and the Codecov upload run on every full run (a release tag or a candidate), not on tags only.
+- Added: `images.yml` is a reusable workflow (`workflow_call`: `push`, `release`; output `refs`). It builds each declared app with buildx, the GitHub Actions cache (or `ci.imageCache: registry`) and an SBOM plus provenance (`mode=max`), pushes the deployed ones to GHCR under the immutable `sha-<sha>`, adds `v<version>` on a release run by retagging that digest (no rebuild), and collects the pushed digests as `{service: repository@sha256:...}`. An image whose public build values live in a sealed member is built by a second job bound to the release environment on a release tag run only; every other image builds with no environment and no secret. Platforms default to `linux/amd64` (`deploy.platforms`; `linux/arm64` adds QEMU).
+- Added: `stack-deploy.yml` is reusable and still dispatchable (`deploy`, `redeploy`, `rollback`). The automatic deploy reads the variable `STARCI_DEPLOY_PAUSED` of its GitHub Environment first and stops without a code change when it is `true` (a manual run ignores it), resolves each image to a digest (the calling run's, else the registry's `sha-<sha>` tag), finds the green CI run of the commit and calls `stack deploy --sha <sha> --ci-run <run>`. Its only secret is the environment's `SOPS_AGE_KEY`.
+- Added: the CI transport is the sealed member `vps-ci` of the environment (`VPS_SSH_KEY`, `VPS_KNOWN_HOSTS`, `VPS_HOST`, `VPS_USER`), opened with the server identity: `stack connect` prefers it over the job's `VPS_*` variables (which still work when the member is absent), pins the host keys with `StrictHostKeyChecking yes` and masks the host, the account and `deploy.remote.releasesBase` in the log of a public repository first.
+- Added: stacks schema keys `environments.<env>.deploy.auto` (default false), `deploy.approval` (`none` | `reviewers`) and `deploy.platforms` (default `[linux/amd64]`), and `ci.imageCache` (`gha` | `registry`).
+- Changed: R221 admits `workflow_call` and, in ci.yml only, `pull_request` to main (`branches: ['main']` and nothing else); `pull_request_target`, `workflow_run` and schedules stay refused. R251 judges a deployment caller (a job of ci.yml that calls the reusable stack-deploy.yml: permissions, concurrency and `with.environment`, no environment of its own), a workflow that runs on `pull_request` (read-only permissions, no job bound to an environment), recognises `starci app stack deploy|rollback|accept` as deployment commands, and judges the secrets allowlist and the dotenv ban on the deployment jobs rather than on the check jobs beside them (the Sonar token of ci.yml). R271 accepts the immutable `sha-${{ github.sha }}` tag from any ref and a release retag (`imagetools create`) only after a step under `if: ${{ inputs.release }}` that rejects a ref other than `refs/tags/v*`. R269 counts a job that the plan (`needs.plan.outputs.<x> == 'true'`) or a boolean input decides as enabled. R296 to R298 treat `vars.STARCI_DEPLOY_PAUSED` as a managed variable no app declares. The CI standard (R301) lists the jobs `plan`, `images` and `verdict` as required, the `deploy-<env>` calls after the verdict, and four new items (`pull-request-ci`, `images-once`, `deploy-brake`, the candidate trigger with pull requests).
+- Changed: R259 (`DB_MIGRATION_DESTRUCTIVE`) states the previous-release rule of the contract migration; `HFS_DB_DEPLOY_UNGUARDED` (R271) still judges a full app's own `db-deploy.yml` and a lite app that has not synced yet, with the pointer to the stack deploy.
+- Removed: the lite `db-deploy.yml` workflow. A lite app migrates in the migrate phase of its stack deploy (a verified backup, the expand migrations before the services, the contract migrations after the accept); `starci app sync --execute` deletes the file and the slot `app.ci-db` is forbidden in lite. The old tarball `images.yml` (never pushed) and the build-and-push step list of `stack-deploy.yml` are gone: the deployed digest is now the attested one the checks ran beside.
+
+- Added: the committed app check cache (ruling app-check-cache, contexts/project/check-cache.md). `starci app check` runs every family diff-only against `.starcistacks/cache/` and writes what it judged back; `--full` runs the selected families in full; the selectors `--hfs --format --db --secrets --wiring --types --lint --test --sonar` run one family each and combine. Each family prints one diagnosis line (full or diff and why, checked, reused, findings new, known, fixed); progress goes to stderr with a percentage (whole lines off a terminal, `--quiet` silences it); timings go to the untracked tool cache. `STARCI_APP_CHECK_CACHE=verify` runs diff then full and fails with exit 2 on any difference; `=full` never reads the cache (the release gate sets it on every gate row). New `cache/` modules: types, hashing (CRLF to LF), JSON Lines, fingerprint, content index, trust (host: the working tree; CI: the cache at the merge-base or first parent), session, progress, run log, the hfs, secrets, db, wiring and format families, an in-memory fake session.
+- Added: slot `app.starcistacks.cache` (slots 3.15.0, both editions); rule R343 with HFS_CHECK_CACHE_FORGED (hard blocker at any count), HFS_CHECK_CACHE_STALE and HFS_CHECK_CACHE_MISSING (warnings); the managed `.gitignore` re-includes the folder, `.gitattributes` marks it `merge=union linguist-generated`, the managed CI runs `app check --format` and sets the cache env to full on release candidates and tags, `db:lint` runs `app check --db`.
+- Changed: Prettier (HFS_FORMAT) runs in batches of 64 files spread over worker threads that load the repository's prettier once, with configuration resolved once per directory (it was one lookup per file).
+- Removed: `app check --fast`, `--base` and `--force`; `--wiring` is now the wiring family.
+
+- Changed: the bundled canon pins name the 0.16.3 cohort (@starci/grammar, eslint-grammar-core and eslint-grammar-offset-pop 0.16.3, eslint-canon-fe 9.6.3, eslint-canon-be 3.9.3, stylelint-canon 2.3.0, jest-preset 2.6.0, hfs 4.13.0); ChatWorkspace and PaneLayout are removed with no alias; PaneGrid and Pane are the one generic pane grid: grammar names are generic. R341 FE_FREESTYLE_REASON_MISSING (eslint-grammar-core `freestyle-has-reason`) joins the bundled rule catalog.
+- Fixed: two migrations written within one second (an app scaffold followed at once by `add table`, `add webhook`, `add queue`) took the same UTC timestamp and the second was refused with HFS_ADD_MIGRATION_ORDER, which failed the CI package job on a fast runner; the stamp now moves to the second after the latest migration when the latest is at most 5 s ahead of the clock (scaffold/migration-stamp), and a clock that is really behind is still refused. Specs: src/migration-stamp.spec.mts.
+- Added: R342 `BE_ENTITY_EXTENDS_BASE` (eslint-canon-be `entity-extends-base`) joins the bundled rule catalog and the failure codes.
+- Fixed: HFS_UNUSED_SYMBOL (R280) no longer reports a catalog key read through a translator helper. A hook that exposes its bound translators as members of a declared object type (`useMemo<OfficeWords>(() => ({ t: (key, values) => t(key, values) }))`) binds the app's own type alias of that member (`OfficeText`), or the member itself, to the translator's namespaces; a value of that type called with a key (`text("composerLabel")`, `props.text(...)`, `view.text(...)`, handed on through props, spreads and render callbacks) reads it in those namespaces. The binding is additive: a literal handed to a callback of another type, or a bare literal, still reads nothing.
+- Fixed: the be skeleton's canon copy `platform/config/env-source.config.ts` is Prettier-formatted with @starci/prettier-config (the `optionalDomain` guard is wrapped), so an app that restores the canon bytes passes its own pre-commit format; HFS_CANON_COPY_DRIFT and HFS_FORMAT no longer contradict each other. A spec keeps every canon-copy template Prettier-stable.
+
 ## 4.12.2 - 2026-10-31
 
 - Changed: the bundled canon pins name @starci/grammar 0.16.2 (the horizontal Stepper connector line; SurfaceListCard takes its depth from the surface context). R340 FE_RAISED_SURFACE_IN_SURFACE joins the bundled rule catalog.

package/README.md

@@ -18,7 +18,7 @@ starci app add spec <file>.service.ts [--cwd <dir>]
 starci app add image [--cwd <dir>]
 starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--json] [--out <sonar file>]
 starci app sync [--execute] [--cwd <dir>]
-starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--db-types]
+starci app check [--cwd <dir>] [--json] [--full] [--hfs] [--format] [--db] [--secrets] [--wiring] [--types] [--lint] [--test] [--sonar] [--coverage-from <lcov>] [--quiet]
 starci app check --staged [--cwd <dir>]
 starci app upgrade [--execute]
 starci app world <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--cwd <dir>]
@@ -193,7 +193,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 | `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/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, the be lcov import with the coverage scope the slot manifest derives 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` | error | a tracked file the repository's own prettier would change (R19; `sync/format.mjs`, run in batches by `--format`) |
 | `HFS_FORMAT_TOOL_MISSING` | refusal (exit 2) | prettier is not installed in the repository; the format check is never skipped |
 
 The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
@@ -208,14 +208,13 @@ the source-shape, contract-form and front-end rules, and the repository-tree rul
 finding under the machine's own rule id (`BE_TIER_DIRECTION`, `HFS_UNUSED_EXPORT`, `ARCH_OWNER_EXPORT_BYPASS`, ...). A
 repository without `typescript` installed fails with `ARCH_TYPESCRIPT_MISSING`; the check never passes because it could not run.
 
-`--fast` judges only what changed since the merge-base of `HEAD` with
-`origin/main` (else `main`; `--base <ref>` names another ref): ESLint on changed source files, the slot and pin checks on the changed paths, the machine on the owners
-of the changed source files without clones and dead exports, and no file-system tree checks. The required-file and minimum-instance
-checks still cover the whole tree. With no merge-base `--fast` is a refusal (exit 2) that names the fix, never a silent full
-pass.
+With no selector `starci app check` runs every family diff-only against the committed cache `.starcistacks/cache/` (contexts/project/check-cache.md) and
+writes what it judged back; the result equals a full run's. `--full` runs the selected families in full. A selector (`--hfs`, `--format`, `--db`, `--secrets`,
+`--wiring`, `--types`, `--lint`, `--test`, `--sonar`) runs one family; selectors combine. Each family prints `<family>: <full|diff> (<reason>), checked n, reused n;
+findings n new, n known, n fixed`. Progress goes to stderr (`--quiet` silences it). `STARCI_APP_CHECK_CACHE=verify` runs diff then full and exits 2 on any difference;
+`STARCI_APP_CHECK_CACHE=full` never reads the cache (the release gate).
 
-Exit codes: 0 clean, 1 an error finding, 2 a tool could not run or a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). `starci app check` and `starci app lint` never write to the app
-(`starci app lint --fix` lets ESLint and stylelint fix in place).
+Exit codes: 0 clean, 1 an error finding, 2 a tool could not run or a refusal (not a Git work tree, bad flag). `starci app check` and `starci app lint` write only `.starcistacks/cache/` (and `starci app lint --fix` lets ESLint and stylelint fix in place).
 
 ## Secrets
 

package/cache/app-families.d.mts

@@ -0,0 +1,30 @@
+import { type CheckFinding } from '../runtime/scripts/hfs/check.mjs';
+import { type TestFamilyResult } from './test-family.mjs';
+import { type TypesFamilyResult, type TypesProgram } from './types-family.mjs';
+import { type QualityFamilyResult } from './quality-baselines.mjs';
+import type { CheckSession } from './types.mjs';
+/** The tsc programs of the app: the back end and each front-end workspace, from the tracked tsconfigs. */
+export declare function programsOf(tracked: readonly string[]): TypesProgram[];
+/** `--types`: `tsc --noEmit` per workspace program through the app's TypeScript, reused by program key. */
+export declare function runTypesForApp(session: CheckSession, { repoRoot, tracked, env }: {
+    repoRoot: string;
+    tracked: readonly string[];
+    env: NodeJS.ProcessEnv;
+}): {
+    result: TypesFamilyResult;
+    findings: CheckFinding[];
+};
+/** `--test`: the unit specs of the back end through the app's own Jest, reused by closure key; the merged total is judged by `@starci/hfs` (the coverage proof). */
+export declare function runTestForApp(session: CheckSession, { repoRoot, tracked }: {
+    repoRoot: string;
+    tracked: readonly string[];
+}): Promise<{
+    result: TestFamilyResult | null;
+    findings: CheckFinding[];
+}>;
+/** `--test --full --shard i/n`: one shard of the full unit run in the shape the shard merge reads; nothing is recorded. */
+export declare function runTestShard(repoRoot: string, index: number, total: number): number;
+/** `--sonar`: the Sonar and Codecov baselines and the predictions from the merged coverage records; they never pass or fail a run. */
+export declare function runSonarForApp(session: CheckSession, { repoRoot }: {
+    repoRoot: string;
+}): QualityFamilyResult | null;

package/cache/app-families.mjs

@@ -0,0 +1,94 @@
+// app-families.mts - the adapters that run the heavy families (`--types`, `--test`, `--sonar`) on a real app: its tsconfigs for the programs, its own Jest and
+// jest-preset for the specs, its owners' files for the baselines. The families themselves (types-family, test-family, quality-baselines) take their tools as seams;
+// this module is where the real ones are chosen. The integration, e2e and contract specs are not run here: they need a world (`npm run test:integration`, ...) and
+// always run in full wherever they run, so no cache key could hold them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { skillRoot } from '../runtime/engine/runtime-root.mjs';
+import { coverageFrom } from '../runtime/scripts/hfs/coverage-from.mjs';
+import { readWhy } from '../runtime/scripts/hfs/check.mjs';
+import { withWhy } from '../runtime/scripts/hfs/check-results.mjs';
+import { git as runGitText } from './git.mjs';
+import { toolCacheDir } from './run-log.mjs';
+import { untrackedProgramInputs } from './side-key.mjs';
+import { createJestEnvironment, installedSpecMerge, runTestFamily, shardArgs } from './test-family.mjs';
+import { createTscRunner, runTypesFamily } from './types-family.mjs';
+import { changedLinesFromDiff, gitRunner, lineCoverageOf, recordsAtCommit, runQualityFamily } from './quality-baselines.mjs';
+const asFinding = (found, code, level, engine) => ({ code, level, engine, path: found.path, line: found.line || undefined, column: found.column || undefined, message: `${found.path}${found.line ? `:${found.line}` : ''}: ${found.message}` });
+/** The tsc programs of the app: the back end and each front-end workspace, from the tracked tsconfigs. */
+export function programsOf(tracked) {
+    const programs = [];
+    for (const file of tracked) {
+        if (file === 'be/tsconfig.json')
+            programs.push({ name: 'be', tsconfig: file, reads: ['be'] });
+        const match = /^(fe\/(?:apps|packages)\/[^/]+)\/tsconfig\.json$/.exec(file);
+        if (match?.[1] !== undefined)
+            programs.push({ name: match[1], tsconfig: file, reads: [match[1]] });
+    }
+    return programs.sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+/** `--types`: `tsc --noEmit` per workspace program through the app's TypeScript, reused by program key. */
+export function runTypesForApp(session, { repoRoot, tracked, env }) {
+    const programs = programsOf(tracked);
+    const trackedSet = new Set(tracked);
+    const result = runTypesFamily({
+        session, programs, run: createTscRunner({ appRoot: repoRoot }), toolCacheDir: toolCacheDir(repoRoot, env),
+        inputsOf: (program) => {
+            const side = program.name.startsWith('be') ? 'be' : 'fe';
+            const prefix = `${program.reads?.[0] ?? side}/`;
+            const staged = runGitText(repoRoot, ['ls-files', '-s', '-z', '--', prefix]).stdout.split('\0').filter(Boolean).map((line) => line.replace(/^\d+ ([0-9a-f]+) (\d)\t(.*)$/u, '$3:$1:$2'));
+            return { staged, untracked: untrackedProgramInputs(repoRoot, side, trackedSet).filter((file) => file.startsWith(prefix)) };
+        },
+    });
+    return { result, findings: result.findings.map((found) => asFinding(found, 'TS_DIAGNOSTIC', 'error', 'tsc')) };
+}
+/** `--test`: the unit specs of the back end through the app's own Jest, reused by closure key; the merged total is judged by `@starci/hfs` (the coverage proof). */
+export async function runTestForApp(session, { repoRoot, tracked }) {
+    if (!tracked.includes('be/package.json') && !tracked.some((file) => file.startsWith('be/')))
+        return { result: null, findings: [] };
+    const jest = await createJestEnvironment({ appRoot: repoRoot, side: 'be' });
+    let judged = [];
+    const result = runTestFamily({
+        session, jest, side: 'be', merge: installedSpecMerge(repoRoot),
+        judge: (lcovPath) => {
+            const report = coverageFrom({ repoRoot, lcov: fs.readFileSync(lcovPath, 'utf8'), files: [...tracked] });
+            judged = report.findings.length === 0 ? [] : withWhy(report.findings, readWhy(skillRoot, [...new Set(report.findings.map((found) => found.code))]));
+            return { ok: report.ok, findings: report.findings.map((found) => ({ code: found.code, message: String(found.message ?? '') })) };
+        },
+    });
+    const findings = [...judged];
+    for (const spec of result.failed)
+        findings.push({ code: 'JEST_SPEC_FAILED', level: 'error', engine: 'jest', path: spec, message: `${spec} failed or reported no coverage; run npm test for its output` });
+    return { result, findings };
+}
+/** `--test --full --shard i/n`: one shard of the full unit run in the shape the shard merge reads; nothing is recorded. */
+export function runTestShard(repoRoot, index, total) {
+    const shard = shardArgs(index, total);
+    const jestBin = createRequire(path.join(repoRoot, 'be', 'package.json')).resolve('jest/bin/jest');
+    const run = spawnSync(process.execPath, [jestBin, ...shard.args], { cwd: path.join(repoRoot, 'be'), stdio: 'inherit', env: { ...process.env, ...shard.env } });
+    return run.status ?? 1;
+}
+/** `--sonar`: the Sonar and Codecov baselines and the predictions from the merged coverage records; they never pass or fail a run. */
+export function runSonarForApp(session, { repoRoot }) {
+    const read = (file) => { try {
+        return fs.readFileSync(path.join(repoRoot, file), 'utf8');
+    }
+    catch {
+        return undefined;
+    } };
+    const properties = read('sonar-project.properties');
+    const codecov = read('codecov.yml');
+    if (properties === undefined || codecov === undefined)
+        return null;
+    const gateYaml = fs.readFileSync(path.join(skillRoot, 'knowledge', 'sonar-gate.yaml'), 'utf8');
+    const git = gitRunner(repoRoot);
+    const base = ['origin/main', 'main'].map((ref) => git(['merge-base', 'HEAD', ref])?.trim()).find((sha) => sha !== undefined && sha !== '') ?? git(['rev-parse', 'HEAD'])?.trim() ?? 'none';
+    const diff = git(['diff', '-U0', '--no-color', base]) ?? '';
+    const baseRecords = recordsAtCommit(base, git);
+    return runQualityFamily({
+        session, sources: { baseCommit: base, sonarGateYaml: gateYaml, sonarProperties: properties, codecovYaml: codecov },
+        changed: changedLinesFromDiff(diff), clones: [], baseCoverage: baseRecords.length > 0 ? lineCoverageOf(baseRecords) : undefined,
+    });
+}

package/cache/content-index.d.mts

@@ -0,0 +1,13 @@
+import { type ContentIndex } from './types.mjs';
+/** Whether `file` is inside the committed cache folder. */
+export declare const inCacheDir: (file: string) => boolean;
+/** The index of `tracked` (app-relative posix paths) read from the work tree at `root`. A path the work tree no longer holds has no hash. */
+export declare function createContentIndex(root: string, tracked: readonly string[]): ContentIndex;
+/** What differs between the work tree and a trusted record set: `modified` (hash differs), `added` (no record), `deleted` (a record, no file). */
+export interface IndexDiff {
+    readonly modified: readonly string[];
+    readonly added: readonly string[];
+    readonly deleted: readonly string[];
+}
+/** The diff of the index against `recorded` (path to the hash a trusted record holds). A rename is a deletion and an addition. */
+export declare function diffIndex(index: ContentIndex, recorded: ReadonlyMap<string, string>): IndexDiff;

package/cache/content-index.mjs

@@ -0,0 +1,37 @@
+// content-index.mts - the tracked files of the app and their content hashes, hashed again on every run. The cache folder itself is outside
+// the index: it never keys a step and is never a step's file set.
+import path from 'node:path';
+import { hashFile } from './hash.mjs';
+import { CACHE_DIR } from './types.mjs';
+/** Whether `file` is inside the committed cache folder. */
+export const inCacheDir = (file) => file === CACHE_DIR || file.startsWith(`${CACHE_DIR}/`);
+/** The index of `tracked` (app-relative posix paths) read from the work tree at `root`. A path the work tree no longer holds has no hash. */
+export function createContentIndex(root, tracked) {
+    const hashes = new Map();
+    const paths = [];
+    for (const file of tracked) {
+        if (inCacheDir(file))
+            continue;
+        paths.push(file);
+        const hash = hashFile(path.join(root, file));
+        if (hash !== undefined)
+            hashes.set(file, hash);
+    }
+    paths.sort();
+    return { paths, hashOf: (file) => hashes.get(file) };
+}
+/** The diff of the index against `recorded` (path to the hash a trusted record holds). A rename is a deletion and an addition. */
+export function diffIndex(index, recorded) {
+    const modified = [];
+    const added = [];
+    for (const file of index.paths) {
+        const had = recorded.get(file);
+        if (had === undefined)
+            added.push(file);
+        else if (had !== index.hashOf(file))
+            modified.push(file);
+    }
+    const live = new Set(index.paths);
+    const deleted = [...recorded.keys()].filter((file) => !live.has(file)).sort();
+    return { modified, added, deleted };
+}

package/cache/db-family.d.mts

@@ -0,0 +1,13 @@
+import type { CheckFinding } from '../runtime/scripts/hfs/check.mjs';
+import type { CheckSession, FamilyReport } from './types.mjs';
+export declare const DB_FOLDER = "check/db";
+/** The merge-base of HEAD with origin/main, else main, as the baseline rules find it; `none` when neither resolves. */
+export declare function dbMergeBase(repoRoot: string): string;
+export declare function runDbFamily(session: CheckSession, { repoRoot, tracked, base }: {
+    repoRoot: string;
+    tracked: readonly string[];
+    base?: string | undefined;
+}): Promise<{
+    findings: CheckFinding[];
+    report: FamilyReport;
+}>;

package/cache/db-family.mjs

@@ -0,0 +1,37 @@
+// db-family.mts - `app check --db`: the database rules of `db/` (DB_*). Scoped: reused when every `db/` hash and the merge-base the baseline
+// rules compare with are unchanged; any `db/` change or a new merge-base judges the rules again.
+import { checkDatabase } from '../runtime/scripts/hfs/rules/database.mjs';
+import { mergeBase } from '../runtime/scripts/api/git/merge-base.mjs';
+import { RecordSet, keyOfPaths, scopedStep } from './records.mjs';
+import { makeReport } from './report.mjs';
+export const DB_FOLDER = 'check/db';
+/** The merge-base of HEAD with origin/main, else main, as the baseline rules find it; `none` when neither resolves. */
+export function dbMergeBase(repoRoot) {
+    for (const ref of ['origin/main', 'main']) {
+        const sha = mergeBase(repoRoot, 'HEAD', ref);
+        if (sha)
+            return sha;
+    }
+    return 'none';
+}
+const compact = (finding) => ({ path: finding.path ?? 'db', line: finding.line ?? 0, column: finding.column ?? 0, rule: finding.code, message: String(finding.message ?? '') });
+export async function runDbFamily(session, { repoRoot, tracked, base }) {
+    const decision = session.decide('db');
+    const records = new RecordSet(session.records(DB_FOLDER));
+    const previous = records.findings('db-rules');
+    const inputs = session.index.paths.filter((file) => file.startsWith('db/') || file.startsWith('supabase/') || file.endsWith('.sql'));
+    const key = keyOfPaths(session.index, inputs, { 'merge-base': base ?? dbMergeBase(repoRoot) });
+    const step = session.progress.step('db', 'rules', inputs.length);
+    const { value, reused } = await scopedStep(session, records, {
+        path: 'db', step: 'db-rules', key, reuse: decision.mode === 'diff', inputs,
+        compute: async () => JSON.parse(JSON.stringify(await checkDatabase({ repoRoot, files: [...tracked], base }))),
+        compact: (found) => found.map(compact),
+    });
+    step.tick(inputs.length, reused ? inputs.length : 0, reused ? 0 : inputs.length);
+    step.end();
+    session.replace(DB_FOLDER, records.toArray());
+    const findings = value;
+    const report = makeReport({ family: 'db', mode: decision.mode, reason: decision.reason, checked: reused ? 0 : inputs.length, reused: reused ? inputs.length : 0, previous, current: findings.map(compact) });
+    session.report(report);
+    return { findings, report };
+}

package/cache/fake-session.d.mts

@@ -0,0 +1,42 @@
+import type { CacheRecord, CheckSession, ContentIndex, FamilyId, FamilyReport, RunMode } from './types.mjs';
+/** One progress event the fake saw. */
+export type ProgressEvent = {
+    readonly kind: 'start';
+    readonly family: FamilyId;
+    readonly name: string;
+    readonly total: number;
+} | {
+    readonly kind: 'tick';
+    readonly family: FamilyId;
+    readonly name: string;
+    readonly done: number;
+    readonly reused: number;
+    readonly checked: number;
+} | {
+    readonly kind: 'end';
+    readonly family: FamilyId;
+    readonly name: string;
+};
+export interface FakeSessionOptions {
+    /** The work tree: app-relative posix path to text. */
+    readonly files?: Readonly<Record<string, string>>;
+    /** The trusted records, by folder. */
+    readonly records?: Readonly<Record<string, readonly CacheRecord[]>>;
+    /** The run mode every family is told; `full` carries `fullReason`. */
+    readonly mode?: RunMode;
+    readonly fullReason?: string;
+}
+/** The fake, with the logs a spec asserts on. */
+export interface FakeSession extends CheckSession {
+    readonly events: ProgressEvent[];
+    readonly reports: FamilyReport[];
+    readonly replaced: Map<string, readonly CacheRecord[]>;
+    /** Edits the fake tree between a run's read and its write (the "edit during the run" case). */
+    setFile(path: string, text: string | undefined): void;
+    flushed: number;
+}
+/** A content index over `files`, hashing as the real one does. */
+export declare function createFakeIndex(files: Readonly<Record<string, string>>): ContentIndex & {
+    set(path: string, text: string | undefined): void;
+};
+export declare function createFakeSession(options?: FakeSessionOptions): FakeSession;

package/cache/fake-session.mjs

@@ -0,0 +1,57 @@
+// fake-session.mts - the in-memory CheckSession specs (and the work packages that build on the cache) run families against: a
+// tree given as text, trusted records given as a map, and a log of everything the family did. It touches no disk and no clock.
+import { hashText } from './hash.mjs';
+/** A content index over `files`, hashing as the real one does. */
+export function createFakeIndex(files) {
+    const hashes = new Map(Object.entries(files).map(([path, text]) => [path, hashText(text)]));
+    return {
+        get paths() {
+            return [...hashes.keys()].sort();
+        },
+        hashOf: (path) => hashes.get(path),
+        set(path, text) {
+            if (text === undefined)
+                hashes.delete(path);
+            else
+                hashes.set(path, hashText(text));
+        },
+    };
+}
+export function createFakeSession(options = {}) {
+    const index = createFakeIndex(options.files ?? {});
+    const initial = new Map(index.paths.map((file) => [file, index.hashOf(file)]));
+    const stored = new Map(Object.entries(options.records ?? {}));
+    const events = [];
+    const reports = [];
+    const replaced = new Map();
+    const decision = { mode: options.mode ?? 'diff', reason: options.fullReason ?? (options.mode === 'full' ? 'full run' : 'diff against the cache') };
+    const progress = {
+        step(family, name, total) {
+            events.push({ kind: 'start', family, name, total });
+            return {
+                tick: (done, reused, checked) => void events.push({ kind: 'tick', family, name, done, reused, checked }),
+                end: () => void events.push({ kind: 'end', family, name }),
+            };
+        },
+    };
+    const session = {
+        root: '/fake/app',
+        index,
+        events,
+        reports,
+        replaced,
+        flushed: 0,
+        decide: () => decision,
+        records: (folder) => replaced.get(folder) ?? stored.get(folder) ?? [],
+        replace: (folder, records) => void replaced.set(folder, records),
+        unchanged: (paths) => paths.every((file) => index.hashOf(file) === initial.get(file)),
+        report: (report) => void reports.push(report),
+        progress,
+        setFile: (path, text) => index.set(path, text),
+        flush() {
+            session.flushed += 1;
+            return { written: [...replaced.keys()].sort(), removed: [], warnings: [] };
+        },
+    };
+    return session;
+}

package/cache/fingerprint.d.mts

@@ -0,0 +1,28 @@
+import { type FingerprintPart } from './types.mjs';
+/** The fingerprint of a run: its parts, and whether it is portable (and if not, why). */
+export interface Fingerprint {
+    readonly parts: readonly FingerprintPart[];
+    readonly portable: boolean;
+    readonly localReasons: readonly string[];
+}
+export interface FingerprintInput {
+    readonly root: string;
+    readonly tracked: readonly string[];
+    /** The version of the CLI that runs this package in-process, when it gave one. */
+    readonly cliVersion?: string | undefined;
+    /** Where @starci/hfs runs from; defaults to this package. */
+    readonly hfsDir?: string | undefined;
+}
+/** The fingerprint of the app at `root`. */
+export declare function computeFingerprint({ root, tracked, cliVersion, hfsDir }: FingerprintInput): Fingerprint;
+/** `fingerprint.jsonl`: one line per part. */
+export declare function serializeFingerprint(parts: readonly FingerprintPart[]): string;
+/** The parts of a `fingerprint.jsonl`; a line that is not a part is dropped. */
+export declare function parseFingerprint(text: string): FingerprintPart[];
+/**
+ * The part names that differ between the cache's fingerprint and this run's: changed, added, removed, and a name held twice with
+ * two digests (a union merge of two branches), which never matches.
+ */
+export declare function fingerprintDifferences(cached: readonly FingerprintPart[], current: readonly FingerprintPart[]): string[];
+/** One digest of all parts, for the run log. */
+export declare function fingerprintDigest(parts: readonly FingerprintPart[]): string;

package/cache/fingerprint.mjs

@@ -0,0 +1,120 @@
+// fingerprint.mts - the one fingerprint check, lint and coverage share. A part is anything a step reads that is not an app source; any part
+// that differs makes the whole run full. Parts are portable (equal on every host for one commit): the cache format, the CLI and
+// @starci/hfs that run, every installed @starci package by version and recorded integrity, the lockfile and the configuration files by
+// normalised content. A run whose CLI or any @starci package is linked or copied from a local folder has no portable fingerprint.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { combineHashes, hashFile, hashText } from './hash.mjs';
+import { CACHE_FORMAT_VERSION } from './types.mjs';
+/** The tracked files (by base name or exact path) that are parts by content. */
+const CONFIG_NAME = /^(hfs\.json|package\.json|tsconfig[^/]*\.json|eslint\.config\.mjs|stylelint\.config\.mjs|jest\.config\.[cm]?[jt]s|jest\.config\.json|\.prettierrc[^/]*|prettier\.config\.[cm]?[jt]s|\.prettierignore|\.editorconfig|\.gitignore|\.gitattributes|turbo\.json|sonar-project\.properties|codecov\.yml|package-lock\.json)$/;
+const sorted = (parts) => [...parts].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+function readJson(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return parsed !== null && typeof parsed === 'object' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function lockEntries(root) {
+    const packages = readJson(path.join(root, 'package-lock.json'))?.['packages'];
+    return packages !== null && typeof packages === 'object' ? packages : {};
+}
+function installedStarci(root) {
+    try {
+        return fs.readdirSync(path.join(root, 'node_modules', '@starci'));
+    }
+    catch {
+        return [];
+    }
+}
+/** Whether the directory sits in an install (a `node_modules` segment of its real path) rather than a local checkout. */
+function installedUnderNodeModules(dir) {
+    let real = dir;
+    try {
+        real = fs.realpathSync(dir);
+    }
+    catch { /* an unreadable directory is judged by its given path */ }
+    return real.split(/[\\/]/).includes('node_modules');
+}
+/** The fingerprint of the app at `root`. */
+export function computeFingerprint({ root, tracked, cliVersion, hfsDir = fileURLToPath(new URL('..', import.meta.url)) }) {
+    const parts = [];
+    const localReasons = [];
+    const add = (name, value) => void parts.push({ name, sha256: hashText(value) });
+    add('cache-format', String(CACHE_FORMAT_VERSION));
+    add('cli', cliVersion ?? 'none');
+    const hfsVersion = String(readJson(path.join(hfsDir, 'package.json'))?.['version'] ?? 'unknown');
+    add('hfs', hfsVersion);
+    if (!installedUnderNodeModules(hfsDir))
+        localReasons.push(`@starci/hfs runs from a local folder (${path.basename(path.resolve(hfsDir))})`);
+    const lock = lockEntries(root);
+    for (const name of installedStarci(root).sort()) {
+        const dir = path.join(root, 'node_modules', '@starci', name);
+        const version = String(readJson(path.join(dir, 'package.json'))?.['version'] ?? 'unknown');
+        const entry = lock[`node_modules/@starci/${name}`];
+        let linked = entry?.link === true;
+        try {
+            linked = linked || fs.lstatSync(dir).isSymbolicLink();
+        }
+        catch { /* absent: not installed */ }
+        if (linked || entry?.integrity === undefined)
+            localReasons.push(`@starci/${name} is linked or copied from a local folder (no recorded integrity)`);
+        add(`pkg:@starci/${name}`, `${version}\0${entry?.integrity ?? 'local'}`);
+    }
+    for (const file of tracked) {
+        if (!CONFIG_NAME.test(path.posix.basename(file)) || file.startsWith('node_modules/'))
+            continue;
+        const sha = hashFile(path.join(root, file));
+        parts.push({ name: `file:${file}`, sha256: sha ?? 'absent' });
+    }
+    return { parts: sorted(parts), portable: localReasons.length === 0, localReasons };
+}
+/** `fingerprint.jsonl`: one line per part. */
+export function serializeFingerprint(parts) {
+    const lines = sorted([...parts]).map((part) => JSON.stringify({ name: part.name, sha256: part.sha256 }));
+    return lines.length === 0 ? '' : `${lines.join('\n')}\n`;
+}
+/** The parts of a `fingerprint.jsonl`; a line that is not a part is dropped. */
+export function parseFingerprint(text) {
+    const parts = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line === '')
+            continue;
+        try {
+            const value = JSON.parse(line);
+            if (typeof value.name === 'string' && typeof value.sha256 === 'string')
+                parts.push({ name: value.name, sha256: value.sha256 });
+        }
+        catch { /* a damaged line is a part that cannot match */ }
+    }
+    return sorted(parts);
+}
+/**
+ * The part names that differ between the cache's fingerprint and this run's: changed, added, removed, and a name held twice with
+ * two digests (a union merge of two branches), which never matches.
+ */
+export function fingerprintDifferences(cached, current) {
+    const differing = new Set();
+    const byName = new Map();
+    for (const part of cached)
+        byName.set(part.name, (byName.get(part.name) ?? new Set()).add(part.sha256));
+    for (const part of current) {
+        const held = byName.get(part.name);
+        if (held === undefined || held.size !== 1 || !held.has(part.sha256))
+            differing.add(part.name);
+    }
+    const names = new Set(current.map((part) => part.name));
+    for (const name of byName.keys())
+        if (!names.has(name))
+            differing.add(name);
+    return [...differing].sort();
+}
+/** One digest of all parts, for the run log. */
+export function fingerprintDigest(parts) {
+    return combineHashes(Object.fromEntries(parts.map((part) => [part.name, part.sha256])));
+}

package/cache/format-family.d.mts

@@ -0,0 +1,13 @@
+import { FORMAT, type FormatFinding, type Prettier } from '../sync/format.mjs';
+import type { CheckSession, FamilyReport } from './types.mjs';
+export declare const FORMAT_FOLDER = "check/format";
+export interface FormatFamilyResult {
+    readonly findings: FormatFinding[];
+    readonly report: FamilyReport;
+}
+/** Runs the format family against `session`: decides, formats what must be formatted, replaces the records, reports. */
+export declare function runFormatFamily(session: CheckSession, { files, prettier }: {
+    files: readonly string[];
+    prettier?: Prettier | undefined;
+}): Promise<FormatFamilyResult>;
+export { FORMAT };