@starci/hfs 4.12.2 → 4.13.0

package/src/main.mjs

@@ -8,27 +8,31 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // The @starci/hfs implementation behind `starci app`: one repository, `<app>/`, with one package.json, lockfile and node_modules
 // at its root and two sides, be/ and fe/, declared by the one hfs.json of kind app. Every verb runs at the app root.
-//   starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--wiring] [--coverage-from <lcov>] | check --staged
+//   starci app check [--cwd <dir>] [--json] [--full] [--hfs] [--format] [--db] [--secrets] [--wiring] [--types] [--lint] [--test] [--sonar] [--coverage-from <lcov>] | check --staged
 //                                            every tracked path has a slot; required files exist; nothing forbidden or
 //                                            tracked-that-must-be-ignored; pins match; every managed file equals its render
 //                                            (sync/managed.mjs, the .gitignore block and sonar-project.properties included); no empty or ghost
 //                                            directory, no untracked entry outside an ignored slot; plaintext secrets, the .starcistacks shape, CI
 //                                            and pre-push canon steps, dependency version skew, the contract snapshot and the test, wire and i18n
-//                                            trees; prettier over every tracked file through the repository's own install (sync/format.mjs; not under
-//                                            --fast, and a repository without prettier is a refusal); soft-size backlog (report only); then the whole
+//                                            trees; prettier over every tracked file through the repository's own install (sync/format.mjs; a repository
+//                                            without prettier is a refusal); soft-size backlog (report only); then the whole
 //                                            architecture machine (tiers, owners, clones, dead exports, module registration, the
 //                                            front-end and back-end source rules), each violation a finding with its why.
 //                                            ESLint executes once per side through the installed managed config; the FE config composes
 //                                            the universal canon and the explicitly selected Grammar-family canon.
+//                                            The results are committed in .starcistacks/cache/ (cache/, contexts/project/check-cache.md): with no selector every
+//                                            family runs diff-only against it and writes what it judged back; --full runs the selected families in full; a
+//                                            selector (--hfs, --format, --db, --secrets, --wiring, --types, --lint, --test, --sonar) runs only that family, and
+//                                            selectors combine. Each family prints one diagnosis line (full or diff and why, checked, reused, findings new, known,
+//                                            fixed); progress goes to stderr (--quiet silences it). STARCI_APP_CHECK_CACHE=verify runs diff then full and fails (exit 2)
+//                                            on any difference; =full never reads the cache (the release gate).
+//                                            --coverage-from <lcov> judges a coverage report produced elsewhere (the merge of a sharded unit run) and records nothing.
 //                                            --staged: the pre-commit guard alone (sync/hygiene.mjs: staged .starciwork and .starcistacks paths, the secrets
 //                                            guard and the bypass guard over every staged file read from the index, a new back-end logic file staged
 //                                            without its unit spec); it takes no other flag.
-//                                            --fast: only what changed since the merge-base with origin/main (else main; --base
-//                                            overrides it); the machine
-//                                            runs on those owners without clones and dead exports. No merge-base is a refusal
-//                                            (exit 2), never a silent full pass. Exit 1 at 20 error findings or a hard blocker (gate-threshold.mjs). The root checks run once and
+//                                            Exit 1 at 20 error findings or a hard blocker (gate-threshold.mjs). The root checks run once and
 //                                            the side checks and the machine once per side, the side folder as their root; every path is app-relative.
-//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--json] [--out <file>]
+//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--full] [--json] [--out <file>]
 //                                            the ONE lint entry (npm run lint): ESLint per side with that side's canon config (per-file rules and
 //                                            the project-graph rules), this check's findings, and stylelint over the fe side, as one starci/lint@1
 //                                            report; --out writes the one Sonar import file. Exit 0 under 20 error findings and no hard blocker, 1 otherwise, 2 a tool could not run (lint/run.mjs).
