@starci/hfs 4.12.2 → 4.13.0

package/cache/trust.d.mts

@@ -0,0 +1,53 @@
+import { type CacheRecord } from './types.mjs';
+export declare const FORGED = "HFS_CHECK_CACHE_FORGED";
+export declare const STALE = "HFS_CHECK_CACHE_STALE";
+export declare const MISSING = "HFS_CHECK_CACHE_MISSING";
+/** The cache files a trust source holds: path under `.starcistacks/cache/` to text. */
+export interface TrustSource {
+    readonly kind: 'worktree' | 'base' | 'none';
+    readonly reason: string;
+    /** The commit the cache is read at, for `base`. */
+    readonly base?: string | undefined;
+    files(): ReadonlyMap<string, string>;
+}
+/** Every file under the cache folder of the work tree, keyed by its path under the folder. */
+export declare function readCacheDir(root: string): Map<string, string>;
+/** The cache folder of commit `rev`: one ls-tree and one cat-file --batch, however many files it holds. */
+export declare function readCacheAt(root: string, rev: string): Map<string, string> | undefined;
+export interface TrustInput {
+    readonly root: string;
+    readonly env: NodeJS.ProcessEnv;
+}
+/** Whether the run is in CI (the managed workflow, or any runner that sets CI). */
+export declare const inCi: (env: NodeJS.ProcessEnv) => boolean;
+/** The commit CI trusts the cache at, or why there is none. */
+export declare function trustedBase(root: string, env: NodeJS.ProcessEnv): {
+    base: string;
+} | {
+    reason: string;
+};
+/** The trust source of this run. */
+export declare function resolveTrust({ root, env }: TrustInput): TrustSource;
+/** One verdict of the comparison of the change's committed cache with what CI inherited or computed. */
+export interface CacheVerdict {
+    readonly code: typeof FORGED | typeof STALE | typeof MISSING;
+    readonly level: 'error' | 'warning';
+    readonly path: string;
+    readonly folder: string;
+    readonly message: string;
+}
+export interface VerifyInput {
+    /** The records CI trusts (the base cache), by folder. */
+    readonly trusted: ReadonlyMap<string, readonly CacheRecord[]>;
+    /** The records of this run (inherited and computed), by folder. */
+    readonly computed: ReadonlyMap<string, readonly CacheRecord[]>;
+    /** The records the change commits, by folder. */
+    readonly committed: ReadonlyMap<string, readonly CacheRecord[]>;
+}
+/**
+ * Compares the change's committed cache with what this run inherited or computed. A committed record whose key matches the tree and
+ * whose findings differ from the computed one is FORGED (a hard blocker, whether it was edited by hand or a step is not deterministic
+ * across hosts). A key the change touched (its record differs from the trusted one, or the trusted cache has none) that the committed
+ * cache does not cover with a current record is STALE. A change that commits no cache at all while the run has computed one is MISSING.
+ */
+export declare function verifyCommitted({ trusted, computed, committed }: VerifyInput): CacheVerdict[];

package/cache/trust.mjs

