@abloh/repository 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,4631 @@
+import { RepoReader, PackageManifestReading, MatrixLeg, MatrixLegs, FailFastReading, SetupCandidateTrigger, SetupWorkflowCaller, SetupCandidateGate, NativeVocabulary, SetupFailFast, SetupCandidateExclusion, Refusal, YamlQuote, CoverageProviderChoice, MatrixValue, WorkflowNodePin, SetupScriptStep, ValueOrigin, CommandScriptHop, AngularTestTarget, PreparedTestCommand, InitFailureClass, InitQuestionKey, EnvironmentConfig, TargetSelectionKind, EvidenceOutputId, resolvePreparedTestCommand, MeasurementPlan, PackageExclusion } from '@abloh/core';
+export { SETUP_STEP_ACTION, SETUP_STEP_IF, SETUP_STEP_JOB_STATUS, SETUP_STEP_NAME, setupStepIf } from '@abloh/core';
+import { JasmineSuite, ProofRunner, StrykerMutationRunner } from '@abloh/measure';
+
+/**
+ * WHERE THIS MODULE'S BYTES COME FROM.
+ *
+ * NOTHING HERE OPENS A FILE ANY MORE (the captain's ruling of 2026-09-05, and `ci-recipe.ts` before
+ * it). `abloh init` reads a checkout on the maintainer's machine and a GitHub App install has to
+ * read the same repository over GitHub's contents API with no checkout at all, and the DECIDING in
+ * between - which package, which runner, which manager - must be one implementation, because two
+ * would drift about what abloh writes into somebody else's repository.
+ * `packages/core/src/repo-reader.ts` states the interface and why it is synchronous.
+ *
+ * IT CARRIES A ROOT AS WELL AS A READER, because this module's own vocabulary is ABSOLUTE paths and
+ * always has been: every exported function takes a `repoDir` or a `dir`, every caller passes one,
+ * and `TargetDetection` reports `workDir` as an absolute path. Rewriting all of that to be
+ * repository-relative would be a second change on top of this one, in the module every other part
+ * of onboarding calls. So the access holds the root, the helpers below turn an absolute path back
+ * into the repository-relative one the reader speaks, and no signature outside this file moves.
+ *
+ * A PATH OUTSIDE THE ROOT READS AS ABSENT, which is the same answer the reader gives for the same
+ * reason. Detection walks UP from the measured package towards the repository root and stops there,
+ * so a path above it was already out of bounds; what changes is that the bound is now enforced by
+ * one function rather than remembered at each of thirty-three call sites.
+ */
+interface RepoAccess {
+    /** The repository root, canonical, and what this module's own walks compare against. */
+    root: string;
+    /**
+     * EVERY ABSOLUTE SPELLING OF THAT ROOT, canonical first.
+     *
+     * A ROOT HAS TWO SPELLINGS ON ANY MACHINE WHERE A TEMP PATH IS A SYMLINK, which is every macOS
+     * one: `/var/folders/...` and `/private/var/folders/...` are the same directory, and this module
+     * meets both in one call. The walk in `detectPackageManagerContext` compares CANONICAL paths, so
+     * the root has to be canonical; every caller builds its absolute paths by joining onto the
+     * `repoDir` it was HANDED, which is whichever spelling that caller had. A single root would turn
+     * one of those two into "outside the repository", and the answer would be a repository with no
+     * `package.json` in it - which is what it was, for the whole of `detect.test.ts`, before this
+     * field existed.
+     *
+     * The same trap `packages/aster/src/roots.ts` records one engine over, where a single-string root
+     * matched nothing and every line map came back empty with no error anywhere.
+     */
+    roots: readonly string[];
+    reader: RepoReader;
+    /**
+     * The canonical absolute form of a path, as this road can see it.
+     *
+     * ON DISK THIS IS `realpathSync` AND IT IS LOAD-BEARING: `detectPackageManagerContext` walks from
+     * the measured package up to the repository root by comparing paths, and on macOS `/tmp` is a
+     * symlink to `/private/tmp`, so a root taken one way and a working directory taken the other
+     * never meet. Over a reader with no disk there are no links, so it is `resolve`.
+     */
+    realpath(path: string): string;
+}
+/** The access `abloh init` and every existing caller get: a checkout on this machine. */
+declare function diskRepoAccess(repoDir: string): RepoAccess;
+/**
+ * The repository-relative path an absolute one names, or null when it names nothing in here.
+ *
+ * `relative` first and `normalizeRepoPath` second: the first turns an absolute path into a
+ * repository-relative one, the second refuses the `..` that says it left. Both are needed - a bare
+ * `relative` answers `../x` cheerfully, and the reader would then refuse it silently, which is the
+ * same outcome by luck rather than by rule.
+ */
+declare function repoPath(ctx: RepoAccess, absolute: string): string | null;
+/** Is there anything at all here - a file or a directory? */
+declare function accessExists(ctx: RepoAccess, absolute: string): boolean;
+/** One file's UTF-8 text, or null when it is not there or is not a plain file. */
+declare function accessText(ctx: RepoAccess, absolute: string): string | null;
+/**
+ * ONE PACKAGE MANIFEST, THROUGH THE ONE READER (`@abloh/core`'s `package-manifest.ts`).
+ *
+ * EVERY MANIFEST THIS PACKAGE READS COMES THROUGH HERE, because the thirty-odd sites that each
+ * held their own `JSON.parse` disagreed about a file npm reads without complaint - a leading
+ * byte-order mark - and the reader that happened to meet it decided whether a repository could be
+ * onboarded at all. The refusal it composes names the file, which is what the caller then either
+ * raises or records beside the one directory it is dropping.
+ *
+ * THE PATH IT NAMES IS THE REPOSITORY-RELATIVE ONE, never the absolute one this module speaks
+ * internally: a sentence a maintainer reads has to name a file in their own repository, and an
+ * absolute path names a directory on whichever machine ran the draft.
+ */
+declare function accessManifest(ctx: RepoAccess, absolute: string): PackageManifestReading;
+/** What is at this path, with a symlink kept apart from an absence. See `RepoReader.entryKind`. */
+declare function accessKind(ctx: RepoAccess, absolute: string): "file" | "directory" | "other" | "absent";
+/** Immediate child directory NAMES of a path, or none when it is absent or unreadable. */
+declare function accessSubdirectories(ctx: RepoAccess, absolute: string): string[];
+
+/**
+ * WHICH REPOSITORIES ACTUALLY HAVE A BROWSER LANE, read from what they committed rather than from
+ * what they called a script.
+ *
+ * THE MEASUREMENT THAT PUT THIS FILE HERE. Round 5's wall census (`wall-census.md`, mechanism M17)
+ * reported "the repository's CI has a browser lane abloh does not measure" on three repositories -
+ * `kaitranntt/ccs`, `storybookjs/storybook`, `vitejs/vite`. Reading all three workflows and
+ * manifests, the sentence was right about two of them and wrong about one, and it described the
+ * wrong thing on the two it was right about:
+ *
+ *   | repository | what M17 quoted                              | what is actually there            |
+ *   |------------|----------------------------------------------|-----------------------------------|
+ *   | ccs        | `bun run test:e2e`                           | `bun test tests/e2e/` - a CLI     |
+ *   |            |                                              | suite. No browser anywhere: no    |
+ *   |            |                                              | playwright, no cypress, no        |
+ *   |            |                                              | @vitest/browser in any manifest.  |
+ *   | storybook  | `yarn exec playwright install chromium`       | an INSTALL step. The lane is      |
+ *   |            |                                              | `vitest run`, whose project list  |
+ *   |            |                                              | includes a browser-mode project.  |
+ *   | vite       | `pnpm playwright install chromium`           | an INSTALL step. The lanes are    |
+ *   |            |                                              | `vitest run -c vitest.config.e2e` |
+ *   |            |                                              | driving playwright as a library.  |
+ *
+ * TWO SEPARATE DEFECTS, and this file exists to remove both. `ccs` was matched by SCRIPT NAME -
+ * `ci-recipe.ts`'s `BROWSER_SCRIPT_NAMES` reads `test:e2e` and concludes browser - which is exactly
+ * the failure mode `docs/lessons/verifying-rules.md` records: a rule written from assumption,
+ * running in bulk, never checked against the data. And on the other two the quoted command is the
+ * step that INSTALLS a browser, which is a fact about the setup phase and not a lane at all.
+ *
+ * SO NOTHING HERE READS A NAME. Every kind below requires a DECLARATION - a dependency in a
+ * manifest, a `browser` block in a vitest config, a runner binary in an argv - and where the
+ * evidence is absent this module returns null and the caller says nothing. That is the safe
+ * direction on both sides: a repository with no browser is never told it has one, and a repository
+ * with a browser abloh cannot yet measure gets a refusal that names its lane rather than a heads-up
+ * that names a script.
+ */
+
+/**
+ * The kinds of browser lane, closed, and each is a different thing to build.
+ *
+ * `vitest-browser` and `playwright-test` are the two phase-1 kinds: in both, a runner abloh already
+ * drives launches the browser through an interface abloh can point at a browser it placed. The other
+ * two are named rather than lumped under "unsupported", because a refusal that names the lane is
+ * what tells a customer whether to wait or to declare a different test command.
+ */
+type BrowserLaneKind = 
+/** `@vitest/browser` with a playwright provider: vitest starts the server and drives the page. */
+"vitest-browser"
+/** The Playwright Test runner itself - `playwright test`. */
+ | "playwright-test"
+/** A node-mode suite that imports playwright or puppeteer and drives a browser in its own code. */
+ | "playwright-library"
+/** Cypress, which brings its own runner, its own server contract and its own binary cache. */
+ | "cypress";
+/** What was read to reach a verdict, by path, so a customer can go and look at the same line. */
+interface BrowserLaneEvidence {
+    /** Repository-relative path of the file the fact was read from. */
+    readonly file: string;
+    /** The fact itself, in the file's own vocabulary. */
+    readonly fact: string;
+}
+interface BrowserLane {
+    readonly kind: BrowserLaneKind;
+    /**
+     * Can abloh measure this lane today?
+     *
+     * A FIELD RATHER THAN A LOOKUP AT EVERY CALL SITE, because "which kinds ship" is the thing that
+     * changes when the next phase lands, and a `kind === "vitest-browser"` written in four places is
+     * four places to forget.
+     */
+    readonly measurable: boolean;
+    /** Every fact behind the verdict. Never empty - a kind with no evidence is not returned at all. */
+    readonly evidence: readonly BrowserLaneEvidence[];
+}
+/**
+ * IS THIS COMMAND A BROWSER INSTALL rather than a browser lane, and the distinction M17 collapsed.
+ *
+ * `pnpm playwright install chromium` places a binary. It runs in the phase that HAS a network, it
+ * runs once, and it measures nothing. Reading it as "a browser lane abloh does not measure" is what
+ * produced the census sentence on `storybook` and `vite`, both of whose actual lanes are ordinary
+ * vitest invocations. Told apart here so the caller can do the right thing with each: an install
+ * step belongs in the setup phase, a lane belongs in the measurement.
+ */
+declare function isBrowserInstallCommand(command: string): boolean;
+/**
+ * WHAT KIND OF BROWSER LANE THIS REPOSITORY HAS, or null when it has none.
+ *
+ * ORDER IS SIGNIFICANT and it is specificity order, exactly as `admission-remedy.ts` orders its
+ * rules. A repository with `@vitest/browser` also has `playwright` in its tree, because that is what
+ * the provider drives; reading the weaker fact first would file `storybookjs/storybook` as a
+ * playwright-library lane and refuse a lane abloh can measure.
+ *
+ * THE MANIFEST IS NECESSARY AND, FOR THE VITEST KIND, NOT SUFFICIENT. `@vitest/browser` in a
+ * manifest with no config enabling it is a dependency somebody added and did not switch on, which is
+ * true of any repository mid-migration. Both facts are required and both are returned as evidence.
+ */
+declare function readBrowserLane(repoDir: string, ctx?: RepoAccess): BrowserLane | null;
+
+/**
+ * THE ENVIRONMENT ONE WORKFLOW STEP RUNS IN, RESOLVED THE WAY GITHUB RESOLVES IT.
+ *
+ * WHY THIS EXISTS (the 2026-09-11 detection audit, findings E1, E2, E3 and S1). The CI reader used
+ * to collect a job's `env:` and the `env:` of a few step kinds into ONE array and let the last push
+ * win. Four separate defects came out of that one shape, and every one of them was measured on a
+ * real repository:
+ *
+ *   - The WORKFLOW's own `env:` was never read at all. `cheeriojs/cheerio`'s `FORCE_COLOR`,
+ *     `sveltejs/svelte`'s `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD`, `swagger-api/swagger-ui`'s
+ *     `CYPRESS_CACHE_FOLDER` and `TanStack/query`'s `NX_CLOUD_ACCESS_TOKEN` each sit at workflow
+ *     level, which GitHub applies to every job as a default, and abloh read none of them.
+ *   - INSTALL, BUILD and TEST were one list, so a value declared for one execution silently
+ *     replaced the value declared for another. `babel/babel` declares `BABEL_ENV: test` on the step
+ *     that runs its suite and `BABEL_ENV: test-legacy` on the step that builds its artifacts in a
+ *     different job; the artifacts job was read second and `test-legacy` became the value abloh gave
+ *     the SUITE. `babel.config.ts` selects different compilation for the two.
+ *   - A step that re-declared a name the job had already set did not replace it when the step's own
+ *     value was an expression: the job's stale literal stayed, and the question that would have
+ *     asked about the expression was suppressed by it.
+ *   - Every `${{ … }}` was "computed, nothing to write", including a direct read of a matrix value
+ *     the maintainer had ALREADY answered. `prettier/prettier` and `Fission-AI/OpenSpec` were asked
+ *     again for values their own answers settle.
+ *
+ * WHAT THIS MODULE IS. Two functions and no reader of its own. {@link layerEnvironment} applies
+ * GitHub's scope rule to a list of `env:` mappings, and {@link readWorkflowExpressions} resolves the
+ * handful of expression forms whose answer is already in hand. Nothing here opens a file, runs a
+ * command or evaluates an expression grammar - see {@link readWorkflowExpressions} for exactly which
+ * forms are answered and why the rest stay unanswered on purpose.
+ *
+ * IMPORT-FREE BUT FOR THE MATRIX VOCABULARY, so the CI reader, the runtime reading and any later
+ * caller all resolve one reference the same way rather than each spelling a regular expression.
+ */
+
+/**
+ * HOW NARROW ONE `env:` MAPPING IS, which is the whole of GitHub's precedence rule.
+ *
+ * The workflow's block is a default for every job, a job's block is a default for every step of that
+ * job, and a step's block applies to that step. Later overrides earlier, per NAME.
+ * See https://docs.github.com/en/actions/reference/workflows-and-actions/contexts#env-context.
+ */
+type WorkflowEnvironmentLevel = "workflow" | "job" | "step";
+/** One `env:` mapping, as `NAME -> raw workflow text`, with how narrow it is. */
+interface WorkflowEnvironmentScope {
+    level: WorkflowEnvironmentLevel;
+    entries: ReadonlyArray<{
+        name: string;
+        text: string;
+    }>;
+}
+/** One name's effective declaration: the narrowest mapping that set it, whole. */
+interface WorkflowEnvironmentEntry {
+    name: string;
+    /** The workflow's own text, unclassified and unresolved. */
+    text: string;
+    /** Which mapping this text came from. */
+    level: WorkflowEnvironmentLevel;
+}
+/**
+ * THE EFFECTIVE ENVIRONMENT FOR ONE EXECUTION, from the mappings that apply to it.
+ *
+ * A LATER SCOPE REPLACES AN EARLIER ONE WHOLE, and "whole" is the load-bearing word. The defect this
+ * replaces kept the earlier entry whenever the later one was something it could not turn into a
+ * literal, so a job's `APP_MODE: test` survived a step's `APP_MODE: ${{ matrix.mode }}` and was
+ * offered as this step's value. A workflow that re-declares a name has said the earlier value does
+ * not apply here, whatever the new one turns out to be; classification happens after this and never
+ * decides which declaration is in force.
+ *
+ * Order is the order the caller passes, so a caller that hands them narrowest-first gets the
+ * narrowest-loses answer, which is not GitHub's. The one caller hands them widest-first.
+ */
+declare function layerEnvironment(scopes: readonly WorkflowEnvironmentScope[]): WorkflowEnvironmentEntry[];
+/**
+ * The facts a reference can be resolved AGAINST, all of them already established elsewhere.
+ *
+ * Every field is optional and an absent field resolves nothing: this module never derives an answer,
+ * it only substitutes one somebody else already has.
+ */
+interface WorkflowExpressionFacts {
+    /**
+     * The matrix leg this derivation is for, when the maintainer answered one.
+     *
+     * A dimension the leg does not name stays unresolved. That is the same restraint
+     * `resolveNodeMajor` already applies: an unanswered matrix is an honest question, and guessing a
+     * cell would describe a different execution from the one abloh's step runs on.
+     */
+    matrix?: MatrixLeg | null;
+    /**
+     * Literal values already resolved from WIDER scopes, for `${{ env.NAME }}`.
+     *
+     * Wider only. A step's own mapping is not visible to itself here, so a self-reference stays
+     * unresolved rather than reading whichever entry happened to be processed first.
+     */
+    env?: ReadonlyMap<string, string> | undefined;
+    /**
+     * Where a run reaches each declared service, for `${{ job.services.<name>.ports[<n>] }}`.
+     *
+     * A workflow that stands up two of one database reads its own ports back this way, because GitHub
+     * gives each service a port of its own and only the run knows which. `backstage/backstage` builds
+     * all four of its database connection strings out of these references, and reading none of them
+     * left a job whose whole purpose is those databases with no address for any of them. Abloh assigns
+     * the ports itself (`service-ports.ts`) and states them in `abloh.yml`, so this is a reference to a
+     * value the drafting already settled rather than a prediction about a run.
+     */
+    servicePorts?: ReadonlyMap<string, number> | undefined;
+}
+/** What one workflow value says once every answerable reference in it has been substituted. */
+interface WorkflowExpressionReading {
+    /** The value with every answerable reference replaced. Equal to the input when none was. */
+    text: string;
+    /** Does this value read something out of the caller's secret store? */
+    hasSecret: boolean;
+    /** Every reference left unanswered, verbatim and in order. */
+    unresolved: readonly string[];
+}
+/** Does this value read the caller's secret store anywhere in it? */
+declare function referencesSecret(text: string): boolean;
+/** Does this value carry any workflow reference at all? */
+declare function referencesExpression(text: string): boolean;
+/**
+ * SUBSTITUTE THE REFERENCES WHOSE ANSWER IS ALREADY IN HAND, AND NOTHING ELSE.
+ *
+ * THREE FORMS ARE ANSWERED and the choice of those three is the whole design. Each one reads a fact
+ * that is settled before this derivation runs, so substituting it states what the maintainer already
+ * said rather than predicting a run:
+ *
+ *   - `matrix.<dimension>` against the leg the maintainer answered. `prettier/prettier` answers
+ *     `ENABLE_CODE_COVERAGE=true` and `FULL_TEST=true`; `Fission-AI/OpenSpec` answers
+ *     `vitest_workers=4`. Continuing to describe those as values abloh cannot know is the defect.
+ *   - `env.<NAME>` against a literal a wider scope already set. `swagger-api/swagger-ui` reads its
+ *     own `CYPRESS_CACHE_FOLDER` back in a cache path.
+ *   - A secret reference is not substituted - it is REPORTED. Nothing here ever copies a value out
+ *     of somebody's secret store into a file abloh writes.
+ *
+ * EVERYTHING ELSE STAYS UNANSWERED, and that is deliberate rather than unfinished. `github.sha`,
+ * `runner.os`, `steps.x.outputs.y`, `hashFiles(...)`, `a && b || c` - each is decided by the run
+ * itself, so there is no literal for a committed file and the honest product is a question naming
+ * the reference. This module is a lookup, never an expression grammar: what it cannot look up it
+ * hands back whole so the caller can say so in the workflow's own words.
+ *
+ * A value is resolved only when EVERY reference in it is. One unanswered reference in a connection
+ * string makes the whole string unanswered, because half a value is not a value.
+ */
+declare function readWorkflowExpressions(text: string, facts?: WorkflowExpressionFacts): WorkflowExpressionReading;
+
+/** One derived setup command, with the workflow job it was read out of for its receipt. */
+interface CiSetupCommand {
+    /** The command exactly as the workflow declares it, normalized to one line. */
+    command: string;
+    /** `.github/workflows/ci.yml::build` - what the receipt in `abloh.yml` names. */
+    source: string;
+    /**
+     * THE LITERAL VALUES CI GIVES THIS COMMAND, which are this command's and not the suite's.
+     *
+     * WHY IT IS HERE RATHER THAN POOLED INTO `environmentValues` (the 2026-09-11 detection audit, E2).
+     * `environment.environmentValues` reaches the measured suite and reaches no setup step: the cold
+     * lane runs each step from the ambient environment and the sealed image runs each step as its own
+     * `sh -c`. So a build's values pooled into that key arrive where the build is not and replace the
+     * suite's own values where the suite is. `babel/babel` is the measured case, in both directions
+     * at once: its suite was handed `BABEL_ENV=test-legacy` and its build was handed nothing.
+     *
+     * A SECRET IS NOT HERE. A name with no literal is declared under `environment.requiredVariables`
+     * and supplied from the caller's own environment, which every step already inherits.
+     */
+    env: ReadonlyArray<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * One OS package read out of an `apt-get install` line in the repository's own workflow.
+ *
+ * `version` is null when the workflow installed the package unpinned, which is what almost every
+ * workflow does - CI reinstalls from the archive on every run and does not care which build it gets.
+ * A recipe does care (`system-packages.ts`), so an unpinned entry is REPORTED and never written:
+ * see the notice in `derive` below, which names the package and the command that produces its pin.
+ */
+interface CiSystemPackage {
+    name: string;
+    version: string | null;
+    /** `.github/workflows/ci.yml::test` - what the receipt in `abloh.yml` names. */
+    source: string;
+}
+/**
+ * One literal, non-secret `NAME: value` pair read out of an `env:` block in the customer's workflow.
+ *
+ * WHAT MAKES IT LITERAL, and it is the whole of the test: the workflow wrote the value as text.
+ * `${{ secrets.X }}`, `${{ github.sha }}` and `$HOME` are not text - they are things the workflow
+ * runner evaluates - and none of them reaches this type. See {@link CiRequiredVariable} for the half
+ * that carries a NAME instead, and `config.ts` at `environmentValues` for why the two are separate
+ * keys rather than one key with two meanings.
+ */
+interface CiEnvironmentValue {
+    name: string;
+    value: string;
+    /** `.github/workflows/ci.yml::test` - what the receipt in `abloh.yml` names. */
+    source: string;
+}
+/**
+ * One environment-variable NAME the customer's workflow supplies from its secret store.
+ *
+ * NO VALUE TRAVELS WITH IT, ever, and that is the point of the split ruled on 2026-08-25. A
+ * `${{ secrets.DATABASE_URL }}` in a workflow is a name whose value lives in GitHub's secret store;
+ * `init` can read the name and must never invent the value, so what it writes is
+ * `environment.requiredVariables: [DATABASE_URL]` - the key whose value is injected at run time and
+ * masked out of every captured line (`secret-scrub.ts`). A literal that merely LOOKS like a
+ * credential lands here too, by shape rather than by name, because a value that is a secret does not
+ * become non-secret by having been committed to a workflow.
+ */
+interface CiRequiredVariable {
+    name: string;
+    source: string;
+    /** `secret` when the workflow named a secret; `credential-shape` when a literal looked like one. */
+    why: "secret" | "credential-shape";
+}
+/**
+ * One backing service the chosen job declares under its own `services:` block, WHOLE.
+ *
+ * THE DECLARATION IS THE SOURCE. Everything abloh needs to stand this service up is in the block
+ * the customer already wrote: the key names it, the image says what it is, `env:` says what
+ * credentials it starts with, `options:` says how to know it is ready, and `ports:` says which port
+ * it listens on. This reader used to take the image string and drop the other four, which is why
+ * abloh started a database with credentials that appeared in no file the customer had ever seen.
+ *
+ * THE TAG IS STILL MUTABLE AND STILL REFUSED downstream: `environment.services` takes a
+ * digest-pinned reference (`config.ts`: `immutableImageProblem`), so `init` resolves the tag the
+ * workflow named to the digest it points at today and writes that. What changed is that the digest
+ * comes from the registry rather than from a hand-reviewed table of two service kinds.
+ */
+interface CiService {
+    /** The workflow's own key for this service - `db`, `postgres`, `cache`. Becomes the alias. */
+    name: string;
+    /** The image reference exactly as declared, tag and all. `init` resolves it to a digest. */
+    image: string;
+    /** The declared `env:`, verbatim; these are the credentials the suite will connect with. */
+    env: ReadonlyArray<{
+        name: string;
+        value: string;
+    }>;
+    /** The `--health-cmd` the declared `options:` carries, or null when it declares none. */
+    healthCommand: string | null;
+    /** The container-side port the declared `ports:` names, or null when it names none. */
+    port: number | null;
+    /**
+     * WHERE A RUN REACHES THIS SERVICE, which is not always the port it listens on.
+     *
+     * Each service stands in a namespace of its own and a forwarder in the namespace the suite runs in
+     * carries this port to that one, so two services listening on 5432 both answer - on two different
+     * ports, which is what GitHub does by giving each its own port on the runner. `service-ports.ts`
+     * is the assignment and this is its answer for this service. Null exactly when {@link port} is.
+     */
+    localhostPort: number | null;
+    source: string;
+}
+/**
+ * A service the chosen job declares that abloh will not stand up, and the sentence saying why.
+ *
+ * NAMED, NOT SILENT, and the reason is the half that matters: "abloh has no preset for mysql" was
+ * a statement about abloh, and every one of these is a statement about the declaration, which is
+ * the thing the customer can change.
+ */
+interface CiUnsupportedService {
+    /** The workflow's own key, so the customer knows which block to open. */
+    name: string;
+    /** One sentence: what abloh could not use, and what would make it usable. */
+    reason: string;
+}
+/**
+ * WHAT THE CHOSEN JOB SAYS ITS NODE IS, VERBATIM, WITH THE SENTENCE THAT SAYS WHERE IT CAME FROM.
+ *
+ * IT USED TO BE A MAJOR AND THAT WAS THE DEFECT. This carried `major: number`, read off the leading
+ * digits of whatever the workflow wrote and clamped to the newest image abloh had reviewed, so
+ * `24.16.0` arrived as `24`, `26` arrived as `24`, and `lts/*` arrived as nothing at all. The
+ * reading is now the repository's own text and the CHOOSING happens once, in `node-declaration.ts`,
+ * where the publisher's release index and the repository's `engines.node` are both in hand.
+ *
+ * MORE THAN ONE, BECAUSE A MATRIX IS MORE THAN ONE. `[26, 22]` is two versions CI proves the suite
+ * green on and either is an honest answer, so both travel, strongest first, and the chooser takes
+ * the first its requirements admit.
+ */
+interface CiNodeVersion {
+    /** Every Node this job declares, strongest first, exactly as the workflow wrote it. */
+    specs: readonly string[];
+    evidence: string;
+}
+/**
+ * ONE EXECUTION A JOB DECLARES: what it runs, where it sits, and the environment it runs in.
+ *
+ * THE THREE FIELDS ARE THE THREE THINGS THE OLD READING LOST. A job used to reach `derive` as a
+ * list of build commands and one flat environment array, so an installation's value, a build's and
+ * the suite's were one dictionary whose last writer won, and a build could not say whether it ran
+ * before the suite or after it. Both cost real repositories a wrong answer:
+ *
+ *   - `babel/babel`'s suite was given its build job's `BABEL_ENV`, which selects a different
+ *     compilation from the one the suite's own step declares.
+ *   - `pmndrs/valtio` and `pmndrs/zustand` each run `pnpm run build` AFTER their suite, with a
+ *     comment saying the step exists to test the build, and each was given that build as
+ *     preparation to run BEFORE the suite.
+ */
+interface CiJobStep {
+    /**
+     * What abloh made of the command.
+     *
+     * `unclassified` is a step abloh declined to translate that declares an `env:` block of its own.
+     * It is carried for that block and for nothing else - it never becomes preparation and it is
+     * never read as the suite. `backstage/backstage` is why it exists: its whole job is built around
+     * `yarn backstage-cli repo test`, which names no runner this module knows, and the four database
+     * connection values that job exists for sit on that one step and reached nothing at all.
+     */
+    kind: "install" | "build" | "test" | "unclassified";
+    /** The command, exactly as the workflow declares it, normalized to one line. */
+    command: string;
+    /** The job-level `steps:` index this command belongs to, or null for a format with no list. */
+    index: number | null;
+    /**
+     * Had a step of this job already run the suite when this one was reached?
+     *
+     * WHAT IT DECIDES. Preparation is what runs BEFORE the suite; a build after it is the job moving
+     * on to check something else, and moving that build in front of the suite runs work the suite
+     * never needed against a tree it was not measured in. The reading is the classifier's own and
+     * never a step's name - the same rule {@link Candidate.lastTestStepIndex} is closed by.
+     */
+    afterTests: boolean;
+    /**
+     * Had this job finished running its suite and moved on to something else before this step?
+     *
+     * NOT THE SAME QUESTION AS {@link afterTests}, and `swagger-api/swagger-ui` is the shape that
+     * separates them: it runs `npm run test:unit`, then `npm run build`, then `npm run test:artifact`,
+     * and the third is a check ON the build rather than more of the suite. The suite's own environment
+     * is the first step's; the third step declares none and reading it as the suite dropped the
+     * `CI: true` the suite really runs with. This is `lastTestStepIndex`'s own closing rule, recorded
+     * per step so every reader takes the same answer.
+     */
+    afterSuite: boolean;
+    /**
+     * THE EFFECTIVE ENVIRONMENT FOR THIS COMMAND: the workflow's `env:`, then the job's, then this
+     * step's own, later replacing earlier per name.
+     *
+     * Raw workflow text. `derive` classifies it into the literal half and the injected half, and it
+     * does that once per execution rather than once per job.
+     */
+    env: readonly WorkflowEnvironmentEntry[];
+}
+/**
+ * ONE STEP OF THE CUSTOMER'S OWN JOB THAT RUNS THEIR SUITE.
+ *
+ * READ, NEVER ANSWERED. See {@link CiBorrowJob.testSteps}: everything here is a fact out of the
+ * file, and whether this step runs is a question about the leg abloh pins.
+ */
+interface CiJobTestStep {
+    /** Where the `jobs.<id>.steps` entry this step came out of sits, counting from zero. */
+    index: number;
+    /** That entry's own `name:`, or null. What a maintainer sees on their checks page. */
+    name: string | null;
+    /** Every `if:` gating it, outermost first. See {@link Step.conditions}. */
+    conditions: readonly string[];
+}
+/**
+ * ONE JOB IN THE CUSTOMER'S OWN CI, AS THE BORROW LANE NEEDS IT.
+ *
+ * Every field is a fact read out of their workflow, and none of them is a decision: which file,
+ * which job id inside it, what that job does, and whether it fans out. The decision - is this job
+ * the one to append a step to - belongs to `setup-job.ts`, which reads these.
+ */
+interface CiBorrowJob {
+    /** Repo-relative path of the workflow file, `.github/workflows/ci.yml`. */
+    file: string;
+    /** The key under `jobs:`, which is what a `steps:` list hangs off. */
+    jobId: string;
+    /** The job's own `name:`, or null. What a maintainer sees on their checks page. */
+    jobName: string | null;
+    /** Does this job install this package's dependencies? */
+    installs: boolean;
+    /** Does it run a build step abloh could read? */
+    builds: boolean;
+    /** Does it run a suite abloh recognized? */
+    tests: boolean;
+    /**
+     * WHERE THE STEP THAT RUNS THE SUITE SITS IN `jobs.<id>.steps`, or null when no step does.
+     *
+     * WHAT IT IS FOR, AND WHY IT IS THE READER'S ANSWER RATHER THAN THE PLACER'S (the fresh-ten
+     * launch-evidence run, 2026-08-31, bug 6). Abloh's step used to be appended to the END of the
+     * job. `swagger-api/swagger-ui` runs `Install dependencies` -> `Lint` -> `Run all tests` ->
+     * `Build SwaggerUI` -> `Test build artifacts`, and its build writes into `dist/`, which that
+     * repository TRACKS. So the placement guaranteed the condition the preflight refuses, and it
+     * refused on both cycles: Abloh stood after a build and then objected to the build's output.
+     *
+     * THE RULE IS "BEHIND THEIR TEST STEP" AND IT NEEDS NO CLASSIFIER OF ITS OWN. Everything the
+     * suite needed has already happened by the time the suite has run - a step cannot depend on one
+     * that runs after it - so the tree at that point is exactly the tree their suite ran in, which is
+     * the tree Abloh is there to measure. Everything after it is by definition not needed to run the
+     * suite. It is NOT a scan for build-sounding step names: the same run put Abloh on `prettier`'s
+     * LINT job by ranking names, and that mistake is not repeated one layer down.
+     *
+     * THE LAST SUITE STEP WHILE THE JOB IS STILL RUNNING ITS SUITE. A job that shards its suite over
+     * two steps has not finished running it until the second has run. A job that BUILDS after its
+     * suite has run has moved on to work the suite did not need, and swagger-ui is exactly that shape
+     * - `Run all tests`, `Build SwaggerUI`, `Test build artifacts` - so the third step is not an
+     * anchor: standing behind it is standing behind the build. See `suiteClosed` in `readJob`.
+     *
+     * NULL MEANS "APPEND AT THE END", which is the old behaviour and the only honest answer for a job
+     * whose suite Abloh could not locate - a declared `setup.job` may name a job that runs no suite
+     * Abloh recognized, and that declaration outranks this reading.
+     */
+    lastTestStepIndex: number | null;
+    /**
+     * EVERY SUITE STEP OF THIS JOB, in file order, each with the `if:` chain that decides whether it
+     * runs.
+     *
+     * WHY THE LIST AND NOT JUST {@link lastTestStepIndex} (census run 4, `prettier/prettier`, F8; run
+     * 33613921638). `prettier`'s test job declares TWO suite steps and an `include:` leg decides which
+     * of them runs - `Run Tests` on `if: ${{ !matrix.ENABLE_CODE_COVERAGE }}` and `Run Tests
+     * (coverage)` on `if: ${{ matrix.ENABLE_CODE_COVERAGE }}`. Abloh pinned its step to the leg
+     * carrying that boolean and anchored on the first suite step, which is the one that leg SKIPS, so
+     * it stood between the two and measured a tree whose suite the maintainer's job had not run.
+     * `lastTestStepIndex` cannot express that: it is one index, decided before any leg is known.
+     *
+     * THE `if:` IS CARRIED AND NOT ANSWERED HERE, exactly as {@link Candidate.gateIf} is. Which of
+     * these runs is a question about the LEG, and the leg is settled a layer up in `setup-job.ts`;
+     * this reader states what the file says and `setupStepAnchor` answers it.
+     */
+    testSteps: readonly CiJobTestStep[];
+    /**
+     * The matrix dimensions this job fans out over, `[]` when it is one job.
+     *
+     * NAMES ONLY, NEVER THE LEGS. What a caller has to decide is whether "this job" is one build or
+     * twelve, and the dimension names are what say so; enumerating the legs would invite a caller to
+     * pick one, and picking one is the silent guess the "needs your edit" state exists to refuse.
+     */
+    matrixDimensions: readonly string[];
+    /**
+     * THE JOB DECLARES A MATRIX THIS READER COULD NOT READ AT ALL, so `[]` above is not "one build".
+     *
+     * See `SetupCandidateJob.matrixUnreadable` in `@abloh/core`, which carries the whole account: a
+     * `matrix: ${{ fromJSON(...) }}` has no dimension name in the file, so there is no leg to ask for
+     * and `setupCandidateExclusion` refuses the job by name rather than letting an unconditional step
+     * be appended to a job that fans out.
+     */
+    matrixUnreadable: boolean;
+    /**
+     * THE LEGS EACH DIMENSION OFFERS, so a maintainer can be told which answers exist.
+     *
+     * WHY THIS EXISTS AND WHY IT IS NOT A CONTRADICTION OF {@link matrixDimensions} (borrow-coverage
+     * audit, 2026-08-30). The dimension names alone were the right answer for as long as there was no
+     * key to name a leg in: enumerating the legs would have invited a caller to pick one, and picking
+     * one silently is the guess the "needs your edit" state refuses. `setup.matrixLeg` changes what
+     * the enumeration is FOR. The refusal now asks the maintainer for a leg, and a question that lists
+     * no possible answers is a question they have to go and read their own workflow to answer.
+     *
+     * ABLOH STILL PICKS NOTHING. The list is printed and no entry is proposed, exactly as the refusal
+     * proposes no `setup.job` for a tie.
+     *
+     * A DIMENSION WHOSE VALUES CANNOT BE READ MAPS TO AN EMPTY LIST - an expression, a list of
+     * objects, a `fromJSON` - and empty means "abloh could not enumerate this", never "there are
+     * none". A declaration is admitted against an unreadable dimension for that reason.
+     */
+    matrixLegs: MatrixLegs;
+    /**
+     * EVERY LEG THIS JOB ACTUALLY RUNS, spelled out, or null when abloh could not enumerate them all.
+     *
+     * WHY A SECOND SHAPE BESIDE {@link matrixLegs} (desk check of the fresh ten, 2026-08-31).
+     * `matrixLegs` answers "which values may I write for this dimension" and it is a list PER
+     * DIMENSION, so the answers it offers are the cross product of those lists. GitHub's matrix is not
+     * always a cross product: an `include:` entry adds one leg with its own values, and
+     * `sveltejs/svelte` writes its whole matrix that way - five legs over `node-version` and `os` that
+     * no product of two lists describes. Offering the cross product alone would offer legs the
+     * workflow does not have, and `docs/lessons/a-remedy-is-a-promise.md` is the whole argument
+     * against a remedy nobody checked.
+     *
+     * NULL IS "NOTHING WAS READ" AND NEVER "NO LEGS", on the same rule as {@link runsOn}. A dimension
+     * written as `${{ fromJSON(...) }}`, legs that are objects rather than scalars, or a fan-out wider
+     * than {@link MAX_MATRIX_COMBINATIONS} all answer null, and every consumer treats that as the
+     * behaviour it had before this field existed.
+     */
+    matrixCombinations: readonly MatrixLeg[] | null;
+    /**
+     * WHAT `strategy.fail-fast` SAYS ABOUT THIS JOB.
+     *
+     * IT IS NOT A REASON TO REFUSE THE JOB and it is read for exactly one thing: whether a leg going
+     * red cancels the leg abloh's step is riding. `packages/core/src/setup-fail-fast.ts` holds the
+     * whole rule, the copy and the run that measured what it costs.
+     *
+     * `default` IS AN ANSWER, NOT AN ABSENCE. A job that declares no `fail-fast` is a job whose legs
+     * cancel each other, because that is GitHub's default - which is the whole of finding F4.
+     */
+    failFast: FailFastReading;
+    /** The job's own `runs-on:` label, or null where it declares one abloh cannot read. */
+    runsOn: string | null;
+    /**
+     * THE `runs-on:` EXPRESSION, VERBATIM, when the job writes one instead of a label.
+     *
+     * WHAT IT IS FOR. `runs-on: ${{ matrix.os }}` is the shape every matrix over operating systems
+     * writes, and `runsOn` is correctly null for it - nothing in the file says which runner the job
+     * gets. A PINNED LEG says it: with `os: ubuntu-latest` declared, that expression has one value,
+     * and `setupRunnerExclusion` can then answer the question it otherwise had to stay silent on. That
+     * matters in exactly the direction safety runs: `electron/asar`'s first leg is macOS, which has no
+     * Docker daemon, and admitting a leg without resolving the runner would put the step there.
+     *
+     * NULL WHEN THE FILE NAMES A LABEL, which is what `runsOn` already carries.
+     */
+    runsOnExpression: string | null;
+    /**
+     * The `pull_request:` block of the workflow this job lives in, verbatim.
+     *
+     * NULL FOR A FORMAT THAT HAS NO SUCH BLOCK - `.travis.yml` and `.circleci/config.yml` are read on
+     * identical terms here and declare their triggers somewhere this reader does not go - AND FOR A
+     * GITHUB WORKFLOW THAT DECLARES NO `pull_request` TRIGGER AT ALL.
+     *
+     * THAT SECOND CASE IS WHY {@link triggers} EXISTS (census run 7, F2). This doc used to say a
+     * GitHub workflow "always carries one, empty lists and all", so a null told `setupCandidateExclusion`
+     * that nothing had been read. It does not: `on: workflow_call` answers null here, and the
+     * exclusion then admitted a workflow GitHub does not start on a pull request as though it were a
+     * workflow with no filter. Ask {@link triggers} for what the file declares; this field stays what
+     * it always was, the filters on a `pull_request` trigger that IS declared.
+     */
+    trigger: SetupCandidateTrigger | null;
+    /**
+     * The `on:` keys of the workflow this job lives in, verbatim, or null for a non-GitHub format.
+     *
+     * The three questions this repository asks of them - is the workflow callable, does it start on a
+     * pull request, is its `pull_request` trigger narrowed - are all `setupCandidateExclusion`'s, in
+     * `@abloh/core`, where the rest of that policy is. Nothing is judged here.
+     */
+    triggers: readonly string[] | null;
+    /**
+     * Every job in this repository whose `uses:` names the workflow this job lives in, or null for a
+     * non-GitHub format.
+     *
+     * Read verbatim, with each caller's own `on:` keys and `pull_request:` block beside it. Which of
+     * them GitHub starts on a pull request, and whether abloh's publish job may go there, is
+     * `setupPublishHost`'s judgement in `@abloh/core`. Nothing is judged here.
+     */
+    callers: readonly SetupWorkflowCaller[] | null;
+    /** Every `if:` between a pull request and this job running: its own, then its `needs:` chain's. */
+    gates: readonly SetupCandidateGate[];
+    /** The ranking score, so a caller can see a clear winner and a tie for what they are. */
+    score: number;
+}
+/**
+ * A JOB THAT CALLS A WORKFLOW ABLOH COULD NOT READ, so it was never a candidate for anything.
+ *
+ * WHY IT IS A FACT AND NOT A SENTENCE (captain's ruling, 2026-08-31). `stylelint/stylelint`'s
+ * `ci.yml` has five jobs and three are calls into `stylelint/.github`, a different repository. The
+ * one carrying its real jest matrix is `ci.yml::test`, and it was skipped with no record anywhere -
+ * so the reading walled on "no pull-request job runs a test command Abloh recognizes" while the job
+ * that runs the suite sat two lines above it in the same file. Disclosure alone is not the fix: the
+ * DECISION has to change when one of these looks like the suite, which means the decision layer
+ * needs the jobs rather than a paragraph about them.
+ */
+interface CiUnreadableJobCall {
+    /** `.github/workflows/ci.yml::test`, the spelling `setup.job` and every refusal use. */
+    job: string;
+    /** The `uses:` value, verbatim, because the refusal quotes the maintainer's own line. */
+    uses: string;
+    /** Why abloh could not read it, in the words the setup pull request prints. */
+    reason: string;
+    /**
+     * DOES ITS OWN NAME READ LIKE THE JOB THAT RUNS THE SUITE?
+     *
+     * A GUESS, AND SAID TO BE ONE. Nothing abloh can read says what a called workflow does, so the
+     * only evidence is the job's id and name - which is exactly the evidence `scoreCandidate` already
+     * ranks readable jobs on. It is asked with the SAME two lists, so "does this look like the front
+     * door" has one answer in this file rather than two.
+     */
+    looksLikeSuite: boolean;
+}
+/** The one command the chosen job runs its suite with, or the named reason there is not one. */
+interface CiTestCommand {
+    command: string;
+    /** `.github/workflows/ci.yml::test` - what the receipt in `abloh.yml` names. */
+    source: string;
+}
+/**
+ * What `init` gets back. A refusal is not an error: most repositories are refused, and the refusal
+ * is the product - it names the one thing a customer can declare by hand to get past it.
+ */
+/**
+ * WHAT `init` LEARNED ABOUT THIS REPOSITORY'S BROWSER LANE, and what it should write because of it.
+ *
+ * A PROJECTION OF `browser-lane.ts` PLUS THE ONE FACT ONLY THE CI WALK HAS: which step of the
+ * customer's own workflow installs the browser. Those are two different readings of two different
+ * files, and joining them here is what lets `init` write both halves of a working recipe - the
+ * declaration that puts a browser posture on the run, and the setup step that puts a browser in the
+ * image while the network is still up.
+ */
+interface CiBrowserLane {
+    /** Which framework drives the browser. See `BrowserLaneKind`. */
+    kind: BrowserLaneKind;
+    /** Can abloh measure this kind today? False kinds get a refusal from the registry, not a key. */
+    measurable: boolean;
+    /** What `environment.browser` should say, or null when the lane is one abloh does not measure. */
+    declaration: "chromium" | null;
+    /**
+     * The step in the customer's own CI that places the browser, verbatim, or null when their CI has
+     * none - a vitest browser-mode repository whose contributors run `playwright install` by hand has
+     * a real lane and no step to copy.
+     */
+    install: string | null;
+    /** Whether that step is one literal command the schema accepts, so `init` may write it as one. */
+    installIsLiteral: boolean;
+    /** Every file and fact behind the verdict, so a customer can go and read the same lines. */
+    evidence: readonly BrowserLaneEvidence[];
+}
+interface CiRecipe {
+    /** Empty whenever `refusal` is set, and often empty when it is not: plenty of CI has no build. */
+    setupCommands: readonly CiSetupCommand[];
+    /**
+     * THE LITERAL VALUES CI GIVES THE STEP THAT INSTALLS THIS PROJECT.
+     *
+     * The third of the three environments a job keeps apart, beside {@link CiSetupCommand.env} and
+     * {@link environmentValues}. The COMMAND abloh installs with is derived from the lockfile rather
+     * than from CI, so it is abloh's; what CI gives that step is the customer's, and it is rendered
+     * with the install step in the setup script because nothing else delivers a value there.
+     *
+     * A secret is not here. It is declared by name under {@link requiredVariables}, and the caller's
+     * own environment supplies it to every step.
+     */
+    installEnvironment: ReadonlyArray<{
+        name: string;
+        value: string;
+    }>;
+    /**
+     * The OS packages the chosen job's own `apt-get install` lines name, pinned ones and unpinned.
+     *
+     * WHY THE UNPINNED ONES ARE HERE AND NOT DROPPED. `init` writes only the pinned entries into
+     * `environment.systemPackages`, because the schema refuses an unpinned one and it is right to. But
+     * "your CI installs libcairo2-dev and Abloh wrote nothing" is precisely the sentence a customer
+     * needs to see, and it can only be said by something that read the name. So the list carries both
+     * and the caller decides: one becomes a key, the other becomes a notice naming the key.
+     */
+    systemPackages: readonly CiSystemPackage[];
+    /**
+     * THE PATHS THE CHOSEN JOB'S OWN CACHE STEPS NAME, exactly as the workflow spells them.
+     *
+     * NOT `generatedFiles` AND NOT A GUESS AT IT. What a cache step says is "this path is worth
+     * carrying between runs", which is TRUE of a dependency store, a compiler cache and a browser
+     * download as well as of something the run writes into the checkout - so this is the READING and
+     * the caller decides which of them is repository dirt, because that question needs a git this
+     * module does not touch.
+     *
+     * WHY IT IS READ AT ALL (census run 3, and the captain's note of 2026-09-01).
+     * `environment.generatedFiles` ABORTS a run when a prepared checkout ends dirty in a path nobody
+     * declared, and its only derivation is an OBSERVATION of the install - so on every `--no-prepare`
+     * init the key is empty and nothing would ever fill it. `swagger-ui/swagger-ui` was refused for
+     * exactly that: its run writes `cypress/`, and its own workflow names that directory in a step
+     * called "Cache Node Modules and Cypress binary". The file was already parsed.
+     */
+    cachedPaths: readonly string[];
+    /**
+     * The literal `NAME: value` pairs the chosen job sets, deduplicated by name, sorted.
+     *
+     * READ FROM THE JOB AND FROM ITS STEPS, because a workflow puts them in both places and a suite
+     * does not care which. A step-level value wins over a job-level one of the same name, which is
+     * what the workflow runner itself does.
+     */
+    environmentValues: readonly CiEnvironmentValue[];
+    /** Named values the chosen job computes, which need an answer rather than a guessed literal. */
+    unresolvedEnvironmentValues?: readonly {
+        name: string;
+        source: string;
+        reason: string;
+    }[];
+    /** Services read from the job that could not be carried into the proof environment. */
+    unresolvedServices?: readonly {
+        name: string;
+        source: string;
+        reason: string;
+    }[];
+    /** The names the chosen job supplies from secrets, or whose literal looked like a credential. */
+    requiredVariables: readonly CiRequiredVariable[];
+    /** The postgres and redis services the chosen job declares. At most one of each. */
+    services: readonly CiService[];
+    /** Null when CI declares no readable Node version; `init`'s own image selection then stands. */
+    node: CiNodeVersion | null;
+    /**
+     * The command the chosen job runs the suite with, or null when the job runs it more than one way
+     * and no single one is the front door.
+     *
+     * WHO USES IT, AND WHEN. `init` prefers its OWN detection wherever the repository declares a
+     * `scripts.test`, because that is the same declaration CI is usually invoking and because a config
+     * command that disagrees with detection demotes the runner to the generic adapter
+     * (`detect.ts: bindPreparedTestCommand`), costing diff coverage and per-test attribution. This one
+     * is used exactly where detection has nothing to read and would otherwise SYNTHESIZE a command -
+     * `socketio/socket.io`'s root manifest declares no scripts at all, detection guessed
+     * `npx --no-install mocha`, and that guess finds no test files in a root that has no test
+     * directory. A declaration from the repository's own CI beats a guess; it does not beat a
+     * declaration.
+     *
+     * IT DOES BEAT A DECLARATION THE PRODUCT HAS ALREADY REFUSED (konva, 2026-08-26). Where `init`'s
+     * own end-to-end door has diagnosed `scripts.test` as unrunnable in the sealed environment and
+     * found no unit stage inside it, that script is not a declaration Abloh can act on, and this one
+     * is taken instead. `init-cmd.ts` holds the condition.
+     */
+    testCommand: CiTestCommand | null;
+    /** `ci.yml::test`, `.travis.yml::script`, or null when nothing was chosen. */
+    job: string | null;
+    /**
+     * THE CHOSEN JOB AS FACTS RATHER THAN AS A STRING, for the borrow lane.
+     *
+     * WHY THIS IS HERE (Kenneth's onboarding-flip decision, 2026-08-28). `job` above is a receipt: it
+     * names, for a human reading `abloh.yml`, which of their files a derived line was read out of.
+     * The setup PR needs something different - it has to APPEND ONE STEP to that job, in that file,
+     * and it cannot do that from `"ci.yml::test"` without splitting a string somebody else composed
+     * and hoping the halves are a path and a job id. Two readings of one decision is exactly the
+     * shape `measurement-plan.ts` was written to end, one layer down.
+     *
+     * IT IS ALSO WHAT SAYS THE JOB IS BORROWABLE AT ALL. A job the step can ride has to install, and
+     * has to run the suite; `builds` is the third fact and is deliberately not required, because
+     * plenty of readable CI has no build step and borrowing its tree is still the right lane.
+     *
+     * NULL WHENEVER `job` IS NULL, and null on a non-GitHub file: `.travis.yml` and CircleCI declare
+     * suites abloh reads for their commands, and neither has a `jobs.<id>.steps` list to append a
+     * GitHub Action to. Those repositories take the fallback road, which is what it is for.
+     */
+    borrow: CiBorrowJob | null;
+    /**
+     * THE JOBS THAT SCORED WITHIN REACH OF THE CHOSEN ONE, and it is what makes ambiguity sayable.
+     *
+     * The design record's own caveat: "Job selection in large matrices (Storybook-scale CI) is the new
+     * hard sub-problem and gets its own 'needs your edit' state rather than a silent guess." A silent
+     * guess is what a single `job` field forces, because a caller holding one name cannot tell a clear
+     * winner from a coin toss. These are the rivals, in score order, so the caller can.
+     */
+    borrowRivals: readonly CiBorrowJob[];
+    /**
+     * EVERY JOB THE WALK READ IN THE TIER THAT ANSWERED, whether or not it scored.
+     *
+     * WHAT IT IS FOR, AND THE ONE THING IT IS NOT FOR (borrow-coverage audit, 2026-08-30). It is the
+     * list a `setup.job` DECLARATION resolves against, and nothing else reads it. Abloh's own choice
+     * still comes from {@link borrow} and {@link borrowRivals} - jobs that declare a suite this module
+     * recognized - because "which job is the front door" is a question the reading answers.
+     *
+     * A MAINTAINER ANSWERS A DIFFERENT QUESTION. They are not ranking; they are stating which job
+     * their verdict comes from, and a job whose suite runs through a repo-local binary or whose CI
+     * runs no suite at all is still a job that installs and builds - which is the whole of what the
+     * borrow lane needs from it. So the declaration resolves against everything read, and the facts
+     * that would stop the step working anyway - the runner, the trigger, the gates, the install - are
+     * checked in `setup-job.ts` exactly as they are for a job abloh picked itself.
+     *
+     * EMPTY WHEN THE WALK DERIVED NOTHING. A recipe that refused before it reached a job offers no
+     * list, which is the same answer it has always given a pin it could not resolve.
+     */
+    declarableJobs: readonly CiBorrowJob[];
+    /**
+     * THE RUNNER IMAGE THE CHOSEN JOB DECLARES, read from its own `runs-on:`.
+     *
+     * `runs-on: ubuntu-24.04` is not a preference. It names a documented, versioned image
+     * (`actions/runner-images`) whose contents are published, so a repository that writes it has said
+     * - precisely, in a file abloh already reads - which distribution its CI's package names belong
+     * to. That is what this is FOR: the OS package names above were written in that distribution's
+     * vocabulary, and the proof image is Debian, and Ubuntu 24.04 renamed a large set of libraries at
+     * once for its 64-bit `time_t` transition. Without this, a workflow that installs `libasound2t64`
+     * hands the proof image a name apt cannot find.
+     *
+     * IT IS NOT LICENCE TO PREINSTALL THE RUNNER IMAGE. What the declaration is allowed to change is
+     * how a name is SPELLED, never how many names there are. Null for windows, macos and a
+     * self-hosted label, whose contents are private and therefore undeclared.
+     */
+    runnerImage: {
+        label: string;
+        vocabulary: NativeVocabulary;
+    } | null;
+    /**
+     * THE BROWSER LANE THIS REPOSITORY HAS, read from what it committed, or null when it has none.
+     *
+     * NULL IS THE ORDINARY ANSWER AND ALSO THE INTERESTING ONE. Until 2026-08-29 a browser step in a
+     * job produced one sentence for every repository - "a browser lane Abloh does not measure" - and
+     * round 5's wall census (M17) measured that sentence on three repositories, of which one has no
+     * browser anywhere: `kaitranntt/ccs`'s lane is `bun test tests/e2e/`, matched by the SCRIPT NAME
+     * `test:e2e` and by nothing else. `browser-lane.ts` reads manifests and configs instead, so a
+     * repository with no browser now gets null here and no sentence at all.
+     */
+    browserLane: CiBrowserLane | null;
+    /**
+     * THE JOBS ABLOH COULD NOT READ AT ALL, because they call a workflow rather than running steps.
+     *
+     * NOT A SUBSET OF ANYTHING ABOVE. A job with a `uses:` has no steps list, so it is not a
+     * candidate, not a rival and not declarable - it is simply absent from every other list here, and
+     * absent is what made `stylelint/stylelint` wall on a sentence about a job it never saw. Empty is
+     * the ordinary answer and it is a statement: this repository's jobs were all readable.
+     */
+    unreadableJobCalls: readonly CiUnreadableJobCall[];
+    /** One sentence naming why nothing was derived, or null when something was. */
+    refusal: string | null;
+    /**
+     * Things a customer should know that did NOT stop the derivation - a build whose CI step also
+     * sets environment values Abloh has no key for, a build scoped to one workspace package.
+     */
+    notices: readonly string[];
+}
+type AptReading = {
+    ok: true;
+    packages: Array<{
+        name: string;
+        version: string | null;
+    }>;
+} | {
+    ok: false;
+    why: string;
+} | null;
+/**
+ * READ AN apt STEP, OR SAY IT IS NOT ONE.
+ *
+ * Returns null when the step is not of this class, so the caller falls through to the ordinary
+ * system-command refusal unchanged. Returns a refusal when it IS an apt step this module will not
+ * translate, because "this looked like your system dependencies and I would not read it" is worth
+ * saying - it is the sentence that tells a customer to write `environment.systemPackages` by hand.
+ */
+declare function readAptStep(command: string): AptReading;
+/**
+ * The repo-defined build class: `make -j build-standalone-ci`, `just build`, `./scripts/build.sh`.
+ *
+ * Returns null when the command is not of this class at all, so the caller falls through to the
+ * package-manager rules. Returns a refusal when it IS of this class and fails one of the
+ * constraints, because "this looked like your build and I would not run it" is worth saying.
+ */
+declare function classifyRepoDefinedBuild(command: string, reader: RepoReader): {
+    ok: true;
+    why?: undefined;
+} | {
+    ok: false;
+    why: string;
+} | null;
+/** The three `env:` blocks that can supply a `node-version:` expression, innermost last. */
+interface NodeEnvironment {
+    workflow: Record<string, string>;
+    job: Record<string, string>;
+    step: Record<string, string>;
+}
+/**
+ * WHAT THE JOB DECLARES, AS IT DECLARES IT.
+ *
+ * NO CLAMP AND NO MAJOR. This returned `{ major }` and cut every version above the newest reviewed
+ * image down to it, which made `prettier/prettier`'s `26` into `24` under a receipt calling it
+ * CI's own Node, and it read `24.16.0` as `24`, discarding a choice `statelyai/xstate` explains in
+ * its own CI action. Whether an image exists for a version is the RESOLVER's question and it is
+ * asked with the publisher's index in hand; this one's job is to say what the repository wrote.
+ *
+ * @param leg the maintainer's `setup.matrixLeg`, when they have named one for this job. See the
+ *   matrix branch below: it is the difference between "which cells does CI prove green" and "which
+ *   cell does Abloh's step actually run on".
+ */
+declare function readCiNodeDeclaration(raw: string | null, matrix: unknown, reader: RepoReader, leg?: MatrixLeg | null | undefined, env?: NodeEnvironment): CiNodeVersion | null;
+/**
+ * DO TWO JOB REFERENCES NAME THE SAME JOB, whichever spelling each of them uses?
+ *
+ * EXPORTED BECAUSE THE TWO SPELLINGS ARE REAL AND CROSS A SEAM. `CiRecipe.job` is the SHORT form -
+ * `ci.yml::unit`, the basename, which is what this file's own receipts have always printed - and
+ * `setupJobReference` is the LONG one, `.github/workflows/ci.yml::unit`, which is what `setup.job`
+ * takes and what the setup PR appends a step through. Anything comparing the recipe's answer with
+ * the decision's is comparing those two, and a string equality between them is false on every
+ * repository - which would make a reconciliation either never fire or always fire.
+ *
+ * MATCHED ON THE TWO HALVES rather than on the string, so a path that merely ends in the same
+ * characters cannot resolve. `pinMatches` above is the same rule and reads it from here.
+ */
+declare function sameJobReference(left: string, right: string): boolean;
+/**
+ * A RECIPE THAT READ NOTHING, with the reason it read nothing.
+ *
+ * FOR THE LANES THAT NEVER CALL THE READER AT ALL - the Python lane returns before it - so a caller
+ * downstream holds a recipe object rather than a null it has to branch on. The refusal is what the
+ * borrow lane quotes when it answers "no job to borrow", so it has to be a sentence rather than an
+ * empty string: "abloh read nothing and will not say why" is the shape this module refuses to have.
+ */
+declare function emptyCiRecipe(refusal: string): CiRecipe;
+/**
+ * READ THIS REPOSITORY'S CI AND RETURN THE LINES `init` MAY WRITE.
+ *
+ * Never called anywhere but `init`. See the file header: deriving at run time would move what Abloh
+ * runs from declared to inferred and would let a fork's workflow edit change it.
+ */
+declare function deriveCiRecipe(input: {
+    repoDir: string;
+    /**
+     * READ THE REPOSITORY THROUGH THIS instead of off the disk under `repoDir`.
+     *
+     * The GitHub App door derives this same recipe with no checkout at all, over bytes fetched from
+     * the contents API. It was accepted by the private `derive` below and not declared here, so the
+     * one caller that needs it could not name it - see that parameter for the argument.
+     */
+    reader?: RepoReader;
+    workDir?: string;
+    /**
+     * DERIVE FROM THIS JOB, `file::jobId`, rather than from the one the ranking would choose.
+     *
+     * WHY A PIN CHANGES THE WHOLE RECIPE AND NOT JUST THE STEP PLACEMENT. Everything in this object is
+     * read out of ONE job: the build steps that become `.abloh/setup.sh`, the test command, the
+     * services, the environment values, the runner image. So "ride `ci.yml::checks` instead" is a
+     * different CONTRACT, not the same contract in a different place - and a pin that moved only the
+     * step would leave abloh borrowing one job while executing the other job's build, which is the
+     * failure the pin exists to escape.
+     *
+     * WHO SETS IT. `abloh.yml`'s own `setup.job`, when a maintainer has declared one, and the
+     * self-healing loop, when a trial has just proved the current job cannot carry it
+     * (`packages/core/src/setup-healing.ts`).
+     *
+     * A PIN THAT NAMES NO JOB THIS WALK READ IS IGNORED, not refused. `setup-job.ts` is the module
+     * that answers a maintainer about an unresolvable `setup.job`, with the jobs it did read in hand;
+     * refusing here would take `init` down over a key that has its own refusal one layer up.
+     */
+    job?: string | undefined;
+    /**
+     * DERIVE FROM THIS LEG of the job's matrix, `abloh.yml`'s own `setup.matrixLeg`.
+     *
+     * WHY THE LEG BELONGS TO THE DERIVATION AND NOT ONLY TO THE PLACEMENT (corpus rehearsal pass 2,
+     * 2026-08-30, finding 2). `setup.job` and `setup.matrixLeg` are ONE answer - the job says which
+     * build, the leg says which of that build's cells - and `setupStepIf` puts Abloh's step behind an
+     * `if:` that is true on that cell alone. A recipe derived without it describes a DIFFERENT cell
+     * than the one the step runs on, and the first thing that goes wrong is the runtime: the sealed
+     * measurement image takes its Node from `ci.node.major`, so a maintainer who pinned `node: 22`
+     * was measured on Node 24.
+     *
+     * A LEG THIS WALK'S CHOSEN JOB DOES NOT OFFER CHANGES NOTHING. Every reader of it below checks
+     * the dimension and the value against the matrix in hand, so a leg belonging to another job -
+     * which `setup-job.ts` refuses one layer up, by name and with the legs listed - cannot quietly
+     * redirect a derivation here.
+     */
+    leg?: MatrixLeg | undefined;
+}): CiRecipe;
+/**
+ * ONE PACKAGE-MANAGER VERSION THIS REPOSITORY'S OWN CI DECLARES, and the job that says so.
+ *
+ * WHY IT IS READ (the 2026-09-11 detection audits, I2 and P1). The pin offer started from the tool
+ * installed on the laptop `abloh init` was typed on, and then edited the repository's own workflows
+ * to agree with it. `react-hook-form` already says pnpm 11.7.0 inside a local action, `0no-co/gql.tada`
+ * already says 11.3.0 in its release workflow, and both were offered this machine's 10.34.5 instead.
+ * A version a repository has written down is a decision somebody made; a version this machine
+ * happens to carry is an accident of who typed the command.
+ *
+ * `declared` IS THE FILE'S OWN TEXT AND {@link exact} SAYS WHETHER IT NAMES A RELEASE. `version: 11`
+ * is a real declaration and is not a pin: `packageManager` accepts `X.Y.Z` alone, so a major can
+ * agree with an exact version or disagree with it, and can never become one.
+ */
+interface CiManagerVersion {
+    pm: PackageManagerName;
+    /** As the workflow writes it: `11.7.0`, `11`, `8`. */
+    declared: string;
+    /** True when {@link declared} is the exact `X.Y.Z` shape `packageManager` accepts. */
+    exact: boolean;
+    /** `.github/workflows/build-test.yml::build`, the job it was read out of. */
+    source: string;
+    /** `pnpm/action-setup` input `version`, or `corepack`, for saying where it was read. */
+    by: "action-input" | "corepack" | "tool-versions";
+}
+/**
+ * THE INSTALL STEP ONE OF THIS REPOSITORY'S OWN CI JOBS RUNS, KEPT WHOLE.
+ *
+ * WHAT THIS REPLACED, AND WHY A NAME WAS NOT ENOUGH (the 2026-09-11 detection audits, I1, I3 and L1).
+ * The reading before it kept two fields - the manager's NAME and the job - and threw the rest of the
+ * step away. Three separate defects came out of that one loss, and each of them is a field here:
+ *
+ *   - THE ARGUMENTS. `spliit-app/spliit` installs with `npm ci --ignore-scripts` because its
+ *     `postinstall` runs `prisma migrate deploy` against a database that does not exist yet, and its
+ *     own workflow says so in a comment. abloh composed `npm ci --no-audit --no-fund` from the
+ *     manager name, which runs that migration. `graphql/graphql-js` and `goniszewski/grimoire`
+ *     suppress scripts the same way; `web-infra-dev/garfish` excludes two workspace packages.
+ *   - THE DIRECTORY. `grimoire` installs its root with npm and its `daemon` with bun, and the reading
+ *     combined the two into one repository-wide pair - so a directory whose CI names one manager
+ *     outright was described to its maintainer as a guess.
+ *   - THE VERSION. See {@link CiManagerVersion}.
+ *
+ * {@link command} IS NULL WHERE THE STEP IS NOT ONE COMMAND, and that is a different answer from
+ * finding nothing. `ruvnet/ruflo` installs through a retry loop - a `until ... npm ci ... done` shell
+ * program - which says which manager installs which directory and is not a line abloh may execute.
+ * So the manager and the directory are read and the prefill falls back to the standard form, which
+ * is exactly what a record with a name in it and no command means.
+ */
+interface CiInstallStep {
+    pm: PackageManagerName;
+    /**
+     * The command line, verbatim, with every argument the workflow wrote - or null where the step is
+     * a shell program rather than one command.
+     *
+     * VERBATIM IS THE POINT. Nothing here is normalized, re-ordered, or given a flag of abloh's: the
+     * whole class of defect this record exists for is abloh composing a command that differs from the
+     * one the maintainer already proved runs on a checkout of this repository.
+     */
+    command: string | null;
+    /** The step's own `env:`, literal values only. A value the workflow computes is not carried. */
+    env: Readonly<Record<string, string>>;
+    /** Repo-relative with forward slashes, `.` at the root: step `working-directory`, else the job's. */
+    directory: string;
+    /** `.github/workflows/ci.yml::checks` - the job the step was read out of. */
+    source: string;
+    /** Every package-manager version that job declares for {@link pm}, in the order they were read. */
+    versions: readonly CiManagerVersion[];
+}
+/**
+ * EVERY INSTALL STEP THIS REPOSITORY'S OWN CI RUNS, whole, in workflow order.
+ *
+ * WHY THIS ONE MAY BE CALLED OUTSIDE `init`, when {@link deriveCiRecipe} may not. The file header's
+ * rule is about DERIVING A COMMAND FOR A RUN TO EXECUTE: a line read out of a workflow and turned
+ * into what abloh runs on a pull request would move the measurement from declared to inferred, and
+ * would let a fork's workflow edit change it. Two of this function's three readers are tie-breaks
+ * between files the repository has already committed - which lockfile owns a directory, and which
+ * version a pin should name - and the third is `abloh init`, which is the one door where reading CI
+ * and writing a line a person then ratifies is the whole point. Nothing here is executed by a run.
+ *
+ * IT IS DELIBERATELY NOT SCOPED TO THE CHOSEN TEST JOB. A repository whose CI is refused for a
+ * browser, a toolchain or an unreadable test step still installs the way it installs, and that fact
+ * is worth just as much when the rest of the recipe is unreadable.
+ */
+declare function ciInstallSteps(repoDir: string, reader?: RepoReader): readonly CiInstallStep[];
+/**
+ * EVERY PACKAGE-MANAGER VERSION THIS REPOSITORY'S CI DECLARES, in every workflow, in file order.
+ *
+ * REPOSITORY-WIDE AND NOT SCOPED TO A TIER OR A DIRECTORY, and that is what the field it feeds is.
+ * `packageManager` is one line in one manifest and `pnpm/action-setup` reads it in EVERY job that
+ * runs - so a pin has to agree with every declaration in the repository, not with the ones in the
+ * jobs that happen to run on a pull request. `reconcileCiDeclarations` in `package-manager-pin.ts`
+ * already walks the whole directory for exactly that reason: reconciling only the ridden file would
+ * leave the pin breaking a release job nobody looked at.
+ *
+ * IT COST A REAL ANSWER TO SCOPE IT (the 2026-09-11 audits' P1). `0no-co/gql.tada` declares pnpm
+ * major 11 in the three workflows that run on a pull request and the exact `11.3.0` in the release
+ * workflow, which runs on a push - so a pull-request-tier reading finds no release anywhere and asks
+ * for a version the repository has already chosen. `ant-design/ant-design-mobile` is the same shape
+ * with the opposite consequence: its `size-limit.yml` says pnpm 8 where six other workflows say 7,
+ * and a reading that could not see it would call the repository agreed when it is not.
+ */
+declare function ciManagerVersions(repoDir: string, reader?: RepoReader): readonly CiManagerVersion[];
+/**
+ * THE MANAGER FAMILIES THIS REPOSITORY'S CI INSTALLS ONE DIRECTORY WITH, distinct and in file order.
+ *
+ * The tie-break `detect.ts` asks at a directory carrying more than one family of lockfile. It is
+ * asked OF A DIRECTORY since the 2026-09-11 audits' L1: `goniszewski/grimoire` installs its root
+ * with npm and its `daemon` with bun, and a repository-wide answer read those two as a repository
+ * that had not chosen - so a root whose own CI names npm outright was described to its maintainer
+ * as an assumption.
+ *
+ * A NULL DIRECTORY IS THE SECOND QUESTION, and the caller asks it only where the first answered
+ * nothing: what does this repository install with ANYWHERE. `ruvnet/ruflo`'s own install step is two
+ * subshells that each `cd` into a bridge package, so nothing in its CI installs the root - and the
+ * two lockfiles the root carries still have to be decided between. The answer carries the directory
+ * it was read from, because a receipt that says "your CI installs with npm" over evidence taken from
+ * a subdirectory is the misplaced source this record was written to end.
+ */
+declare function ciInstallersFor(steps: readonly CiInstallStep[], 
+/** The repo-relative directory being decided, or null to ask what the repository installs at all. */
+directory: string | null): readonly {
+    pm: PackageManagerName;
+    source: string;
+    directory: string;
+}[];
+type PackageManagerName = "npm" | "pnpm" | "yarn" | "bun";
+/** Exported for the tests that hold the refusal wording to its ruling. */
+declare const CI_RECIPE_REFUSALS: {
+    readonly browser: "browser-driven suites are not supported in the sealed run - keep them in your own CI";
+    readonly noWorkflows: "no .github/workflows directory";
+    readonly noPullRequestWorkflow: "no workflow runs on pull_request, so your CI declares no build Abloh can read";
+    readonly noTestJob: "no pull-request job runs a test command Abloh recognizes";
+    readonly noTestJobAnywhere: "no job in your CI runs a test command Abloh recognizes";
+};
+/**
+ * Is this refusal worth a customer's attention, or is it just "there was nothing here to read"?
+ *
+ * THE DISTINCTION IS THE WHOLE VALUE OF PRINTING REFUSALS AT ALL. "Your CI test job needs a
+ * browser" tells somebody why their suite will not go green and what to do instead. "No
+ * .github/workflows directory" tells a repository with no GitHub Actions something it already
+ * knows, on every `init`, forever - and a notice that fires on the majority of repositories is the
+ * one people learn to skip past, taking the useful ones with it.
+ */
+declare function ciRefusalIsActionable(refusal: string | null): boolean;
+/** Exported for the unit tests that exercise one rule at a time rather than a whole repository. */
+declare const __testing: {
+    classifyRepoDefinedBuild: typeof classifyRepoDefinedBuild;
+    readAptStep: typeof readAptStep;
+    readCiNodeDeclaration: typeof readCiNodeDeclaration;
+};
+
+/**
+ * WHICH OF THE CUSTOMER'S OWN CI JOBS THE ABLOH STEP RIDES, AND WHEN ABLOH REFUSES TO DECIDE.
+ *
+ * WHAT CHANGED (Kenneth's onboarding-flip decision, 2026-08-28). The old default wrote a STANDALONE
+ * workflow: a fresh job on a blank runner, which builds nothing, so abloh had to rebuild the whole
+ * project from a recipe it had guessed. The measured cost of that lane is 1 of 6 repositories
+ * surviving first contact with zero edits. The new default appends ONE step to the job the customer
+ * already gates their own pull requests on, so their steps do the build and abloh borrows the
+ * result. The measured ceiling of the borrow lane is 23 of 29 repositories having a build to ride.
+ *
+ * SO THE WHOLE PROBLEM MOVES TO ONE QUESTION: which job. This module answers it, and its most
+ * important answer is the one where it does not.
+ *
+ * NEVER A SILENT GUESS. The design record's own caveat: "Job selection in large matrices
+ * (Storybook-scale CI) is the new hard sub-problem and gets its own 'needs your edit' state rather
+ * than a silent guess." A guess here is uniquely expensive, because every later stage then argues
+ * about the wrong build - the trial's baseline runs a suite the maintainer does not gate on, and a
+ * green setup check would mean something other than what it says. Two shapes get the "needs your
+ * edit" state:
+ *
+ *   A TIE. Two or more jobs install, build and test, and the ranking cannot separate them.
+ *   A MATRIX. The chosen job fans out, so "the job" is several builds and abloh cannot say which
+ *   leg's tree it would be borrowing.
+ *
+ * Both name `abloh.yml` key `setup.job`, and that key EXISTS - `config.ts` parses it in the same
+ * change that added these refusals. A remedy whose edit cannot change the refused state is the
+ * defect the 2026-08-28 census counted, and shipping the refusal before the key would have been it.
+ *
+ * AND A CONFIDENT READING IS NOT A LICENCE TO STAY SILENT (captain's ruling, 2026-08-31, off the
+ * fresh-ten run). A tie was never the only way to ride the wrong job. `prettier/prettier`'s ranking
+ * had a clear WINNER, the winner was a LINT job, and the step went there without a word - four of
+ * ten repositories measured a job that ran no tests. So a `borrow` outcome now carries a QUESTION
+ * too: the jobs the choice was made between, chosen first, whenever there was more than one. It is
+ * not a refusal and it changes no unattended road - the ranking still picks and still rides - it is
+ * the set a terminal gets asked about before the draft is written.
+ *
+ * WHAT THIS DOES NOT DO. It reads nothing off disk and starts nothing: `ci-recipe.ts` has already
+ * read the workflows under its own bounds and its own refusals, and a second reading here would be
+ * a second answer to "what does this repository's CI declare". Everything below is a decision over
+ * facts that reader produced.
+ */
+
+/**
+ * One value per matrix dimension, as `abloh.yml`'s `setup.matrixLeg` spells it.
+ *
+ * EACH VALUE KEEPS ITS TYPE, and `matrix-value.ts` in core is the whole reason: the condition
+ * `setup-step.ts` writes compares a YAML boolean bare and everything else quoted, so a leg flattened
+ * to text is one the renderer cannot spell correctly any more.
+ */
+type SetupMatrixLeg = MatrixLeg;
+/**
+ * WHAT THE COMMITTED `setup:` BLOCK SAID, INCLUDING "SOMETHING ABLOH COULD NOT READ".
+ *
+ * `unreadable` IS THE FIELD THAT DID NOT EXIST (blind-maintainer report, `electron/asar`,
+ * 2026-08-30). A pin that failed to parse used to come back as an empty object - indistinguishable
+ * from a repository that had never answered - so the product asked its one question twice and
+ * behaved, both times, as though nothing had been written. It travels as a value rather than as a
+ * throw because the caller is `abloh init`, which has a refusal channel and no error channel here.
+ */
+interface SetupPin {
+    job?: string;
+    leg?: SetupMatrixLeg;
+    /**
+     * `setup.failFast`: what the maintainer already told abloh to do about a job that cancels its legs.
+     *
+     * IT RIDES WITH THE JOB AND THE LEG BECAUSE IT IS THE SAME STATEMENT. All three are answers about
+     * one job, and a caller holding two of them without the third would re-ask a question that has
+     * been answered - which is the whole of what `setup.job` and `setup.matrixLeg` already refuse.
+     */
+    failFast?: SetupFailFast;
+    unreadable?: {
+        key: string;
+        problem: string;
+    };
+}
+/**
+ * `setup.job` out of the repository's committed `abloh.yml`, or undefined.
+ *
+ * READ OFF DISK, and that is correct HERE and would be wrong on the run path. This is `init`,
+ * looking at the working tree in front of the maintainer; a pull-request run loads its policy from
+ * the trusted merge-base commit precisely so a later commit cannot change what runs, and nothing in
+ * this module is ever called from there (`measurement-plan-resolver.ts` states the same split).
+ *
+ * AN UNREADABLE POLICY ANSWERS NOTHING rather than throwing. `abloh run` fails a malformed file
+ * with its own precise error, and job selection has never been the surface that reports one.
+ */
+declare function declaredSetupJob(repoDir: string): string | undefined;
+/**
+ * `setup.job` AND `setup.matrixLeg` TOGETHER, because they are one answer.
+ *
+ * A maintainer who names a leg has answered a question about a job, and reading the two through
+ * separate doors would let a caller hold one without the other - which is how a leg would end up
+ * being applied to a job nobody declared, or a declared matrix job would meet the fan-out refusal
+ * again with the answer sitting in the file beside it.
+ */
+declare function declaredSetupPin(repoDir: string, ctx?: RepoAccess): SetupPin;
+/**
+ * THE PIN THIS RUN IS ABOUT, out of the two places one can arrive from, and never out of both.
+ *
+ * TWO SOURCES. `caller` is what this invocation was HANDED - the control plane's healing loop, or
+ * an `abloh init --answers-file` document written by a census or an agent. `committed` is the
+ * `setup:` block already in the repository's `abloh.yml`.
+ *
+ * THE CALLER OUTRANKS THE FILE, whole, because it is the newer statement of the same fact: a loop
+ * that has just proved the committed job cannot carry the trial is not asking to re-derive it, and
+ * a census handing over the answer a maintainer would have written is standing in for that
+ * maintainer.
+ *
+ * AND IT OUTRANKS IT AS ONE ANSWER, not key by key. Taking the caller's job and the file's leg would
+ * pin a leg of one job onto another, which `matrixLegProblem` would then refuse for reasons nobody
+ * could act on. NAMING EITHER KEY IS SPEAKING: a caller that names only a leg - which is what a
+ * cross-product matrix asks for, and is the whole of the teaser census's finding 2 - has stated the
+ * answer for whichever job abloh goes on to choose, and reading the file's job underneath it would
+ * be the same mix one direction later.
+ */
+declare function resolveSetupPin(caller: {
+    job?: string;
+    matrixLeg?: SetupMatrixLeg;
+    failFast?: SetupFailFast;
+}, committed: SetupPin): SetupPin;
+/**
+ * WHAT `abloh init` DOES ABOUT THE STEP, in three outcomes and no fourth.
+ *
+ * `borrow` is the default lane. `needs-your-edit` is the honest stop - the contract is still
+ * drafted and the setup PR is still opened, because the PR body IS where a maintainer answers this,
+ * and refusing to open it would put the question somewhere they have to go and find. `fallback` is
+ * the demoted old lane: the standalone workflow and the rebuild recipe, which are now what happens
+ * when there is no build to borrow rather than what happens to everybody.
+ */
+type SetupJobDecision = SetupJobOutcome & {
+    /**
+     * THE JOBS A `setup.job` DECLARATION WOULD BE ADMITTED FOR, `file::job`, on every outcome.
+     *
+     * ON THE DECISION AND NOT RECOMPUTED BY THE PAGE (census cycle 2 retry, `vitejs/vite`,
+     * 2026-08-31), on the same argument `answerable` makes above and on `runSetupFlow`'s own rule that
+     * it is handed a decision rather than a recipe. The refusal prints this list and the setup pull
+     * request offers it; a second computation would be the first place the two could come to name
+     * different jobs, and a maintainer would be offered one that the next run refuses.
+     *
+     * See {@link declarableSetupJobs}. Empty means no declaration works here, which is a thing the
+     * fallback road says out loud rather than leaving as an absence.
+     */
+    offers: readonly string[];
+};
+/**
+ * A QUESTION ABOUT WHICH JOB, WITH THE ONLY VALUES ITS ANSWER MAY TAKE.
+ *
+ * ONE TYPE FOR BOTH ROADS SINCE 2026-08-31, because since the captain's ruling below there are two:
+ * the tie abloh could not settle, and the choice abloh settled but did not have the right to settle
+ * silently. The prompt asks them with one function and the difference between them is the
+ * RECOMMENDATION, not the shape of the answer.
+ *
+ * THE FIRST CANDIDATE IS THE JOB ABLOH WOULD RIDE. On a tie that is the higher-scoring of two jobs
+ * the ranking calls equal, so nothing is recommended; on a settled choice it is a real winner and
+ * the prompt says so. Either way it is first, so a maintainer who agrees with abloh types `1`.
+ */
+interface SetupJobQuestion {
+    key: "setup.job";
+    /** `<file>::<jobId>` for the job abloh would ride, then every other job it could ride instead. */
+    candidates: readonly string[];
+    /**
+     * THE ONE CLAUSE THAT FLAGS A CANDIDATE, PER REFERENCE, and absent for a candidate with nothing
+     * to flag.
+     *
+     * WHY THE LIST CARRIES IT FROM THE FIRST PASS (Kenneth's ruling of 2026-09-02, census run 4 F4).
+     * A matrix job with no `fail-fast: false` cancels every leg the moment one fails, abloh's leg
+     * included, and `sveltejs/svelte` lost a nearly-finished measurement to exactly that. The
+     * maintainer is the one who knows whether that matters, and they are already standing at this
+     * question choosing between these jobs - so the fact goes on the line they are choosing from
+     * rather than in a sentence after the choice is made.
+     *
+     * COMPUTED WITH THE CANDIDATES AND NEVER BY THE PROMPT, on this file's standing rule: the decision
+     * owns the answer set, and a second reading in the door is where the flag and the question that
+     * follows it would come to disagree about which jobs cancel.
+     */
+    notes: Readonly<Record<string, string>>;
+}
+/**
+ * WHAT ABLOH DOES ABOUT THE RIDDEN JOB'S `fail-fast`, decided once and read by everything after.
+ *
+ * IT IS ON THE DECISION FOR THE SAME REASON THE LEG IS. The step writer needs to know whether to
+ * write a line into the customer's `strategy:` block, the contract renderer needs to know what to
+ * record, and the door needs to know whether there is a question at all. Three readings of one
+ * workflow node is three answers the first time any of them learns something.
+ *
+ * `packages/core/src/setup-fail-fast.ts` holds the rule, the copy and the run it was measured on.
+ */
+interface SetupFailFastDecision {
+    /** Does a failing leg of this job cancel the leg abloh's step rides? */
+    cancelsLegs: boolean;
+    /** May abloh write `fail-fast: false` into it, or is there a value of theirs in the way? */
+    editable: boolean;
+    /** The maintainer's standing answer, or null when nobody has answered. */
+    answer: SetupFailFast | null;
+    /**
+     * WRITE THE LINE, and this is the only field the step writer reads.
+     *
+     * BOTH HALVES, ASKED HERE. An `add` answer on a job abloh may not edit writes nothing, and a
+     * caller that tested the answer alone would replace a `fail-fast:` the maintainer typed. One
+     * field means the flow cannot ask half the question.
+     */
+    write: boolean;
+    /** What a maintainer is told about it, or null when there is nothing to say. */
+    notice: string | null;
+}
+type SetupJobOutcome = {
+    kind: "borrow";
+    job: CiBorrowJob;
+    declared: boolean;
+    excluded: readonly SetupCandidateExclusion[];
+    /**
+     * THE JOBS THIS REPOSITORY COULD HAVE RIDDEN INSTEAD, or null when there was no choice.
+     *
+     * WHY A SETTLED DECISION CARRIES A QUESTION AT ALL (captain's ruling, 2026-08-31, off the
+     * fresh-ten run). The ranking is a reading of what a job DOES - it installs, it builds, it runs
+     * a suite abloh recognized - and on `prettier/prettier` that reading has a clear winner: the
+     * LINT job. The step went there, silently, because nothing was tied. Four of the ten
+     * repositories measured a job that ran no tests, and every wrong desk-check prediction in that
+     * run was a job-selection prediction.
+     *
+     * THE MAINTAINER KNOWS THIS INSTANTLY. It is the check that goes red when they break
+     * something. Five seconds of typing against a wrong pick costing a full CI cycle and a verdict
+     * that means nothing is not a close call, so the rule is: more than one candidate, ASK.
+     *
+     * NULL WHERE THERE IS NOTHING TO ASK. One candidate is not a choice, and a repository whose
+     * maintainer already declared `setup.job` has answered - re-asking would put the question to
+     * somebody who wrote the answer down.
+     *
+     * EVERY VALUE IN IT IS ONE {@link doorSetupJobs} ADMITS, which is what stops the prompt
+     * offering a job the next run's declaration branch refuses.
+     */
+    answerable: SetupJobQuestion | null;
+    /**
+     * WHAT ABLOH DOES ABOUT THIS JOB CANCELLING ITS OWN LEGS. See {@link SetupFailFastDecision}.
+     *
+     * ONLY ON `borrow`, and that is the shape rather than an omission. Every other outcome has no
+     * job abloh is about to ride - a fan-out places no step until a leg is named, a fallback rides
+     * a workflow of abloh's own - so there is nothing for the question to be about and nothing for
+     * the step writer to act on. The flag on the job LIST is a different thing and rides on
+     * {@link SetupJobQuestion.notes}, which every road that asks about jobs carries.
+     */
+    failFast: SetupFailFastDecision;
+    /**
+     * THE RIDE IS HELD ONLY UNTIL THE TRIAL ANSWERS.
+     *
+     * TRUE WHERE NO JOB IN THIS CI RUNS A SUITE ABLOH RECOGNIZED (the captain's ride-and-prove
+     * ruling, 2026-09-04). `spliit-app/spliit`'s one pull-request job installs and then runs
+     * types, lint and formatting, so the borrow road used to be closed to it - and what the road
+     * needs from somebody else's job is a prepared tree, which that job produces. So the job that
+     * installs is ridden, and the setup trial runs abloh's own derived test command in it once.
+     * The ride is kept only if the baseline there is green and observed.
+     *
+     * NOTHING IN THIS MODULE ACTS ON IT, AND THAT IS THE POINT. A prediction about whether a
+     * suite will run in a tree nobody has run it in is exactly the guess the ruling forbids. The
+     * decision to keep or abandon is `decideSetupHealing`'s, taken from a finished trial, and it
+     * reads the job's own `tests` fact rather than this flag - see `setupRideIsProvisional`. What
+     * this field is for is the surfaces: a terminal and a setup pull request body saying that
+     * abloh rode a job whose green does not currently mean a suite passed.
+     *
+     * FALSE ON A DECLARED JOB, whatever it runs. A maintainer naming `setup.job` has stated which
+     * job their verdict comes from, and a mechanism that abandoned their answer after one trial
+     * would be overriding the one statement in the file that was never abloh's to discard.
+     */
+    provisional: boolean;
+    /**
+     * THE MATRIX LEG THE STEP IS PINNED TO, or null when the job is one build.
+     *
+     * IT IS PART OF THE DECISION AND NOT A DETAIL OF IT. The step that gets written carries an
+     * `if:` that is true on this leg alone, and the contract in `abloh.yml` states it, so a caller
+     * that held the job without the leg would place a step that runs on every leg - which is the
+     * fan-out this whole key exists to end.
+     */
+    leg: SetupMatrixLeg | null;
+} | {
+    kind: "needs-your-edit";
+    /**
+     * THE JOB THE QUESTION IS ABOUT, or null when the question is about the contract itself.
+     *
+     * NULL IS NEW AND IT IS NOT A DEFAULT (blind-maintainer report, `electron/asar`, 2026-08-30).
+     * `setup-contract-unreadable` is raised over a `setup:` block abloh could not parse, which can
+     * happen in a repository whose CI abloh could not read either - there is then no job to name,
+     * and naming one anyway would be inventing the half of the sentence that is missing.
+     */
+    job: CiBorrowJob | null;
+    refusal: Refusal;
+    excluded: readonly SetupCandidateExclusion[];
+    /**
+     * MAY THE ONE STEP GO IN WHILE THE MAINTAINER ANSWERS?
+     *
+     * TRUE FOR A TIE AND FALSE FOR A MATRIX, and the difference is not a preference (2026-08-29,
+     * peer implementation review defect 7).
+     *
+     * A TIE IS ONE JOB. Abloh picked the higher-scoring of two, the step runs once, one trial
+     * reports, and the maintainer's answer redirects it if the other was meant. Withholding the
+     * edit there would cost them a whole round trip to learn something a trial can tell them now.
+     *
+     * A MATRIX IS SEVERAL BUILDS SHARING ONE JOB ID. Appending the step fans it out over every
+     * leg: several trials, several runtime-derived plans, and - because GitHub's `GITHUB_JOB` is
+     * the job KEY and is identical on every leg - reports that no reader can tell apart, racing
+     * into one setup row. The last one to land wins, which makes "the trial said" a statement
+     * about scheduling. Nothing downstream can recover that, so the edit waits.
+     */
+    placeStep: boolean;
+    /**
+     * WHAT AN ANSWER MAY BE, STATED BY THE DECISION THAT COULD NOT SETTLE IT.
+     *
+     * WHY IT IS ON THE DECISION AND NOT RECOMPUTED BY THE ASKER (Kenneth's ruling of 2026-08-30:
+     * a foreseeable question is asked upfront). The refusal already carries these values as facts,
+     * because a remedy that names `setup.job` without naming the jobs is a key with no answer in
+     * it. A door that asked the same question would have to rank the candidates and filter the
+     * legs a second time, and the first time those two rankings disagreed the maintainer would be
+     * offered an answer this function then refuses - the remedy-that-cannot-work defect, one
+     * layer in. So the set is computed once, here, and the refusal and the prompt read the same
+     * one.
+     *
+     * THE TWO SHAPES ARE THE TWO KEYS, and they are not interchangeable: a declaration answers
+     * "which job" and cannot answer "which leg" (`decideSetupJob` refuses a declared matrix job
+     * for exactly that reason), so the prompt has to know which of the two it is asking about.
+     *
+     * NULL IS THE UNREADABLE-DECLARATION CASE, and it is an explicit null rather than an optional
+     * key so a new return site cannot forget to decide: the maintainer already answered, abloh
+     * could not read what they wrote, and a door that re-asked would overwrite a written
+     * declaration instead of sending them to fix it. The refusal's own located remedy is the
+     * whole of what that case offers.
+     */
+    answerable: SetupJobQuestion | {
+        key: "setup.matrixLeg";
+        /** The job the leg is a leg OF, `<file>::<jobId>`. */
+        job: string;
+        /** Per dimension, the values abloh could ride. See {@link ridableLegs}. */
+        legs: MatrixLegs;
+    } | null;
+} | {
+    kind: "fallback";
+    refusal: Refusal;
+    excluded: readonly SetupCandidateExclusion[];
+    /**
+     * EVERY JOB OF THEIRS THAT INSTALLS AND WAS NOT RIDDEN, WITH WHY, in score order.
+     *
+     * THE FALLBACK QUESTION SAYS WHY PER JOB (the captain's ruling of 2026-09-10, over "abloh
+     * did not detect"). `abloh init` used to open this road with "No job in your CI runs on pull
+     * requests", which was false of `fastify/fastify` - `ci.yml::test-unit` installs, runs the
+     * suite and runs on every pull request - and said nothing a maintainer could check against
+     * their own file. What they can check is a list: this job, this reason, in the sentences the
+     * setup pull request prints under "Jobs Abloh did not ride, and why".
+     *
+     * INSTALLING JOBS ONLY. A lint or labeler job that installs nothing was never a candidate and
+     * is not what a maintainer means by "my test job"; naming it would pad the list with jobs the
+     * answer could never be. Computed with the decision, on this file's standing rule, so the
+     * prompt and the pull request cannot name different jobs or give one job two reasons.
+     */
+    notRidden: readonly SetupCandidateExclusion[];
+};
+/**
+ * DECIDE.
+ *
+ * The order is the order of authority: what the maintainer declared, then whether there is anything
+ * to borrow at all, then whether abloh's own reading is unambiguous.
+ */
+declare function decideSetupJob(input: {
+    recipe: CiRecipe;
+    /** `abloh.yml`'s `setup.job`, when the repository already declares one. */
+    declaredJob?: string | undefined;
+    /**
+     * `abloh.yml`'s `setup.matrixLeg`, when the repository already declares one.
+     *
+     * IT ANSWERS THE FAN-OUT AND NOTHING ELSE. A leg on a job that is one build is not an error and
+     * not a preference - `matrixLegProblem` refuses it, because a workflow with no matrix declares no
+     * dimension the leg could name, and a key that quietly did nothing would be worse than one that
+     * says so.
+     */
+    declaredLeg?: SetupMatrixLeg | undefined;
+    /**
+     * `abloh.yml` HAD A `setup:` BLOCK AND ABLOH COULD NOT READ IT.
+     *
+     * Handed in from `declaredSetupPin`'s own reading, and it outranks everything below: a decision
+     * taken over an answer that was discarded is a decision taken against the maintainer's stated
+     * intent, and it is what asked `electron/asar` the fan-out question twice.
+     */
+    declaredUnreadable?: {
+        key: string;
+        problem: string;
+    } | undefined;
+    /**
+     * `abloh.yml`'s `setup.failFast`, when the maintainer has answered that question.
+     *
+     * IT DECIDES NOTHING ABOUT WHICH JOB and is read for one thing: whether the step writer adds
+     * `fail-fast: false` beside its own step, and whether the door still has a question to ask. An
+     * answer of `keep` is therefore load-bearing rather than a no-op - it is what stops abloh asking
+     * again on every re-run of `init`.
+     */
+    declaredFailFast?: SetupFailFast | undefined;
+    /**
+     * WHAT THIS REPOSITORY CALLS ITS MAINLINE, when the caller resolved it.
+     *
+     * Handed in rather than looked up, on this module's own rule: it reads nothing off disk. `init`
+     * has the clone and already asks git this question to pick the setup pull request's base, so the
+     * value is in hand at the moment this runs. Absent falls back to core's three names.
+     */
+    defaultBranch?: string | null;
+    /**
+     * `environment.runtimeImage` AS THIS SAME RUN WROTE IT, so the worked example agrees with it.
+     *
+     * WHY A DECISION ABOUT JOBS TAKES AN IMAGE (the fresh-ten launch-evidence run, 2026-08-31, bug 4).
+     * It changes no decision and it is not read by any branch below: what it reaches is the FACT SET
+     * of the two matrix refusals, where `matrixLegShape` in core turns it into which leg the copyable
+     * block names. The setup pull request writes the image and shows the example, a few sections
+     * apart, and until now each chose a Node without reading the other - `moment/luxon` was pinned
+     * Node 24 and shown a leg on Node 20. A maintainer who copies the block is then measured in an
+     * image a major away from the build abloh borrows.
+     *
+     * IT TRAVELS IN THE FACTS RATHER THAN AT RENDER TIME, because a refusal is rendered twice: on the
+     * pull request body when it is raised, and on the sticky comment the control plane posts from the
+     * trial artifact later. A shape chosen at render time would be chosen once with the pin and once
+     * without, which is this same defect between two of abloh's own surfaces.
+     *
+     * ABSENT IS "THE CALLER HAS NO PIN", and the example falls back to the first leg the workflow
+     * lists, which is what it always was.
+     */
+    runtimeImage?: string | null;
+}): SetupJobDecision;
+/**
+ * EVERY JOB A `setup.job` DECLARATION WOULD BE ADMITTED FOR, `file::job`, IN ONE EDIT.
+ *
+ * WHAT IT IS FOR (blind-maintainer census cycle 2 retry, `vitejs/vite`, 2026-08-31). Every
+ * `setup-no-usable-job` refusal names `setup.job` as the way back onto the borrow road, and until
+ * this existed none of them could say which value works. vite's reader was told its suite job could
+ * not carry the check and pointed at a key; the only value that key accepts for that repository is
+ * `.github/workflows/ci.yml::lint`, three jobs further down the same file, and no surface named it.
+ * A key whose every obvious value refuses the reader again is the remedy-that-cannot-work defect
+ * with a round trip in front of it.
+ *
+ * THE SET IS `declarableJobs` AND NOT `borrowable`, on the same argument `findDeclared` makes: a
+ * declaration resolves against every job the walk read, because "which job is the front door" is
+ * abloh's guess and a maintainer is not guessing. `ci.yml::lint` runs no suite abloh recognized and
+ * is a perfectly good tree to borrow.
+ *
+ * ONE EDIT, WHICH IS WHY A MATRIX JOB IS NOT OFFERED. Naming a job that fans out lands the reader on
+ * the leg question, so the offer would be half an answer presented as a whole one. A repository
+ * whose only ridable jobs fan out therefore offers nothing here, and the refusal says so - which is
+ * the fallback truth rather than a door with a second door behind it.
+ *
+ * SCORE ORDER, THEN THE REFERENCE, exactly as {@link filterSetupCandidates} sorts, because two
+ * orderings of one list is two answers to "which job would abloh take".
+ */
+declare function declarableSetupJobs(recipe: CiRecipe, options?: {
+    defaultBranch?: string | null;
+}): readonly string[];
+/**
+ * EVERY JOB THE UPFRONT DOOR MAY OFFER, `file::job`, IN SCORE ORDER.
+ *
+ * WHY IT IS NOT {@link declarableSetupJobs} (captain's ruling, 2026-08-31, and it is the difference
+ * between the rule working on `prettier/prettier` and not). That list answers a question a FILE
+ * asks: what can somebody write in `abloh.yml`, on their own, in one edit, and be on the borrow road
+ * afterwards. A job that fans out fails that test - naming it lands the reader on the leg question -
+ * so it is left out on purpose.
+ *
+ * A TERMINAL IS NOT A FILE. The person at the door can be asked the second question the moment the
+ * first is answered, and `init` does exactly that: an answer naming a matrix job reopens the door on
+ * `setup.matrixLeg`. Holding those jobs back here would be the rule refusing to offer prettier the
+ * only jobs it runs its suite in - every one of `dev-test.yml::test`, `prod-test.yml::test` and
+ * `dev-package-test.yml::test` fans out - which is the exact wrong pick the ruling is about.
+ *
+ * A FAN-OUT WITH NO RIDABLE LEG IS STILL NOT OFFERED. {@link unaskableFanOut} is the same reading
+ * the refusal road uses, so a job whose every leg lands on a runner abloh cannot work on is absent
+ * here rather than offered and then refused one question later.
+ */
+declare function doorSetupJobs(recipe: CiRecipe, options?: {
+    defaultBranch?: string | null;
+}): readonly string[];
+/**
+ * `.github/workflows/ci.yml::unit`, the one spelling `setup.job` and every refusal use.
+ *
+ * IT DELEGATES TO CORE, which is where the spelling moved when self-healing job selection landed:
+ * the healing ledger, the exhaustion refusal and this module all name jobs, and the control plane
+ * cannot import this file. Two `${file}::${jobId}` templates is two places for a separator to
+ * change, and the `setup.job` a maintainer copies out of one has to be the one the other admits.
+ */
+declare function setupJobReference(job: CiBorrowJob): string;
+/**
+ * EVERY JOB THIS REPOSITORY OFFERS THE SETUP TRIAL, in the order the healing loop will ride them.
+ *
+ * WHAT IT IS FOR. `decideSetupJob` answers "which job first"; this answers "and then which", which
+ * is the question `setup-healing.ts` asks after a trial fails at the borrow or wire-in stage. The
+ * ORDER is core's and the FACTS are the CI reader's - this function is only the join, so that the
+ * service (which reads the same list over its own discovery port) and the CLI cannot end up trying
+ * a customer's jobs in two different orders.
+ *
+ * THE CHOSEN JOB IS IN IT. It is the first candidate rather than a thing beside the list: the ledger
+ * counts it against the cap, and a list that omitted it would let the loop ride four jobs on a
+ * budget of three.
+ */
+declare function setupJobCandidates(recipe: CiRecipe, 
+/** What this repository calls its mainline, when the caller resolved it. */
+options?: {
+    defaultBranch?: string | null;
+}): readonly CiBorrowJob[];
+
+/**
+ * A RUNTIME THE GITHUB RUNNER DOES NOT SHIP, and the line in the customer's own file that says so.
+ *
+ * DECLARED HERE AND RE-EXPORTED BY ITS READER. `runtime-needs.ts` is the module that FINDS these,
+ * by reading a repository's scripts, and it stayed in the CLI. The shape travels with the renderer
+ * that writes it into a workflow, so the two doors cannot disagree about the field while agreeing
+ * about the file.
+ */
+interface RuntimeNeed {
+    runtime: "bun" | "deno";
+    /** The customer's own file and the string in it, for the comment written above the key. */
+    evidence: string;
+}
+/**
+ * THE BUILD COMMAND A MUTATION RUN PAYS FOR, with the candidates when more than one could be it.
+ *
+ * Declared here for the same reason {@link RuntimeNeed} is: `init-questions.ts` asks about it and
+ * this file writes it, and the field is the thing they have to agree on.
+ */
+interface RebuildDraftValue {
+    value: string | null;
+    evidence: string;
+    /** The declared build scripts, when more than one could be the answer. Empty otherwise. */
+    candidates: readonly string[];
+    /** The package manager whose `run` would reach one of them, for the example. */
+    manager: string;
+}
+/**
+ * One OS package line as it will appear in the file, with the receipt that goes above it.
+ *
+ * `source` is a `.github/workflows/ci.yml::test` for a package the repository's own CI declared,
+ * and the customer's own failing suite line for one the closure loop discovered. Both are
+ * receipts, and the file must never carry a package whose comment cannot say where it came from.
+ */
+interface ConfigSystemPackage {
+    name: string;
+    /**
+     * Null for a package the customer named without a version, which the setup script installs
+     * unpinned (removal R2). Everything abloh DERIVED carries a version, and everything the closure
+     * loop discovered carries one too, because it reads the archive before writing it.
+     */
+    version: string | null;
+    source: string;
+}
+interface ConfigInput {
+    /**
+     * THE QUOTE CHARACTER FOR THE ONE CLASS OF SCALAR THAT CANNOT BE WRITTEN PLAIN.
+     *
+     * Every value this file writes is spelled plain wherever YAML reads it back unchanged, which is
+     * what makes it survive `prettier --check` under any quote setting (`yaml-scalar.ts`). What is
+     * left is a string that would otherwise parse as a number - a matrix leg like `node: "26"` - and
+     * that one has no quote-neutral spelling, so it takes the character the repository's own
+     * formatter config names. Absent is `"`, which is what every repository configuring nothing gets
+     * and what this file wrote before the plain-scalar rule existed.
+     */
+    yamlQuote?: YamlQuote;
+    subdir: string | null;
+    /**
+     * WHAT A RUN DOES ABOUT A SUITE THAT IS ALREADY RED, when the maintainer answered that question.
+     *
+     * Absent, or `quarantine`, writes nothing: that is what a file with no `flaky:` key already means.
+     * See `configFlakyLines`, and `askRedBaselineDoor` for the one place this is answered.
+     */
+    flaky?: "quarantine" | "strict";
+    /**
+     * THE ANSWER TO "MAY ABLOH INSTALL THE COVERAGE PROVIDER", when there is one.
+     *
+     * Absent writes no line, which is what `install` already means - see
+     * {@link EnvironmentConfig.coverageProvider}. It is written for BOTH answers all the same when
+     * somebody gave one, because a recorded answer is the difference between a maintainer who chose
+     * the default and one who was never asked.
+     */
+    coverageProvider?: CoverageProviderChoice;
+    /**
+     * WHERE THIS REPOSITORY'S SETUP SCRIPT LIVES, when it is not where `init` puts one.
+     *
+     * Absent means {@link SETUP_SCRIPT_PATH}, which is every repository `init` created. A repository
+     * being RECONFIGURED may declare its own path in `environment.setup`, and that path is the one
+     * every cold run already executes - so a re-run reads its steps from there and writes them back
+     * there. Re-pointing the key at our default would leave their file on disk, unread, with nothing
+     * saying so.
+     */
+    setupPath?: string;
+    /**
+     * THE INSTALL COMMAND RESOLVES RATHER THAN INSTALLING A FROZEN SET, because this repository will
+     * not carry a lockfile (census run 7 F3).
+     *
+     * It decides the install step's own description alone - {@link STEP_WHAT.installUnlocked} - and
+     * writes no `abloh.yml` key: the command and the evidence beside it already carry the fact into
+     * the file, and a key nobody answers is a key nobody edits. Absent is the ordinary frozen install,
+     * which is every repository that commits a lockfile.
+     */
+    installUnlocked?: boolean;
+    /**
+     * `.github/workflows/ci.yml::unit` - the customer's own job the Abloh step rides, or null.
+     *
+     * WHY THE CONTRACT CARRIES IT. The borrow lane appends one step to one of their jobs, and
+     * self-healing job selection moves that step between jobs until a trial proves one
+     * (`packages/core/src/setup-healing.ts`). The winning job is then a fact that has to survive, and
+     * the tree is the only place that does: the receipt a green trial earns is a digest over this
+     * file, so a contract naming no job would bind evidence to a measurement whose most consequential
+     * input is unstated. It is also the key a maintainer edits to move the step by hand, which means
+     * abloh writing it and them changing it are one mechanism rather than two.
+     *
+     * NULL ON THE FALLBACK ROAD AND ON AN AMBIGUOUS READ. Abloh's own workflow rides no job of theirs,
+     * and a tie is the one case where the whole design says abloh will not pick - writing a key for
+     * either would commit a guess the surrounding copy promises not to make.
+     */
+    setupJob?: string | null;
+    /**
+     * THE MATRIX LEG {@link setupJob} RIDES, when the job that won fans out.
+     *
+     * SAME RULE AS THE JOB AND FOR THE SAME REASON. The step abloh appends carries an `if:` that is
+     * true on this leg alone, so which leg was measured is as consequential an input as which job, and
+     * the receipt is a digest over the file that has to state it.
+     */
+    setupMatrixLeg?: SetupMatrixLeg | null;
+    /**
+     * WHAT THE MAINTAINER ANSWERED ABOUT THE RIDDEN JOB CANCELLING ITS OWN MATRIX LEGS.
+     *
+     * NOT THE SAME RULE AS THE JOB AND THE LEG, and the difference is who said it. Those two are
+     * abloh's derivation and are written only where abloh proved them; this is the maintainer's own
+     * answer to a question abloh asked, so it is written wherever they gave one - the same exception
+     * `configSetupJobLines` already makes for a leg they named.
+     */
+    setupFailFast?: SetupFailFast | null;
+    /**
+     * WHAT ABLOH COULD NOT READ WHILE PLACING ITS STEP INSIDE {@link setupJob}, one sentence each.
+     *
+     * See `configSetupJobLines` and `setup-step-anchor.ts`. It is a fact about the job the contract
+     * names, so it travels with the job rather than being re-derived by whoever renders the file.
+     */
+    setupStepUnreadableConditions?: readonly string[];
+    /**
+     * WHAT THE LAST TWO QUESTIONS IN THE WALK ARE ABOUT - the job abloh rides and its matrix.
+     *
+     * Not `abloh.yml` values in themselves: `setupJob` above is the key, and this is the pair of facts
+     * the PROMPT needs, which are the receipt and the legs. Same reason `boundRunner` sits beside
+     * `runner` one screen up - the walk's prompts are derived from this object and a prompt has to
+     * show the answer the run reaches rather than the key the file happens to carry.
+     */
+    setupQuestions?: SetupDraftValues;
+    /**
+     * THE PROOF IMAGE THIS CONTRACT PINS, or null when the drafting road could not resolve one.
+     *
+     * `init` ALWAYS RESOLVES ONE, by pulling an image whose Node major matches what the repository
+     * declares, so on that road this is always a string. The App door has no machine to pull with, and
+     * writing the reviewed DEFAULT instead would pin Node 22 into a repository that declares Node 24 -
+     * a wrong answer nothing downstream could see. Null writes no key, which is what a repository that
+     * pins nothing already means: the run resolves the default at run time and the maintainer is asked.
+     * `receiptLines` already skips a null value, so the renderer needs no branch for it.
+     */
+    runtimeImage: string | null;
+    /**
+     * WHICH NODE THE GENERATED WORKFLOW PINS, resolved from the repository's own declaration.
+     *
+     * Here rather than re-derived inside `renderWorkflow` because the draft has to be able to SHOW the
+     * workflow before it writes it, and a value read twice from a tree that may have changed between
+     * the two reads is two answers. See {@link workflowNodePin} for the preference order and for the
+     * `shardeum/shardeum` row that made it a ruling.
+     */
+    workflowNode: WorkflowNodePin | null;
+    /**
+     * Extra runtimes the proof image must carry beyond node, each with the file that asked for it.
+     * Empty for almost every repository; see `runtime-needs.ts` for the two that are not.
+     */
+    runtimes: readonly RuntimeNeed[];
+    /**
+     * The browser this repository's suite drives, with the files that said so, or null for the great
+     * majority that drive none.
+     *
+     * DRAFTED FROM TWO DECLARATIONS AND NEVER FROM A NAME. `browser-lane.ts` requires a vitest config
+     * that enables browser mode AND a manifest that depends on `@vitest/browser`; round 5's census
+     * (M17) is what made both facts mandatory, having reported a browser lane on `kaitranntt/ccs`
+     * whose whole evidence was a script called `test:e2e`.
+     */
+    browser: {
+        value: "chromium";
+        evidence: readonly string[];
+    } | null;
+    testCommand: string | null;
+    /**
+     * THE RUNNER THE FILE DECLARES, or null when the file leaves detection to answer.
+     *
+     * WRITTEN ONLY WHERE IT SAYS SOMETHING (audit F2, and the same restraint every other derived key
+     * here follows). A repository whose command names its runner unambiguously gets no `runner:` line:
+     * the key would restate what `bindPreparedTestCommand` reads off that command anyway, and a file
+     * full of lines that change nothing is a file nobody reviews. What earns the line is a repository
+     * where abloh DISCARDED a candidate - pino's five-stage chain - or where the maintainer answered
+     * the prompt themselves.
+     */
+    runner: string | null;
+    /**
+     * THE RUNNER THE RUN WILL BIND, whether or not the file declares one.
+     *
+     * NOT AN `abloh.yml` VALUE, and it is here for the same reason `sealedPromptEvidence` and
+     * `testCommandCostNote` are: the walk's prompts are derived from this object, and the prompt for
+     * this key has to show the answer the run reaches rather than the key the file happens to carry.
+     * A repository whose command names vitest shows `vitest` and writes no line, which is the true
+     * pair; showing the file's null there would be an empty prompt on a repository with no question.
+     *
+     * `"command"` IS THE ONE VALUE THAT MEANS THE PROMPT IS EMPTY - see `ScalarDraftValues.runner`.
+     */
+    boundRunner: string;
+    /** Did abloh discard a candidate runner here? Decides the prompt's weight and nothing else. */
+    runnerContested: boolean;
+    installCommand: string | null;
+    /**
+     * The build steps this repository's own CI runs between install and test, each with the workflow
+     * job it was read out of. Empty for the repositories whose CI declares no build, which is most of
+     * them, and empty whenever the CI could not be read - see `ci-recipe.ts` for why a refusal there
+     * is the product rather than a failure.
+     */
+    setupCommands: readonly CiSetupCommand[];
+    /**
+     * The literal values this repository's own CI gives the step that installs it.
+     *
+     * Rendered with the install step in the setup script, because that is the only thing that
+     * delivers a value there. See {@link CiRecipe.installEnvironment}.
+     */
+    installEnvironment: ReadonlyArray<{
+        name: string;
+        value: string;
+    }>;
+    /**
+     * The PINNED OS packages this repository's own CI installs, each with the workflow job it came
+     * from. Empty for nearly every repository, and empty for a repository whose CI installs system
+     * libraries WITHOUT pinning them - which is nearly all of the ones that install any. The unpinned
+     * case is reported as a notice naming the packages and the pin, never written; `ci-recipe.ts`
+     * carries why an unpinned entry cannot be a recipe line.
+     */
+    systemPackages: readonly ConfigSystemPackage[];
+    sealedTestCommand: string | null;
+    /**
+     * THE COMPILE THIS REPOSITORY PAYS PER PLANTED MUTANT, or null for the repositories - nearly all
+     * of them - whose tests are about the files they change.
+     *
+     * PRESENT WITH A NULL `value` IS ITS OWN STATE and is not the same as absent: it means abloh found
+     * that the tests read compiled output and found more than one declared build script, so the file
+     * carries the finding, names the candidates and leaves the key out. A run of such a repository
+     * still reports false survivors until somebody answers, and a file that said nothing about it
+     * would leave them no reason to look.
+     */
+    rebuild: RebuildDraftValue | null;
+    installDirectory: string;
+    identityFiles: readonly string[];
+    /**
+     * Files this repository's own test boot writes into the checkout, each with the evidence for it.
+     * See `framework-run-outputs.ts`: without the declaration such a run measures correctly and is
+     * then refused for having changed the checkout.
+     */
+    generatedFiles: readonly {
+        path: string;
+        evidence: string;
+    }[];
+    /**
+     * TRACKED files this repository's own install rewrites, each with the evidence for it.
+     *
+     * DERIVED AND NEVER ASKED. The reading is `observed-install-outputs.ts`: abloh runs the
+     * repository's own install once in a throwaway checkout of HEAD and asks git which COMMITTED
+     * files came back different. That is a fact about their install rather than a preference, so
+     * there is no prompt for it - what a maintainer does with the line is read it in the draft, check
+     * it against their own `prepare` script, and delete it if it is wrong.
+     *
+     * A TEST FILE IS NEVER DRAFTED HERE, because `rewritten-files.ts` refuses one at the run and a
+     * key init wrote that the run then refuses is the promise this product has already paid for
+     * twice.
+     */
+    rewrittenFiles: readonly {
+        path: string;
+        evidence: string;
+    }[];
+    /**
+     * Literal, NON-SECRET `NAME: value` pairs this repository's own CI declares, each with the
+     * workflow line it came from.
+     *
+     * EMPTY UNTIL SOMETHING FILLS IT. `init`'s own derivation - package.json, lockfile, Dockerfile -
+     * has no workflow reader in it, so nothing here comes from this file today. It is the shape the
+     * CI-recipe translator writes into, and it is separate from `requiredVariables` for the reason
+     * `config.ts` gives at the key: a value here is committed and a name there is injected, and the
+     * customer has to be able to see which of the two they are getting.
+     */
+    environmentValues: readonly {
+        name: string;
+        value: string;
+        evidence: string;
+    }[];
+    /**
+     * Environment-variable NAMES the suite needs and this file must never carry values for, each with
+     * the workflow line that asked for it.
+     *
+     * The other half of the 2026-08-25 split. A name here is injected from the caller's own
+     * environment at run time and masked out of every captured line; a value under
+     * `environmentValues` is committed and disclosed to everyone who can read the repository. The
+     * translator decides which of the two a workflow line is (`ci-recipe.ts`), and the customer sees
+     * both lists before either is written.
+     */
+    requiredVariables: readonly {
+        name: string;
+        evidence: string;
+    }[];
+    /**
+     * The backing services the proof container stands up, exactly as the repository declared them.
+     *
+     * `spelling` is the prompt's spelling of the same entry - `db=postgres:16` - and reaches the file
+     * nowhere: what the file carries is the name, the pinned image, the declared environment and the
+     * readiness gate. It travels here so the walk and the rendered block cannot disagree about which
+     * services a draft has.
+     */
+    services: readonly DraftService[];
+    coverageNote?: string | null;
+    /** One sentence per derived line, naming the customer's own file it came from. */
+    evidence: {
+        runtimeImage: string;
+        installCommand: string;
+        testCommand: string;
+        /**
+         * WHY THIS RUNNER AND NOT ANOTHER, which is the half the audit found missing entirely.
+         *
+         * A receipt naming only the source - `scripts.test in package.json` - says where the value came
+         * from and not what abloh DECIDED. On pino it would have been true and useless: the jest leg is
+         * in `scripts.test`, and so is the borp stage abloh skipped. `rejectedRunnerSentence` composes
+         * the second half where there is one, for the file and the prompt alike, so an unattended init
+         * discloses exactly what an interactive one does.
+         */
+        runner: string;
+        /** Written into the file only when {@link sealedNote} says so. */
+        sealedTestCommand: string;
+    };
+    /**
+     * The `sealedTestCommand` receipt as the WALK says it, which is shorter than the file's.
+     *
+     * The file explains an absent key to a reviewer, permanently. The prompt is one line read once,
+     * with its weight beside it already saying what enter costs. See `sealedSuggestion`.
+     */
+    sealedPromptEvidence: string;
+    /**
+     * WHAT A GENERIC-ADAPTER DEMOTION COSTS, appended to the `testCommand` receipt in BOTH the file
+     * and the prompt, or null for the repositories that are not demoted - which is nearly all of them.
+     *
+     * IT USED TO BE THE PROMPT'S ALONE, and that is what made it unreachable: the prompt is walked
+     * only by a human, and the census, an agent, a control plane and `--yes` all write the file
+     * without one. See {@link genericAdapterCost} for the measured cost of that, and
+     * {@link testCommandReceipt} for the one composition both surfaces read.
+     */
+    testCommandCostNote?: string | null;
+    /**
+     * Is an absent `sealedTestCommand` the right answer for this repository, or merely the one nothing
+     * could be derived? Decides the prompt's weight and nothing else. See `sealedSuggestion`.
+     */
+    sealedTestCommandNeeded?: boolean;
+    /**
+     * THE EXAMPLE THE EMPTY `sealedTestCommand` PROMPT ENDS WITH, spelled for THIS repository's runner.
+     *
+     * Null where there is no runner to name - a task-runner root, whose absent key is by design. The
+     * walk used to print a constant vitest command at every repository, which is the
+     * audit's Finding 16: the one line a customer copies the spelling from named the wrong runner on
+     * every jest, mocha and bun repository there is.
+     */
+    sealedPromptExample?: string | null;
+    /**
+     * The `sealedTestCommand` comment, or null to write none.
+     *
+     * A key absent because nothing calls for it needs no explanation in the file. A key absent while
+     * the repository's script really does gate its runner needs one, because that absence is a live
+     * cause of every proposed test being rejected and nothing else would say so.
+     */
+    sealedNote: string | null;
+}
+/**
+ * The part `init` alone can work out: where the project is and how to rebuild it.
+ *
+ * Kept separate from the settings above because this is the half that gets APPENDED to a policy
+ * file somebody already has. `installCommand` is the load-bearing line — the fix loop refuses to
+ * start without it, before the first model call, so a run with no install command produces findings
+ * and no proposed tests.
+ *
+ * EVERY DERIVED LINE CARRIES ITS EVIDENCE as a comment above it. A value a machine worked out and a
+ * value somebody typed look identical in YAML, and the whole point of a drafted file is that the
+ * customer can check the working. Naming the file it came from - `pnpm-lock.yaml`, the FROM line in
+ * `docker/Dockerfile` - is what makes "is this right?" a question they can answer in ten seconds
+ * rather than a question about Abloh.
+ */
+/**
+ * Wrap one evidence sentence into `#` comment lines at the given indent, without breaking words.
+ *
+ * The width is 108 rather than 96 because of Kenneth's compact ruling (2026-08-23): every receipt
+ * below is written to fit on ONE line, and a narrower wrap would turn a one-sentence receipt back
+ * into a two-line paragraph purely by folding it. The wrap still exists because some receipts name
+ * a customer's own path, and a deep monorepo path has no length we get to choose.
+ */
+declare function commentLines(text: string, indent: string, width?: number): string[];
+/**
+ * The `environment:` block as it will appear in the customer's file.
+ *
+ * EXPORTED for its tests and for the CI-recipe hook: what this renders is what gets committed, so
+ * the lines are worth asserting on directly rather than through a whole `init` run.
+ */
+declare function renderEnvironmentBlock(input: ConfigInput): string[];
+/**
+ * The whole created file. The coverage note LEADS when it exists (Kenneth, 2026-08-24: it is the
+ * one line that tells a customer their changed lines cannot be attested yet, and it was buried
+ * mid-file). The environment block keeps the note for the EXTENDED path, where an existing file's
+ * lines cannot be moved and the appended block is the only place the note can go.
+ */
+declare function renderConfig(input: ConfigInput): string;
+/**
+ * THE WORKFLOW, WRITTEN RATHER THAN COPIED.
+ *
+ * It used to be the customer's job: the setup panel printed the file and they pasted it into a path
+ * they had to create. That is the step people got wrong — not the Abloh line, which is three lines,
+ * but the build and install steps above it, which have to match the job their tests already pass in.
+ *
+ * `init` has just worked out the install command for the environment block, so it is the one place
+ * that knows them. Writing the file here means the only thing a customer types is one command.
+ *
+ * THE PIN IS A COMMIT, NOT A TAG, and it is baked into this CLI. A copy of `abloh init` installed
+ * months ago therefore writes a months-old Action. `npx` fetches the newest CLI, which is the common
+ * path, but a cached or version-pinned one does not — the file it writes looks perfectly correct and
+ * runs an old Action with no signal. Reading the recommended pin from the control plane at run time,
+ * falling back to the constant when offline, is the fix; it is not built yet.
+ *
+ * The file's body and its pin are `@abloh/core`'s, for the same reason the policy header is: the
+ * website's setup panel prints the same workflow, and a second copy here is a second thing to
+ * remember to change on a release.
+ */
+declare function renderWorkflow(input: ConfigInput): string;
+/**
+ * The `testCommand` receipt, composed ONCE for the file and the prompt.
+ *
+ * They were two compositions of the same two strings, in two functions, and only one of them ran on
+ * an unattended init. A reader who is told at a prompt what a value costs and then finds no trace of
+ * it in the file they commit has been told twice that two different things are true.
+ */
+declare function testCommandReceipt(input: {
+    evidence: string;
+    cost?: string | null;
+}): string;
+/**
+ * One service on a draft: what the repository declared, with its tag pinned.
+ *
+ * `spelling` is the prompt's line and nothing else. `image` is the only field abloh added, and
+ * `evidence` is the sentence saying which file the rest came from.
+ */
+interface DraftService {
+    name: string;
+    spelling: string;
+    image: string;
+    env: readonly {
+        name: string;
+        value: string;
+    }[];
+    healthCommand: string | null;
+    healthPort: number | null;
+    /** Where a run reaches it, when that is not the port it listens on. See `service-ports.ts`. */
+    localhostPort?: number | null;
+    source: string;
+    evidence: string;
+}
+/**
+ * The one comment line that opens every `environment:` block this command writes.
+ *
+ * A constant because a re-run has to RECOGNIZE it: the block is replaced from its own `environment:`
+ * line down, and a header left stranded above the replacement appears twice in the customer's file.
+ */
+declare const ENVIRONMENT_BLOCK_HEADER = "# Rebuild recipe for the proof container. Comments name the source file.";
+/**
+ * WHAT ABLOH READ ABOUT THE JOB ITS STEP RIDES, as the contract will state it.
+ *
+ * Declared here for the reason {@link RuntimeNeed} and {@link RebuildDraftValue} are: the walk in
+ * `init-questions.ts` asks about these values and this file writes them, so the shape is the thing
+ * those two have to agree on rather than a type one of them owns.
+ */
+interface SetupDraftValues {
+    job: {
+        value: string | null;
+        evidence: string;
+    } | null;
+    legs: readonly {
+        dimension: string;
+        offered: readonly MatrixValue[];
+        evidence: string;
+    }[];
+}
+/**
+ * THE FOUR STEP DESCRIPTIONS `init` ITSELF WRITES, and the key each one is generated from.
+ *
+ * They are constants because a re-run has to be able to tell ITS OWN steps from the customer's. A
+ * step whose description is not one of these four was written by a person or by their coding agent,
+ * and a regeneration carries it through untouched (see {@link mergeSetupSteps}). Spelling one of
+ * these differently here and in the merge would silently turn every customer's install step into a
+ * step abloh no longer recognizes, so there is one spelling.
+ */
+declare const STEP_WHAT: {
+    readonly systemPackages: "OS packages your suite needs, pinned";
+    readonly corepack: "put the package manager on PATH, for your own lifecycle scripts";
+    readonly install: "dependencies, from your lockfile";
+    /**
+     * THE SAME STEP ON A REPOSITORY THAT CARRIES NO LOCKFILE (census run 7 F3, 2026-09-06).
+     *
+     * A SECOND SPELLING RATHER THAN A REWORD, on the rule above: `install`'s exact text is what a
+     * re-run recognizes as its own step, so changing it would orphan every install step already
+     * committed. Both are install steps to {@link initStepRole} and to {@link isInstallStep}, which is
+     * what every reader asks instead of comparing against one of them.
+     *
+     * IT EXISTS BECAUSE THE OTHER ONE WOULD BE FALSE. `fastify/fastify` and `pinojs/pino` both
+     * `.gitignore` their lockfile, so the drafted step resolves rather than installing frozen, and a
+     * comment saying "from your lockfile" above a command that has none is a claim the file cannot
+     * back. The `source` beside it names the ignore rule.
+     */
+    readonly installUnlocked: "dependencies, resolved - your repository commits no lockfile";
+    readonly build: "your build";
+};
+/** Whether a step is the install step `init` writes, in EITHER of its two spellings. */
+declare function isInstallStep(what: string): boolean;
+/**
+ * WHO WROTE A STEP: abloh where its description is one {@link STEP_WHAT} carries, the maintainer
+ * otherwise.
+ *
+ * IT IS THE MERGE'S OWN READING AND NOT A SECOND ONE. {@link mergeSetupSteps} already treats those
+ * four descriptions as abloh's own and carries everything else through untouched, so a refusal that
+ * asked a different question would name a different author from the one the re-run acts on.
+ *
+ * WHY A RUN NEEDS IT (census run 8's F1, and the ownership audit's finding 1). A cold run executes
+ * this file and `setup-step-failed` declares an abloh arm that no producer supplied, so a step abloh
+ * composed from the maintainer's own CI failed and was filed against the maintainer. It fails
+ * towards the customer: a description this does not recognise is theirs, which is the owner that
+ * refusal has always carried.
+ */
+declare function setupStepOrigin(step: {
+    readonly what: string;
+}): ValueOrigin;
+/** Which environment key a step was generated from, or null for a step `init` did not write. */
+declare function initStepRole(what: string): "systemPackages" | "installCommand" | "setupCommands" | null;
+/**
+ * THE SETUP SCRIPT'S STEPS, from the same derivation that used to fill four config keys.
+ *
+ * WHAT CHANGED ON 2026-08-26, and what did not. The reading is unchanged: the same lockfile, the
+ * same `packageManager` field, the same workflow job, the same answers a customer gave at the walk.
+ * What changed is where the answer LANDS. It used to be config that abloh re-derived into an image
+ * recipe at every run; it is now a file in the customer's repository that a run executes.
+ *
+ * THE ORDER IS THE ORDER THINGS HAPPEN IN, and it is the order the image already built them in:
+ * system libraries first, because a native module compiles DURING the install and a header that
+ * arrives afterwards arrives too late; then corepack, because a package manager has to be on PATH
+ * before the repository's own lifecycle scripts call it; then the frozen install; then whatever the
+ * repository's own CI builds between installing and testing.
+ *
+ * EVERY STEP NAMES ITS SOURCE, which is the whole reason a customer can ratify this file in ten
+ * seconds rather than take it on trust.
+ */
+/**
+ * THE ONE SETUP STEP THAT INSTALLS OS PACKAGES, or null when this repository declares none.
+ *
+ * SPLIT OUT BECAUSE IT IS REBUILT AFTER THE FILE IS WRITTEN (the captain's ruling of 2026-09-10).
+ * `abloh init` now writes and commits the contract BEFORE it builds the proof image, so a library
+ * the suite proves it needs arrives after the script is on disk - and the amend that puts it there
+ * has to compose exactly the step this function composes, or the file a maintainer ratified and the
+ * file a run executes would be two different renderings of one list.
+ *
+ * IT READS NOTHING BUT THE LIST, which is what makes that safe: the step's text is a function of the
+ * pinned packages alone.
+ */
+declare function systemPackagesStep(pinned: readonly ConfigSystemPackage[]): SetupScriptStep | null;
+declare function setupScriptSteps(input: ConfigInput): SetupScriptStep[];
+
+/**
+ * WHERE AN ANSWER IS APPLIED, because three of them are not values in the contract at all.
+ *
+ * `contract` answers change the drafted `abloh.yml`. `discovery` answers move what the whole
+ * contract is DERIVED FROM, so they go back through the drafting rather than being written over its
+ * result: the job to ride and the leg of its matrix decide which job the recipe, the services and
+ * the environment values are read out of, and the package to measure decides which manifest the
+ * runner and the test command are read out of. A value written over the rendered file would leave
+ * every sibling line derived from the old one, which is the shape AGENTS.md's self-healing row
+ * already states - "a pin re-derives the WHOLE recipe".
+ */
+type SetupAnswerChannel = "contract" | "discovery";
+/** How a maintainer's TEXT becomes the shape the key takes. */
+type SetupAnswerShape = 
+/** One value, written as typed. */
+{
+    kind: "scalar";
+}
+/** Comma-separated entries, blank entries dropped. */
+ | {
+    kind: "list";
+}
+/** `&&`-separated commands, which is how a build reads top to bottom. */
+ | {
+    kind: "commands";
+}
+/** Comma-separated `name=version`, the version optional. */
+ | {
+    kind: "packages";
+}
+/** Comma-separated `NAME=value`. */
+ | {
+    kind: "pairs";
+}
+/** Comma-separated names. */
+ | {
+    kind: "names";
+}
+/**
+ * Comma-separated `name=image:port`, the image immutable-pinned and the port its readiness gate.
+ *
+ * THE WHOLE ENTRY, because the contract holds no half of one. `abloh init` accepts `db=postgres:16`
+ * and then resolves the digest and the exposed port off a registry, which is a machine reading and
+ * not a file one; this door has no machine, so what it takes is what the file will hold. A value
+ * it could not judge would be a form that writes a line the loader refuses one command later.
+ */
+ | {
+    kind: "services";
+};
+interface SetupQuestionDescriptor {
+    /** The `abloh.yml` key the answer is written under. The form and the file agree by construction. */
+    key: string;
+    /** What is being asked, in one line. */
+    ask: string;
+    /** Why abloh is asking, where the run has said nothing more specific. */
+    why: string;
+    /** The values the contract accepts, where they are a closed set. Empty is a free field. */
+    candidates: readonly string[];
+    required: boolean;
+    /**
+     * ASKED OF EVERY REPOSITORY, because no reader can establish this value at all.
+     *
+     * The rest are values discovery either settles or believes irrelevant, so they are hidden until a
+     * stopped stage names one.
+     */
+    unreadable?: true;
+    shape: SetupAnswerShape;
+    channel: SetupAnswerChannel;
+    /**
+     * HOW AN ACCEPTED VALUE CHANGES THE DRAFTED CONTRACT.
+     *
+     * Absent exactly for the `discovery` channel, whose answers move what the contract is derived
+     * FROM rather than a line in it. Every `contract` descriptor has one, and
+     * `scripts/setup-answer-application.test.ts` is what keeps that true.
+     */
+    apply?: (draft: ConfigInput, answer: string) => ConfigInput;
+}
+/** The entries in a list answer, blanks dropped. One grammar, read by both lanes. */
+declare function splitAnswerList(shape: SetupAnswerShape, raw: string): string[];
+/**
+ * THE VALUE THE KEY IS SET TO, out of what the maintainer typed.
+ *
+ * The shape decides the JavaScript value; `judgeConfigKeyValue` decides whether the key may hold it.
+ */
+declare function readAnswerValue(descriptor: SetupQuestionDescriptor, raw: string): unknown;
+/** What is wrong with this answer to this question, or null. The one door both lanes ask. */
+declare function setupAnswerProblem(key: string, raw: string): string | null;
+/**
+ * THE ANSWERS APPLIED TO ONE DRAFTED CONTRACT, in declaration order.
+ *
+ * An answer for a key with no descriptor is not applied and not silently swallowed either - the
+ * caller admitted it or refused it before this ran, through {@link setupAnswerProblem}. This
+ * function is the second half of that door and never a second door.
+ */
+declare function applyAnswersToContract(draft: ConfigInput, answers: Readonly<Record<string, string>>): ConfigInput;
+/** WHAT ABLOH SAYS ABOUT A VALUE SOMEBODY TYPED, on every receipt line an answer wrote. */
+declare const ANSWERED_EVIDENCE = "you answered this when you set abloh up";
+/**
+ * ---------------------------------------------------------------------------------------------
+ * THE TABLE.
+ * ---------------------------------------------------------------------------------------------
+ *
+ * Every key here is one `abloh init` already asks about - `apps/cli/src/init-question-map.ts` is
+ * that inventory and `scripts/setup-question-placement.test.ts` pins the two together - because
+ * there is ONE fixed list of questions and both doors onto one contract ask from it.
+ */
+declare const SETUP_QUESTION_DESCRIPTORS: Readonly<Record<string, SetupQuestionDescriptor>>;
+/**
+ * EVERY KEY AN ANSWER OR AN EDIT MAY NAME, derived rather than listed.
+ *
+ * A key not here is not offered as a field, rather than being accepted and dropped - which is the
+ * whole of F1 said as one sentence.
+ */
+declare const ANSWERABLE_SETUP_KEYS: readonly string[];
+/** The descriptors whose answers change the drafted contract, in declaration order. */
+declare function contractDescriptors(): readonly SetupQuestionDescriptor[];
+/** The package a maintainer asked abloh to measure, or undefined. Read before the derivation. */
+declare function answeredTargetDirectory(answers: Readonly<Record<string, string>>): string | undefined;
+
+/**
+ * HOW THIS MODULE GETS BYTES, since the captain's ruling of 2026-09-05.
+ *
+ * It opened files itself until then, which put a checkout in the middle of a decision the service
+ * has to make over GitHub's contents API with no checkout at all - see `packages/core/src/repo-reader.ts`.
+ * The caller supplies the reading and the deciding stays here, so both doors decide alike.
+ *
+ * The parameter takes an ABSOLUTE path and answers text or nothing, because that is the vocabulary
+ * `detect.ts` speaks and this module is called from nowhere else. It defaults to `node:fs` so every
+ * other caller of {@link denoLockfilePath} is unchanged.
+ */
+type ReadTextAt = (absolutePath: string) => string | null;
+/** The two names deno itself looks for, in deno's own precedence order. */
+declare const DENO_CONFIG_FILES: readonly ["deno.json", "deno.jsonc"];
+/** Deno's lockfile. Present far less often than a node lockfile - see {@link denoLockfilePath}. */
+declare const DENO_LOCKFILE = "deno.lock";
+interface DenoProject {
+    /** Which of {@link DENO_CONFIG_FILES} declared it, repository-relative to the project directory. */
+    configFile: string;
+    /** The body of `tasks.test`, verbatim, or null when the project declares no test task. */
+    testTask: string | null;
+    /**
+     * The single `deno test` stage of that task, verbatim, when the task has exactly one and is a
+     * plain `&&` chain. Null when the task is composed some other way, names deno in zero or more
+     * than one stage, or is not a `deno test` at all - in which case the run falls back to
+     * `deno task test`, which is always correct and merely opaque.
+     */
+    testInvocation: string | null;
+}
+/**
+ * The one `deno test` stage of a task body, or null when there is not exactly one to take.
+ *
+ * Mirrors `runnerInvocation` in `detect.ts` stage for stage, including its refusals: anything that
+ * is not a plain `&&` chain is left alone, because the fallback (`deno task test`) reproduces the
+ * whole task and a partial reading of it would not.
+ */
+declare function denoTestInvocation(taskBody: string | null): string | null;
+/**
+ * Read a directory's deno declaration, or null when it declares nothing this run can act on.
+ *
+ * A `deno.json` with no `tasks.test` yields null rather than a project with a null task: deno's own
+ * `deno test` discovers `*_test.ts` and friends by convention, so such a repository MIGHT be
+ * testable - but nobody wrote down that it is, and inventing `deno test` for a config file that
+ * exists only to set `nodeModulesDir` would claim a suite the author never declared. The honest
+ * answer stays `TargetNotFoundError`, exactly as an npm package with no `test` script gets.
+ */
+declare function readDenoProject(dir: string, readText?: ReadTextAt): DenoProject | null;
+/** The deno lockfile a directory commits, or null. Absence is what refuses a frozen install. */
+declare function denoLockfilePath(dir: string, readText?: ReadTextAt): string | null;
+/**
+ * Does a `package.json` test script run deno's own runner?
+ *
+ * The HYBRID row, and it is the one shape this answers for. A repository whose `scripts.test` is
+ * `deno test -A` classified as the generic `command` runner before 2026-08-18, which cost it Layer
+ * 0, per-test attribution and the whole v2 engine over a spelling: it is the same suite a pure deno
+ * repository declares, written in the other file. Mirrors `usesBun` in `classifyPackageManifest`,
+ * which exists for exactly the same reason one runtime over.
+ */
+declare function scriptRunsDenoTest(testScript: string | null): boolean;
+
+/**
+ * Workspace AGGREGATORS - turbo, lage and nx - and the one monorepo shape whose packages are not
+ * declared in a manifest at all.
+ *
+ * TWO FACTS, ONE FILE, because they are the two halves of the same question. A repository whose
+ * root `scripts.test` is `turbo run test` has not told us how to run a suite; it has told us that
+ * every package runs its own. So the aggregator's name is a routing fact (this root is not a
+ * runner - go and measure the packages), and for the Nx flavour that declares no `workspaces` the
+ * package list has to come from somewhere other than the root manifest.
+ *
+ * WHY THE AGGREGATOR IS NOT A RUNNER, and why leaving it to classify as the generic `command`
+ * adapter was wrong in two directions:
+ *
+ *   1. it MEASURES THE WHOLE REPOSITORY. `npm test` at the root of a Turborepo runs every
+ *      package's suite through one process tree, so Stryker's command runner re-runs all of them
+ *      per mutant and diff coverage has no single provider to read - the exact shape the multi-suite
+ *      fanout work refused for `vitest a && vitest b`, one level up: packages compose the way
+ *      suites do.
+ *   2. it can be READ AS A RUNNER BY ACCIDENT. `runnerNamesInScript` looks for a runner binary
+ *      anywhere in the script, and `turbo run test --filter=./packages/jest` ends in the bare token
+ *      `jest` behind a path separator, which is exactly the shape that function admits. That
+ *      repository would have classified as a direct jest project and had jest's coverage flags
+ *      appended to a turbo invocation.
+ *
+ * So an aggregator invocation is recognised BEFORE any runner name is looked for, and a package
+ * whose test script is one classifies as no runner at all - the same treatment `npm-run-all`
+ * already gets in {@link classifyPackageManifest}, for the same reason.
+ *
+ * PACKAGE-BASED MONOREPOS ARE UNAFFECTED BY DESIGN. A root that declares `workspaces` (or a
+ * `pnpm-workspace.yaml`) already rides per-package composition, whatever aggregator its scripts
+ * name - the aggregator is ignored, and that is the correct outcome, not an oversight. What is new
+ * here is the INTEGRATED Nx flavour, which declares no `workspaces` field at all: its projects are
+ * declared one `project.json` at a time and the root carries `nx.json`. Without a reader for that
+ * shape the selector found no workspace definition, skipped, and the run fell back to measuring the
+ * aggregator command at the root.
+ *
+ * THE THIRD WORKING DIRECTORY, added 2026-08-16. An integrated-Nx project declares its suite through
+ * an executor Nx runs FROM THE WORKSPACE ROOT against a root-relative config, and per-package
+ * composition had only two positions for a working directory - the repository root, measuring the
+ * repository, or a package's own directory, measuring that package. So those projects were honest
+ * excluded rows. {@link WorkspaceRootSuite} is the third position: the runner runs where the
+ * declaration says it runs, and the measurement is scoped to the project directory. It is keyed on
+ * that structural fact and never on the name of the tool that produced it.
+ *
+ * Everything here is fail-closed. A script that is not exactly one aggregator invocation is not an
+ * aggregator, an `nx.json` that does not parse yields no projects, and a project whose test target
+ * this file cannot drive is named as unmeasurable rather than guessed at.
+ */
+/** The three workspace task runners. `nx` covers both flavours; the flavour is a separate fact. */
+type AggregatorTool = "turbo" | "lage" | "nx";
+interface AggregatorInvocation {
+    tool: AggregatorTool;
+    /**
+     * The task names the invocation selects, when they are stated positionally or through nx's
+     * `-t`/`--target`. Empty when the invocation selects its tasks some other way (an nx
+     * `run-many` with no target reads its own default) - the tool is still the routing fact.
+     */
+    tasks: string[];
+}
+/**
+ * The aggregator a test script invokes, or null when it invokes none.
+ *
+ * ONE STAGE ONLY, deliberately. A script that composes an aggregator with anything else
+ * (`nx run-many -t lint && nx run-many -t test`, `turbo run test | tee log`) is left to the
+ * existing fanout and gate machinery, which already reads chains; claiming the aggregator for a
+ * composed script would take a routing decision on a script this file has not read whole.
+ */
+declare function aggregatorInvocation(testScript: string | null): AggregatorInvocation | null;
+/**
+ * The tasks half of an aggregator invocation, as one printable phrase for a refusal message.
+ *
+ * An invocation that names no task reads its selection from configuration this file does not
+ * parse, and saying so is more honest than naming a task nobody read.
+ *
+ * COMMAS ONCE THERE ARE MORE THAN TWO, because this sentence became reachable for a long list on
+ * 2026-09-01: it was only ever produced for a directly-written `turbo run test` until the aliased
+ * root started reaching it, and TanStack/query's run-many names eight tasks. Eight joined by "and"
+ * is not a sentence anybody reads.
+ */
+declare function aggregatorTaskPhrase(invocation: AggregatorInvocation): string;
+/** One integrated-Nx project: its directory and what its own `project.json` says about testing. */
+interface NxProject {
+    /** Repository-relative project directory, never "" (the workspace root is not a project). */
+    directory: string;
+    /** The project's own name, when it declares one. */
+    name: string | null;
+    /** What the project's `test` target is, once read. */
+    test: NxTestTarget;
+}
+type NxTestTarget = {
+    state: "runner";
+    runner: string;
+    command: string;
+} | ({
+    state: "workspace-root";
+} & WorkspaceRootSuite) | {
+    state: "unmeasurable";
+    reason: string;
+    remedy: string;
+};
+/**
+ * A suite whose runner runs FROM THE WORKSPACE ROOT against a root-relative config, while the
+ * measurement it produces belongs to one project directory.
+ *
+ * THE STRUCTURAL FACT, and it is deliberately not "this repository uses Nx". Two positions used to
+ * be the whole vocabulary - a suite runs at the repository root and measures the repository, or a
+ * suite runs inside a package and measures that package. This is the third: the working directory
+ * and the measured directory are DIFFERENT, and the declaration says which is which. Nx's official
+ * executors are the first shape that produces it; nothing below reads the string "nx" to decide.
+ *
+ * Every field is what the run needs to act on it, and each is a fact somebody wrote down:
+ *  - `runner` is a runner the existing adapters already drive; an executor that maps to none stays
+ *    an excluded row, which is the boundary this mode does not widen.
+ *  - `configFile` is the workspace-root-relative config the declaration names. Never guessed: a
+ *    target that names none is excluded, because running a root-found config against one project
+ *    would measure a suite nobody selected.
+ *  - `directory` is the measured project, which is what scopes coverage, mutation and attribution.
+ *  - `declaredBy` is the executor that said so, carried for the log and the artifact.
+ */
+interface WorkspaceRootSuite {
+    runner: "jest" | "vitest";
+    /** Workspace-root-relative config file the runner is pointed at. */
+    configFile: string;
+    /** Repository-relative directory whose measurement this suite produces. */
+    directory: string;
+    /** The declaration this was read from, e.g. `@nx/jest:jest`. */
+    declaredBy: string;
+    /** The runner invocation, run from the workspace root. */
+    command: string;
+}
+/**
+ * Read one project's `test` target into the answers per-package composition can act on.
+ *
+ * A `run-commands` target whose command is one literal runner invocation AND whose `cwd` is the
+ * project's own directory is drivable exactly as a package script is - it is the same invocation,
+ * written in a different file. Everything else is named.
+ */
+declare function classifyNxTestTarget(projectJson: unknown, directory: string): NxTestTarget;
+/**
+ * Enumerate an integrated-Nx workspace's projects from the files a tree listing already has.
+ *
+ * READ THROUGH A SEAM, on purpose. Selection reads the TRUSTED merge-base tree and `abloh prepare`
+ * reads the working tree; both must enumerate identically or they desync on the same repository -
+ * the same rule `classifyPackageManifest` carries for manifests. So this function takes the path
+ * list and a reader and never touches the filesystem itself.
+ *
+ * @param paths every repository-relative path in the tree
+ * @param readFile the bytes of one path, or null when absent/unreadable
+ */
+declare function enumerateNxProjects(paths: readonly string[], readFile: (path: string) => string | null, limit: number): NxProject[];
+
+/**
+ * The tool that installs a repository's dependencies.
+ *
+ * `deno` and `rush` joined the four node package managers on 2026-08-18, and neither is a node
+ * package manager in the ordinary sense - which is the point. This union is what selects the frozen
+ * install command and what `preparation.ts` matches a lockfile against, and BOTH of those refused a
+ * fifth value outright (`no reviewed sandbox install command exists for package manager X`), so a
+ * repository installing through either tool could not be prepared at all.
+ *
+ *   - `deno` caches from `deno.lock` with `deno install --frozen --entrypoint .`, into a baked cache.
+ *   - `rush` installs from `common/config/**\/pnpm-lock.yaml` with a COMMITTED bootstrap script,
+ *     which then installs its own pinned pnpm. The lockfile is pnpm's; the command is Rush's, and
+ *     `rush.json` pins both versions - so it is Rush that owns the install, not pnpm.
+ */
+type PackageManager = "npm" | "pnpm" | "yarn" | "bun" | "deno" | "rush";
+type Runner = "jest" | "vitest" | "mocha" | "node-test" | "ava" | "tap" | "jasmine" | "bun" | "deno" | "angular-karma" | "angular-vitest" | "command";
+interface CoverageChildSuite {
+    /**
+     * Exact package.json script name this suite came from, when it came from one. Absent for a suite
+     * the script INVOKES INLINE (`vitest run -c a.ts && vitest run -c b.ts`), which has no script name
+     * to give - `testCommand` is what names such a suite to an operator.
+     */
+    script?: string;
+    /**
+     * Native runner named by that leaf script. All children in one plan use the same runner.
+     *
+     * bun and deno are excluded for the same structural reason and not for a capability one: a fanout
+     * child is a leaf of an `npm-run-all`, `concurrently` or `&&` chain declared in a package.json,
+     * and neither runtime's suites are declared there. A deno project's tasks live in `deno.json`,
+     * which has no wrapper vocabulary at all. `NATIVE_COVERAGE_RUNNERS` below is the runtime set and
+     * this type is its compile-time twin; the two must not drift.
+     *
+     * The two Angular runners are excluded on the same reasoning one step further: a child suite is a
+     * leaf SCRIPT naming its runner, and an Angular suite is never named by a script - it is named by
+     * a workspace file, per project, and `angular.json` says nothing about which of a wrapper's
+     * stages runs which project. A repository whose wrapper fans out over `ng test` stages keeps the
+     * bounded command treatment rather than getting a child plan built on a guess.
+     */
+    runner: Exclude<Runner, "command" | "bun" | "deno" | "angular-karma" | "angular-vitest">;
+    /** Package-manager invocation that preserves the leaf script's config, environment and selectors. */
+    testCommand: string;
+}
+interface TargetDetection {
+    /** package manager detected from the lockfile */
+    pm: PackageManager;
+    /** test runner: an installed vitest/jest dep, else the command fallback */
+    runner: Runner;
+    /** direct-runner invocation (bypasses lint in `npm test`), or the repo's own `test` script */
+    testCommand: string;
+    /**
+     * Set when `testCommand` carries an appended `--watch=false --watchAll=false` that the repository
+     * did not write.
+     *
+     * A rewritten test command is a thing the customer is owed an explanation for, so the fact
+     * travels rather than being inferrable only by diffing strings: `abloh init` turns it into the
+     * evidence line beside `environment.testCommand` in the file they ratify. Absent - never false -
+     * for every repository whose script exits on its own, which is nearly all of them.
+     */
+    watchModeNormalized?: true;
+    /**
+     * The one stage of that script which runs the test runner, when the script is a gated `&&` chain.
+     * The mutation engine falls back to it after Stryker's initial run fails, and nowhere else; see
+     * {@link runnerStageCommand}. Undefined when there is nothing separable to fall back to.
+     */
+    runnerStageCommand?: string;
+    /**
+     * The stages that same script runs BEFORE the runner stage, in the author's order, when running
+     * one stage alone would otherwise skip work the suite needs; see {@link preRunnerStageCommands}.
+     * Absent whenever {@link runnerStageCommand} is absent, and whenever the chain has no earlier
+     * stage of its own.
+     */
+    preRunnerStageCommands?: readonly string[];
+    /**
+     * The repository's OWN runner invocation, taken from `scripts.test` with nothing but a package-
+     * runner prefix removed, for the runners whose suite or configuration is named by the invocation
+     * rather than found by the runner itself. Forwarded to the per-test plugins and to the mutation
+     * engine's jest and mocha blocks; see {@link runnerInvocation}. Undefined when the script does
+     * not name the runner unambiguously.
+     */
+    runnerInvocation?: string;
+    /** vitest `test.dir`, read from the repo's vitest/vite config (undefined when unset) */
+    vitestDir?: string;
+    /**
+     * Where the repo's own jasmine invocation says its specs are, forwarded to the mutation engine.
+     * Undefined when the repo keeps its config where jasmine's own fallback already looks, which is
+     * the only case that needs no help; see {@link detectJasmineSuite}.
+     */
+    jasmineSuite?: JasmineSuite;
+    /**
+     * The `angular.json` test target behind `ng test`, for the two Angular runners and nothing else.
+     *
+     * Forwarded rather than re-read because three consumers need it and each would otherwise parse the
+     * workspace file again with its own rules: the mutation engine needs the PROJECT name and the
+     * BUILDER (the Stryker karma config, and the sandbox rewrite the unit-test builder needs), diff coverage
+     * needs the project name to ask for coverage, and the sealed v2 command needs it to run one spec.
+     * Undefined for every non-Angular repository.
+     */
+    angularTarget?: AngularTestTarget;
+    /** relative subdir holding the testable package.json, or null for the repo root */
+    subdir: string | null;
+    /**
+     * Absolute directory stryker/triage run in.
+     *
+     * `repoDir/subdir` for every ordinary package, and `repoDir` at the root. The ONE shape where it
+     * is neither is {@link workspaceRootSuite}: there the suite is declared to run from the workspace
+     * root while `subdir` stays the package being measured, so the two facts separate. Anything
+     * deriving a path prefix from this must derive it from `relative(repoDir, workDir)` and not from
+     * `subdir` - they are equal in every other case, and only one of them is the stryker cwd.
+     */
+    workDir: string;
+    /**
+     * Set when this package's suite is declared to run FROM THE WORKSPACE ROOT against a
+     * root-relative config, rather than from the package's own directory.
+     *
+     * WHAT IT CHANGES, and it is only ever these three things: `workDir` becomes the repository root,
+     * `testCommand` is the invocation the declaration names, and the measurement stays scoped to
+     * `subdir`. Coverage, mutation and per-test attribution are all still one package's.
+     */
+    workspaceRootSuite?: WorkspaceRootSuite;
+    /**
+     * A runner recognized from the script rather than from an installed dependency (currently "bun",
+     * whose test runner is built into the binary and so has nothing in `node_modules` to find).
+     *
+     * The artifact discloses WHICH runner was identified instead of a generic "command". It used to
+     * mean "identified but undrivable", and for bun that stopped being true on 2026-08-16: mutation
+     * now runs through `@abloh/stryker-bun-runner`, one test at a time. What remains disabled for bun
+     * is diff coverage, for a reason that is bun's rather than ours - see the bun row in
+     * `capability-registry.ts` and the copy in `BUN_DIFF_COVERAGE_NOTICE`.
+     */
+    identifiedRunner?: string;
+    /**
+     * Statically resolved native coverage plan for a bounded npm-run-all aggregate. The baseline
+     * still executes `testCommand` unchanged; this plan exists only to collect truthful diff-coverage
+     * coverage from every selected child with that child's native provider.
+     */
+    coverageChildren?: CoverageChildSuite[];
+    /** Preserve the wrapper's declared scheduling semantics during native coverage collection. */
+    coverageExecution?: "parallel" | "sequential";
+    /**
+     * Why a script that launches MORE THAN ONE suite got no coverage plan, in the operator's words.
+     *
+     * A fanout that cannot be merged is EXCLUDED AND SAID SO, never measured in part: the standing
+     * principle, and the reason this field exists rather than the run reporting the generic "no
+     * coverage provider for the command runner", which names neither the suites nor what would fix it.
+     */
+    coverageExclusion?: string;
+    /**
+     * The workspace task runner this package's `test` script delegates to, when it delegates to one.
+     *
+     * Reported rather than inferred: `turbo run test` names no suite, so the honest identity of such
+     * a root is "an aggregator", and a run that measures it is measuring every package at once. The
+     * field exists so the log and the artifact can say WHICH tool, and so per-package composition's
+     * refusals can name what the root actually is.
+     */
+    workspaceAggregator?: AggregatorTool;
+    /**
+     * The aggregator TASK this package's suite was read from, when the package declares no `test`
+     * script and the root's aggregator named a task it does declare.
+     *
+     * Reported for the same reason `workspaceAggregator` is, and for one more: `abloh init` has to
+     * know whether the runner it is looking at came from something the REPOSITORY wrote down or from
+     * a guess off an installed dependency, because a CI-derived `testCommand` is drafted over the
+     * second and must never be drafted over the first. Absent for every package whose declaration is
+     * `scripts.test`.
+     */
+    aggregatorTask?: string;
+    /**
+     * The build this package must run BEFORE its suite can see a change to its source, when its tests
+     * read compiled output rather than source.
+     *
+     * WHAT IT IS FOR, and it is one thing: mutation. Stryker writes a mutant into `src/*.ts`, and a
+     * project whose jest config roots at `lib-commonjs/` runs tests that never load it - so the mutant
+     * is invisible, the suite is green, and the verdict is SURVIVED for a mutant the suite would kill.
+     * Measured on rushstack's `libraries/node-core-library`, 2026-08-18: 10 passed / 0 failed unbuilt,
+     * 9 passed / 1 failed rebuilt. Every mutant a false survivor, and the finding handed to a customer
+     * would say their tests notice nothing when they notice everything.
+     *
+     * KENNETH RULED ON 2026-08-18 that abloh pays the compile
+     * (`abloh-deno-rush-decision-compile-then-test-mutation-rebuild`), so this travels to the mutation
+     * engine and becomes the first half of every mutant's cycle. Undefined for every ordinary package,
+     * whose tests read the source they are about.
+     *
+     * IT IS NOT USED BY DIFF COVERAGE OR THE BASELINE. Both run the suite as the repository runs it, against
+     * whatever the checkout already contains; only mutation changes a source file underneath them.
+     *
+     * IT IS NOT A RUSH FIELD ANY MORE. Until 2026-09-01 the Rush probe was the only thing that set it,
+     * which is the ruling shipped by example: every other repository of the same shape got the false
+     * survivors and had no key to correct them with (audit F8). `readsCompiledOutput` in `@abloh/core`
+     * is the general reading, `environment.rebuildCommand` is the declaration that outranks it, and
+     * Rush is now one case rather than a branch beside it.
+     */
+    rebuildCommand?: string;
+    /**
+     * WHAT SAID THIS REPOSITORY'S TESTS READ COMPILED OUTPUT, in one line naming both files.
+     *
+     * PRESENT WHENEVER THE SHAPE WAS DETECTED, INCLUDING WITH NO COMMAND BESIDE IT, and that pairing
+     * is the point: a detected shape whose build script could not be picked out is exactly the case
+     * `abloh init` has to ASK about, and a reading with no receipt is a question with no evidence in
+     * it. Absent for every repository whose suite is about the files it changes.
+     */
+    rebuildEvidence?: string;
+    /**
+     * The declared build scripts, when more than one could be the answer and nothing ranks them.
+     *
+     * TWO BUILD SCRIPTS ARE TWO DEFENSIBLE ANSWERS to "which one writes the directory the tests read",
+     * so neither is picked - the same posture `setup.job` takes on a tie. Present only alongside an
+     * absent {@link rebuildCommand}.
+     */
+    rebuildCandidates?: readonly string[];
+    /**
+     * The directory this package's suite reads instead of its source, repo-relative.
+     *
+     * IT IS A FACT ON A CUSTOMER SENTENCE and that is the whole of what it is for: a run that finds
+     * this shape and has no command to run names the directory, so the maintainer reads "your tests
+     * import from lib/" rather than "your tests import built output".
+     */
+    rebuildOutputDirectory?: string;
+}
+/**
+ * The runner a DECLARED test command names as its own binary, or null when it names none.
+ *
+ * DECLARATION-FIRST, and this is the function that makes the phrase mean something. A command a
+ * human wrote down - `--test-command` or `environment.testCommand` - is a statement about how this
+ * suite runs. When it names a runner directly, that name is a FACT about the command the run will
+ * execute, not an inference from anything else in the tree, so nothing in the tree may outrank it.
+ *
+ * IT READS ONE ARGV AND NOTHING ELSE. A prepared command has already been through
+ * `parsePreparedTestCommand`, so it is one literal command with no shell composition - there is no
+ * chain to disambiguate and no second stage to lose. A package-manager invocation (`npm test`,
+ * `pnpm run x`) names a SCRIPT here and not a runner, deliberately: the answer to what that script
+ * runs is in the manifest, which this reading does not hold. {@link bindDeclaredCommand} is the one
+ * that does, and it is what every caller deciding an ADAPTER asks.
+ *
+ * `node <path-to-runner>` IS A RUNNER, and until 2026-08-31 it was not - which made the one remedy
+ * this product offers a demotion in disguise. See {@link nodeInvokedRunner} and the note on
+ * {@link bindPreparedTestCommand} about the trap that header records as closed.
+ */
+declare function declaredRunner(argv: readonly string[]): Runner | null;
+/**
+ * {@link declaredRunner}, plus the argv WITHOUT the tokens that only stand in front of the binary.
+ *
+ * The stripped form is what a derived command must be rebuilt from: `npx jest --ci` and `jest --ci`
+ * name the same invocation, and re-prefixing the first would produce `npx --no-install npx jest`.
+ */
+declare function declaredRunnerInvocation(argv: readonly string[]): {
+    runner: Runner;
+    argv: readonly string[];
+} | null;
+/** What a declared command turned out to be, once the manifest was allowed to answer. */
+interface DeclaredBinding {
+    /** The runner that will measure it. */
+    runner: Runner;
+    /**
+     * The script text the command reached that runner THROUGH, or null when the command named the
+     * runner itself. This is what every reading of a script - the stage split, the `--config` a
+     * plugin needs, a jasmine spec list - has to be taken from, because for a hopped command the
+     * command itself says none of it.
+     */
+    script: string | null;
+    /** The script NAME of the last hop, for the lifecycle hooks the manager runs around it. */
+    scriptName: string | null;
+    /** The hops taken, outermost first. Empty when the command named its runner directly. */
+    hops: readonly CommandScriptHop[];
+}
+/**
+ * THE RUNNER A DECLARED COMMAND WILL BE MEASURED BY, reading the manifest when the command points
+ * into it. This is the one function every surface that decides an ADAPTER asks.
+ *
+ * WHY IT EXISTS, and it is the single largest defect of the 2026-08-31 ten-repository run
+ * (`data/abloh-ten-run-2/report.md` §6.1). abloh printed, to five of ten maintainers:
+ *
+ *     the baseline will report 0 executed tests ... Naming one runner directly here is what
+ *     changes that
+ *
+ * Every one of them did exactly that, out of their own `package.json`, and five were refused anyway,
+ * because the reader behind that sentence was {@link declaredRunner} - which takes the FIRST token
+ * and asks whether it is a runner. Measured over `jotai`'s frozen commit, one
+ * `abloh init --answers-file` at a time: `vitest run` and `npx vitest run` bound;
+ * `corepack pnpm vitest run` and `corepack pnpm run test:spec`, where `test:spec` is literally
+ * `vitest run`, did not. The two spellings that worked are the two abloh never writes - its own
+ * derived command on every pnpm and yarn repository in that population is `corepack pnpm test` - so
+ * a maintainer correcting abloh's command, in abloh's own idiom, was refused. Six of ten rows died
+ * there, and 243 seconds of green test execution were counted as zero.
+ *
+ * THE SCRIPT IS CLASSIFIED THE WAY EVERY OTHER SCRIPT IS. Following the hop is `resolveCommandPlan`
+ * in `@abloh/core`; deciding what the script it lands on IS is `classifyPackageManifest`, called
+ * here on the same script table with that text substituted for `test`. That is deliberate and it is
+ * the whole difference between this and a second reading: `eslint . && vitest run` names vitest and
+ * IS measurable behind its gate, `vitest run -c unit && vitest run -c int` names vitest and is a
+ * fanout that gets no runner identity, and `turbo run test` is an aggregator - and every one of
+ * those three answers already existed. A hop that answered them again, its own way, would be the
+ * drift `command-plan.ts` was built to end.
+ *
+ * FLAGS THAT SURVIVE THE HOPS. abloh's reporter flags are appended to the command it executes, and
+ * they have to arrive at the runner or the baseline observes nothing - the state this whole reading
+ * exists to leave. One hop is safe on every manager: `withRunnerArgs` puts npm's documented `--` in
+ * front where npm needs it, and pnpm >=10 and yarn forward verbatim. A SECOND hop is not, and
+ * `aliasHopFamily` is the measurement of exactly that - pnpm <=9 and npm consume the tokens at the
+ * second hop. Binding a runner whose flags will be eaten would trade an honest refusal for a silent
+ * zero, so it is not done.
+ */
+declare function bindDeclaredCommand(argv: readonly string[], context?: DeclaredCommandContext): DeclaredBinding | null;
+/**
+ * Bind an explicit prepared command to the adapter that will measure it.
+ *
+ * A specialized adapter may add runner-specific coverage flags and Stryker may invoke its own
+ * runner plugin, so baseline, coverage capability and mutation must all be describing the SAME
+ * suite. The invariant is that the adapter and the command agree; it is not that the command and
+ * `scripts.test` agree.
+ *
+ * SELECTION FOLLOWS THE COMMAND THAT ACTUALLY RUNS. Kenneth's admission-first order of 2026-08-27,
+ * closing D1 of `data/abloh-real-bugs-study-5/report.md` - four repositories at admission (§4) and
+ * the proposal stage's only measured wall (§5.2). Until then this function demoted any prepared
+ * command that differed from detection's to the generic adapter, which reads the invariant one term
+ * too wide: the prepared command is what this run will execute, so it, and not the script detection
+ * first read, is what the adapter has to agree with.
+ *
+ * WHAT THAT COST WHILE IT READ THE OTHER WAY. `electron/asar`'s `scripts.test` is
+ * `yarn lint && yarn vitest run && xvfb-maybe electron …`, so detection selected vitest from the
+ * script and the baseline ran the whole gated chain: `0 executed test(s) … red true` on a suite that
+ * is 11 files and 190 tests green by hand. The maintainer then wrote the one thing that failure
+ * invites - `testCommand: npx --no-install vitest run` - and the run answered `test command differs
+ * from the command that selected vitest; using the generic command adapter`, which has no reporter
+ * at all: `0 executed test(s)` a second time, from a command that is a bare vitest invocation. The
+ * report's own sentence: "Correcting the command costs the runner adapter; leaving it costs the
+ * baseline. There is no third answer." This is the third answer, and it was always the honest one -
+ * the demotion was never protecting against a mixed measurement, because a command NAMING vitest
+ * and vitest's own adapter describe the same suite.
+ *
+ * THE THREE OUTCOMES, and each is a fact about `prepared` alone:
+ *
+ *   - it names a runner ⇒ THAT runner's adapter, whether or not detection agreed. A declaration
+ *     naming a DIFFERENT runner is not two statements to reconcile: one of them is a guess read off
+ *     a script that this run will not execute, and the other is the binary about to be spawned.
+ *   - it names no runner and restates detection's own command ⇒ nothing changed, so nothing moves.
+ *   - it names no runner and is something else - `./run-tests.sh` - ⇒ the generic command adapter,
+ *     because what executes is genuinely opaque. That is the ONLY demotion left, and
+ *     `identifiedRunner` still discloses what the script had said.
+ *
+ * `npm run test:ci` LEFT THAT THIRD ROW ON 2026-09-01, and it is why `context` exists. It is not
+ * opaque: the script is in the manifest, it is the same manifest detection reads, and following it
+ * is the difference between measuring a suite and reporting zero executed tests over it. Six of the
+ * ten rows of `data/abloh-ten-run-2/report.md` died on that reading being one token wide - each of
+ * them a maintainer who had just been told "Naming one runner directly here is what changes that"
+ * and had done exactly that. §6.1 carries the six spellings and which two of them bound.
+ *
+ * WHAT IS DROPPED WITH THE COMMAND, in every branch that changes it: the fanout coverage plan and
+ * the watch-mode correction, both readings of `scripts.test` that a declared command replaces.
+ *
+ * WHAT IS NO LONGER DROPPED BLINDLY IS THE RUNNER-STAGE SPLIT. For a command that names its runner
+ * directly the old sentence holds exactly - `pnpm exec vitest run` IS one stage - so the split is
+ * still dropped there. For a command that reached its runner THROUGH a script, the script is a
+ * script like any other: it can gate the runner behind a linter, and `baselineCommand`'s whole
+ * reason for taking a stage is that appending reporter flags to `lint && jest` puts them on the
+ * linter. So the split is RECOMPUTED from the resolved script rather than discarded, by the same
+ * two functions detection calls on `scripts.test`.
+ *
+ * AND A SCRIPT THAT RUNS THE SUITE TWICE STILL NAMES NO RUNNER, which is the fail-closed rule
+ * `classifyPackageManifest` states for `scripts.test` and which a hop must not be able to walk
+ * around: `vitest run -c unit && vitest run -c int` names vitest once and launches two suites, and
+ * measuring one of them silently is the defect that rule exists for.
+ */
+declare function bindPreparedTestCommand(detected: TargetDetection, prepared: PreparedTestCommand, context?: DeclaredCommandContext, ctx?: RepoAccess): TargetDetection;
+/**
+ * THE RUNNER THE MAINTAINER WROTE DOWN, APPLIED - `environment.runner`, and nothing else reaches it.
+ *
+ * WHY IT IS A SEPARATE FUNCTION FROM {@link bindPreparedTestCommand} rather than a fourth outcome
+ * inside it. That function answers "what does the command that will execute name", which is a
+ * reading. This answers "what did a person state", which is not - and folding a declaration into a
+ * reading is how the two would come to disagree about which of them wins. They run in that order,
+ * here and only here (`measurement-plan-resolver.ts`), so a declaration is applied to whatever the
+ * command reading produced and never the other way round.
+ *
+ * IT MOVES THE ADAPTER AND NOTHING ELSE. The command is untouched, which is the whole point: a
+ * repository whose command is right and whose runner abloh read wrong - `pinojs/pino`, whose
+ * five-stage chain abloh reduced to a one-test `jest test/jest` leg - needs one of those corrected
+ * and not both. What that leaves open is a declared runner whose reporter flags the command in force
+ * cannot carry, and the baseline is what closes it: `baselineObservedNoTests` refuses a green run
+ * that observed no test rather than scoring over none.
+ *
+ * WHAT TRAVELS WITH THE RUNNER AND WHAT DOES NOT, on exactly the terms `bindPreparedTestCommand`
+ * sets for its own declared branch. `vitestDir` and `jasmineSuite` belong to a runner and are
+ * re-read for the one now named; `angularTarget` is read from `angular.json` and survives only for
+ * the two Angular runners, because a project name attached to a run of something else is a claim
+ * about a file that run never opens; `runnerInvocation` survives only for the runners that select
+ * their specs or their config from it, which is the same list detection reads it for.
+ *
+ * A DECLARATION THAT AGREES WITH THE READING CHANGES NOTHING, and returns the same object, so the
+ * commonest case - a maintainer ratifying what abloh detected - cannot cost a re-read.
+ */
+declare function applyDeclaredRunner(detected: TargetDetection, declared: string | undefined, ctx?: RepoAccess): TargetDetection;
+/**
+ * What a caller holds ABOUT THE REPOSITORY that a declared command needs in order to be read whole.
+ *
+ * One optional argument rather than two: a caller either has the target package's manifest or it
+ * does not, and the two fields are always read out of the same one. Absent, every reading below
+ * behaves exactly as it did before scripts could be followed - `abloh run --test-command` from a
+ * directory with no manifest is still a valid, if narrower, question.
+ */
+interface DeclaredCommandContext {
+    /** `scripts` from the target package's `package.json`. */
+    scripts: Record<string, string>;
+    /**
+     * The manifest itself, for {@link aliasHopFamily} - which decides whether abloh's own appended
+     * reporter flags survive more than one package-manager hop.
+     */
+    manifest?: unknown;
+}
+interface PackageManagerContext {
+    pm: PackageManager;
+    /** Canonical directory that owns the selected lockfile or packageManager declaration. */
+    ownerDir: string;
+    /** Lockfiles from the selected manager family at ownerDir. Empty means no frozen install exists. */
+    lockfiles: string[];
+    source: "lockfile" | "packageManager" | "default";
+    version: string | null;
+    /**
+     * How a level carrying MORE THAN ONE lockfile family was decided, or absent when no level did.
+     *
+     * Present so `init` can put the decision in the receipt beside `environment.installCommand`,
+     * where the customer ratifies it and can flip it in the same breath. A choice nobody was told
+     * about would be the refusal's failure mode wearing a different face.
+     */
+    lockfileChoice?: LockfileChoice;
+}
+/** The decision made at a directory holding two families of lockfile. See {@link chooseAmongLockfiles}. */
+interface LockfileChoice {
+    /** Every competing lockfile, in the walk's own order, e.g. `["package-lock.json", "bun.lock"]`. */
+    competing: readonly string[];
+    /** The lockfiles NOT selected. What a customer edits their way towards if the choice is wrong. */
+    rejected: readonly string[];
+    /**
+     * One manager per competing FAMILY, in this walk's own order. Not index-aligned with
+     * {@link competing}, which is per FILE - npm alone can contribute two of those.
+     *
+     * Carried rather than re-derived from the file names, because the name-to-manager table lives
+     * here and a second copy of it in `init` would be a second answer to which manager
+     * `npm-shrinkwrap.json` means.
+     */
+    families: readonly PackageManager[];
+    /**
+     * Which rung of the precedence answered.
+     *
+     * `customer` and `undecided` are the two halves of the ruflo ruling (Kenneth, 2026-08-26). A pair
+     * nothing in the repository decides is no longer a refusal: `undecided` means one was taken
+     * PROVISIONALLY so that `init` could draft a file and ask, and `customer` means the answer came
+     * back. Only `init` ever sees `undecided` - every measuring path still refuses, because a run
+     * that silently installs with the other half of a pair measures the wrong tree.
+     */
+    by: "packageManager" | "ci" | "conservative-default" | "customer" | "undecided";
+    /**
+     * Why, with no subject: "your CI installs with bun (.github/workflows/ci.yml::test)". Kept
+     * subjectless so the receipt beside `environment.installCommand`, which has already named the
+     * selected lockfile, does not name it twice.
+     */
+    because: string;
+    /** The whole sentence: what was chosen, over what, and why. */
+    evidence: string;
+}
+/**
+ * Resolve the package manager from the selected package outward to the Git root.
+ *
+ * A child lock owns that package. An ancestor lock owns it only when no nearer level has a lock.
+ * Mixed lockfile families at one level are decided by {@link chooseAmongLockfiles} - never by a
+ * priority rule of ours, and still refused where nothing in the repository decides them. With no
+ * lock anywhere, an exact packageManager declaration selects the host command but deliberately
+ * yields no frozen install recipe.
+ */
+/**
+ * HOW A CALLER WANTS A TWO-FAMILY DIRECTORY HANDLED, and what it already knows about one.
+ *
+ * Both fields are `init`'s and nothing else passes them. The default is the behaviour every
+ * measuring path has always had: a pair nothing decides is refused rather than guessed at.
+ */
+interface PackageManagerResolution {
+    /** The family the customer chose at the prompt, where two competed and nothing else decided. */
+    chosen?: PackageManager;
+    /**
+     * `refuse` - the default, and every path that measures - or `provisional`, which takes one so a
+     * file can be drafted and the question can be asked over it. See {@link chooseAmongLockfiles}.
+     */
+    undecided?: "refuse" | "provisional";
+}
+declare function detectPackageManagerContext(repoDir: string, workDir?: string, resolution?: PackageManagerResolution, ctx?: RepoAccess): PackageManagerContext;
+/**
+ * THE NAME THE RUN DRIVES THIS RUNNER BY, or `command` when it has none.
+ *
+ * Every runner the capability registry marks `named-runner` passes through under its own name; the
+ * rest fall back to the repository's own command. Both halves still measure - the fallback runs the
+ * whole suite for every mutant and reads its exit status, which is a verdict - and the difference is
+ * what else can be asked. A named runner's report says WHICH test failed, so a baseline can
+ * quarantine one test rather than a file, and its arguments can ask for particular test files, so a
+ * mutant can be judged by the tests that cover it instead of by the suite.
+ *
+ * NOTHING IS LEFT ON THE FALLBACK EXCEPT deno AND pytest, as of 2026-08-16, and the registry row is
+ * what says so rather than a list here.
+ *
+ * IT USED TO BE READ AS "does a Stryker plugin exist", which is what the column was called until
+ * 2026-08-31 and what its return type is still spelled after. The plugins no longer run; the name
+ * they gave this function outlives them until the packages themselves go.
+ */
+declare function engineRunner(runner: Runner): StrykerMutationRunner | "command";
+/** pnpm-lock ⇒ pnpm, yarn.lock ⇒ yarn, else npm (spike detectPm). */
+declare function detectPackageManager(dir: string): PackageManager;
+interface PkgProbe {
+    dir: string;
+    /** a runner we can drive DIRECTLY (fast path); null means fall back to the project's own script */
+    runner: "jest" | "vitest" | "mocha" | "node-test" | "ava" | "tap" | "jasmine" | "bun" | "deno" | "angular-karma" | "angular-vitest" | null;
+    testScript: string | null;
+    /** a runner identified from the script rather than a dependency (e.g. "bun") - never guessed at */
+    note: string | null;
+    scripts: Record<string, string>;
+    /** the workspace task runner this package's test script delegates to, when it delegates */
+    aggregator: AggregatorTool | null;
+    /**
+     * The TASK NAMES that delegation selects, empty when it names none. Beside the tool because the
+     * two are one reading, and because a reader that re-derives them from `testScript` gets a
+     * different answer on an ALIASED root - which is what left `suiteFanoutPlan` silent about the one
+     * repository shape the sentence exists for. See {@link ManifestClassification.aggregatorTasks}.
+     */
+    aggregatorTasks: readonly string[];
+    /** The one of those tasks this package's suite was read from; null for an ordinary package. */
+    aggregatorTask: string | null;
+    /**
+     * The `angular.json` test target this package's suite is, when it is an Angular one. Carried
+     * because everything downstream needs facts the script cannot give: which PROJECT `ng test` must
+     * be given, and which BUILDER is behind it - the mutation config, the sealed command and the
+     * coverage lane each branch on one of the two. Null for every non-Angular package.
+     */
+    angular: AngularTestTarget | null;
+    /**
+     * This package's own literal test invocation when it is declared somewhere other than
+     * `scripts.test` — today that is an integrated-Nx `project.json` run-commands target. Null for
+     * every ordinary package, whose declaration IS `scripts.test`.
+     */
+    declaredCommand: string | null;
+    /**
+     * Set when {@link declaredCommand} is declared to run from the WORKSPACE ROOT rather than from
+     * `dir`. Null for every package whose suite runs where the package lives.
+     */
+    workspaceRootSuite: WorkspaceRootSuite | null;
+}
+/**
+ * The runners a `package.json` script names by writing the runner's own binary name.
+ *
+ * ONE LIST, IN `@abloh/core`, DERIVED FROM THE CAPABILITY REGISTRY. Four sites used to type this
+ * list out - here, `TEST_BINARIES` and `DIRECT_RUNNER` in `ci-recipe.ts`, and `LEAF_RUNNERS` in
+ * `workspace-aggregator.ts` - and they disagreed: init omitted jasmine from one of its two copies,
+ * so `abloh init` could reject a jasmine command `abloh run` measures perfectly (audit F49).
+ */
+type ScriptRunner = string;
+/**
+ * How many times a script INVOKES ONE NAMED RUNNER as a suite. {@link suiteStages} is the general
+ * question and carries the measurement; this is the per-runner form, used to tell a leaf that runs
+ * one suite from a leaf that is itself a chain.
+ *
+ * The split is deliberately wider than the `&&` chains the plan builder admits (`;`, `||`, `|`, `&`
+ * count too). Recognising a fanout is the safety half of this answer and must not depend on the
+ * composition being one we can also reproduce; a `jest a; jest b` script is still two suites.
+ */
+declare function runnerSuiteInvocations(testScript: string, runner: ScriptRunner | "node-test"): number;
+/**
+ * THE ONE RULE FOR "does this invoke node's built-in test runner", used by every reader that asks.
+ *
+ * BOTH HALVES OF IT ARE `@abloh/core`'s NOW - the wrapper prefixes this file used to strip in its own
+ * `withoutCommandPrefix`, and the flag-not-adjacent reading. Six places used to answer this question
+ * with three different patterns, and `abloh init` still had a fourth as late as this mechanism (audit
+ * F49): it recognized only `node --test`, while a TypeScript repository writes `node --import tsx
+ * --test`. See `planCommand` for the measurement and for why `tsx` counts and `borp` does not.
+ */
+declare function argvInvokesNodeTest(argv: readonly string[]): boolean;
+/** {@link argvInvokesNodeTest} for ONE command segment that has not been split yet. */
+declare function invokesNodeTest(command: string): boolean;
+/**
+ * How many stages of a script RUN A SUITE, counting the ones that reach a suite through a package
+ * script as well as the ones that name a runner directly.
+ *
+ * THE DEFECT THIS EXISTS FOR, measured 2026-08-16 on a real vitest 4.1.10 install. A script that
+ * runs two suites of ONE runner:
+ *
+ *     "test": "vitest run -c vitest.unit.ts && vitest run -c vitest.integration.ts"
+ *
+ * named vitest exactly ONCE as far as {@link runnerNamesInScript} was concerned, because that
+ * function answers which runner NAMES appear, not how many suites are launched. So the repository
+ * classified as a direct vitest project. Diff coverage then appended its coverage flags to the run's test
+ * command, and `npm test -- --coverage ...` appends to the END of the script string, which put every
+ * flag on the LAST stage alone. The unit suite ran, uninstrumented, and its coverage was never
+ * collected: a source function exercised by the unit suite came back with ZERO hits on every line
+ * while the customer's own `npm test` covers it completely. That is silent coverage loss inside a
+ * signed certificate, the worst class, and it was silent in BOTH directions - the sealed v2 engine
+ * synthesized `npx --no-install vitest run` for the same repository, which is neither config, and
+ * Stryker drove its vitest plugin against the runner's default discovery rather than either suite.
+ *
+ * The alias half is not a refinement, it is the same defect wearing a different composition:
+ *
+ *     "test": "vitest run && npm run test:integration"      // test:integration: "jest"
+ *
+ * names vitest once and jest not at all, so that package classified as a direct vitest project too,
+ * and the appended flags landed on the jest stage. Two suites is two suites however the author wrote
+ * the second one.
+ *
+ * So the count, not the name set, decides. More than one suite stage means the script is a FANOUT:
+ * it is not one drivable runner, and {@link suiteFanoutPlan} decides what of it can be measured.
+ *
+ * IT IS `scriptRuns`'s LIST SINCE 2026-09-11, and the widening is the point. The hand-rolled split
+ * and one-level alias hop above it counted 1 for `iamkun/dayjs` (nine jest executions, eight of them
+ * behind a `cross-env TZ=…` prefix this could not see through), 1 for `immerjs/immer` (a second
+ * vitest execution inside a chained alias body) and 0 for `electron/asar` (a second vitest execution
+ * under `xvfb-maybe electron`). Each of those is exactly the appended-flag defect recorded above,
+ * measured on three more repositories.
+ *
+ * WHAT IT COUNTS IS UNCHANGED: a stage running a suite abloh would MEASURE. A browser suite is not
+ * one - `vitest run && playwright test` has always been a direct vitest project - and neither is a
+ * runner abloh cannot drive, which is what keeps `pinojs/pino`'s borp stage from demoting a
+ * repository whose jest stage abloh measures perfectly well.
+ */
+declare function suiteStages(testScript: string, scripts?: Record<string, string>): number;
+/**
+ * The stages a repository's `test` script runs BEFORE its runner stage, as commands, in the
+ * author's order. Empty whenever there is nothing before it.
+ *
+ * WHY THEY HAVE TO RUN. The baseline measures one stage of a chained script - {@link
+ * baselineCommand} in `@abloh/measure` carries the defect that made that necessary. Running that
+ * stage alone silently skips whatever the earlier stages did, and for a repository whose first
+ * stage GENERATES a file the suite imports, what it skips is the suite. Measured on
+ * All-Hands-AI/OpenHands at `10d2285dd`, whose script is `npm run make-i18n && vitest run`
+ * (`data/abloh-timeout-coverage-diagnosis/report.md` §2.3): with the first stage dropped, 339 of
+ * 600 test files fail on `Failed to resolve import "#/i18n/declaration"` and no coverage report is
+ * written at all; run it first and the identical command passes 600 files and writes the report.
+ *
+ * WHY RUNNING THEM IS SAFE HERE AND NOT UNDER MUTATION. These stages are the reason
+ * {@link runnerStageCommand} exists: a linter or a typechecker in front of the runner fails on
+ * Stryker's instrumented source, so the mutation engine strips them and must keep stripping them.
+ * The baseline runs the UNTOUCHED tree - the same tree the repository's own `npm test` runs on - so
+ * a gate that passes for its author passes here, and a gate that does not was never the baseline's
+ * question. That asymmetry is the whole rule: prerequisite and gate are indistinguishable from the
+ * text, and on unmutated source it does not matter which one a stage is.
+ *
+ * TAKEN VERBATIM, THEN MADE RESOLVABLE. A stage is the author's own command, so its flags, config
+ * files and selectors survive. The one adjustment is the same one the runner stage gets: inside
+ * `npm test` a bare `tsc` resolves out of `node_modules/.bin`, which npm puts on PATH and a direct
+ * spawn does not, so a stage that is not already a package manager or a runtime is invoked through
+ * `npx --no-install` - which resolves from that same tree and never reaches the network.
+ *
+ * Stages AFTER the runner are deliberately not returned: nothing the runner needs can be produced
+ * by a command the author wrote to run once the tests were already over.
+ */
+declare function preRunnerStageCommands(testScript: string, runner: Runner, scripts?: Record<string, string>): string[];
+/**
+ * The one stage of a repository's `test` script that runs the test RUNNER, as a command, or null
+ * when the script has no separable stage.
+ *
+ * WHAT IT IS FOR. Runners with no Stryker plugin - ava above all - go through Stryker's generic
+ * command runner, which executes the repository's own `scripts.test` once per mutant. When that
+ * script GATES the runner (`xo && ava && tsd`, `tsc --noEmit && jest`, `posttest: npm run lint`),
+ * the gate is handed Stryker's own instrumented source and fails on it. Measured on
+ * sindresorhus/p-map 3f153f1: 276 lint errors, EVERY ONE of them on a file Stryker had rewritten -
+ * 274 style errors on the instrumented `index.js`, plus the `@ts-nocheck` Stryker wrote into two
+ * `.d.ts` files, which that linter bans. `npm test` on the untouched tree passes.
+ *
+ * Instrumented source cannot pass a style linter, by construction. So a repository whose test
+ * script gates the runner cannot be mutation-tested at all through the command runner, however
+ * healthy its suite is, and the failure names the linter rather than the cause.
+ *
+ * THE AUTHOR'S OWN INVOCATION, MINUS THE GATE. This deliberately does not synthesize a bare
+ * `npx ava`: it returns the stage the author wrote, so a `--config`, a project selector or a spec
+ * path they put there is preserved. `sealed-test-command.ts` explains at length why a synthesized
+ * invocation is a guess for ava, tap and node:test; taking the stage verbatim is not a guess.
+ *
+ * A GATE IS NOT ALWAYS IN THE SCRIPT. npm runs `pretest` before `scripts.test` and `posttest`
+ * after it, automatically, on every `npm test` - so a repository can gate its runner without its
+ * `test` script containing a single `&&`. mapbox/supercluster `8a97f6a` is exactly that shape: its
+ * `test` is a bare `node --test`, its `pretest` is a linter, and the whole repository was
+ * unmeasurable because this function read one key. It died in Stryker's initial run naming
+ * `@stylistic/indent` on instrumented source, with no retry line in the log at all, and this was
+ * read as node:test being unreachable rather than as a gate (measured 2026-08-16).
+ *
+ * A hook is therefore what makes a ONE-STAGE script separable: running the stage directly is what
+ * skips the hooks, because Stryker's command runner executes the string given here rather than
+ * `npm test`. The chain rules below are unchanged for a script that has stages of its own.
+ *
+ * IT DECLINES far more often than it answers, and that is the point - the caller only reaches for
+ * it after the full script has already failed:
+ *   - a one-stage script with no `pretest`/`posttest` hook has nothing to strip (a bare `ava`
+ *     returns null, not `npx ava`)
+ *   - anything that is not a plain `&&` chain (`;`, `|`, `||`, redirection, substitution, a
+ *     subshell) is left alone, because the command runner passes this string to a shell
+ *   - a chain naming the runner in zero stages, or in more than one, is ambiguous and declines
+ *
+ * @param lifecycleHooks the non-empty `pretest`/`posttest` script bodies npm would run around this
+ *   script; their CONTENT is never parsed, only their existence, because a hook that is a
+ *   prerequisite rather than a gate is indistinguishable from one that is - and this answer is only
+ *   ever reached for after the full script has already failed, so neither can regress a run.
+ */
+declare function runnerStageCommand(testScript: string, runner: Runner, lifecycleHooks?: readonly string[], scripts?: Record<string, string>): string | null;
+/**
+ * The same stage with a PACKAGE-RUNNER PREFIX removed: `npx jest --config test/ut/jest.config.cjs`
+ * becomes `jest --config test/ut/jest.config.cjs`.
+ *
+ * WHY IT EXISTS. `apache/echarts` writes its whole suite as `npx jest --config
+ * test/ut/jest.config.cjs`, and a matcher that compares the stage's FIRST token to the runner's
+ * name reads no invocation there at all - so the config file the repository names is lost, the
+ * mutation run drives jest under its defaults, and the run dies before a test executes (measured
+ * 2026-08-24, `report.md` §3). A package runner is a way of RESOLVING the binary, not a different
+ * command, so removing it changes nothing about what runs.
+ *
+ * IT STRIPS RESOLVERS AND NOTHING ELSE, which is why it is not `withoutCommandPrefix`. That
+ * function answers a different question for a DECLARED argv and also drops `NODE_ENV=test`, `env`
+ * and `cross-env` - and an environment assignment is part of what the author runs, not a way of
+ * finding it. `runnerStageCommand` re-spawns the stage as argv with no shell, so a stage whose env
+ * this dropped would run a different suite: `xo && NODE_ENV=test ava` is declined on purpose, and
+ * `detect.test.ts` pins that.
+ *
+ * WHAT IT LEAVES ALONE, and each is a case where the prefix is not merely a resolver:
+ *
+ *   - `npx` carrying a flag not listed below. `-p`/`--package` installs and runs something ELSE
+ *     under the same name, so the stage is handed back as written and then reads as naming no
+ *     runner rather than as naming this one.
+ *   - a BARE `yarn <name>` or `pnpm <name>` WITH NO SCRIPT TABLE TO CHECK IT AGAINST. Both managers
+ *     run a package SCRIPT of that name when one exists and a binary only when one does not, so
+ *     `yarn jest` is ambiguous from the string alone - `yarn exec jest` is not, and is the spelling
+ *     that is always stripped.
+ *
+ *     THE AMBIGUITY IS RESOLVABLE WHEN THE MANIFEST IS IN HAND, and round 5a's D1 is what made that
+ *     worth resolving. `electron/asar`'s script is `yarn lint && yarn vitest run && xvfb-maybe
+ *     electron …` and its manifest declares no script called `vitest`, so `yarn vitest run` can only
+ *     be the binary - but the stage read as naming no runner, the whole split declined, and the
+ *     baseline ran the entire gated chain for `0 executed test(s) … red true` on a suite that is 190
+ *     tests green (`data/abloh-real-bugs-study-5/findings.md` F1, cycle 1). Given `scripts`, a name
+ *     that is NOT a script in it is a binary by yarn's and pnpm's own resolution order; without the
+ *     table nothing changes and the stage is still handed back as written. `npm` is not in this
+ *     branch at all: npm has no bare-script shorthand, so `npm jest` never runs a script.
+ */
+declare function withoutPackageRunnerPrefix(stage: string, scripts?: Record<string, string>): string;
+/**
+ * The stage of `scripts.test` that INVOKES the runner, whether or not the script is a chain.
+ *
+ * {@link runnerStageCommand} answers a different question — what to retry with after a gated script
+ * has already failed — and so it deliberately declines a single-stage script with no lifecycle hook,
+ * which has nothing to strip. The per-test plugins need something else: `node --test` and ava select
+ * their SPECS from the invocation, so a repository whose whole script is
+ * `node --test 'test/*.test.js'` is naming its suite there, and a plugin that never sees it falls
+ * back to the runner's default discovery.
+ *
+ * Measured on mourner/suncalc, whose script is exactly that: the default patterns also match
+ * `test/fetch-truth.js`, a helper that fetches over the network, and running it once per mutant took
+ * the run from seconds to 102. The author already said which files are the suite.
+ */
+declare function runnerInvocation(testScript: string | null, runner: Runner, scripts?: Record<string, string>): string | null;
+/**
+ * The suite a repository's own jasmine invocation names — a config file, or spec globs.
+ *
+ * WHY THIS IS READ AT ALL. `JasmineSuite` in `@abloh/measure` carries the mechanism: the Stryker
+ * jasmine-runner asks jasmine to load a config file, and jasmine's fallback tries exactly the three
+ * paths above and reads neither `--config=` nor `JASMINE_CONFIG_PATH`. A repository that points
+ * jasmine anywhere else runs zero specs under mutation while its own suite is perfectly green, and
+ * the run dies `No tests were executed` — measured on all three jasmine repositories the corpus
+ * holds.
+ *
+ * IT READS THE AUTHOR'S COMMAND, IT DOES NOT SYNTHESIZE ONE. Every rule below mirrors jasmine's own
+ * argument parser (`jasmine/lib/command.js`, `parseOptions`) rather than guessing:
+ *
+ *   - jasmine spells EVERY option `--name=value`; there is no space-separated form. So a token that
+ *     does not start with `-` is a spec path, which is what makes the two shapes separable at all.
+ *   - `FOO=bar` AFTER the binary is not an environment assignment. jasmine's `isEnvironmentVariable`
+ *     recognises the shape and silently DROPS it, which is why xlsx-populate's
+ *     `jasmine JASMINE_CONFIG_PATH=test/unit/jasmine.json` runs no specs when that repository runs
+ *     it itself. Reading it as a config path here would measure a suite the customer does not run.
+ *     Before the binary it is a real shell assignment, and jasmine's CLI does read it there.
+ *   - `--` ends jasmine's own arguments, exactly as its parser does.
+ *
+ * IT DECLINES rather than guesses: a script that is not a plain `&&` chain, or that names jasmine in
+ * zero or more than one stage, yields undefined and the run behaves exactly as it does today.
+ */
+declare function jasmineSuiteFromScript(testScript: string): JasmineSuite | undefined;
+/**
+ * The jasmine suite to hand the mutation engine for one package directory, or nothing to hand it.
+ *
+ * The one thing this adds to reading the script is the case where BOTH are true: the author names
+ * spec paths positionally AND keeps a config where jasmine's fallback already looks. Jasmine loads
+ * that config for its helpers, requires and `jsLoader` and only then narrows to the named paths, and
+ * a generated config carrying the paths alone would silently drop all three. So that repository is
+ * left to the fallback, which measures the config's own spec set - a superset of what the author
+ * named, which can only add kills, never invent them.
+ */
+declare function detectJasmineSuite(dir: string, testScript: string | null, ctx?: RepoAccess): JasmineSuite | undefined;
+/**
+ * A manifest that EXISTS but cannot be read.
+ *
+ * Distinct from a directory with no `package.json`, which is a legitimate absence and yields null.
+ * A malformed manifest used to throw a bare `SyntaxError`, which the CLI caught, logged to stderr,
+ * and continued from — leaving `runner: "command"` and an artifact reporting `not-run: no-runner`,
+ * rendered as "no test runner detected". That is a claim about the repository. The truth was that
+ * we could not read its manifest, and the repository may have a perfectly good suite.
+ */
+declare class TargetDetectionError extends Error {
+    /**
+     * THE REGISTRY REFUSAL THIS SENTENCE WAS COMPOSED FROM, where there was one.
+     *
+     * `cli-failure.ts`'s `declaredRefusalOf` is the one reader: every class it recognises that
+     * composes from the registry sets this, so a caller that wants the code, the owner and the next
+     * action rather than the sentence gets them. Optional, and stays optional - most of this file's
+     * refusals compose their own sentence and the record says so rather than inventing a code.
+     */
+    readonly refusal: Refusal | undefined;
+    constructor(message: string, refusal?: Refusal);
+}
+/**
+ * WHY NO TARGET WAS FOUND, as a closed code rather than a sentence.
+ *
+ * WHAT THIS FIXES (external refusal review, rank 12). All three refusals below were composed,
+ * printed on the terminal, and then thrown away: `index.ts` caught the error, logged the sentence,
+ * and continued with no detection, at which point the run PERSISTED
+ * `baseline: skipped - nothing to baseline (no runner detected / empty scope)` and
+ * `Diff coverage: not applicable - no test runner detected`. A customer whose `target.directory`
+ * pointed one directory too high, and a repository abloh genuinely cannot measure, produced the
+ * same recorded claim - and that claim was about the REPOSITORY, on a run where the repository was
+ * fine and the configuration was one line out.
+ *
+ * The code and the remedy travel with the error so the artifact records which of the three
+ * happened, and every surface reading the artifact stops having to guess.
+ */
+type TargetNotFoundReason = 
+/** `--subdir` or `target.directory` names a directory that holds no package.json */
+"configured-directory-has-no-package"
+/** nothing under the repository declares a test runner or a test script */
+ | "no-testable-package"
+/** a workspace root with no test script of its own, which abloh will not guess one for */
+ | "workspace-root-declares-no-test-script"
+/**
+ * two package-manager lockfile families in one directory and nothing in the repository deciding.
+ *
+ * WHY IT JOINED THIS UNION (round 5 v4 census, M9 - `ruvnet/ruflo`). It threw a bare
+ * `TargetDetectionError` carrying one sentence - "conflicting package-manager lockfiles in
+ * /tmp/...: package-lock.json, pnpm-lock.yaml" - and no next action of any kind. A sentence with
+ * no remedy is not a refusal, it is a wall, and this one was reached AFTER `abloh init` had
+ * already drafted a whole file for the same repository: init asks the customer which family is
+ * theirs, and every measuring path threw the answer away and refused again.
+ */
+ | "conflicting-lockfiles";
+declare class TargetNotFoundError extends Error {
+    /** Which of the three, as a code an artifact can carry. */
+    readonly reason: TargetNotFoundReason;
+    /** The one thing to do next, on its own so a surface can render it apart from the explanation. */
+    readonly remedy: string;
+    constructor(reason: TargetNotFoundReason, message: string, remedy: string);
+}
+/** The runner/test-script facts of one parsed package.json, independent of where it was read from. */
+interface ManifestClassification {
+    runner: PkgProbe["runner"];
+    testScript: string | null;
+    note: string | null;
+    scripts: Record<string, string>;
+    /** The workspace task runner this manifest's `test` script delegates to, when it delegates. */
+    aggregator: AggregatorTool | null;
+    /**
+     * The TASK NAMES that aggregator invocation selects, empty when it selects them some other way.
+     *
+     * Carried beside the tool because it is the other half of the same sentence, and because the
+     * tool alone could not answer the question the packages have: `nx run-many --targets=test:lib`
+     * says which SCRIPT KEY every package behind it declares its suite under. Read at the ROOT and
+     * handed down; see {@link rootAggregatorTasks}.
+     */
+    aggregatorTasks: readonly string[];
+    /**
+     * The aggregator task {@link testScript} was read from, when this package declares no `test`
+     * script of its own and the root's aggregator named a task it does declare. Null everywhere
+     * else, including for every package whose declaration is `scripts.test`.
+     */
+    aggregatorTask: string | null;
+    /**
+     * Why the aggregator's tasks did not resolve to ONE suite here, when more than one of them is a
+     * suite. Null when nothing tied - a package that simply declares no runner is already refused in
+     * those words by every caller, and inventing a second sentence for it would say the same thing
+     * twice.
+     */
+    aggregatorTaskRefusal: string | null;
+}
+/**
+ * The task names a ROOT manifest's aggregator selects, ready to hand to each package.
+ *
+ * ONE DERIVATION, because detection, selection and `abloh prepare` all need it and a package
+ * classified from a different list than the one selection used is the desync `classifyWithAliasHop`
+ * exists to prevent. The hop is made here for the same reason it is made there: TanStack/query's
+ * root `test` is `pnpm run test:ci` and the aggregator is one script further in.
+ */
+declare function rootAggregatorTasks(rootManifest: any): readonly string[];
+/**
+ * Classify a parsed package.json without touching the filesystem.
+ *
+ * Split out of {@link probePkg} so workspace target selection can classify a manifest read from a
+ * trusted git TREE (merge base) with byte-identical semantics to the working-tree probe — the two
+ * must never disagree about what counts as a direct runner.
+ *
+ * `aggregatorTasks` is the ROOT's answer to "which script key do the packages here use", read once
+ * by {@link rootAggregatorTasks} and handed down. Empty is the ordinary case and changes nothing.
+ */
+declare function classifyPackageManifest(pkg: any, aggregatorTasks?: readonly string[]): ManifestClassification;
+/**
+ * Alias-hop admissibility. Appended reporter/coverage flags must survive TWO package-manager
+ * hops (outer `pnpm test` -> inner `pnpm test:spec` -> runner). Measured live: pnpm >=10 and
+ * yarn forward post-script tokens verbatim through both hops; pnpm <=9 and npm consume them at
+ * the second hop. So the hop is admissible ONLY under a pinned pnpm>=10 or yarn root, and only
+ * for a same-family alias (an `npm run x` alias inside a pnpm repo re-creates the silent hop).
+ */
+declare function aliasHopFamily(rootManifest: any): "pnpm" | "yarn" | null;
+/**
+ * Classify a manifest, resolving ONE pure single-script alias when the gate admits it. PURE
+ * means the entire test script is one package-manager invocation of one other script in the
+ * SAME manifest — chains, globs, env prefixes, and cross-family calls never hop. Selection
+ * (workspace-packages.ts) and detection MUST share this rule or they desync on the same repo.
+ */
+declare function classifyWithAliasHop(manifest: any, family: "pnpm" | "yarn" | null, aggregatorTasks?: readonly string[]): ManifestClassification;
+/**
+ * Classify ONE package directory's manifest exactly as measurement will, alias hop included.
+ *
+ * EXPORTED FOR `abloh prepare`, WHICH IS FINDING F28. Prepare enumerates workspace packages to
+ * decide what to stage a coverage provider for, and it called `classifyPackageManifest` directly -
+ * the classifier WITHOUT the alias hop - while measurement resolves the same package through
+ * {@link classifyWithAliasHop}. So a package whose `test` script is `pnpm run test:unit` and whose
+ * `test:unit` is vitest was MEASURED as vitest and OMITTED from staging, which fails preparation or
+ * loses that package's coverage for a reason nothing in the output names.
+ *
+ * The family comes from the repository root, which is where the pin that admits the hop is declared
+ * and is exactly what {@link detectTarget} reads.
+ */
+declare function classifyPackageDirectory(repoDir: string, dir: string, ctx?: RepoAccess): ManifestClassification | null;
+/**
+ * What {@link bindPreparedTestCommand} needs about the package a declared command runs in.
+ *
+ * THE SCRIPTS ARE THE TARGET PACKAGE'S and the alias-hop manifest is THE ROOT'S, and the two are
+ * deliberately different files. `npm run test:ci` names a script in the manifest beside the suite,
+ * which under `--subdir` is not the repository root; the `packageManager` pin that decides whether
+ * a second hop carries abloh's flags is declared once, at the root, which is where `detectTarget`
+ * and `classifyPackageDirectory` both already read it from.
+ *
+ * An unreadable or absent manifest yields empty scripts rather than throwing: a declared command
+ * that names no script is a perfectly ordinary thing to run from a directory with no `package.json`,
+ * and the reading it gets is the narrower one it always had.
+ */
+declare function declaredCommandContext(repoDir: string, subdir: string | null, ctx?: RepoAccess): DeclaredCommandContext;
+/**
+ * Read `test.dir` out of the repo's vitest (or vite) config. Heuristic, dependency-free:
+ * find the first `dir:` string literal inside the `test: { ... }` block. Stryker's
+ * vitest-runner forwards `vitest.dir` as a CLI-level override, so an unset value would
+ * clobber the repo's own config (the redux layout) — we forward the repo's value instead.
+ */
+declare function detectVitestDir(dir: string, ctx?: RepoAccess): string | undefined;
+/**
+ * `test.dir` out of one config's source, read from INSIDE the `test` block and nowhere else.
+ *
+ * The defect this replaces was `/test\s*:\s*\{[\s\S]*?\bdir\s*:\s*…/`. `[\s\S]*?` is lazy but
+ * unbounded: it does not stop at the block's closing brace, so the first `dir:` ANYWHERE later in
+ * the file was taken as vitest's. Measured on a config whose `build` block carries a `dir`, the
+ * answer was `OOPS-not-a-test-dir` - and a wrong `dir` means vitest finds no tests, which surfaces
+ * as "No tests were executed" and kills the mutation run before a single mutant exists.
+ *
+ * The block is delimited by COUNTING BRACES, and when it cannot be delimited - an unbalanced file,
+ * a `test` key that is not an object literal - this refuses to answer rather than reading past it.
+ * Stryker's own default is a better answer than a confident wrong one.
+ */
+declare function vitestDirIn(source: string): string | undefined;
+/**
+ * Detect how to test `repoDir` (optionally a subdir holding the testable package.json).
+ * Prefers a dir whose package.json declares a runner; falls back to any dir with a `test`
+ * script (command runner). Throws when nothing testable is found.
+ */
+/**
+ * The path prefix between REPOSITORY-relative paths and the paths spoken by the tools that run in
+ * `workDir` - Stryker's `mutate` entries, and the file paths its report comes back with.
+ *
+ * NOT THE SAME QUESTION AS "which package is measured", and this function exists because the two
+ * used to be one string. They are equal for every ordinary package, where the tools run inside the
+ * package they measure, and they diverge for exactly one shape: a {@link TargetDetection.workspaceRootSuite}
+ * runs the tools at the repository root while measuring one package, so their paths are already
+ * repository-relative and stripping the package prefix would name files that do not exist.
+ *
+ * The MEASUREMENT scope stays `subdir` in both modes, and the runner-relative prefix diff coverage uses
+ * stays `subdir` too - a jest `rootDir` and a vitest `root` are the project's, whatever directory
+ * the process was started in.
+ */
+declare function workDirPrefix(detection: Pick<TargetDetection, "subdir" | "workspaceRootSuite">): string | null;
+/**
+ * Why the CLASSIC layer cannot drive ONE test of this runner, or null when it can.
+ *
+ * THE CAPABILITY THIS NAMES, precisely. `ProofRunner` in `@abloh/measure` is the set of runners the
+ * v1 fix loop and the deep-audit container can execute one test file at a time and read a per-test
+ * report from, and every member of it has a Stryker plugin or a hand-written runner command in
+ * `runner.ts`. deno has neither: Stryker ships no deno plugin, so its mutation runs whole-suite
+ * through the command runner, and `runner.ts` is the frozen benchmark control arm that may not gain
+ * a deno arm on the way past.
+ *
+ * IT IS NOT A STATEMENT ABOUT DENO'S RUNNER. `deno test --filter '/(?:^|\s)name$/' --reporter=junit`
+ * selects exactly one test and names it in a machine-readable report - measured 2026-08-18 - and the
+ * SEALED v2 engine drives deno that way on the shipped path. So the sentence says which layer, not
+ * "unsupported", because a reader who is told the latter will conclude the wrong thing about the v2
+ * results in the same artifact.
+ */
+declare function classicPerTestRunner(runner: Runner): runner is ProofRunner;
+declare function classicPerTestRefusal(runner: Runner): string | null;
+/**
+ * THE PACKAGES A WORKSPACE ROOT COULD BE POINTED AT, read off disk.
+ *
+ * WHAT WAS BROKEN WITHOUT IT. Both refusals below describe a repository whose suites live in its
+ * workspace packages, and neither one named a single package - so a customer or an agent standing
+ * at a workspace root was told what was absent and never told what was present, on a repository
+ * where the answer is a directory listing this codebase already knows how to produce. The
+ * fresh-clone refusal named no remedy at all.
+ *
+ * A CANDIDATE IS A PACKAGE THAT DECLARES A SUITE, not merely a package. The enumeration is the
+ * workspace declaration's own (`enumerateWorkspacePackagesOnDisk` - pnpm-workspace.yaml,
+ * `workspaces`, `rush.json`, `nx.json`), and the filter is the same test `detectTarget` applies to
+ * a `--subdir`: a runner or a `test` script. A package with neither is not somewhere the customer
+ * could point this command, so naming it would be naming a wrong answer.
+ */
+declare function testableWorkspacePackages(repoDir: string, refusals?: string[], ctx?: RepoAccess): string[];
+declare function detectTarget(repoDir: string, subdir?: string | null, resolution?: PackageManagerResolution, ctx?: RepoAccess): TargetDetection;
+
+/**
+ * A REFUSAL FROM `init`, CARRYING ITS OWN CATEGORY.
+ *
+ * WHY THE CLASS IS ON THE ERROR. `init` reports one outcome category at the end of every run
+ * (`@abloh/core`'s `init-telemetry.ts`), and the failure half of that category has to be the SAME
+ * vocabulary as the refusal the customer just read on their terminal - otherwise there are two
+ * answers to "why did this init not finish" and only one of them is in front of the person it
+ * happened to.
+ *
+ * The alternative was a table of regular expressions over the refusal text, and it is the wrong
+ * shape for a reason worth stating: a refusal message is COPY. It gets rewritten - this file's own
+ * neighbours have been rewritten twice this month - and the day somebody improves a sentence, every
+ * event it raised silently changes bucket while the code that raised it did not move. A class on
+ * the throw cannot drift from the throw.
+ *
+ * NOTHING ELSE CHANGES. The message is the message; `initRefusal` is `new Error` with one extra
+ * field, so every existing reader - the `catch` in `index.ts`, every test that asserts on the
+ * sentence - sees exactly what it saw before.
+ */
+
+declare class InitRefusal extends Error {
+    readonly failureClass: InitFailureClass;
+    /**
+     * THE WALK KEY THIS REFUSAL IS ABOUT, where the throw site knows one the class cannot.
+     *
+     * Null on almost every throw, and that is right: the class already implies the key for a refusal
+     * that can only ever be about one - `no-reviewed-image` is `runtimeImage` wherever it is raised,
+     * and `init-refusal-shape.ts` holds that mapping in one table rather than repeating it at forty
+     * throw sites. This field is for the refusals where the class covers SEVERAL keys, which today is
+     * the answers document: `invalid-answers-file` is about whichever key the document got wrong, and
+     * a fix depends on knowing which.
+     */
+    readonly questionKey: InitQuestionKey | null;
+    /**
+     * THIS REFUSAL'S OWN REMEDY, where the class table's is not true of this instance.
+     *
+     * Null on almost every throw, and that is still right: a per-class remedy is what stops forty
+     * throw sites carrying forty drifting copies of the same sentence. But a CLASS is not always one
+     * situation, and `repository-too-large` is where that broke (external refusal review, rank 15).
+     * Its four throw sites all tell the human to pass `--environment-image`, because the scan they
+     * abandon is the Dockerfile scan and an image is what makes it unnecessary. The class table told
+     * the MACHINE to pass `--subdir`, which narrows nothing: the scan walks the repository root
+     * whatever `--subdir` says. A human and an agent reading the same refusal were sent to different
+     * options, and only one of them could work.
+     *
+     * So a throw site that knows better than its class says so here, and `init-refusal-shape.ts`
+     * prefers it. One refusal instance, one remedy, whoever is reading.
+     */
+    readonly remedy: string | null;
+    constructor(failureClass: InitFailureClass, message: string, questionKey?: InitQuestionKey | null, remedy?: string | null);
+}
+/** The throw site's own spelling: `throw initRefusal("no-reviewed-image", "...")`. */
+declare function initRefusal(failureClass: InitFailureClass, message: string, questionKey?: InitQuestionKey | null, remedy?: string | null): InitRefusal;
+/** The remedy an error itself carries, or null to fall back to its class. */
+declare function refusalRemedyOf(error: unknown): string | null;
+/**
+ * The class an error ends up counted under.
+ *
+ * `unclassified` for anything init did not raise itself - a filesystem error, a bug. Losing those
+ * would make the one number that says "something is wrong that we have not named" always zero.
+ */
+declare function initFailureClassOf(error: unknown): InitFailureClass;
+
+/**
+ * THE ONE FUNCTION THAT DECIDES WHAT A TARGET'S MEASUREMENT IS.
+ *
+ * `init`, `prepare`, `run` and publication each used to reconstruct the same plan from the same
+ * tree, separately, and the structural review of 2026-08-28 found that the disagreements between
+ * those reconstructions are where abloh's measured failures live (§7.3, §7.5). `vitejs/vite` is the
+ * clearest one: `abloh prepare` read the manifests alone and answered "nothing to prepare", `abloh
+ * run` read `abloh.yml` first and measured vitest 4.1.11, and the refusal the maintainer got named
+ * the command that had just told them there was nothing to do.
+ *
+ * SO THE SEQUENCE LIVES HERE, ONCE:
+ *
+ *     policy declaration -> detectTarget -> resolvePreparedTestCommand -> bindPreparedTestCommand
+ *                        -> applyDeclaredRunner
+ *
+ * and every surface calls this rather than something that resembles it. A second copy of that
+ * sequence anywhere in the product is the divergence coming back.
+ *
+ * WHAT THIS PHASE DOES NOT DO, and the restraint is the point. It admits nothing, gates nothing, and
+ * changes no external behaviour - same generated files, same terminal output, same published
+ * payloads. §11.1: "no candidate receives admitted status until the common executor validates it."
+ * The executor is phase 2.
+ *
+ * WHAT IT DELIBERATELY DOES NOT REACH FOR. It does no network, starts no container, and runs no
+ * install. Two of the plan's fields are therefore OBSERVATIONS the caller supplies rather than facts
+ * this module can discover: {@link ResolveMeasurementPlanInput.provider}, which needs the coverage
+ * adapter the caller has already prepared, and the proof image's DIGEST, which needs a registry.
+ * Both are optional and both are stated-absent rather than guessed - a plan that invented a provider
+ * identity would be the `prepare` defect again, one layer down.
+ */
+
+/**
+ * The declaration `abloh.yml` makes about the suite, read once.
+ *
+ * EVERY FIELD, because the run reads every one and only reading some is what put prepare and the run
+ * on different packages. `target.directory` names the package; `environment.testCommand` names the
+ * command and OUTRANKS the manifest, so a declared `vitest run` over a `scripts.test` of
+ * `run-s test-unit test-serve` measures with vitest whatever the script says; `environment.runner`
+ * names the adapter and outranks what that command was read as naming.
+ *
+ * AN INVALID POLICY ANSWERS NOTHING. `abloh run` fails it with its own precise error, and neither
+ * this resolver nor `prepare` has ever been the surface that reports a malformed policy.
+ */
+interface PolicyDeclaration {
+    directory: string | null;
+    testCommand: string | undefined;
+    /**
+     * `environment.runner`, the runner the maintainer wrote down.
+     *
+     * READ HERE BECAUSE THE RUN MUST NOT RE-DERIVE IT (audit F2). Nineteen detection facts were
+     * re-worked-out from the tree on every run and none was recorded, so a repository abloh read
+     * wrong at setup was read wrong again for ever. This is the recorded half, and `resolveTarget`
+     * applies it after the command reading, which is the only order in which a statement can outrank
+     * a guess.
+     */
+    runner: string | undefined;
+}
+/**
+ * WHAT THE WORKING TREE'S OWN `abloh.yml` DECLARES, or nothing when it declares none.
+ *
+ * THE PARSE IS STILL `loadConfig`, WHICH OPENS THE FILE ITSELF, and that is the one reading in this
+ * module the reader does not cover. It is bounded rather than open: the access decides whether
+ * there is a file to read at all, so a road with no checkout answers "no declaration" and stops,
+ * which is the right answer for the door this reader exists for - a repository being onboarded has
+ * no `abloh.yml` yet, that being the whole point of onboarding it. Giving `loadConfig` a text
+ * argument is the fix when a road needs one, and it is a change to core's parser rather than here.
+ */
+declare function policyDeclaration(repoDir: string, ctx?: RepoAccess): PolicyDeclaration;
+/**
+ * WHO ANSWERS THE DECLARED QUESTIONS - and this is a SECURITY distinction, not a convenience.
+ *
+ * `from-disk` reads the repository's own `abloh.yml`, which is what `init` and `prepare` want: they
+ * are looking at the working tree in front of the maintainer.
+ *
+ * `supplied` is the RUN's, and it must never be made to re-read the working tree. A pull-request run
+ * loads its policy from the TRUSTED merge-base commit precisely so that a later commit cannot change
+ * what privileged infrastructure executes by editing a file. Handing this resolver a `repoDir` and
+ * letting it open `abloh.yml` would hand that decision back to the pull request.
+ */
+type PlanDeclaration = {
+    source: "from-disk";
+} | {
+    source: "supplied";
+    directory: string | null;
+    testCommand: string | undefined;
+    /**
+     * The trusted environment block, for every plan field that comes from the policy rather than
+     * from the tree: the setup script, the services, the required variable NAMES, the declared
+     * runtimes and system packages, the generated outputs.
+     *
+     * OMITTING IT MEANS THE CALLER HOLDS NONE, and the plan then carries the empty answer. It does
+     * NOT fall back to reading `abloh.yml` off disk: a caller that supplied a declaration did so
+     * because the working tree is not the authority for it, and a silent disk fallback for the
+     * other half of the same file would be exactly the hole this discriminator exists to close.
+     */
+    environment?: EnvironmentConfig;
+};
+interface ResolveMeasurementPlanInput {
+    /** Repository root, already resolved through `resolveRepositoryContext`. */
+    repoDir: string;
+    /**
+     * The package to measure, when a caller has already chosen one.
+     *
+     * `--subdir` on `run` and `prepare`, the auto-selected package on a pull request, the workspace
+     * package `init` picked. Null lets `target.directory` answer, and null again lets detection walk.
+     */
+    subdir?: string | null;
+    /** `--test-command`, which outranks the policy and the manifest both. */
+    cliTestCommand?: string | undefined;
+    /** How the directory was chosen, so the plan records a stated value rather than an inference. */
+    selection?: TargetSelectionKind;
+    /** See {@link TargetResolutionInput.access}. Omitted is a checkout at `repoDir`. */
+    access?: RepoAccess;
+    /**
+     * The coverage adapter the caller has already resolved, when it has one.
+     *
+     * SUPPLIED RATHER THAN LOOKED UP. Resolving it means reading `node_modules` and possibly abloh's
+     * provider cache, which is I/O this module has no business doing on `init`'s path - and the run
+     * has already done it by the time it wants a plan.
+     */
+    provider?: {
+        name: string;
+        source: "project" | "runtime" | "abloh-bundled" | "abloh-cache";
+        version: string | null;
+    } | null;
+    /** Why no provider resolved, in the customer's words. Ignored when a provider is supplied. */
+    providerReason?: string | null;
+    /** The proof image ref in force, from `--environment-image` or the policy default. */
+    imageRef?: string | null;
+    imageSource?: "customer" | "abloh-default" | null;
+    /** Which owned outputs this target's configuration is expected to produce. */
+    expectedEvidence?: readonly EvidenceOutputId[];
+    /**
+     * Detection already performed by the caller, so a run does not detect twice.
+     *
+     * THE RUN SUPPLIES THIS. `index.ts` establishes detection inside a try/catch that turns two
+     * distinct failures into two distinct artifact records, and re-detecting here would either
+     * duplicate that handling or lose it. What matters for the seam is that both paths call the SAME
+     * three functions in the SAME order, which {@link resolveTargetDetection} is.
+     */
+    detection?: TargetDetection;
+    /** Where the declared directory and command come from; see {@link PlanDeclaration}. */
+    declaration?: PlanDeclaration;
+}
+/**
+ * DETECTION, BOUND TO THE DECLARED COMMAND - the exact three calls, in the exact order.
+ *
+ * Exported because `prepare` and the run both need the resolved {@link TargetDetection} itself and
+ * not only the plan built over it. It is the smallest thing both can share, and sharing it is what
+ * stops them resolving different packages in the same tree.
+ */
+interface TargetResolutionInput {
+    repoDir: string;
+    /**
+     * The package to measure.
+     *
+     * `undefined` and `null` ARE DIFFERENT ANSWERS, and conflating them would change what the run
+     * measures. `undefined` means nobody has chosen, so the declaration's `target.directory` answers.
+     * An explicit `null` means the caller HAS chosen, and chose the repository root - which is what
+     * the run passes, because `effectiveSubdir` has already folded the declared directory into its
+     * own `opts.subdir` several hundred lines earlier.
+     */
+    subdir?: string | null;
+    cliTestCommand?: string | undefined;
+    declaration?: PlanDeclaration;
+    /**
+     * WHERE THIS REPOSITORY'S BYTES COME FROM, when they do not come from a checkout.
+     *
+     * Omitted is a checkout at `repoDir`, which is every caller in the CLI. It is supplied by the
+     * control plane, which reads the same repository over GitHub's contents API and has no checkout
+     * at all - see `packages/core/src/repo-reader.ts` for why the deciding in between must be one
+     * implementation rather than two.
+     */
+    access?: RepoAccess;
+}
+/**
+ * BOTH HALVES OF THE RESOLUTION, so a caller that needs the raw detection as well as the bound one
+ * gets them from a single pass.
+ *
+ * The run needs all three: `detected` to say whether the declared command outranked the manifest's
+ * runner, `command` to build the environment contract, and `detection` to measure with. It used to
+ * write those three calls out itself, which is one of the two copies of this sequence the
+ * structural review counted.
+ */
+interface TargetResolution {
+    /** What the tree alone says, before any declared command is applied. */
+    detected: TargetDetection;
+    /** The command that will execute, and where it came from. */
+    command: ReturnType<typeof resolvePreparedTestCommand>;
+    /** Detection re-bound to that command - what a measurement actually uses. */
+    detection: TargetDetection;
+}
+declare function resolveTarget(input: TargetResolutionInput): TargetResolution;
+/** The bound detection alone, for the callers that need nothing else. */
+declare function resolveTargetDetection(input: TargetResolutionInput): TargetDetection;
+/**
+ * RESOLVE ONE TARGET'S PLAN.
+ *
+ * Every field is decided here and nowhere else. A consumer that finds itself re-deriving one has
+ * found the seam this object exists to close, and the fix is to add the field rather than to
+ * recompute it locally.
+ */
+declare function resolveMeasurementPlan(input: ResolveMeasurementPlanInput): MeasurementPlan;
+
+/** One Node version a repository states, exactly as it states it, and where it was read. */
+interface NodeDeclaration {
+    /** The text verbatim: `16`, `24.16.0`, `v26`, `lts/*`, `latest`. Never normalised. */
+    spec: string;
+    /** Where it came from, in the receipt's own words. */
+    evidence: string;
+    /**
+     * The repo-relative file that states it, separately from the sentence about it.
+     *
+     * The generated workflow needs the path on its own: `actions/setup-node` reads `.nvmrc`,
+     * `.node-version`, `.tool-versions` and `package.json` itself, and pointing it at the
+     * repository's own file is what stops the check's Node and the repository's Node from drifting
+     * apart. Null for a declaration that lives in a CI file rather than in a version file.
+     */
+    path: string | null;
+}
+/** One `engines.node` range, kept apart from every other one in the package chain. */
+interface NodeRequirement {
+    range: string;
+    /** The repo-relative manifest that states it. */
+    source: string;
+}
+/** One entry of the publisher's release index, as `nodejs.org/dist/index.json` states it. */
+interface NodeRelease {
+    /** `26.8.2`, with no leading `v`. */
+    version: string;
+    /** The LTS codename, or false for a release that is not on an LTS line. */
+    lts: string | false;
+}
+/**
+ * What one declaration's text says, before anything is looked up.
+ *
+ * `unreadable` is a real answer and never a refusal: a `.nvmrc` reading `lts/-1` is a form this
+ * product does not resolve, and the honest response is to say so and let the next declaration or
+ * the host answer - which is what the receipt already did for it.
+ */
+type NodeSpecReading = {
+    kind: "exact";
+    version: string;
+}
+/** A major or a major.minor, as the semver range it names and the words for it. */
+ | {
+    kind: "family";
+    range: string;
+}
+/** `latest`, `current`, `node` - the newest release there is. */
+ | {
+    kind: "newest";
+}
+/** `lts`, `lts/*`, `lts/latest` - the newest release on the newest LTS line. */
+ | {
+    kind: "newest-lts";
+}
+/** `lts/jod` - the newest release on the line with that codename. */
+ | {
+    kind: "lts-line";
+    name: string;
+} | {
+    kind: "unreadable";
+};
+/**
+ * The one grammar every declaration form goes through, whichever file or workflow stated it.
+ *
+ * THE ALIASES ARE ASKED BEFORE THE RANGE and the order is load-bearing: `semver` reads `latest` as
+ * no range at all, but it would happily read a future alias as one, and an alias resolved by
+ * arithmetic rather than by the publisher's own index is exactly the guess this module refuses.
+ *
+ * THE FAMILY IS `semver`'S OWN READING and not a pattern of ours. A `node-version` is written every
+ * way a range can be written - `16`, `22.14`, `24.x`, `^20`, `>=18`, `18 || 20` - and
+ * `actions/setup-node` resolves all of them with semver, so a second implementation here would be a
+ * second answer to a question that already has one. `moment/luxon` writes `24.x`, which a
+ * digits-only reader called unreadable.
+ */
+declare function readNodeSpec(text: string): NodeSpecReading;
+/**
+ * Every published version a spec admits, newest first.
+ *
+ * An alias names exactly one, because that is what an alias IS: `lts/*` on the day `init` runs is
+ * one release, and the digest the image resolver then pins is what freezes it. A family names
+ * every release inside it, so the newest is taken once the requirements have had their say.
+ */
+declare function nodeSpecVersions(reading: NodeSpecReading, releases: readonly NodeRelease[]): string[];
+/** Why one declaration produced no version this repository could be measured on. */
+type NodeDeclarationProblem = 
+/** Abloh has no reading for the form it is written in. Disclosed, never refused. */
+{
+    kind: "unreadable";
+}
+/** It reads correctly and names a Node the publisher has never released. */
+ | {
+    kind: "never-published";
+}
+/** It reads correctly and this repository's own `engines.node` excludes every version of it. */
+ | {
+    kind: "excluded";
+    by: readonly NodeRequirement[];
+};
+interface NodeDeclarationRejection {
+    declaration: NodeDeclaration;
+    problem: NodeDeclarationProblem;
+}
+type NodeChoice = {
+    kind: "chosen";
+    /** The concrete published version the image is resolved from. */
+    version: string;
+    major: number;
+    /** The declaration it came from, or null when the repository declares none. */
+    declaration: NodeDeclaration | null;
+    /** Declarations passed over on the way here, each with the reason, for the receipt. */
+    rejected: readonly NodeDeclarationRejection[];
+}
+/** No published Node satisfies every `engines.node` in this repository, whatever is declared. */
+ | {
+    kind: "requirements-conflict";
+    requirements: readonly NodeRequirement[];
+}
+/** The requirements admit a Node and not one declaration lands inside them. */
+ | {
+    kind: "declarations-unsatisfiable";
+    rejected: readonly NodeDeclarationRejection[];
+};
+/**
+ * THE ONE CHOICE, AND THE ORDER IS THE WHOLE RULE.
+ *
+ * Declarations arrive strongest first - a version file before a CI job, because a version file is a
+ * single deliberate line every contributor's tooling reads while a CI `node-version` is frequently
+ * one cell of a matrix. Each is offered its published versions, each version is tested against
+ * EVERY requirement separately, and the first declaration with a survivor wins at its own newest.
+ *
+ * WHAT REFUSES, AND WHAT DOES NOT. A form abloh cannot read is skipped and carried on `rejected` so
+ * the receipt can name the line it could not read - that is a disclosure, and it is what `lts/-1`
+ * has always got. A declaration abloh CAN read that no admitted Node satisfies is a contradiction
+ * inside the repository, and there is no honest image for it: picking one anyway is the defect this
+ * function replaces. The two are told apart so a repository is never refused over a spelling.
+ */
+declare function chooseNodeVersion(input: {
+    /** Strongest first. */
+    declarations: readonly NodeDeclaration[];
+    requirements: readonly NodeRequirement[];
+    releases: readonly NodeRelease[];
+    /** The major to prefer when the repository declares nothing at all. */
+    preferredMajor: number | null;
+}): NodeChoice;
+/** The sentence a receipt or a notice uses for one declaration abloh passed over. */
+declare function nodeDeclarationProblemReason(rejection: NodeDeclarationRejection): string;
+
+/**
+ * THE CLI's HALF OF THE SHARED READER: a checkout on this machine.
+ *
+ * `packages/core/src/repo-reader.ts` states why the interface exists and why it is synchronous.
+ * This is the implementation `abloh init` hands to the drafting functions; the control plane hands
+ * them one over bytes it fetched from GitHub, and the deciding in between is the same code.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * IT KEEPS EVERY REFUSAL THE CALLERS USED TO MAKE FOR THEMSELVES.
+ * ---------------------------------------------------------------------------------------------
+ *
+ * The three call sites this replaces did not simply read files. They checked containment against
+ * the checkout root before opening anything, because a `uses: ./../../x` and a `node-version-file`
+ * are repository-author-controlled text; they refused SYMLINKS, because a symlink in a stranger's
+ * repository points wherever its author decided; and they refused anything that was not a plain
+ * file. Every one of those refusals is here instead of there, which is the point of moving them:
+ * a reader that only refused on some paths would be a reader every future caller had to remember
+ * to check around.
+ *
+ * CONTAINMENT IS CHECKED TWICE ON PURPOSE. `normalizeRepoPath` refuses `..` and absolute paths
+ * before a path is joined, and the PARENT of the join is resolved and checked against the resolved
+ * root afterwards. The first catches the ordinary case; the second catches the one the first cannot
+ * see, which is a SYMLINKED DIRECTORY partway down a path that is itself perfectly relative.
+ *
+ * WHAT THE SYMLINK RULE NARROWS, stated because it is a product-visible change rather than a
+ * refactor. `detect.ts` used to reach its manifests with bare `existsSync`/`readFileSync`, which
+ * FOLLOW a link, so a repository whose `package.json` is a symlink was read; through this reader it
+ * is absent. A symlinked DIRECTORY on the way to a file is a different case and still works, because
+ * the check below is "does this resolve inside the repository" rather than "is there a link in this
+ * path" - which is what a monorepo linking one package into another needs. What is refused is a link
+ * that leaves, and a link AS the file, on the ground that its target is chosen by the author of the
+ * repository being drafted for.
+ *
+ * The second half said this and did not do it until 2026-09-05: the join was compared against the
+ * root as TEXT, so `elsewhere/secret.json` was inside the repository whatever `elsewhere` pointed
+ * at, and refusing a symlink at the leaf never reaches one in the middle. `repo-reader-disk.test.ts`
+ * is what found it, which is the argument for a reader having a test of its own rather than being
+ * covered only through its callers.
+ */
+declare function diskRepoReader(repoDir: string): RepoReader;
+
+/** The declaration at a Rush repository's root. Its presence IS what makes a repository one. */
+declare const RUSH_CONFIG_FILE = "rush.json";
+/**
+ * The script name a Rush project spells its test phase with, and the ordinary one it may also have.
+ *
+ * `rush test` is a PHASED command defined in `common/config/rush/command-line.json`, and phases map
+ * onto `_phase:<name>` scripts. A project that declares a plain `test` has said the same thing in
+ * the spelling every other monorepo uses, so both are read and the ordinary one wins - if an author
+ * wrote both, the one every other tool would run is the one they meant.
+ */
+declare const RUSH_TEST_SCRIPTS: readonly ["test", "_phase:test"];
+/** Where a Rush repository keeps the files that decide what an install produces. */
+declare const RUSH_CONFIG_DIRECTORY = "common/config/rush";
+declare const RUSH_SUBSPACE_DIRECTORY = "common/config/subspaces";
+declare const RUSH_LOCKFILE_NAME = "pnpm-lock.yaml";
+declare const RUSH_REPO_STATE_NAME = "repo-state.json";
+/**
+ * The COMMITTED bootstrap that installs the exact Rush a repository pins, then installs with it.
+ *
+ * `node common/scripts/install-run-rush.js install` and nothing shorter. `rush install` alone
+ * requires a globally installed Rush of a compatible version, which a sealed image has no reason to
+ * carry; the committed script reads `rushVersion` out of `rush.json`, fetches exactly that Rush, and
+ * that Rush then installs exactly the pnpm `pnpmVersion` names. So the version pinning is the
+ * repository's own, all the way down, and abloh adds none of it.
+ *
+ * Measured on rushstack 2026-08-18: `Rush install finished successfully. (2 minutes 17.9 seconds)`,
+ * 193 projects, from the committed lockfile.
+ */
+declare const RUSH_INSTALL_COMMAND = "node common/scripts/install-run-rush.js install";
+/** The path of the bootstrap the command above runs, so its ABSENCE can be reported as one. */
+declare const RUSH_INSTALL_SCRIPT = "common/scripts/install-run-rush.js";
+/** One project a Rush root declares, and what its own manifest says about building and testing. */
+interface RushProject {
+    /** Repository-relative project directory, exactly as `rush.json` spells it. */
+    directory: string;
+    /** The package name `rush.json` pairs with that folder. */
+    name: string;
+    /** What this project's `test` phase is, once its manifest has been read. */
+    test: RushTestTarget;
+}
+type RushTestTarget = 
+/** A literal command, run in the project's own directory, exactly as a package script would be. */
+{
+    state: "command";
+    script: string;
+    command: string;
+} | {
+    state: "unmeasurable";
+    reason: string;
+    remedy: string;
+};
+/**
+ * Read one Rush project's manifest into the answer per-package composition can act on.
+ *
+ * The command is taken VERBATIM and run in the project's own directory, which is the whole reason
+ * Rush is drivable where integrated Nx was not: there is no workspace-root cwd problem to solve,
+ * because `heft run --only test` is what the author runs, where they run it.
+ *
+ * Everything it declines, it declines by name. A shell-composed command is not one suite; a project
+ * with no test phase declares no suite at all.
+ */
+declare function classifyRushTestScript(manifest: unknown, directory: string): RushTestTarget;
+/**
+ * Enumerate a Rush workspace's projects from `rush.json` and the manifests it points at.
+ *
+ * READ THROUGH A SEAM, for the reason `enumerateNxProjects` states: selection reads the TRUSTED
+ * merge-base tree and `abloh prepare` reads the working tree, and the two desyncing on one
+ * repository is the failure this shares with manifest classification. So this takes a reader and
+ * never touches the filesystem.
+ *
+ * @param readFile the bytes of one repository-relative path, or null when absent/unreadable
+ */
+declare function enumerateRushProjects(readFile: (path: string) => string | null, limit: number): RushProject[];
+/**
+ * The identity files a Rush install's outcome depends on, in the order a reader should see them.
+ *
+ * THREE FACTS, NOT ONE LOCKFILE, and each is load-bearing:
+ *
+ *   - `rush.json` pins the Rush version AND the pnpm version, so the same lockfile installed by two
+ *     Rush versions is two installs.
+ *   - the pnpm lockfile is the dependency set, and it lives per SUBSPACE. rushstack declares two
+ *     (`default` and `build-tests-subspace`), so a single path would name one of them and miss the
+ *     other; every one found is an identity file.
+ *   - `repo-state.json` is Rush's own record that the lockfile has not been hand-edited
+ *     (`pnpmShrinkwrapHash`, `preferredVersionsHash`), and Rush verifies it BEFORE installing. It is
+ *     the one file in this list whose whole purpose is to make the install deterministic, which is
+ *     exactly what an identity file is for.
+ *
+ * @param exists whether a repository-relative path is present
+ * @param subdirectories the immediate child directory names of a repository-relative directory
+ */
+declare function rushIdentityFiles(input: {
+    exists: (path: string) => boolean;
+    subdirectories: (path: string) => readonly string[];
+}): string[];
+/** Every lockfile a Rush install reads, for the install-recipe's "there is a frozen set" check. */
+declare function rushLockfiles(input: {
+    exists: (path: string) => boolean;
+    subdirectories: (path: string) => readonly string[];
+}): string[];
+/**
+ * The node version range a Rush repository ENFORCES on its host, or null when it declares none.
+ *
+ * A GATE NO OTHER JS REPOSITORY SHAPE IMPOSES, and it is a hard error rather than a warning:
+ *
+ *     ERROR: Your dev environment is running Node.js version v24.7.0 which does not meet the
+ *     requirements for building this repository. (The rush.json configuration requires
+ *     nodeSupportedVersionRange=">=20.9.0 <21.0.0 || >=22.12.0 <23.0.0 || ...")
+ *
+ * Rush refuses to install at all. It cuts both ways, and the second way is the useful one: it is a
+ * DECLARATION abloh can read to validate the base image before a build, which no other shape offers.
+ * Reported rather than acted on here - the caller decides whether an image satisfies it.
+ */
+declare function rushNodeVersionRange(rushJsonText: string | null): string | null;
+
+/**
+ * ONE FACT ABOUT THE JOB THAT THE TRIAL WILL NEED AND THE JOB DOES NOT DECLARE.
+ *
+ * NOT A REFUSAL. Nothing here stops the step being appended or the setup PR being opened; the trial
+ * runs and either it mattered or it did not. What this exists to prevent is a maintainer meeting
+ * the consequence with no idea it was foreseeable - the same complaint the whole flip is about, one
+ * layer down.
+ */
+interface SetupStepPrecondition {
+    /** What sort of thing is missing, in the words the setup PR body prints. */
+    kind: "workflow-step";
+    /** The file the fix goes in, always one the setup PR touches. */
+    file: string;
+    /** The key inside it, in the workflow's own spelling. */
+    key: string;
+    /** What the trial needs, in one sentence. */
+    need: string;
+}
+/**
+ * WHAT ABLOH DID ABOUT THE ATTESTATION JOB, so the setup PR body can say it in one sentence.
+ *
+ * A reviewer is being asked to accept a NEW JOB in their workflow, which is a bigger thing than a
+ * step and the one part of this change that costs them a runner. It is never left to be inferred
+ * from an indentation level: the body names the job, what it runs, and the single permission it
+ * holds.
+ */
+type AttestationJob = 
+/** The job was written into the file, and depends on the job the measuring step rides. */
+{
+    kind: "written";
+    jobId: string;
+    needs: string;
+    key: string;
+    file: string;
+}
+/** A job of ours by that id was already in the file, so nothing was written. */
+ | {
+    kind: "already-there";
+    jobId: string;
+    key: string;
+    file: string;
+};
+/**
+ * THE SECOND FILE THIS PLACEMENT EDITS, when abloh's publish job may not go where its step went.
+ *
+ * WHY THERE IS A SECOND FILE AT ALL (census run 7, F2, part two). A workflow declaring
+ * `workflow_call` has its jobs' permissions capped by whatever calls it, so the publish job cannot
+ * live there - but the STEP asks for no permission and rides that job perfectly well. So the step
+ * goes into the callee and the job into a caller GitHub starts itself. `setupPublishHost` in
+ * `@abloh/core` decides which file that is, and the caller of this function hands it in.
+ */
+interface SetupPublishPlacement {
+    /** The workflow the publish job was written into, repo-relative. */
+    file: string;
+    /** That file as it is on disk now. */
+    before: string;
+    /** That file with the job in it. Identical to `before` when the job was already there. */
+    after: string;
+    /** The unified diff a reviewer reads, empty when nothing was written. */
+    diff: string;
+}
+interface SetupStepPlacement {
+    /** The workflow file, repo-relative. */
+    file: string;
+    /** The job the step was appended to. */
+    jobId: string;
+    /**
+     * WHICH OF THE JOB'S OWN STEPS ABLOH'S STEP WENT IN BEHIND, or null when it went in at the end.
+     *
+     * A FACT THE SETUP PULL REQUEST STATES rather than one a reviewer has to count lines to find.
+     * The whole point of the change is that Abloh no longer stands at the end of somebody's job, and
+     * a reviewer reading "one step appended" over a diff in the MIDDLE of their steps list would be
+     * reading a sentence that no longer matches the edit.
+     */
+    afterStepIndex: number | null;
+    /** The file as it is on disk now. */
+    before: string;
+    /** The file with both insertions. Identical to `before` when there was nothing left to add. */
+    after: string;
+    /** True when this job already ends in an Abloh step, so no step was appended. */
+    alreadyThere: boolean;
+    /** The unified diff a reviewer reads, empty when nothing was written. */
+    diff: string;
+    /** The job that holds the identity, and what abloh did about it. */
+    attestationJob: AttestationJob;
+    /**
+     * THE EDIT TO THE FILE THE PUBLISH JOB WENT INTO, or null when that was this file.
+     *
+     * NULL IS THE ORDINARY BORROW and not an omission: {@link after} already carries both insertions
+     * there. A non-null value is the split road, where {@link after} carries the step alone and this
+     * carries the job - two files, both of which the setup pull request lists.
+     */
+    publish: SetupPublishPlacement | null;
+    /**
+     * DID ABLOH WRITE `fail-fast: false` INTO THE RIDDEN JOB'S `strategy:` BLOCK?
+     *
+     * A FACT THE SETUP PULL REQUEST STATES rather than one a reviewer has to find in the diff. It is
+     * the one edit abloh makes that is not about abloh: it changes how the maintainer's OWN legs
+     * behave when one of them fails, so a reviewer has to be told it happened and why, in the same
+     * sentence that says one step was appended.
+     *
+     * FALSE WHERE THE ANSWER WAS `keep`, where the job does not fan out, where it already declares
+     * `fail-fast: false`, and where it declares a `fail-fast` of the maintainer's that abloh will not
+     * write over. `setup-fail-fast.ts` holds all four.
+     */
+    failFastWritten: boolean;
+    /** What the trial will need that this job does not declare. */
+    preconditions: readonly SetupStepPrecondition[];
+}
+
+/**
+ * APPEND THE STEP.
+ *
+ * `before` is the file's exact bytes and the caller owns reading them; this function opens nothing,
+ * so the same code runs over a fixture, over a scratch repository and over a real checkout.
+ */
+declare function placeSetupStep(input: {
+    file: string;
+    jobId: string;
+    before: string;
+    /**
+     * THE MATRIX LEG THIS STEP IS PINNED TO, or absent when the job is one build.
+     *
+     * It only changes the step's `if:`. See {@link setupStepIf}: a matrix has one steps list, so a leg
+     * is a condition rather than a second place to write.
+     */
+    leg?: MatrixLeg | null;
+    /**
+     * THE INDEX OF THE STEP THAT RUNS THEIR SUITE, so abloh's step goes in immediately behind it.
+     *
+     * WHY THE PLACEMENT MOVED (the fresh-ten launch-evidence run, 2026-08-31, bug 6). Appending at
+     * the END of the job put abloh after `swagger-api/swagger-ui`'s `Build SwaggerUI` step, which
+     * writes into a `dist/` that repository TRACKS - so abloh stood after a build and then refused
+     * the job for the build's output, on both cycles, and the maintainer moved nothing.
+     *
+     * BEHIND THE SUITE IS THE RIGHT PLACE AND IT NEEDS NO GUESS. Everything the suite needed has
+     * already run by the time it has run; everything after it is by definition not needed to run it.
+     * The value comes from {@link CiBorrowJob.lastTestStepIndex} - the reader's own classification of
+     * the step, which is how the job was chosen in the first place - and never from a scan of step
+     * names for build-sounding words.
+     *
+     * ABSENT OR NULL APPENDS AT THE END, which is the old behaviour and the honest answer for a job
+     * whose suite abloh could not locate: a declared `setup.job` need not run one at all.
+     */
+    afterStepIndex?: number | null;
+    /**
+     * WRITE `fail-fast: false` INTO THIS JOB'S `strategy:` BLOCK, in the same edit as the step.
+     *
+     * THE CALLER DECIDES AND THIS FUNCTION DOES NOT RE-READ THE WORKFLOW. `SetupJobDecision.failFast`
+     * has already asked all four questions - does the job fan out, does it already opt out, did the
+     * maintainer write a `fail-fast` of their own, and what did they answer - and a second reading
+     * here would be a second answer to the one question `setup-fail-fast.ts` owns.
+     *
+     * IT IS STILL REFUSED WHERE THE FILE CANNOT CARRY IT. A `strategy:` written as a one-line flow
+     * mapping has no block to insert into, and this module does not rewrite a line the maintainer
+     * wrote - so the step goes in and the line does not, which {@link SetupStepPlacement.failFastWritten}
+     * reports rather than claiming an edit that did not happen.
+     */
+    failFast?: boolean;
+    /**
+     * THE `name:` OF THE STEP `afterStepIndex` POINTS AT, so the comment can name it.
+     *
+     * WHY THE COMMENT NAMES IT (census run 4, `prettier/prettier`, F8). The line abloh writes into
+     * somebody else's workflow says where its step sits, and on a job with two suite steps under two
+     * `if:` conditions "the step that runs your suite" is a claim about WHICH of them - the claim
+     * that was false on prettier. A name is checkable by the person reading the diff; a description
+     * is not. Absent falls back to the unnamed wording, which claims nothing it cannot show.
+     */
+    afterStepName?: string | null;
+    /**
+     * THE FILE ABLOH'S PUBLISH JOB GOES INTO, when it may not go into the one the step goes into.
+     *
+     * THE CALLER DECIDES AND THIS FUNCTION DOES NOT RE-READ ANY WORKFLOW. `setupPublishHost` in
+     * `@abloh/core` is the one place the question is answered - callable file, is there a caller
+     * GitHub starts on a pull request - and a second reading here would be a second answer to it.
+     *
+     * `jobId` IS THE CALLER'S OWN JOB, the one whose `uses:` names the workflow the step went into,
+     * so abloh's job `needs:` the job that runs the step and reads the artifact it left on the same
+     * run. `before` is that file's exact bytes, on the same terms as {@link before}: this function
+     * opens nothing.
+     *
+     * ABSENT IS THE ORDINARY BORROW, where the job goes in beside the step exactly as it always has.
+     */
+    publishInto?: {
+        file: string;
+        jobId: string;
+        before: string;
+    } | null;
+}): SetupStepPlacement | Refusal;
+
+/**
+ * WHICH OF THE MAINTAINER'S SUITE STEPS ABLOH'S STEP GOES BEHIND, ON THE LEG IT PINNED.
+ *
+ * WHAT WAS BROKEN (census run 4, `prettier/prettier`, F8; run 33613921638 on the fork).
+ * `prettier`'s `.github/workflows/dev-test.yml::test` declares two suite steps and an `include:`
+ * leg decides which one runs:
+ *
+ *     - name: Run Tests
+ *       if: ${{ !matrix.ENABLE_CODE_COVERAGE }}
+ *       run: yarn test
+ *     - name: Run Tests (coverage)
+ *       if: ${{ matrix.ENABLE_CODE_COVERAGE }}
+ *       run: yarn c8 yarn test
+ *
+ * `setup-step.ts` was handed `CiBorrowJob.lastTestStepIndex`, one number decided by the reader
+ * before any leg existed, and the leg was decided separately by `setup-job.ts`. The two never
+ * spoke. Abloh pinned the cell carrying `ENABLE_CODE_COVERAGE: true` and stood behind the step that
+ * cell SKIPS - between the two suite steps, measuring a tree whose suite the maintainer's job had
+ * not run, while the comment abloh wrote into their own file said "It sits right after the step
+ * that runs your suite". Nothing could notice, because neither half knew about the other.
+ *
+ * THIS IS WHERE THE TWO MEET, and it is the only place either question is asked together. The
+ * reader states what the file says (`CiBorrowJob.testSteps`), `setup-job.ts` settles the leg, and
+ * this answers each step's own `if:` with GitHub's arithmetic - `evaluateStepConditions`, over
+ * `matrix-value.ts`'s coercion, which is the same rule F7 writes conditions with.
+ *
+ * WHEN SEVERAL RUN, THE LAST OF THEM. A job that shards its suite over two steps has not finished
+ * running it until the second has run, which is `lastTestStepIndex`'s own rule one question deeper.
+ *
+ * WHEN ABLOH CANNOT READ A CONDITION IT SAYS SO AND CHANGES NOTHING. A step gated on a secret, on
+ * another job's output, on the event payload or on an environment value something earlier exported
+ * is one no reading of the file can answer, so the anchor falls back to the last test-shaped step -
+ * which is exactly where it stood before this module existed - and the uncertainty is NAMED, on the
+ * job list `abloh init` prints and in the contract it writes. It is never a question: there is
+ * nothing to ask a maintainer that their own `if:` does not already say.
+ *
+ * AND WHEN NOTHING RUNS, THE SAME FALLBACK. A leg on which every suite step is skipped is a leg
+ * that runs no suite abloh recognized, and the honest anchor there is the unchanged one; the trial
+ * that follows is what says so, in its own words, having measured.
+ */
+
+/** Where abloh's step goes, and what abloh could not read on the way to deciding. */
+interface SetupStepAnchor {
+    /**
+     * The `jobs.<id>.steps` index to insert behind, or null to append at the end of the job.
+     *
+     * Null is the honest answer for a job whose suite abloh could not locate at all - a declared
+     * `setup.job` need not run one - and it is what `placeSetupStep` has always taken.
+     */
+    index: number | null;
+    /** That step's own `name:`, or null, so the comment abloh writes can name it. */
+    stepName: string | null;
+    /**
+     * ONE SENTENCE PER SUITE STEP WHOSE `if:` ABLOH COULD NOT ANSWER, in file order.
+     *
+     * Empty is the ordinary case and means the anchor is a reading rather than a fallback.
+     */
+    unreadable: readonly string[];
+}
+/**
+ * WHAT A STEP IS CALLED WHEN IT SAYS SO, and where it is when it does not.
+ *
+ * THE NAME IS THE MAINTAINER'S OWN TEXT AND IT IS REDUCED BEFORE IT IS QUOTED. This label reaches
+ * two surfaces and one of them is a COMMENT in the `abloh.yml` abloh writes into their repository,
+ * where a newline is not a comment - a `name:` spelled as a YAML block scalar carries one, and
+ * writing it through would break the file abloh is asking them to ratify. So whitespace collapses
+ * to one space and the name is clipped; past the clip the label says WHERE the step is, which is
+ * less than the name and is never wrong.
+ */
+declare function testStepLabel(step: CiJobTestStep): string;
+/**
+ * THE ONE SENTENCE THAT SAYS ABLOH COULD NOT ANSWER A STEP'S CONDITION.
+ *
+ * Written once because it is printed twice - on the job list a maintainer chooses from and in the
+ * `abloh.yml` that outlives the terminal - and two spellings of one fact is how a reader ends up
+ * unable to tell whether they are the same fact.
+ */
+declare function unreadableConditionLine(step: CiJobTestStep): string;
+/**
+ * DECIDE THE ANCHOR.
+ *
+ * @param job the reader's answer about this job: every suite step it declares, and the index the
+ * placement used before any leg was consulted.
+ * @param leg the leg abloh pinned, or null when the job is one build. A non-matrix job still goes
+ * through here, and still gets an answer: a `matrix.<x>` reference reads as null there, which is
+ * what GitHub answers too.
+ */
+declare function setupStepAnchor(job: {
+    readonly testSteps: readonly CiJobTestStep[];
+    readonly lastTestStepIndex: number | null;
+}, leg: MatrixLeg | null | undefined): SetupStepAnchor;
+
+/**
+ * Refuse the run when ANY entry in the measured range touches a gitlink — added, removed, bumped,
+ * or type-changed (old OR new mode 160000). `--raw` carries the modes the unified parser never
+ * sees; no pathspec, so the check covers every run arm (root, --subdir, auto, multi) identically.
+ */
+declare function assertNoGitlinkChanges(repoDir: string, base: string, head: string, uncommitted: boolean): void;
+interface SubmoduleRoot {
+    /** Repo-relative gitlink path. */
+    path: string;
+    /** The exact commit the superproject's index binds for this path. */
+    gitlink: string;
+    /** False = admitted-as-absent: the caller never materialized it (empty dir, byte-faithful). */
+    materialized: boolean;
+}
+/**
+ * Admit every tracked gitlink or refuse with a named rule. The doctrine mirrors tracked
+ * symlinks: a gitlink binds only a COMMIT SHA into HEAD, not the bytes at that SHA — so a
+ * materialized submodule is admitted exactly when its interior provably sits AT that commit,
+ * completely clean (including gitignored content: unbound bytes are not evidence), with no
+ * nested gitlinks and no interior symlink escaping the submodule. Every probe interrogates the
+ * SUBMODULE's own repository — never the superproject, whose view is blinded by the
+ * author-writable `.gitmodules ignore` setting (measured), and whose answers a mis-anchored
+ * `git -C` silently substitutes when the path is not a repository (also measured).
+ */
+declare function admitSubmodules(repoDir: string): SubmoduleRoot[];
+/**
+ * Materialize an admitted submodule into the worktree FROM THE OBJECT STORE at exactly the
+ * gitlink SHA — never from the caller's working files. Content-addressed extraction makes
+ * time-of-check/time-of-use divergence impossible: whatever happens in the caller's checkout
+ * after admission, the worktree receives the bytes the superproject's commit binds, or the
+ * extraction fails. The result carries no `.git`; no git command ever runs inside it. All
+ * access to the submodule's gitdir is read-only (read-tree writes only the scratch index).
+ */
+declare function materializeSubmodule(sourceRepoDir: string, worktreeDir: string, root: SubmoduleRoot, scratchDir: string): void;
+
+type AutoTargetSelection = {
+    state: "selected";
+    subdir: string;
+    changedFiles: number;
+    runner: string;
+} | {
+    /** Multi-target: measurable packages (runners may DIFFER — mixed-runner runs measure). */
+    state: "multi";
+    targets: string[];
+    /** Per-package runner for every entry in `targets`. */
+    runners: Map<string, string>;
+    /** Environmental-failure packages, disclosed as rows and driving cannot-attest by name. */
+    unmeasurable: Array<{
+        directory: string;
+    } & PackageExclusion>;
+    changedFiles: number;
+} | {
+    state: "skipped";
+    reason: string;
+};
+/**
+ * WHAT AN ENUMERATION COULD NOT SEE (junction audit WALK-12, 2026-08-28).
+ *
+ * Every failure in this walk collapsed into an empty list: a directory this process may not read, a
+ * malformed `pnpm-workspace.yaml`, a glob shape the pattern parser has no rule for, a tree deeper
+ * than the depth bound, a workspace wider than the enumeration cap. "This repository declares no
+ * workspace packages" and "this walk could not finish" then read identically - and the first is
+ * what every caller acted on, so a permissions problem on one directory presented as a repository
+ * with nothing in it.
+ *
+ * Structured, because these reach a customer through several different surfaces and each writes its
+ * own sentence.
+ */
+interface WorkspaceEnumeration {
+    /** the package directories this walk did find, sorted */
+    packages: string[];
+    /**
+     * Why the walk is not a complete answer, one entry per cause. Empty on the ordinary repository,
+     * which is every repository whose tree this process can read.
+     */
+    refusals: string[];
+}
+/**
+ * Workspace package dirs read from the WORKING TREE — for `abloh prepare`, which runs as a
+ * trusted setup step on the caller's own checkout (there is no PR boundary to defend, and the
+ * installed dependency tree it must stage from only exists on disk). Measurement-time selection
+ * uses {@link selectAutoTarget}, which reads the merge-base tree instead.
+ */
+declare function enumerateWorkspacePackagesOnDisk(repoDir: string): string[];
+/**
+ * The same enumeration, WITH WHAT IT COULD NOT SEE (junction audit WALK-12, 2026-08-28).
+ *
+ * Every caller that has somewhere to put a sentence should use this one; `enumerateWorkspacePackages
+ * OnDisk` above stays for the callers that genuinely only want the list, and is the same walk.
+ */
+declare function enumerateWorkspacePackages(repoDir: string, ctx?: RepoAccess): WorkspaceEnumeration;
+declare function selectAutoTarget(input: {
+    repoDir: string;
+    base: string;
+    head: string;
+    uncommitted: boolean;
+    /** Opt-in to the homogeneous multi-target arm; without it spanning diffs refuse as before. */
+    allowMulti?: boolean;
+}): AutoTargetSelection;
+
+/**
+ * The exact yarn version this directory commits for itself, or null when it commits none.
+ *
+ * `directory` is the one that owns the `yarn.lock` - the same directory `detectPackageManagerContext`
+ * selected - so the release, the rc file and the lockfile are all read as one repository's answer.
+ */
+declare function committedYarnVersion(directory: string, lockfileName: string, ctx?: RepoAccess): string | null;
+
+export { ANSWERABLE_SETUP_KEYS, ANSWERED_EVIDENCE, type AggregatorInvocation, type AggregatorTool, type AttestationJob, type AutoTargetSelection, type BrowserLane, type BrowserLaneEvidence, type BrowserLaneKind, CI_RECIPE_REFUSALS, type CiBorrowJob, type CiBrowserLane, type CiEnvironmentValue, type CiInstallStep, type CiJobStep, type CiJobTestStep, type CiManagerVersion, type CiNodeVersion, type CiRecipe, type CiRequiredVariable, type CiService, type CiSetupCommand, type CiSystemPackage, type CiTestCommand, type CiUnreadableJobCall, type CiUnsupportedService, type ConfigInput, type ConfigSystemPackage, type CoverageChildSuite, DENO_CONFIG_FILES, DENO_LOCKFILE, type DeclaredBinding, type DeclaredCommandContext, type DenoProject, type DraftService, ENVIRONMENT_BLOCK_HEADER, InitRefusal, type LockfileChoice, type ManifestClassification, type NodeChoice, type NodeDeclaration, type NodeDeclarationProblem, type NodeDeclarationRejection, type NodeEnvironment, type NodeRelease, type NodeRequirement, type NodeSpecReading, type NxProject, type NxTestTarget, type PackageManager, type PackageManagerContext, type PackageManagerResolution, type PlanDeclaration, type PolicyDeclaration, RUSH_CONFIG_DIRECTORY, RUSH_CONFIG_FILE, RUSH_INSTALL_COMMAND, RUSH_INSTALL_SCRIPT, RUSH_LOCKFILE_NAME, RUSH_REPO_STATE_NAME, RUSH_SUBSPACE_DIRECTORY, RUSH_TEST_SCRIPTS, type ReadTextAt, type RebuildDraftValue, type RepoAccess, type ResolveMeasurementPlanInput, type Runner, type RuntimeNeed, type RushProject, type RushTestTarget, SETUP_QUESTION_DESCRIPTORS, STEP_WHAT, type SetupAnswerChannel, type SetupAnswerShape, type SetupDraftValues, type SetupFailFastDecision, type SetupJobDecision, type SetupJobQuestion, type SetupMatrixLeg, type SetupPin, type SetupPublishPlacement, type SetupQuestionDescriptor, type SetupStepAnchor, type SetupStepPlacement, type SetupStepPrecondition, type SubmoduleRoot, type TargetDetection, TargetDetectionError, TargetNotFoundError, type TargetNotFoundReason, type TargetResolution, type TargetResolutionInput, type WorkflowEnvironmentEntry, type WorkflowEnvironmentLevel, type WorkflowEnvironmentScope, type WorkflowExpressionFacts, type WorkflowExpressionReading, type WorkspaceEnumeration, type WorkspaceRootSuite, __testing, accessExists, accessKind, accessManifest, accessSubdirectories, accessText, admitSubmodules, aggregatorInvocation, aggregatorTaskPhrase, aliasHopFamily, answeredTargetDirectory, applyAnswersToContract, applyDeclaredRunner, argvInvokesNodeTest, assertNoGitlinkChanges, bindDeclaredCommand, bindPreparedTestCommand, chooseNodeVersion, ciInstallSteps, ciInstallersFor, ciManagerVersions, ciRefusalIsActionable, classicPerTestRefusal, classicPerTestRunner, classifyNxTestTarget, classifyPackageDirectory, classifyPackageManifest, classifyRushTestScript, classifyWithAliasHop, commentLines, committedYarnVersion, contractDescriptors, decideSetupJob, declarableSetupJobs, declaredCommandContext, declaredRunner, declaredRunnerInvocation, declaredSetupJob, declaredSetupPin, denoLockfilePath, denoTestInvocation, deriveCiRecipe, detectJasmineSuite, detectPackageManager, detectPackageManagerContext, detectTarget, detectVitestDir, diskRepoAccess, diskRepoReader, doorSetupJobs, emptyCiRecipe, engineRunner, enumerateNxProjects, enumerateRushProjects, enumerateWorkspacePackages, enumerateWorkspacePackagesOnDisk, initFailureClassOf, initRefusal, initStepRole, invokesNodeTest, isBrowserInstallCommand, isInstallStep, jasmineSuiteFromScript, layerEnvironment, materializeSubmodule, nodeDeclarationProblemReason, nodeSpecVersions, placeSetupStep, policyDeclaration, preRunnerStageCommands, readAnswerValue, readBrowserLane, readDenoProject, readNodeSpec, readWorkflowExpressions, referencesExpression, referencesSecret, refusalRemedyOf, renderConfig, renderEnvironmentBlock, renderWorkflow, repoPath, resolveMeasurementPlan, resolveSetupPin, resolveTarget, resolveTargetDetection, rootAggregatorTasks, runnerInvocation, runnerStageCommand, runnerSuiteInvocations, rushIdentityFiles, rushLockfiles, rushNodeVersionRange, sameJobReference, scriptRunsDenoTest, selectAutoTarget, setupAnswerProblem, setupJobCandidates, setupJobReference, setupScriptSteps, setupStepAnchor, setupStepOrigin, splitAnswerList, suiteStages, systemPackagesStep, testCommandReceipt, testStepLabel, testableWorkspacePackages, unreadableConditionLine, vitestDirIn, withoutPackageRunnerPrefix, workDirPrefix };