@@ -81,26 +85,33 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isMain } from '../runtime/scripts/lib/is-main.mjs';
-import { changedSince, checkDatabase, checkRepository, explainPath, trackedFiles, withCheckProofs } from '../runtime/scripts/hfs/check.mjs';
+import { explainPath, readWhy, trackedFiles, withCheckProofs } from '../runtime/scripts/hfs/check.mjs';
+import { withWhy } from '../runtime/scripts/hfs/check-results.mjs';
+import { skillRoot } from '../runtime/engine/runtime-root.mjs';
 import { secretMain } from '../runtime/scripts/hfs/secret.mjs';
 import { dbBaselineMain } from '../runtime/scripts/hfs/db-baseline-verb.mjs';
 import { dbRestampMain } from '../runtime/scripts/hfs/db-restamp-verb.mjs';
 import { formatCoverageReport } from '../runtime/scripts/hfs/coverage-from.mjs';
 import { gateVerdict } from '../runtime/scripts/hfs/gate-threshold.mjs';
 import { HFS_DECLARATION_FILE, HfsSlotsError, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
-import { formatFindings } from '../sync/format.mjs';
 import { main as syncMain } from '../sync/cli.mjs';
 import { runWorkHygiene } from '../sync/hygiene.mjs';
 import { SyncError, bundledPresets } from '../sync/index.mjs';
-import { managedFindings } from '../sync/managed.mjs';
 import { emitContracts } from '../emit/contracts.mjs';
 import { ScaffoldError, newService, newSpec } from '../scaffold/service.mjs';
 import { EditionRefusal } from '../scaffold/edition-gate.mjs';
 import { addKind } from '../scaffold/add.mjs';
 import { scaffoldApp } from '../scaffold/app.mjs';
 import { newImages } from '../scaffold/image.mjs';
-import { contractEmitFindings } from '../runtime/scripts/hfs/rules/contract.mjs';
-import { eslintRepository, lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
+import { cachedLinters, eslintRepository, lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
+import { runSonarForApp, runTestForApp, runTestShard, runTypesForApp } from '../cache/app-families.mjs';
+import { CACHE_ENV, createDiskSession } from '../cache/session.mjs';
+import { DEFAULT_FAMILIES, runAppFamilies } from '../cache/run.mjs';
+import { createProgress, silentProgress } from '../cache/progress.mjs';
+import { familyLine } from '../cache/report.mjs';
+import { writeRunLog } from '../cache/run-log.mjs';
+import { FAMILIES } from '../cache/types.mjs';
+import { SECRET_CODES as SECRET_CODE_LIST } from '../cache/hfs-family.mjs';
 import { writeReport } from '../report/sonar.mjs';
 import { checkEdition } from '../upgrade/check.mjs';
 import { UpgradeError, upgradeMain } from '../upgrade/index.mjs';
@@ -134,6 +145,8 @@ const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRest
  */
 /** The flags of the add nouns that generate a file tree from a pattern (service, spec and image take none of them, and --inject is only theirs). */
 const ADD_FLAGS = { value: ['--event', '--from', '--service', '--connection', '--owner', '--failed', '--done', '--shapes', '--read', '--app', '--kind', '--blocks', '--tabs'], boolean: ['--fe', '--form'] };
+/** The family selectors of `app check`, one flag per family of the cache (contexts/project/check-cache.md). */
+const FAMILY_FLAGS = FAMILIES.map((family) => `--${family}`);
 const PARSED = {
     scaffold: { run: scaffoldMain, value: ['--registry-visibility'], edition: true, forms: [{ operands: '<name>' }] },
     add: {
@@ -145,7 +158,7 @@ const PARSED = {
             { operands: 'image', flags: [] },
         ],
     },
-    check: { run: checkMain, value: ['--base', '--coverage-from'], boolean: ['--json', '--fast', '--wiring', '--staged'], edition: true, forms: [{ only: { boolean: ['--json', '--fast', '--wiring'], value: ['--base', '--coverage-from'] } }, { only: { boolean: ['--staged'] }, edition: false }] },
+    check: { run: checkMain, value: ['--coverage-from', '--shard'], boolean: ['--json', '--staged', '--full', ...FAMILY_FLAGS], edition: true, forms: [{ only: { boolean: ['--json', '--full', ...FAMILY_FLAGS], value: ['--coverage-from', '--shard'] } }, { only: { boolean: ['--staged'] }, edition: false }] },
     slot: { run: slotMain, boolean: ['--json'], forms: [{ operands: '<path>' }] },
     emit: { run: emitMain, forms: [{}] },
 };
@@ -155,7 +168,7 @@ const ADD_FLAGS_ALL = flagsOf(ADD_FLAGS);
 const PARSED_FLAGS = new Set([...Object.values(PARSED).flatMap(flagsOf), '--edition']);
 /** The placeholder of a value flag in the usage; any other prints as <name>. */
 const PLACEHOLDERS = {
-    '--registry-visibility': 'public|private', '--edition': 'full|lite', '--base': '<ref>', '--coverage-from': '<lcov>', '--inject': '<binding>',
+    '--registry-visibility': 'public|private', '--edition': 'full|lite', '--base': '<ref>', '--coverage-from': '<lcov>', '--shard': '<i>/<n>', '--inject': '<binding>',
     '--event': '<event>', '--from': '<service>', '--service': '<Class>=<module>', '--owner': '<service>', '--failed': '<event>', '--done': '<event>',
     '--shapes': '<a,b,c>', '--blocks': '<a,b>', '--tabs': '<a,b>', '--kind': 'modal|drawer', '--image': '<service>=<ref>', '--sha': '<sha>',
     '--previous': '<release>', '--release': '<release>', '--out': '<path>', '--since': '<ISO>', '--timeout': '<seconds>', '--retry': '<seconds>',
@@ -178,7 +191,7 @@ const DATABASE_USAGE = [['new', '<kebab-name>', DB_NEW_FLAGS], ['baseline', '',
 /** The usage of each verb, from the tables its parser refuses every other flag with (lint, codemod and upgrade keep hand-parsed arguments, held by main.spec.mjs). */
 const VERB_USAGE = {
     ...Object.fromEntries(Object.entries(PARSED).map(([verb, spec]) => [verb, spec.forms.map((form) => line(`starci app ${verb}`, form.operands, specUsage(form.only ?? (form.flags === undefined ? spec : { value: form.flags })), spec.edition && form.edition !== false ? flagUsage('--edition', { value: true }) : ''))])),
-    lint: ['starci app lint [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--json] [--out <file>]'],
+    lint: ['starci app lint [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--full] [--full] [--json] [--out <file>]'],
     codemod: ['starci app codemod button-intent [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]'],
     upgrade: ['starci app upgrade [--execute]'],
     sync: [SYNC_USAGE.sync],
@@ -244,22 +257,31 @@ function contractDescription(contracts) {
     return `emitted and compared, ${apps}`;
 }
 function printCheckOverview(result, out) {
-    out(`starci app check${result.fast ? ' --fast' : ''} ${result.repoRoot} (profile ${result.profile ?? 'unknown'}, manifest ${result.manifest}, ${result.tracked} tracked paths)\n`);
-    if (result.fast)
-        out(`  ${result.fast.changed} path${result.fast.changed === 1 ? '' : 's'} changed since ${result.fast.base.slice(0, 12)}\n`);
-    out(`  architecture machine: ${machineDescription(result.machine)}\n`);
+    out(`starci app check ${result.repoRoot} (profile ${result.profile ?? 'unknown'}, manifest ${result.manifest}, ${result.tracked} tracked paths)
+`);
+    for (const report of (result.families ?? []))
+        out(`  ${familyLine(report)}
+`);
+    for (const warning of (result.cacheWarnings ?? []))
+        out(`  cache: ${warning}
+`);
+    out(`  architecture machine: ${machineDescription(result.machine)}
+`);
     if (result.contracts)
-        out(`  contract snapshots: ${contractDescription(result.contracts)}\n`);
+        out(`  contract snapshots: ${contractDescription(result.contracts)}
+`);
     if (result.eslint) {
         const sides = Object.entries(result.eslint.sides).map(([side, run]) => `${side}: ${run.files} files${run.skipped ? ` (${run.skipped})` : ''}`).join(', ');
-        out(`  ESLint: ${sides}\n`);
+        out(`  ESLint: ${sides}
+`);
         for (const error of result.eslint.errors)
-            out(`  ESLint tool error: ${error}\n`);
+            out(`  ESLint tool error: ${error}
+`);
     }
 }
 function printFindingGroup(code, list, out) {
     const first = list[0];
-    if (first.engine === 'eslint')
+    if (first.engine)
         out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}\n`);
     else
         out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}: ${first.titleVi}\n  ${first.whyVi}\n  -> ${first.nextStepVi}\n`);
@@ -307,36 +329,37 @@ function printExplain(e, out) {
     if (e.code)
         out(`  ${e.code}: ${e.titleVi}\n  ${e.whyVi}\n`);
 }
+/** The family selectors given, as families; none given selects `fallback`. */
+function selectedFamilies(opts, fallback) {
+    const given = FAMILIES.filter((family) => opts[family] === true);
+    return new Set(given.length > 0 ? given : fallback);
+}
+/** Opens the session of a verb over the tracked files of the app: progress on stderr, `--quiet` silent, a terminal rewriting running lines in place. */
+function openSession({ repoRoot, tracked, io, full, use, planned }) {
+    const progress = io.quiet === true ? silentProgress : createProgress({ write: (text) => io.stderr(text), tty: io.stderrIsTty === true, planned });
+    const env = use === 'bypass' ? { ...io.env, [CACHE_ENV]: 'full' } : use === 'read' ? { ...io.env, [CACHE_ENV]: io.env[CACHE_ENV] === 'full' ? 'full' : 'verify' } : io.env;
+    return createDiskSession({ root: repoRoot, tracked, env, progress, cliVersion: io.harness?.version, full });
+}
 /**
- * The app pass: slots, managed files, formatter, contract snapshots and the architecture machine's check surface, root and sides.
- * `only` limits the formatter to those (app-relative) files.
+ * The app pass of `starci app check` and `starci app lint`: the families the verb selects, against one cache session, merged into one result.
+ * `only` limits the formatter to those (app-relative) files and bypasses the cache (`app lint --changed`).
  */
-async function runCheck({ repoRoot, harness, fast = false, base, only, presets, prettier }) {
+async function appPass({ repoRoot, harness, only, presets, prettier, io, selected, full, use = 'normal', session: given }) {
     const tracked = trackedFiles(repoRoot);
-    // Managed files of the root and both sides, the .gitignore block and sonar against their render (R04, R05, R11, ...), and prettier
-    // through the app's own install (R19, never under --fast).
-    const extraFindings = [...await managedFindings({ repoRoot, tracked, presets }), ...await checkDatabase({ repoRoot, files: tracked, base }), ...(fast ? [] : await formatFindings({ repoRoot, files: only ?? tracked, prettier }))];
-    // R23 against the be side itself (full pass only): committed snapshots equal what `starci app emit` writes now.
-    let contracts = null;
-    let be = null;
-    try {
-        be = readRepoDeclaration(loadSlotManifest(), repoRoot).sides?.be ?? null;
-    }
-    catch { /* checkRepository reports the unreadable declaration */ }
-    if (be) {
-        if (fast)
-            contracts = { status: 'skipped', reason: '--fast does not emit the apps' };
-        else {
-            const files = tracked.filter((file) => file.startsWith('be/')).map((file) => file.slice('be/'.length));
-            const emitted = contractEmitFindings({ repoRoot: path.join(repoRoot, 'be'), files, repo: be, emit: emitContracts });
-            extraFindings.push(...emitted.findings.map((finding) => ({ ...finding, side: 'be', path: `be/${finding.path}` })));
-            contracts = { status: 'checked', apps: emitted.apps };
-        }
-    }
-    const result = checkRepository({ repoRoot, harness, fast, base, extraFindings });
-    if (contracts)
-        result.contracts = contracts;
-    return result;
+    const session = given ?? openSession({ repoRoot, tracked, io, full, use: only === undefined ? use : 'bypass', planned: tracked.length * Math.max(1, selected.size) });
+    const result = await runAppFamilies({ repoRoot, tracked, session, selected, harness, presets, prettier, only, edition: undefined });
+    if (given !== undefined)
+        return result;
+    const flushed = session.flush();
+    return { ...result, findings: [...result.findings, ...verdictFindings(session)], cacheWarnings: flushed.warnings };
+}
+/** The verdicts of the CI comparison (forged, stale, missing) as findings with their why. */
+function verdictFindings(session) {
+    const verdicts = session.verdicts();
+    if (verdicts.length === 0)
+        return [];
+    const why = readWhy(skillRoot, [...new Set(verdicts.map((verdict) => verdict.code))]);
+    return withWhy(verdicts.map((verdict) => ({ code: verdict.code, level: verdict.level, path: verdict.path, message: verdict.message })), why);
 }
 /** The nearest folder at or above `dir` that holds hfs.json (the app root of a workspace), or `dir` itself when none does (the lint then refuses it). */
 export function appRootAbove(dir) {
@@ -348,7 +371,8 @@ export function appRootAbove(dir) {
     }
 }
 /** `starci app lint`: ESLint per side, the app checks and stylelint over the fe side as one report; see lint/run.mjs. */
-async function lintMain(argv, { cwd, harness, stdout, presets, prettier, runLinter, checkApp = runCheck }) {
+async function lintMain(argv, io) {
+    const { cwd, harness, stdout, presets, prettier, runLinter, checkApp = appPass } = io;
     const opts = parseLintArgs(argv);
     // --workspace names a folder from the working directory (`starci app lint --workspace .` is an fe workspace script); the app
     // root is then the nearest folder above it that holds hfs.json, and the workspace is passed on app-relative.
@@ -356,10 +380,17 @@ async function lintMain(argv, { cwd, harness, stdout, presets, prettier, runLint
     const repoRoot = path.resolve(workspaceDir ? appRootAbove(workspaceDir) : cwd);
     if (workspaceDir)
         opts.workspace = path.relative(repoRoot, workspaceDir).split(path.sep).join('/');
+    // The lint shares the cache of `app check`: --workspace reads it and writes none, --changed and --fix neither read nor write, --full judges again.
+    const use = opts.changed !== null || opts.fix ? 'bypass' : opts.workspace !== undefined ? 'read' : 'normal';
+    const selected = new Set(['hfs', 'secrets', 'db', 'format']);
+    // One session for the app findings and the linters, so the two never hold two answers; checkApp is a spec seam that brings its own.
+    const session = io.checkApp === undefined ? openSession({ repoRoot, tracked: trackedFiles(repoRoot), io, full: opts.full === true ? new Set([...selected, 'lint']) : undefined, use, planned: 1 }) : undefined;
     const { report, sonar, exit } = await lintRepository({
-        repoRoot, opts, trackedFiles, runLinter,
-        hfsCheck: (root) => checkApp({ repoRoot: root, harness, only: opts.changed ?? undefined, presets, prettier }),
+        repoRoot, opts, trackedFiles, runLinter, ...(session === undefined ? {} : { cache: { session } }),
+        hfsCheck: (root) => checkApp({ repoRoot: root, harness, only: opts.changed ?? undefined, presets, prettier, io, selected, use, session }),
     });
+    const flushed = session?.flush();
+    const verdicts = session === undefined ? [] : verdictFindings(session);
     if (opts.out !== undefined)
         writeReport(path.resolve(cwd, opts.out), sonar);
     if (opts.format === 'json')
@@ -367,7 +398,11 @@ async function lintMain(argv, { cwd, harness, stdout, presets, prettier, runLint
 `);
     else
         printLintText(report, stdout);
-    return exit;
+    for (const verdict of verdicts)
+        stdout(`${verdict.level.toUpperCase()} ${verdict.code}: ${verdict.message}\n`);
+    for (const warning of flushed?.warnings ?? [])
+        stdout(`cache: ${warning}\n`);
+    return Math.max(exit, verdicts.some((verdict) => verdict.level === 'error') ? 1 : 0);
 }
 /**
  * The jest preset a new app renders its Sonar exclusions from: the copy this @starci/hfs ships (bundledPresets), the same version the
@@ -448,8 +483,80 @@ function printCheckProofs(result, out) {
         out(formatCoverageReport(result.coverage));
 }
 /** The flags `check --staged` refuses: it is the pre-commit guard alone, so none of the whole-app pass's options means anything with it. */
-const STAGED_REFUSES = ['--json', '--fast', '--base', '--wiring', '--coverage-from'];
-async function checkMain(opts, { cwd: repoRoot, harness, edition, stdout: out, presets, prettier, checkApp = runCheck, runLinter }) {
+const STAGED_REFUSES = ['--json', '--full', '--coverage-from', '--shard', ...FAMILY_FLAGS];
+/** The family a finding belongs to, for naming it when a verified run disagrees with the cache. */
+function familyOf(finding) {
+    const code = finding.code ?? '';
+    if (finding.engine === 'eslint' || finding.engine === 'stylelint')
+        return 'lint';
+    if (code === 'HFS_FORMAT')
+        return 'format';
+    if (/^(DB_|LITE_DB_)/.test(code))
+        return 'db';
+    if (code === 'BE_APP_BOOT_PROOF_MISSING' || code === 'BOOT_PROOF_TIMEOUT')
+        return 'wiring';
+    return SECRET_CODE_LIST.has(code) ? 'secrets' : 'hfs';
+}
+/** One run of the selected families against the cache, then the coverage proof on top; returns the result and what it took. */
+async function checkRun({ io, selected, full, use, coverageFrom }) {
+    const { cwd: repoRoot, harness, edition, presets, prettier, checkApp = appPass, runLinter } = io;
+    const started = Date.now();
+    const tracked = io.checkApp === undefined ? trackedFiles(repoRoot) : [];
+    const session = io.checkApp === undefined ? openSession({ repoRoot, tracked, io, full, use, planned: tracked.length * Math.max(1, selected.size) }) : undefined;
+    const checked = await checkEdition({ repoRoot, edition, normal: () => checkApp({ repoRoot, harness, presets, prettier, io, selected, full, use, session }), presets, prettier });
+    const proof = withCheckProofs(checked, { repoRoot, edition, wiring: false, coverageFrom });
+    const extra = [];
+    const lines = [];
+    let eslint = null;
+    if (selected.has('lint')) {
+        if (session !== undefined) {
+            const app = readRepoDeclaration(loadSlotManifest(), repoRoot);
+            eslint = (await cachedLinters({ repoRoot, app, opts: { changed: null, fix: false, format: 'text', out: undefined, workspace: undefined }, workspace: null, onFe: null, run: runLinter, cache: { session } })).eslint;
+        }
+        else
+            eslint = await eslintRepository({ repoRoot, changed: null, existing: [], run: runLinter });
+    }
+    if (session !== undefined && selected.has('types'))
+        extra.push(...runTypesForApp(session, { repoRoot, tracked, env: io.env }).findings);
+    if (session !== undefined && selected.has('test')) {
+        const tests = await runTestForApp(session, { repoRoot, tracked });
+        extra.push(...tests.findings);
+    }
+    if (session !== undefined && selected.has('sonar'))
+        lines.push(...(runSonarForApp(session, { repoRoot })?.lines ?? []));
+    const flushed = session?.flush();
+    const verdicts = session === undefined ? [] : verdictFindings(session);
+    const reports = session === undefined ? [...(checked.families ?? [])] : [...session.reports];
+    const findings = [...proof.findings, ...extra, ...verdicts, ...(eslint?.findings ?? []).map(finding => ({ ...finding, code: finding.code ?? finding.rule, level: 'error' }))];
+    // Green under the threshold (gate-threshold.mjs): every finding is still listed, only the verdict changes.
+    const verdict = gateVerdict(findings.filter(finding => finding.level === 'error'));
+    const toolErrors = eslint?.errors ?? [];
+    const counts = { ...proof.counts, error: findings.filter(finding => finding.level === 'error').length, warning: findings.filter(finding => finding.level === 'warning').length };
+    const result = { ...proof, findings, families: reports, predictions: lines, cacheWarnings: [...(checked.cacheWarnings ?? []), ...(flushed?.warnings ?? [])], counts, ...(eslint ? { eslint: { ...eslint.engine, errors: eslint.errors } } : {}), ok: verdict.pass && toolErrors.length === 0, gate: verdict };
+    return { result, seconds: (Date.now() - started) / 1000 };
+}
+/** STARCI_APP_CHECK_CACHE=verify: the diff-only run, then the full run, compared finding by finding; any difference names family and file (exit 2). */
+async function verifyCache(io, selected, coverageFrom) {
+    const diff = await checkRun({ io, selected, full: undefined, use: 'read', coverageFrom });
+    const full = await checkRun({ io, selected, full: new Set(selected), use: 'bypass', coverageFrom });
+    const keyed = (result) => new Map(result.findings.map((finding) => [`${finding.code}|${finding.path ?? ''}|${finding.message}`, `${familyOf(finding)}: ${finding.path ?? finding.code}`]));
+    const left = keyed(diff.result);
+    const right = keyed(full.result);
+    const differences = [...left].filter(([key]) => !right.has(key)).map(([, name]) => `diff-only only: ${name}`)
+        .concat([...right].filter(([key]) => !left.has(key)).map(([, name]) => `full only: ${name}`)).sort();
+    io.stdout(`${CACHE_ENV}=verify: diff-only ${diff.seconds.toFixed(1)}s, full ${full.seconds.toFixed(1)}s, ${right.size} finding(s) compared\n`);
+    for (const report of diff.result.families)
+        io.stdout(`  diff-only ${familyLine(report)}\n`);
+    if (differences.length === 0) {
+        io.stdout('  identical\n');
+        return 0;
+    }
+    for (const difference of differences)
+        io.stdout(`  DIFFERENCE ${difference}\n`);
+    return 2;
+}
+async function checkMain(opts, io) {
+    const { cwd: repoRoot, edition, stdout: out } = io;
     if (opts.positional.length)
         throw new Error('starci app check takes no path');
     if (opts.staged === true) {
@@ -458,26 +565,33 @@ async function checkMain(opts, { cwd: repoRoot, harness, edition, stdout: out, p
             throw new Error(`starci app check --staged is the pre-commit guard alone and takes no ${given.join(', ')}`);
         return runWorkHygiene({ cwd: repoRoot, out: (text) => out(`${text}\n`) });
     }
-    if (opts.base !== undefined && opts.fast !== true)
-        throw new Error('--base names the ref --fast compares with; it needs --fast');
-    const checked = await checkEdition({ repoRoot, edition, normal: () => checkApp({ repoRoot, harness, fast: opts.fast === true, base: opts.base, presets, prettier }), presets, prettier });
-    const proof = withCheckProofs(checked, { repoRoot, edition, wiring: opts.wiring === true, coverageFrom: valueFlag(opts, 'coverage-from') });
-    const changed = opts.fast === true ? changedSince(repoRoot, proof.fast?.base ?? valueFlag(opts, 'base')).files : null;
-    const existing = changed ? changed.filter((file) => fs.existsSync(path.join(repoRoot, file))) : [];
-    const eslint = await eslintRepository({ repoRoot, changed, existing, run: runLinter });
-    const findings = [...proof.findings, ...eslint.findings.map(finding => ({ ...finding, code: finding.code ?? finding.rule, level: 'error' }))];
-    // Green under the threshold (gate-threshold.mjs): every finding is still listed, only the verdict changes.
-    const verdict = gateVerdict(findings.filter(finding => finding.level === 'error'));
-    const result = { ...proof, findings, counts: { ...proof.counts, error: proof.counts.error + eslint.findings.length }, eslint: { ...eslint.engine, errors: eslint.errors }, ok: verdict.pass && eslint.errors.length === 0, gate: verdict };
+    const coverageFrom = valueFlag(opts, 'coverage-from');
+    const shard = valueFlag(opts, 'shard');
+    if (shard !== undefined) {
+        // The sharded full unit run of CI (--test --full --shard <i>/<n>): the shard's Jest run in the shape the shard merge reads; nothing is recorded.
+        const match = /^(\d+)\/(\d+)$/.exec(shard);
+        if (match === null || opts.test !== true || opts.full !== true)
+            throw new Error('--shard <i>/<n> belongs to `starci app check --test --full`');
+        return runTestShard(repoRoot, Number(match[1]), Number(match[2]));
+    }
+    const explicit = selectedFamilies(opts, []);
+    // A coverage report judged on its own (the merge job of a sharded run) runs no family; with selectors it comes on top of them.
+    const selected = explicit.size > 0 ? explicit : coverageFrom === undefined ? new Set(DEFAULT_FAMILIES) : new Set();
+    const full = opts.full === true ? new Set(selected) : undefined;
+    if (io.env[CACHE_ENV] === 'verify')
+        return verifyCache(io, selected, coverageFrom);
+    const { result, seconds } = await checkRun({ io, selected, full, use: coverageFrom !== undefined && explicit.size === 0 ? 'bypass' : 'normal', coverageFrom });
     if (opts.json)
         out(`${JSON.stringify(result, null, 2)}\n`);
     else {
         printCheck(result, out);
         printCheckProofs(result, out);
-        if (verdict.line)
-            out(`${verdict.line}\n`);
+        if (result.gate.line)
+            out(`${result.gate.line}\n`);
     }
-    return eslint.errors.length ? 2 : result.ok ? 0 : 1;
+    const exit = result.eslint?.errors.length ? 2 : result.ok ? 0 : 1;
+    writeRunLog(repoRoot, { command: `check${[...selected].map((family) => ` --${family}`).join('')}${opts.full === true ? ' --full' : ''}`, seconds, exit, families: result.families.map((report) => ({ ...report, seconds: 0 })) }, io.env);
+    return exit;
 }
 function emitMain(opts, { cwd: repoRoot, stdout: out }) {
     if (opts.positional.length)
@@ -607,11 +721,12 @@ function errorMessage(error) {
  * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
  * harness CLI's own secret.env SOPS_AGE_KEY, which every verb that opens a sealed member (secret, stack, release, db) reads last for the age identity (decryptionIdentity); `prompt` replaces its masked prompt.
  */
-export async function main(argv, { cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain, env = process.env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp, } = {}) {
+export async function main(argv, { cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain, env = process.env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp, stderrIsTty = process.stderr.isTTY === true, } = {}) {
     try {
         const global = globalOptions(argv, path.resolve(baseCwd));
         const [verb, ...given] = global.argv;
-        const out = global.quiet ? () => { } : stdout;
+        // --quiet silences stdout for every verb but check and lint, whose diagnosis it keeps (their progress on stderr is what it mutes).
+        const out = global.quiet && !['check', 'lint'].includes(verb) ? () => { } : stdout;
         if (global.help) {
             out(USAGE);
             return 0;
@@ -621,7 +736,7 @@ export async function main(argv, { cwd: baseCwd = process.cwd(), harness, stdout
             return 2;
         }
         const { edition, argv: rest } = editionOption(verb, given);
-        return await dispatchMain(verb, rest, { cwd: global.cwd, harness, edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp });
+        return await dispatchMain(verb, rest, { cwd: global.cwd, harness, edition, quiet: global.quiet, stderrIsTty, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp });
     }
     catch (error) {
         stderr(errorMessage(error));

package/src/stack-records-double.d.mts

@@ -0,0 +1,31 @@
+import type { ReleaseStore, StoredRelease } from '../stack/release-store.mjs';
+/** The records half of a ReleaseStore, plus what it kept. */
+export interface RecordsDouble extends Pick<ReleaseStore, 'read' | 'tryLock' | 'refreshLock' | 'unlock' | 'journal'> {
+    /** The latest document of each attempt, as the journal wrote it (a copy at each write). */
+    documents: Map<string, Record<string, unknown>>;
+    /** Every write of every document, in order: the phase boundaries a cancelled job would have left. */
+    writes: Record<string, unknown>[];
+    /** The append-only index. */
+    index: Record<string, unknown>[];
+    /** The holder token and trigger of the lock, null when it is free. */
+    lock: {
+        token: string;
+        trigger: string;
+    } | null;
+    /** Lock calls in order: `try:<trigger>`, `refresh`, `unlock`. */
+    calls: string[];
+}
+/** What a double can be told: the release `read` answers, a lock held by someone else, and journal writes that fail. */
+export interface RecordsOptions {
+    read?: (id: string) => StoredRelease | Promise<StoredRelease>;
+    /** The lock is held by another deploy for this many seconds: `tryLock` answers busy until `freeAfterTries` tries have passed. */
+    busy?: {
+        holder: string;
+        ageSeconds: number;
+        freeAfterTries?: number;
+    } | undefined;
+    failJournal?: boolean | undefined;
+    /** The journal accepts this many document writes and fails every later one (a manager that drops mid-deploy). */
+    failJournalAfter?: number | undefined;
+}
+export declare function recordsDouble(options?: RecordsOptions): RecordsDouble;

package/stack/cli.d.mts

@@ -14,6 +14,7 @@ export interface Flags {
     push?: boolean;
     urgent?: boolean;
     'first-start'?: boolean;
+    redeploy?: boolean;
     image?: string[];
     keep?: string[];
     'extra-compose'?: string[];
@@ -33,8 +34,9 @@ export interface Flags {
     'db-service'?: string;
     reason?: string;
     remote?: string;
+    'ci-run'?: string;
 }
-export declare const ACTIONS: readonly ["prepare", "connect", "disconnect", "build-args", "render", "deploy", "converge", "verify", "rollback", "prune", "backup", "jobs", "task", "ingress", "retire", "build", "accept"];
+export declare const ACTIONS: readonly ["prepare", "connect", "disconnect", "build-args", "render", "deploy", "converge", "verify", "rollback", "prune", "backup", "jobs", "task", "ingress", "retire", "build", "accept", "status"];
 /** One action of `starci app stack`. */
 export type Action = (typeof ACTIONS)[number];
 /** True when `value` names one action of `starci app stack`. */

package/stack/cli.mjs

@@ -9,7 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // cli.mjs - `starci app stack <action>` for the Swarm deploy tooling: flags, dry run versus --execute, dispatch, text and --json output.
 //   starci app stack <action> --env <env> [the action's FLAGS]     (only the READ_ONLY actions default --env to production)
 // Each action takes only its own flags: a flag of another action is a refusal, never ignored.
-// (up, down and status are the test-world verbs and are dispatched by packages/hfs/src/main.mjs.)
+// (`starci app world <up|down|status>` is the test world's, dispatched by packages/hfs/src/main.mjs; `stack status` below is the deploy's drift report.)
 // Every action module exports one async function (ctx, config, options) -> { ok, lines, data }; a refusal throws StackError.
 import path from 'node:path';
 import { stackContext } from './context.mjs';
@@ -19,12 +19,12 @@ import { StackError, EXIT, refusal } from './errors.mjs';
 import { parseTargetBinding, bindStackTarget, nativeToolEnvironment } from './target-binding.mjs';
 import { oneCommand, prepareUrgentRelease } from './urgent-release.mjs';
 /** The actions that drive the docker CLI of the operator machine (pointed at the manager by docker-transport.mjs when the key is sealed). */
-const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollback', 'prune']);
-export const ACTIONS = Object.freeze(['prepare', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept']);
+const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollback', 'prune', 'status']);
+export const ACTIONS = Object.freeze(['prepare', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept', 'status']);
 /** True when `value` names one action of `starci app stack`. */
 export const isAction = (value) => ACTIONS.includes(value);
-export const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start']);
-export const VALUE = new Set(['--env', '--image', '--sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service', '--reason', '--remote']);
+export const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start', '--redeploy']);
+export const VALUE = new Set(['--env', '--image', '--sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service', '--reason', '--remote', '--ci-run']);
 export const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
 /** `--ssh-cmd` replaces the configured alias for an action whose module (or the Docker transport) reaches the manager over SSH. */
 const SSH = ['--ssh-cmd'];
@@ -38,7 +38,7 @@ export const FLAGS = Object.freeze({
     disconnect: ['--execute'],
     'build-args': ['--app'],
     render: ['--image', '--sha', '--previous', '--out', '--allow-unpinned', '--extra-compose'],
-    deploy: ['--image', '--sha', '--execute', '--out', '--timeout', '--retry', '--skip-public', '--target-binding', '--urgent', '--reason', '--remote', '--db-url-env', '--backup-out', '--first-start', '--db-service', ...SSH],
+    deploy: ['--image', '--sha', '--execute', '--out', '--timeout', '--retry', '--skip-public', '--target-binding', '--urgent', '--reason', '--remote', '--db-url-env', '--backup-out', '--first-start', '--db-service', '--ci-run', '--redeploy', ...SSH],
     converge: ['--since', '--timeout', ...SSH],
     verify: ['--retry', '--skip-public', '--skip-internal', '--target-binding', ...SSH],
     rollback: ['--release', '--execute', '--timeout', ...SSH],
@@ -49,12 +49,13 @@ export const FLAGS = Object.freeze({
     ingress: ['--execute', ...SSH],
     retire: ['--project', '--execute', ...SSH],
     build: ['--push', '--execute'],
-    accept: ['--release', '--execute', '--retry', ...SSH],
+    accept: ['--release', '--execute', '--retry', '--db-url-env', ...SSH],
+    status: [...SSH],
 });
 /** The operands of the actions that take any, as the usage prints them. */
 export const OPERANDS = Object.freeze({ jobs: '<action> [<arg>...]', task: '<name> [<arg>...]', ingress: '<action> [<arg>...]' });
 /** The read-only actions, whose `--env` defaults to production. Every action with an effect names its environment, so none reaches production by omission. */
-export const READ_ONLY = Object.freeze(['build-args', 'render', 'verify']);
+export const READ_ONLY = Object.freeze(['build-args', 'render', 'verify', 'status']);
 /** Splits argv into { flags, positional }; an unknown flag, a flag of another action or a flag without its value is a refusal. */
 function parseFlags(action, argv) {
     const own = new Set(['--env', '--json', ...FLAGS[action]]);
@@ -91,8 +92,10 @@ function checkDeployForm(flags) {
     }
     if (!flags.urgent && (flags['first-start'] || flags['db-service']))
         throw refusal('STACK_USAGE', '--first-start and --db-service are the first start of an empty database under the urgent floor: add --urgent');
-    if (!flags.urgent && (flags['db-url-env'] || flags['backup-out']))
-        throw refusal('STACK_USAGE', '--db-url-env and --backup-out choose the urgent floor\'s database and backup folder: add --urgent');
+    if (flags.urgent && flags['ci-run'])
+        throw refusal('STACK_USAGE', '--ci-run names the CI run that deploys; an urgent deploy runs no CI (the CI run of its tag is the back-fill)');
+    if (flags['ci-run'] !== undefined && !/^[0-9]{1,20}$/u.test(flags['ci-run']))
+        throw refusal('STACK_USAGE', '--ci-run takes the numeric id of the CI run');
 }
 /** `--image api=ghcr.io/o/x@sha256:...` (repeatable or comma separated) -> { api: 'ghcr.io/o/x@sha256:...' }. */
 function parseImages(values = []) {
@@ -130,6 +133,7 @@ const OPTIONS = {
         out: flags.out ? path.resolve(cwd, flags.out) : null, timeoutSeconds: number(flags, 'timeout'), retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true,
         urgent: flags.urgent === true, dbUrlEnv: flags['db-url-env'], backupOut: flags['backup-out'] ? path.resolve(cwd, flags['backup-out']) : undefined,
         firstStart: flags['first-start'] === true, dbService: flags['db-service'], reason: flags.reason, remote: flags.remote,
+        ciRun: flags['ci-run'], redeploy: flags.redeploy === true,
     }),
     converge: ({ flags }) => ({ since: flags.since, timeoutSeconds: number(flags, 'timeout') }),
     verify: ({ flags }) => ({ retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true, skipInternal: flags['skip-internal'] === true }),
@@ -138,7 +142,8 @@ const OPTIONS = {
     backup: ({ flags }) => ({ swarmState: flags['swarm-state'] === true, execute: flags.execute === true }),
     ingress: ({ flags, positional }) => ({ action: positional[0], execute: flags.execute === true, args: positional.slice(1) }),
     build: ({ flags }) => ({ push: flags.push === true, execute: flags.execute === true }),
-    accept: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, retrySeconds: number(flags, 'retry') }),
+    accept: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, retrySeconds: number(flags, 'retry'), dbUrlEnv: flags['db-url-env'] }),
+    status: () => ({}),
     retire: ({ flags }) => ({ projects: flags.project ?? [], execute: flags.execute === true }),
     jobs: ({ flags, positional }) => ({ action: positional[0], args: positional.slice(1), execute: flags.execute === true }),
     task: ({ flags, positional }) => ({ name: positional[0], args: positional.slice(1), execute: flags.execute === true }),
@@ -154,6 +159,7 @@ const MODULES = {
     retire: ['./retire.mjs', 'retireCompose'],
     build: ['./build.mjs', 'buildImages'],
     accept: ['./deploy.mjs', 'acceptRelease'],
+    status: ['./status.mjs', 'statusStack'],
 };
 async function handlerOf(action, importer) {
     const [file, name] = MODULES[action];

package/stack/config.d.mts

@@ -158,6 +158,12 @@ export interface DeployBlock {
     environment: Record<string, ServiceEnvironment>;
     configs: ConfigEntry[];
     passEnv: string[];
+    /** deploy.auto: a green release tag deploys here by itself (the CI workflow reads it; the verbs do not). */
+    auto: boolean;
+    /** deploy.approval: none, or reviewers set on the GitHub Environment. */
+    approval: 'none' | 'reviewers';
+    /** deploy.platforms: the platforms the images are built for (default linux/amd64). */
+    platforms: string[];
     verify: {
         http: HttpCheck[];
         exec: ExecCheck[];

package/stack/converge.d.mts

@@ -2,6 +2,8 @@ import type { DeployConfig } from './config.mjs';
 import type { StackContext } from './context.mjs';
 import type { ActionResult } from './remote.mjs';
 type Ctx = Pick<StackContext, 'spawn' | 'now' | 'sleep'>;
+/** The JSON text with object keys sorted at every depth, so two equal specs compare equal whatever the key order. */
+export declare function canonical(value: unknown): string;
 /**
  * Waits until the stack converged. `since` is the ISO instant the deploy began (required). Returns { ok, lines, data: { services, failed, pending } };
  * on failure the lines name the service and the Swarm task error text.

package/stack/converge.mjs

@@ -13,7 +13,7 @@ const TAB = String.fromCodePoint(9);
 const TASK_FORMAT = `{{.DesiredState}}|{{.Status.State}}|{{.Status.Timestamp}}|{{.Status.Err}}${TAB}{{json .Spec}}`;
 const docker = (ctx, args) => toolOutput(ctx, 'docker', args);
 /** The JSON text with object keys sorted at every depth, so two equal specs compare equal whatever the key order. */
-function canonical(value) {
+export function canonical(value) {
     if (Array.isArray(value))
         return `[${value.map(canonical).join(',')}]`;
     if (value !== null && typeof value === 'object')