@@ -0,0 +1,157 @@
+// trust.mts - where the cache is trusted from. On a host the cache in the working tree is trusted (a local run is the developer's own
+// view). In CI the cache is trusted only as it stands at the trusted base: the merge-base with the default branch for a pull request,
+// the first parent for a push to the default branch. The change's own edits to the cache are never trusted: CI judges everything the base
+// cache does not cover and then compares the committed cache with what it inherited or computed (verifyCommitted).
+// No trusted base (a tag build, a schedule, an unreadable base) is a full run.
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalJson } from './jsonl.mjs';
+import { git, gitBytes } from './git.mjs';
+import { CACHE_DIR } from './types.mjs';
+export const FORGED = 'HFS_CHECK_CACHE_FORGED';
+export const STALE = 'HFS_CHECK_CACHE_STALE';
+export const MISSING = 'HFS_CHECK_CACHE_MISSING';
+/** Every file under the cache folder of the work tree, keyed by its path under the folder. */
+export function readCacheDir(root) {
+    const files = new Map();
+    const top = path.join(root, ...CACHE_DIR.split('/'));
+    const walk = (dir, prefix) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+            if (entry.isDirectory())
+                walk(path.join(dir, entry.name), rel);
+            else if (entry.isFile()) {
+                try {
+                    files.set(rel, fs.readFileSync(path.join(dir, entry.name), 'utf8'));
+                }
+                catch { /* unreadable: absent */ }
+            }
+        }
+    };
+    walk(top, '');
+    return files;
+}
+/** The cache folder of commit `rev`: one ls-tree and one cat-file --batch, however many files it holds. */
+export function readCacheAt(root, rev) {
+    const listed = git(root, ['ls-tree', '-r', '-z', rev, '--', CACHE_DIR]);
+    if (!listed.ok)
+        return undefined;
+    const entries = listed.stdout.split('\0').filter(Boolean).map((line) => {
+        const tab = line.indexOf('\t');
+        return { sha: line.slice(0, tab).split(' ')[2] ?? '', file: line.slice(tab + 1) };
+    }).filter((entry) => entry.sha !== '');
+    const files = new Map();
+    if (entries.length === 0)
+        return files;
+    const blobs = gitBytes(root, ['cat-file', '--batch'], `${entries.map((entry) => entry.sha).join('\n')}\n`);
+    if (!blobs.ok)
+        return undefined;
+    let at = 0;
+    for (const entry of entries) {
+        const eol = blobs.stdout.indexOf(0x0a, at);
+        if (eol < 0)
+            return undefined;
+        const [, type, size] = blobs.stdout.subarray(at, eol).toString('utf8').split(' ');
+        if (type !== 'blob' || size === undefined)
+            return undefined;
+        const start = eol + 1;
+        const end = start + Number(size);
+        files.set(entry.file.slice(CACHE_DIR.length + 1), blobs.stdout.subarray(start, end).toString('utf8'));
+        at = end + 1;
+    }
+    return files;
+}
+/** Whether the run is in CI (the managed workflow, or any runner that sets CI). */
+export const inCi = (env) => env['CI'] === 'true' || env['GITHUB_ACTIONS'] === 'true';
+const DEFAULT_BRANCHES = new Set(['main', 'master']);
+/** The commit CI trusts the cache at, or why there is none. */
+export function trustedBase(root, env) {
+    const event = env['GITHUB_EVENT_NAME'];
+    if (event === 'pull_request' || event === 'pull_request_target') {
+        const target = env['GITHUB_BASE_REF'];
+        if (!target)
+            return { reason: 'a pull request with no base ref' };
+        const merged = git(root, ['merge-base', 'HEAD', `origin/${target}`]);
+        return merged.ok && merged.stdout.trim() !== '' ? { base: merged.stdout.trim() } : { reason: `no merge-base with origin/${target} (fetch it)` };
+    }
+    if (event === 'push') {
+        const branch = (env['GITHUB_REF'] ?? '').replace(/^refs\/heads\//, '');
+        if (!(DEFAULT_BRANCHES.has(branch) || branch === env['STARCI_DEFAULT_BRANCH']))
+            return { reason: `a push to ${branch || 'a non-branch ref'}, not the default branch` };
+        const parent = git(root, ['rev-parse', '--verify', '-q', 'HEAD^1']);
+        return parent.ok && parent.stdout.trim() !== '' ? { base: parent.stdout.trim() } : { reason: 'no first parent (fetch depth 1)' };
+    }
+    return { reason: `${event ?? 'an unknown CI event'} has no trusted base` };
+}
+/** The trust source of this run. */
+export function resolveTrust({ root, env }) {
+    if (!inCi(env)) {
+        let cached;
+        return { kind: 'worktree', reason: 'the working tree', files: () => (cached ??= readCacheDir(root)) };
+    }
+    const found = trustedBase(root, env);
+    if ('reason' in found)
+        return { kind: 'none', reason: found.reason, files: () => new Map() };
+    const files = readCacheAt(root, found.base);
+    if (files === undefined)
+        return { kind: 'none', reason: `the cache at ${found.base.slice(0, 12)} is unreadable`, files: () => new Map() };
+    return { kind: 'base', reason: `the cache at ${found.base.slice(0, 12)}`, base: found.base, files: () => files };
+}
+const keyOf = (record) => `${record.path}\0${record.step}`;
+const sameFindings = (a, b) => canonicalJson(a) === canonicalJson(b);
+/**
+ * Compares the change's committed cache with what this run inherited or computed. A committed record whose key matches the tree and
+ * whose findings differ from the computed one is FORGED (a hard blocker, whether it was edited by hand or a step is not deterministic
+ * across hosts). A key the change touched (its record differs from the trusted one, or the trusted cache has none) that the committed
+ * cache does not cover with a current record is STALE. A change that commits no cache at all while the run has computed one is MISSING.
+ */
+export function verifyCommitted({ trusted, computed, committed }) {
+    const verdicts = [];
+    let anyCommitted = false;
+    let anyComputed = false;
+    for (const [folder, records] of computed) {
+        if (records.length === 0)
+            continue;
+        anyComputed = true;
+        const own = new Map();
+        for (const record of records)
+            own.set(keyOf(record), record);
+        const base = new Map((trusted.get(folder) ?? []).map((record) => [keyOf(record), record]));
+        const mine = committed.get(folder) ?? [];
+        if (mine.length > 0)
+            anyCommitted = true;
+        const byKey = new Map();
+        for (const record of mine)
+            byKey.set(keyOf(record), [...(byKey.get(keyOf(record)) ?? []), record]);
+        for (const record of mine) {
+            const truth = own.get(keyOf(record));
+            if (truth === undefined || truth.hash !== record.hash)
+                continue;
+            if (!sameFindings(truth.findings, record.findings)) {
+                verdicts.push({ code: FORGED, level: 'error', path: record.path, folder, message: `${folder}: the committed record of ${record.path} (${record.step}) matches the tree but its findings differ from what the check computes; regenerate the cache with starci app check` });
+            }
+        }
+        for (const [key, truth] of own) {
+            const before = base.get(key);
+            const touched = before === undefined || before.hash !== truth.hash || !sameFindings(before.findings, truth.findings);
+            if (!touched)
+                continue;
+            const held = (byKey.get(key) ?? []).some((record) => record.hash === truth.hash);
+            if (!held)
+                verdicts.push({ code: STALE, level: 'warning', path: truth.path, folder, message: `${folder}: ${truth.path} (${truth.step}) changed and the committed cache holds no current record of it; run starci app check and commit .starcistacks/cache` });
+        }
+    }
+    if (anyComputed && !anyCommitted) {
+        // One verdict for a change that commits no cache, not one stale key per file.
+        verdicts.length = 0;
+        verdicts.push({ code: MISSING, level: 'warning', path: CACHE_DIR, folder: '', message: `${CACHE_DIR} holds no records; run starci app check and commit the folder so later runs judge only what changed` });
+    }
+    return verdicts.sort((a, b) => (a.code + a.folder + a.path < b.code + b.folder + b.path ? -1 : 1));
+}

package/cache/types-family.d.mts

@@ -0,0 +1,74 @@
+import type { CheckSession, FamilyReport, Finding } from './types.mjs';
+/** The folder of the session that holds the records of this family. */
+export declare const TYPES_FOLDER = "check/types";
+/** The step of a program's record. */
+export declare const TSC_STEP = "tsc";
+/** One workspace program: `tsc -p <tsconfig> --noEmit`. Paths are app-relative posix. */
+export interface TypesProgram {
+    /** The record key, unique in the app (`be`, `fe/apps/web`). */
+    readonly name: string;
+    /** The tsconfig the program is built from. */
+    readonly tsconfig: string;
+    /** The folders (or files) the program reads, whose tracked paths make its key; defaults to the tsconfig's folder. */
+    readonly reads?: readonly string[];
+}
+/** What the program reads that the content index does not hold. */
+export interface ProgramInputs {
+    /** Staged entries for the program's paths, as `path:blob` pairs (the machine reads the index). */
+    readonly staged?: readonly string[];
+    /** Untracked files its TypeScript program reads (what its tsconfig includes or an import resolves to that git does not track), app-relative. */
+    readonly untracked?: readonly string[];
+}
+/** What one `tsc` run came to. */
+export interface TscOutcome {
+    readonly status: number;
+    /** tsc's output, `--pretty false`. */
+    readonly output: string;
+}
+export interface TypesFamilyOptions {
+    readonly session: CheckSession;
+    readonly programs: readonly TypesProgram[];
+    /** Runs one program's `tsc`; `buildInfo` is where its `.tsbuildinfo` goes (the untracked tool cache). */
+    readonly run: (program: TypesProgram, buildInfo: string) => TscOutcome;
+    /** The untracked tool cache of slot `app.tool-cache` (`<STARCI_CACHE_HOME>/<repo>/app-check`). */
+    readonly toolCacheDir: string;
+    readonly inputsOf?: (program: TypesProgram) => ProgramInputs;
+}
+export interface TypesFamilyResult {
+    readonly ok: boolean;
+    readonly ran: readonly string[];
+    readonly reused: readonly string[];
+    /** Programs whose `tsc` did not complete (no diagnostics and a failing status): nothing of theirs is stored. */
+    readonly incomplete: readonly string[];
+    readonly findings: readonly Finding[];
+    readonly report: FamilyReport;
+}
+/** The folders a program reads, app-relative: its `reads`, else the folder of its tsconfig. */
+export declare function readsOf(program: TypesProgram): readonly string[];
+/**
+ * The key of a program: its tsconfig and every tracked path under what it reads by content hash (`absent` for a tracked path the work tree no longer holds), the staged
+ * entries and the untracked inputs. Equal on every host for one commit; a program that reads nothing that changed keeps its key.
+ */
+export declare function programKey(program: TypesProgram, session: CheckSession, inputs?: ProgramInputs): string;
+/**
+ * Where a program's `.tsbuildinfo` goes. It must be outside the app's committed cache, so a tool-cache folder configured inside `.starcistacks/cache` is refused: a
+ * `.tsbuildinfo` holds versions and signatures, not results, and is never committed.
+ */
+export declare function tsBuildInfoPath(toolCacheDir: string, appRoot: string, program: TypesProgram): string;
+/** `text` with every occurrence of the app's absolute path removed, so a message carries app-relative posix paths only. */
+export declare function relativise(text: string, appRoot: string): string;
+/** The findings in tsc's `--pretty false` output: `file(line,col): error TS1234: message`, continuation lines joined to their message. Run from the app root. */
+export declare function parseTscOutput(output: string, appRoot: string, fallbackPath: string): Finding[];
+/**
+ * Runs the type check of every program against the cache. A program whose key is unchanged takes its recorded diagnostics; a changed one runs in full (all of them
+ * under `--full`). A run that produced no diagnostics and failed (tsc itself could not complete) stores nothing, and so does a program whose files changed while it ran.
+ */
+export declare function runTypesFamily(options: TypesFamilyOptions): TypesFamilyResult;
+/**
+ * The real `tsc` of an app: the program's own TypeScript (resolved from its folder, so the version the lockfile pins), `--noEmit` with an incremental build info in the
+ * tool cache, run from the app root so paths in the output are app-relative.
+ */
+export declare function createTscRunner({ appRoot, typescriptFrom }: {
+    appRoot: string;
+    typescriptFrom?: string;
+}): TypesFamilyOptions['run'];

package/cache/types-family.mjs

@@ -0,0 +1,154 @@
+// types-family.mts - the `--types` family of the app check cache (contexts/project/check-cache.md, "Which step reuses what"): each workspace's `tsc --noEmit` through the
+// app's own TypeScript, one program at a time. A program's key is the sha256 of everything the program reads: the hash of each tracked path it covers (`absent` for one the
+// work tree lost), the entries staged for it and the untracked files its TypeScript reads (generated code). An unchanged key reuses the program's recorded diagnostics; a
+// changed one runs that program's `tsc` in full. TypeScript's `.tsbuildinfo` speeds that run but is host state, not a result: it lives in the untracked tool cache and is
+// never written into the app, so never committed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { CACHE_DIR } from './types.mjs';
+import { combineHashes, hashFile } from './hash.mjs';
+import { sortFindings } from './jsonl.mjs';
+/** The folder of the session that holds the records of this family. */
+export const TYPES_FOLDER = 'check/types';
+/** The step of a program's record. */
+export const TSC_STEP = 'tsc';
+const posix = (file) => file.split(path.sep).join('/');
+const within = (file, prefix) => prefix === '.' || prefix === '' || file === prefix || file.startsWith(`${prefix}/`);
+/** The folders a program reads, app-relative: its `reads`, else the folder of its tsconfig. */
+export function readsOf(program) {
+    return program.reads ?? [path.posix.dirname(program.tsconfig)];
+}
+/**
+ * The key of a program: its tsconfig and every tracked path under what it reads by content hash (`absent` for a tracked path the work tree no longer holds), the staged
+ * entries and the untracked inputs. Equal on every host for one commit; a program that reads nothing that changed keeps its key.
+ */
+export function programKey(program, session, inputs = {}) {
+    const parts = {};
+    const reads = readsOf(program);
+    for (const file of session.index.paths)
+        if (reads.some((prefix) => within(file, prefix)) || file === program.tsconfig)
+            parts[`tracked:${file}`] = session.index.hashOf(file) ?? 'absent';
+    for (const entry of inputs.staged ?? [])
+        parts[`staged:${entry}`] = '1';
+    for (const file of inputs.untracked ?? [])
+        parts[`untracked:${file}`] = hashFile(path.join(session.root, file)) ?? 'absent';
+    return combineHashes(parts);
+}
+/**
+ * Where a program's `.tsbuildinfo` goes. It must be outside the app's committed cache, so a tool-cache folder configured inside `.starcistacks/cache` is refused: a
+ * `.tsbuildinfo` holds versions and signatures, not results, and is never committed.
+ */
+export function tsBuildInfoPath(toolCacheDir, appRoot, program) {
+    const file = path.join(path.resolve(toolCacheDir), 'tsbuildinfo', `${program.name.replaceAll('/', '__')}.tsbuildinfo`);
+    const committed = path.resolve(appRoot, CACHE_DIR);
+    if (file === committed || file.startsWith(`${committed}${path.sep}`))
+        throw new Error(`the tool cache ${toolCacheDir} is inside ${CACHE_DIR}: a .tsbuildinfo is host state and is never committed`);
+    return file;
+}
+/** `text` with every occurrence of the app's absolute path removed, so a message carries app-relative posix paths only. */
+export function relativise(text, appRoot) {
+    const root = path.resolve(appRoot);
+    let out = text;
+    for (const variant of new Set([root, root.split(path.sep).join('/')]))
+        out = out.split(`${variant}/`).join('').split(`${variant}${path.sep}`).join('').split(variant).join('.');
+    return out;
+}
+const DIAGNOSTIC = /^(.+?)\((\d+),(\d+)\): (?:error|warning) (TS\d+): (.*)$/u;
+const GLOBAL_DIAGNOSTIC = /^(?:error|warning) (TS\d+): (.*)$/u;
+/** The findings in tsc's `--pretty false` output: `file(line,col): error TS1234: message`, continuation lines joined to their message. Run from the app root. */
+export function parseTscOutput(output, appRoot, fallbackPath) {
+    const findings = [];
+    let last;
+    for (const raw of output.split(/\r?\n/u)) {
+        const line = relativise(raw, appRoot);
+        const match = DIAGNOSTIC.exec(line);
+        const global = match ? null : GLOBAL_DIAGNOSTIC.exec(line);
+        if (match) {
+            last = { path: (match[1] ?? '').replaceAll('\\', '/').replace(/^\.\//u, ''), line: Number(match[2]), column: Number(match[3]), rule: match[4] ?? '', message: match[5] ?? '' };
+            findings.push(last);
+        }
+        else if (global) {
+            last = { path: fallbackPath, line: 1, column: 1, rule: global[1] ?? '', message: global[2] ?? '' };
+            findings.push(last);
+        }
+        else if (last !== undefined && /^\s+\S/u.test(line)) {
+            last.message += `\n${line.trim()}`;
+        }
+    }
+    return sortFindings(findings);
+}
+const identity = (finding) => `${finding.path}\0${finding.rule}\0${finding.message}`;
+/**
+ * Runs the type check of every program against the cache. A program whose key is unchanged takes its recorded diagnostics; a changed one runs in full (all of them
+ * under `--full`). A run that produced no diagnostics and failed (tsc itself could not complete) stores nothing, and so does a program whose files changed while it ran.
+ */
+export function runTypesFamily(options) {
+    const { session, programs, run, toolCacheDir } = options;
+    const decision = session.decide('types');
+    const previous = new Map(session.records(TYPES_FOLDER).filter((record) => record.step === TSC_STEP).map((record) => [record.path, record]));
+    const progress = session.progress.step('types', 'tsc', programs.length);
+    const records = [];
+    const ran = [];
+    const reused = [];
+    const incomplete = [];
+    const findings = [];
+    let known = 0;
+    let added = 0;
+    let fixed = 0;
+    for (const program of programs) {
+        const inputs = options.inputsOf?.(program) ?? {};
+        const key = programKey(program, session, inputs);
+        const before = previous.get(program.name);
+        let current;
+        if (decision.mode === 'diff' && before !== undefined && before.hash === key) {
+            current = before.findings;
+            records.push(before);
+            reused.push(program.name);
+        }
+        else {
+            const outcome = run(program, tsBuildInfoPath(toolCacheDir, session.root, program));
+            ran.push(program.name);
+            current = parseTscOutput(outcome.output, session.root, program.tsconfig);
+            if (current.length === 0 && outcome.status !== 0)
+                incomplete.push(program.name);
+            else if (programKey(program, session, inputs) === key)
+                records.push({ path: program.name, step: TSC_STEP, hash: key, findings: current });
+            else
+                incomplete.push(program.name);
+        }
+        const had = new Set((before?.findings ?? []).map(identity));
+        const now = new Set(current.map(identity));
+        for (const finding of current)
+            if (had.has(identity(finding)))
+                known += 1;
+            else
+                added += 1;
+        for (const id of had)
+            if (!now.has(id))
+                fixed += 1;
+        findings.push(...current);
+        progress.tick(reused.length + ran.length, reused.length, ran.length);
+    }
+    progress.end();
+    session.replace(TYPES_FOLDER, records);
+    const report = { family: 'types', mode: decision.mode, reason: decision.reason, checked: ran.length, reused: reused.length, newFindings: added, knownFindings: known, fixedFindings: fixed };
+    session.report(report);
+    return { ok: findings.length === 0 && incomplete.length === 0, ran, reused, incomplete, findings: sortFindings(findings), report };
+}
+/**
+ * The real `tsc` of an app: the program's own TypeScript (resolved from its folder, so the version the lockfile pins), `--noEmit` with an incremental build info in the
+ * tool cache, run from the app root so paths in the output are app-relative.
+ */
+export function createTscRunner({ appRoot, typescriptFrom }) {
+    return (program, buildInfo) => {
+        const folder = path.resolve(appRoot, path.posix.dirname(program.tsconfig));
+        const tsc = path.join(path.dirname(createRequire(typescriptFrom ?? path.join(folder, 'package.json')).resolve('typescript/package.json')), 'bin', 'tsc');
+        fs.mkdirSync(path.dirname(buildInfo), { recursive: true });
+        const result = spawnSync(process.execPath, [tsc, '-p', posix(path.relative(appRoot, path.resolve(appRoot, program.tsconfig))), '--noEmit', '--incremental', '--tsBuildInfoFile', buildInfo, '--pretty', 'false'], {
+            cwd: appRoot, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024,
+        });
+        return { status: result.status ?? 1, output: `${result.stdout}${result.stderr}` };
+    };
+}

package/cache/types.d.mts

@@ -0,0 +1,99 @@
+/** The format of the records on disk; a cache of another version is replaced, never read. */
+export declare const CACHE_FORMAT_VERSION = 1;
+/** Where the committed cache lives, app-relative and posix. */
+export declare const CACHE_DIR = ".starcistacks/cache";
+/** The families a run selects (`app check --<family>`). */
+export declare const FAMILIES: readonly ["hfs", "format", "db", "secrets", "wiring", "types", "lint", "test", "sonar"];
+export type FamilyId = (typeof FAMILIES)[number];
+/** Whether a family judged everything (`full`) or only what differs from the trusted cache (`diff`). */
+export type RunMode = 'full' | 'diff';
+/** Plain JSON, the only thing a record may carry: no undefined, no functions, no dates. */
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** One finding of a step. Messages carry app-relative posix paths only. */
+export interface Finding {
+    readonly path: string;
+    readonly line: number;
+    readonly column: number;
+    readonly rule: string;
+    readonly message: string;
+}
+/**
+ * One self-contained result: the `step` judged the `path` (or the input set a scoped step names) whose content was `hash`, and
+ * found `findings` (none for a clean file). `data` is the step's own extra payload (resolved imports, coverage items).
+ */
+export interface CacheRecord {
+    readonly path: string;
+    readonly step: string;
+    readonly hash: string;
+    readonly findings: readonly Finding[];
+    readonly data?: JsonValue;
+}
+/** One part of the fingerprint: a name and the sha256 of what it stands for. */
+export interface FingerprintPart {
+    readonly name: string;
+    readonly sha256: string;
+}
+/** What one family reports on its own line: `<family>: <full|diff> (<reason>), checked n, reused n; findings ...`. */
+export interface FamilyReport {
+    readonly family: FamilyId;
+    readonly mode: RunMode;
+    readonly reason: string;
+    readonly checked: number;
+    readonly reused: number;
+    /** Findings this run produced that its records did not already hold. */
+    readonly newFindings: number;
+    /** Findings this run produced that its records already held. */
+    readonly knownFindings: number;
+    /** Findings the records held that this run no longer produces. */
+    readonly fixedFindings: number;
+}
+/** The tracked files of the app and their normalised content hashes. */
+export interface ContentIndex {
+    readonly paths: readonly string[];
+    /** The hash of `path` now, or undefined when the work tree no longer holds it. */
+    hashOf(path: string): string | undefined;
+}
+/** A running step's progress: `tick` as files complete. */
+export interface StepProgress {
+    tick(done: number, reused: number, checked: number): void;
+    end(): void;
+}
+/** Where progress goes (stderr in the CLI). Never stdout, which keeps the diagnosis. */
+export interface ProgressSink {
+    step(family: FamilyId, name: string, total: number): StepProgress;
+}
+/** How a family decides to run: the global situation (no cache, `--full`, fingerprint, release) already folded in. */
+export interface FamilyDecision {
+    readonly mode: RunMode;
+    readonly reason: string;
+}
+/** What the session wrote when it was flushed. */
+export interface FlushResult {
+    readonly written: readonly string[];
+    readonly removed: readonly string[];
+    /** A disk error is a warning, never an exit code. */
+    readonly warnings: readonly string[];
+}
+/**
+ * The cache as one run sees it. A family asks it for its decision and its trusted records, judges, and replaces its records;
+ * the session writes them once at the end (`flush`), byte-stable.
+ */
+export interface CheckSession {
+    readonly root: string;
+    readonly index: ContentIndex;
+    /** Whether the family may read the cache this run, and why not when it may not (no cache, `--full`, fingerprint, release). */
+    decide(family: FamilyId): FamilyDecision;
+    /** The trusted records of a folder (`lint/be`, `check/format`, `test-coverage`), unfiltered: the step compares hashes itself. */
+    records(folder: string): readonly CacheRecord[];
+    /** Replaces every record of a folder with `records`; written on `flush`. `depth` is how many folders of a path name its area file (default 2). */
+    replace(folder: string, records: readonly CacheRecord[], options?: {
+        readonly depth?: number;
+    }): void;
+    /** True when none of `paths` changed in the work tree since the run began: a scoped step stores nothing keyed on a file edited during the run. */
+    unchanged(paths: readonly string[]): boolean;
+    report(report: FamilyReport): void;
+    readonly progress: ProgressSink;
+    flush(): FlushResult;
+}

package/cache/types.mjs

@@ -0,0 +1,8 @@
+// types.mts - the vocabulary of the committed app check cache (contexts/project/check-cache.md). Every family, step and spec of
+// the cache speaks these types; nothing here reads the disk or the network.
+/** The format of the records on disk; a cache of another version is replaced, never read. */
+export const CACHE_FORMAT_VERSION = 1;
+/** Where the committed cache lives, app-relative and posix. */
+export const CACHE_DIR = '.starcistacks/cache';
+/** The families a run selects (`app check --<family>`). */
+export const FAMILIES = ['hfs', 'format', 'db', 'secrets', 'wiring', 'types', 'lint', 'test', 'sonar'];

package/cache/wiring-family.d.mts

@@ -0,0 +1,14 @@
+import { type WiringResult } from '../runtime/scripts/hfs/app-wiring.mjs';
+import type { CheckSession, FamilyReport } from './types.mjs';
+export declare const WIRING_FOLDER = "check/wiring";
+export interface WiringFamilyResult {
+    readonly wiring: WiringResult;
+    readonly report: FamilyReport;
+}
+/** The boot proof family. `explicit` is the whole-tree proof of `--wiring`; without it a missing install leaves the compile unjudged, as the content finder does. */
+export declare function runWiringFamily(session: CheckSession, { repoRoot, edition, files, run }: {
+    repoRoot: string;
+    edition?: string | undefined;
+    files?: readonly string[] | undefined;
+    run?: ((repoRoot: string) => WiringResult) | undefined;
+}): Promise<WiringFamilyResult>;

package/cache/wiring-family.mjs

@@ -0,0 +1,43 @@
+// wiring-family.mts - `app check --wiring`: the boot proof of every app, a lite back end's composition with doubles. Scoped: reused when the
+// back-end side key is unchanged. A timeout reached no verdict and is never stored.
+import fs from 'node:fs';
+import path from 'node:path';
+import { appWiring, BOOT_PROOF_TIMEOUT } from '../runtime/scripts/hfs/app-wiring.mjs';
+import { loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
+import { trackedFiles } from '../runtime/scripts/hfs/check.mjs';
+import { RecordSet, scopedStep } from './records.mjs';
+import { makeReport } from './report.mjs';
+import { sideKey } from './side-key.mjs';
+export const WIRING_FOLDER = 'check/wiring';
+const compact = (finding) => ({ path: finding.path, line: 0, column: 0, rule: finding.code, message: finding.message });
+/** The boot proof family. `explicit` is the whole-tree proof of `--wiring`; without it a missing install leaves the compile unjudged, as the content finder does. */
+export async function runWiringFamily(session, { repoRoot, edition, files, run }) {
+    const decision = session.decide('wiring');
+    const records = new RecordSet(session.records(WIRING_FOLDER));
+    const key = sideKey(repoRoot, session.index, 'be');
+    const prove = () => {
+        if (run)
+            return run(repoRoot);
+        const declared = readRepoDeclaration(loadSlotManifest(), repoRoot);
+        const repo = { ...declared, edition: edition ?? declared.edition };
+        const proof = appWiring({ repoRoot, repo: repo, files: [...(files ?? trackedFiles(repoRoot))] });
+        const installed = fs.existsSync(path.join(repoRoot, 'node_modules')) || fs.existsSync(path.join(repoRoot, 'be', 'node_modules'));
+        const findings = proof.findings.filter((finding) => installed || finding.reason !== 'module or proof could not be compiled');
+        return { ...proof, findings, ok: findings.length === 0 };
+    };
+    const step = session.progress.step('wiring', 'boot proof', Math.max(1, key.inputs.length));
+    const { value, reused } = await scopedStep(session, records, {
+        path: 'be', step: 'boot-proof', key: key.key, reuse: decision.mode === 'diff', inputs: key.inputs,
+        compute: () => JSON.parse(JSON.stringify(prove())),
+        compact: (found) => found.findings.map(compact),
+        store: (found) => !found.findings.some((finding) => finding.code === BOOT_PROOF_TIMEOUT),
+    });
+    step.tick(key.inputs.length, reused ? key.inputs.length : 0, reused ? 0 : key.inputs.length);
+    step.end();
+    const wiring = value;
+    const previousRecords = session.records(WIRING_FOLDER).flatMap((record) => record.findings);
+    session.replace(WIRING_FOLDER, records.toArray());
+    const report = makeReport({ family: 'wiring', mode: decision.mode, reason: decision.reason, checked: reused ? 0 : 1, reused: reused ? 1 : 0, previous: previousRecords, current: wiring.findings.map(compact) });
+    session.report(report);
+    return { wiring, report };
+}

package/coverage/cli.d.mts

@@ -1,3 +1,4 @@
+import type { MergeSpecRecords } from '../cache/test-family.mjs';
 /** The preset's merge: shard coverage maps in, one lcov out. */
 type MergeCoverage = (args: {
     inputs: string[];
@@ -13,16 +14,17 @@ type Prove = (args: {
 }) => {
     ok: boolean;
 };
-export declare const USAGE = "usage: starci app coverage merge --out <lcov> <coverage-final.json-or-dir>... [--cwd <dir>] | starci app coverage verify <lcov> [--cwd <dir>]";
+export declare const USAGE = "usage: starci app coverage merge --out <lcov> (<coverage-final.json-or-dir>... | --records <test-coverage-dir>) [--cwd <dir>] | starci app coverage verify <lcov> [--cwd <dir>]";
 /**
  * Exit 0 merged or proved, 1 a refused proof, 2 bad usage, no preset or no report found. `merge` replaces the installed preset merge and
  * `prove` the coverage proof in a spec.
  */
-export declare function coverageMain(argv: string[], { cwd: baseCwd, stdout, stderr, merge, prove }?: {
+export declare function coverageMain(argv: string[], { cwd: baseCwd, stdout, stderr, merge, mergeSpecs, prove }?: {
     cwd?: string;
     stdout?: (text: string) => unknown;
     stderr?: (text: string) => unknown;
     merge?: MergeCoverage;
+    mergeSpecs?: MergeSpecRecords;
     prove?: Prove;
 }): Promise<number>;
 export {};