@abloh/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2772 @@
+/**
+ * THE single source of truth for per-runner capability facts.
+ *
+ * Seven sites used to re-enumerate these facts independently (engine layer0Capable, cli
+ * engineRunner, corpus DRIVABLE, the api draft provider matrix, the action handoff normalizers,
+ * the conformance fixture roster) and each stale copy surfaced as a run-time failure during
+ * capability work. Consumers must either import these views or — where they cannot import
+ * TypeScript (the composite-action .mjs / workflow-template jq) — be pinned to this table by a
+ * text-sync test. Never re-type a capability list by hand.
+ *
+ * Changing a row here is a CAPABILITY decision, not bookkeeping: Layer 0 admission additionally
+ * requires the Tier B conformance fixture demanded by scripts/diffCoverageAxis-conformance.mts, and the
+ * bun row is deliberately disabled (measured false covered line; see engine coverage.ts).
+ */
+type RunnerEcosystem = "js" | "python";
+type MutationMode = "stryker-plugin" | "whole-suite-command" | "cosmic-ray";
+type RawCoverageFormatName = "istanbul-coverage-final-v1" | "lcov-v1" | "coverage-py-json-v1";
+interface RunnerCapability {
+    readonly runner: string;
+    readonly ecosystem: RunnerEcosystem;
+    /** Provider names admissible for this runner inside a signed artifact (historical included). */
+    readonly layer0Providers: readonly string[];
+    /** May abloh PRODUCE new Layer 0 evidence with this runner today. */
+    readonly layer0Enabled: boolean;
+    readonly mutation: MutationMode;
+    /** Can the engine drive one test at a time (ProofRunner surface). */
+    readonly perTestDrivable: boolean;
+}
+/** Raw evidence sidecar format each provider writes; consumers derive format checks from this. */
+declare const PROVIDER_RAW_FORMAT: Readonly<Record<string, RawCoverageFormatName>>;
+declare const RUNNER_CAPABILITIES: readonly RunnerCapability[];
+declare function capability(runner: string): RunnerCapability;
+declare function knownRunner(runner: string): boolean;
+declare function jsRunners(): string[];
+declare function layer0EnabledRunners(ecosystem?: RunnerEcosystem): string[];
+declare function strykerPluginRunners(): string[];
+declare function recognizedProvidersFor(runner: string): ReadonlySet<string>;
+/**
+ * Closed vocabulary of `results.target` keys in the SIGNED artifact (attest-results/v2).
+ *
+ * Lockstep gates: packages/core/src/schema.ts (the type) and apps/action/prepare-upload.mjs (the
+ * structural allowlist) must carry exactly these keys — a key present in one and not the other
+ * silently forks the uploaded evidence from the digest that binds the raw artifact. Pinned by the
+ * target-disclosure sync test.
+ *
+ * The CONTROL-PLANE handoff target is a narrower FROZEN shape (see HANDOFF_TARGET_KEYS): the
+ * reusable-workflow template's jq produces it and apps/api/src/ci-handoff.ts exactKeys-rejects
+ * anything else. Widening the handoff is a versioned API change, never a side effect of adding
+ * artifact disclosure.
+ */
+declare const TARGET_ARTIFACT_KEYS: readonly ["repo", "baseSha", "sha", "runner", "directory", "targetSelection"];
+/** Frozen control-plane handoff target keys — widening requires a versioned API change. */
+declare const HANDOFF_TARGET_KEYS: readonly ["baseSha", "sha", "runner"];
+/**
+ * The exact top-level evidence keys a hosted-handoff body carries, per handoff SHAPE version.
+ * The server selects the required shape from the AUTHENTICATED reusable-workflow SHA (each
+ * workflow release pins one CLI build, so SHA ⟹ producer ⟹ shape). Every copy of a shape —
+ * server exactKeys, the workflow jq projection, the in-runner validator — is sync-test-pinned
+ * to THIS list so a partial widening cannot ship green and 400 in production.
+ */
+declare const HANDOFF_EVIDENCE_KEYS_V1: readonly ["schema", "engine", "target", "scope", "diffCoverage", "rawCoverageDigest", "rawCoverageFormat", "mutationExecution", "mutationScope", "tier", "mutantsPlanned", "mutantsRun", "counts", "scores", "floor", "gate", "baseline", "findingCount", "findings", "policy", "rationalesDigest", "rawReportDigest", "skipBaseline"];
+/**
+ * The widened WS3 shape: + evidenceProfile (the worst-of compat signal — previously unreachable
+ * on any CI path), + packages (per-package evidence rows), + mutantRoster (bounded per-mutant
+ * (file,status) — the server-side basis for per-package mutation verification). A workflow
+ * release that emits this shape maps its SHA to V2 in ci-handoff's code-resident table IN THE
+ * SAME COMMIT; the server deploys before the workflow publishes.
+ */
+declare const HANDOFF_EVIDENCE_KEYS_V2: readonly ["schema", "engine", "target", "scope", "diffCoverage", "rawCoverageDigest", "rawCoverageFormat", "mutationExecution", "mutationScope", "tier", "mutantsPlanned", "mutantsRun", "counts", "scores", "floor", "gate", "baseline", "findingCount", "findings", "policy", "rationalesDigest", "rawReportDigest", "skipBaseline", "evidenceProfile", "packages", "mutantRoster", "patchRevert"];
+/** How the measured directory was chosen; always recorded so a verifier reads a stated value. */
+declare const TARGET_SELECTION_KINDS: readonly ["declared-policy", "declared-cli", "auto-diff", "auto-diff-multi", "repository-root"];
+type TargetSelectionKind = (typeof TARGET_SELECTION_KINDS)[number];
+
+/**
+ * Normalized result contract `attest-results/v2` (build plan §4.2.1).
+ *
+ * Two-layer rule: raw engine reports (Stryker's mutation-testing report-schema) are
+ * preserved verbatim as evidence; THIS schema is what every downstream consumer reads.
+ * `engine-stryker` maps raw → this; future engines implement the same mapping. We never
+ * extend or mutate someone else's schema.
+ */
+
+declare const MUTANT_STATUSES: readonly ["killed", "timeout", "survived", "no-coverage", "runtime-error", "build-error", "skipped-by-cap"];
+type MutantStatus = (typeof MUTANT_STATUSES)[number];
+type Counts = Record<MutantStatus, number>;
+declare function emptyCounts(): Counts;
+interface NormalizedMutant {
+    /**
+     * `<file>:<line>:<col>:<mutator>`, plus a `#N` suffix when several mutants share that prefix.
+     *
+     * UNIQUE WITHIN A RUN, and nothing more. `#N` is an ordinal over the mutants the engine reported,
+     * so which physical mutation owns a given ordinal depends on the report — and on which siblings
+     * were sampled into this run at all. Never key anything durable on it, and never compare ids
+     * between two runs: use `mutantIdentity()` below, which is derived from what was actually mutated.
+     */
+    id: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    mutator: string;
+    replacement: string | null;
+    status: MutantStatus;
+    /** raw engine test ids that killed it (killed/timeout only) — Stryker emits opaque ids like "1" */
+    killedBy: string[];
+    /**
+     * `killedBy` ids resolved to human test names via the engine report's test dictionary
+     * (Stryker `testFiles[*].tests[]`), used for the §4.9.3 flaky-quarantine comparison — the
+     * flaky set is keyed by test NAME, not by raw id. Optional: present only when the engine
+     * carried a resolvable dictionary; absent/short (fewer names than `killedBy`) means the
+     * attribution could not be fully resolved, and the quarantine downgrade must NO-OP that
+     * mutant rather than compare on a broken mapping.
+     */
+    killedByNames?: string[];
+    /** number of tests covering the location */
+    coveredBy: number;
+    /**
+     * Which producer pass emitted this mutant. Absent ⇒ treated as `"stryker"` (a classic built-in
+     * operator). `"realistic"` = an LLM-shaped mutant materialized through a Stryker carrier;
+     * `"error-path"` = a forced changed-handler mutant. Presentational + composition metadata only.
+     */
+    origin?: "stryker" | "realistic" | "deterministic" | "error-path";
+    /**
+     * Engine-pass identity — namespaces raw test/mutant ids so classic and carrier passes cannot
+     * collide when their reports are ingested into one array. Absent on single-pass historical runs.
+     */
+    passId?: string;
+    /** exact 1-based columns of the mutated span (multipass remapping/proof needs sub-line precision) */
+    startColumn?: number;
+    endColumn?: number;
+    /**
+     * The exact source text this mutant replaced, taken from the engine report's own file source.
+     *
+     * LOCAL ONLY — it is a source slice, so it never egresses (the API's sanitizers reject it). It
+     * exists because reconstructing a mutation span from (line, column) alone is not verifiable: the
+     * engine report's column base cannot be confirmed from the report itself, and an off-by-one would
+     * mutate the wrong bytes with no drift guard able to fire. Carrying the text lets a consumer
+     * LOCATE the span and refuse when it cannot be found unambiguously.
+     */
+    originalText?: string;
+    /** raw engine ids of the covering tests (the un-collapsed form of `coveredBy`); absent ⇒ unknown */
+    coveredByIds?: string[];
+    /** covering tests as canonical `<workdir-relative-file>::<fullName>` identities; absent ⇒ unknown */
+    coveredByTests?: string[];
+    /** killer tests as canonical `<workdir-relative-file>::<fullName>` identities (killed/timeout only) */
+    killedByTests?: string[];
+}
+/**
+ * WHAT was mutated, as a string — the identity that survives between runs, unlike `id`.
+ *
+ * THE INCIDENT. A mutant's `id` ends in a `#N` ordinal assigned in engine-report order, so the same
+ * physical mutation is `…:EqualityOperator` in one run and `…:EqualityOperator#2` in the next. The
+ * triage verdict cache keyed on that id, so one mutation occupied several cache slots, each answered
+ * by its own model call — and a run read whichever slot matched the ordinal it drew that time.
+ * Measured on one commit, twice, with zero live calls on either side:
+ *
+ *     nonEmpty.length < columns.length  →  nonEmpty.length <= columns.length
+ *       run A: likely-equivalent          run B: real-gap
+ *
+ * A `likely-equivalent` verdict DROPS the survivor from the reported gaps, so identical code reported
+ * a different number of gaps, and a real gap was dismissed on an answer computed for a different
+ * mutation on the same line. Both runs looked clean and fully cached.
+ *
+ * WHY THESE FIELDS. The span END is load-bearing, not padding: two `ConditionalExpression` mutants
+ * can share file, line, start column AND replacement (both `"true"`) and differ only in how much of
+ * the expression they replaced — `a > 0` versus `a > 0 && b < c`. Without `endColumn`/`originalText`
+ * those two collapse to one identity, which is the same class of bug pointing the other way.
+ *
+ * `originalText`, `startColumn` and `endColumn` are optional (absent on @abloh/engine-python and on
+ * historical artifacts). Absent fields render empty rather than being skipped, so a run that has them
+ * can never collide with one that does not, and an engine without them degrades to exactly the
+ * discrimination it has today.
+ *
+ * ONE definition, exported, because three separate caches need it. Each deriving its own tuple is how
+ * they drifted apart in the first place.
+ */
+declare function mutantIdentity(m: NormalizedMutant): string;
+/** One source file's changed-line ranges, valid at the evidence SHA. */
+interface FileScope {
+    file: string;
+    /** inclusive [start, end] line ranges */
+    ranges: Array<[number, number]>;
+    lines: number;
+}
+interface EvidenceFloor {
+    minMutantsExecuted: boolean;
+    maxErrorRate: boolean;
+    minSamplingFraction: boolean;
+    passed: boolean;
+}
+type DiffCoverageLineState = 
+/** at least one starting statement counter on the line is positive */
+"covered"
+/** the line has counters, all zero */
+ | "uncovered"
+/** the reported file has no counter for this changed line — counts as zero-touch */
+ | "not-instrumented"
+/**
+ * The line cannot execute at all: blank, comment-only, or nothing but closing punctuation.
+ *
+ * Disclosed rather than dropped. Every changed line must appear exactly once — that invariant is
+ * what stops a producer quietly omitting the lines it would rather not answer for — so a
+ * non-executable line is STATED and then left out of the denominator, instead of vanishing.
+ */
+ | "not-executable";
+interface DiffCoverageLine {
+    file: string;
+    line: number;
+    state: DiffCoverageLineState;
+}
+interface DiffCoverageCounts {
+    /** changed source lines that CAN execute — the Layer-0 denominator */
+    changed: number;
+    covered: number;
+    uncovered: number;
+    notInstrumented: number;
+    /** changed lines excluded as non-executable (comment/blank/brace); never part of `changed` */
+    notExecutable?: number;
+}
+/** Which runner + coverage provider produced the report. */
+interface CoverageProvider {
+    /** the identified test runner, e.g. "jest" | "vitest" | "mocha" | "node-test" | "bun" | "pytest".
+     *  The authoritative capability set is `layer0Capable` in the engine — never re-enumerate it in a
+     *  consumer, because a copied list goes stale silently as providers are added. */
+    runner: string;
+    /** coverage provider, e.g. "v8" | "babel" */
+    provider: string;
+    /** installed runner version, null when it could not be resolved */
+    runnerVersion: string | null;
+    /** installed coverage-provider version, distinct from the test runner version */
+    providerVersion?: string | null;
+}
+/** Closed identifier for the verbatim Layer-0 sidecar bytes bound by rawCoverageDigest. */
+type RawCoverageFormat = "istanbul-coverage-final-v1" | "lcov-v1" | "coverage-py-json-v1";
+/** Why Layer 0 did not produce a measured pass/fail. */
+type DiffCoverageNotApplicableReason = 
+/** the identified runner has no Layer 0 coverage provider (`layer0Capable` is the source of
+ *  truth; do not restate the supported set here — it drifts as providers are added) */
+"unsupported-runner"
+/** the diff scope is empty — no changed source lines to evaluate */
+ | "empty-scope"
+/** changed source files exist, but every scoped line is non-executable */
+ | "no-executable-lines"
+/**
+ * The change only REMOVED source lines. There is no new-side line to measure and none is
+ * invented, but this is emphatically not `empty-scope`: code behaviour changed. Reported
+ * distinctly so a deletion-only commit can never be read as "nothing changed".
+ */
+ | "deletion-only";
+type DiffCoverageNotRunReason = "baseline-abort" | "pre-mutation-deadline";
+/**
+ * Layer-0 result, discriminated on `state`:
+ *  - `completed`: a measured result — every changed line classified covered/uncovered/not-instrumented.
+ *  - `cannot-attest`: coverage could not be trusted (missing/malformed report, requested file absent).
+ *  - `not-applicable`: no measurement was appropriate (runner without a coverage provider, empty
+ *    scope, or a scope whose every changed line is non-executable — the last carries a provider,
+ *    counts and lines, so it is a MEASURED zero-denominator result, not an absence of measurement).
+ *  - `not-run`: the run aborted before Layer 0 (red/strict-flaky baseline).
+ */
+type DiffCoverageResult = {
+    state: "completed";
+    provider: CoverageProvider;
+    counts: DiffCoverageCounts;
+    /** one entry per changed line, canonical (file, then line) order */
+    lines: DiffCoverageLine[];
+    /**
+     * ADVISORY structural evidence over the changed scope. NEVER gating: not in the Layer-0 gate,
+     * not in the score, not in the evidence floor. Layer 0's claim is "a test executed this line";
+     * "this changed function was never invoked" is a strictly stronger statement, and the evidence
+     * for it is only as good as the provider's fn/branch tables.
+     *
+     * `null` — NOT `{total: 0, invoked: 0}` — when the provider carried no such tables (lcov,
+     * coverage.py). A zero here would assert "no changed functions", which is a measurement, and
+     * nothing was measured. Same absent-vs-zero rule as `filesUnmeasured` below.
+     *
+     * Absent (undefined) on artifacts written before this field existed.
+     */
+    changedFunctions?: {
+        total: number;
+        invoked: number;
+    } | null;
+    /** Branch ARMS in the changed scope, keyed by each arm's own start line. Advisory; see above. */
+    changedBranches?: {
+        total: number;
+        taken: number;
+    } | null;
+    /**
+     * How many acquisition executions produced this result. 1 for the normal path. 2 means the
+     * first coverage run exited nonzero and was DISCARDED UNREAD; every signed field derives
+     * exclusively from the green retry, and `wallMs` spans both attempts. An UNDISCLOSED retry
+     * is itself a process false-claim — this field is what makes retry-once honest.
+     * Absent (undefined) on artifacts written before retries existed.
+     */
+    acquisitionAttempts?: number;
+    wallMs: number;
+} | {
+    state: "cannot-attest";
+    reason: string;
+    provider: CoverageProvider | null;
+    /** See the completed variant — 2 means the retry ALSO failed; wallMs spans both attempts. */
+    acquisitionAttempts?: number;
+    wallMs: number;
+} | {
+    state: "not-applicable";
+    reason: "no-executable-lines";
+    /** Provider evidence and the complete line mapping remain available even with a zero denominator. */
+    provider: CoverageProvider;
+    counts: DiffCoverageCounts;
+    lines: DiffCoverageLine[];
+    /** See the completed variant. */
+    acquisitionAttempts?: number;
+    wallMs: number;
+} | {
+    state: "not-applicable";
+    reason: Exclude<DiffCoverageNotApplicableReason, "no-executable-lines">;
+} | {
+    state: "not-run";
+    reason: DiffCoverageNotRunReason;
+};
+/** Why Layer 1 (mutation) was skipped after Layer 0. */
+type MutationSkipReason = 
+/** policy `shortCircuit:true` and Layer 0 failed */
+"layer-0-failed"
+/** Layer 0 failed and no changed line is covered, so there is nothing worth mutating */
+ | "no-covered-changed-lines"
+/** coverage could not be acquired and policy `shortCircuit:true` */
+ | "layer-0-unavailable";
+type MutationNotRunReason = "empty-scope" | "baseline-abort" | "pre-mutation-deadline" | "no-runner"
+/** the mutation engine failed to execute; Layer 0 evidence stands, mutation carries none */
+ | "engine-error";
+/**
+ * How the mutation scope was chosen:
+ * - `original` = the full diff scope;
+ * - `covered-only` = the covered-changed-line reconstruction (Layer-0 fail, diagnostic run);
+ * - `covered-plus-error-handlers` = covered changed lines ∪ changed executable handler lines;
+ * - `error-handlers-only` = changed executable handler lines only (Layer-0 short-circuit + forcing).
+ */
+type MutationScopeKind = "original" | "covered-only" | "covered-plus-error-handlers" | "error-handlers-only";
+/**
+ * Engine scope → the three-value vocabulary every GitHub surface renders.
+ *
+ * Three separate copies of this table existed, all keyed on strings that are NOT members of
+ * {@link MutationScopeKind} ("covered-lines", "error-handlers"). Only "original" ever matched, so
+ * every reduced-scope run fell through to "full" and the renderer's "· covered lines only" note
+ * could never appear — a run that mutated only the already-covered subset was presented as having
+ * mutated the whole diff. One exported mapping, keyed on the type, so a new member is a compile
+ * error rather than a silent overstatement.
+ */
+declare const MUTATION_SCOPE_SURFACE: Record<MutationScopeKind, "full" | "covered-only" | "error-handlers-only">;
+/** How Layer 1 executed relative to Layer 0. */
+type MutationExecution = {
+    state: "completed";
+    scope: MutationScopeKind;
+} | {
+    state: "skipped";
+    reason: MutationSkipReason;
+} | {
+    state: "not-run";
+    reason: MutationNotRunReason;
+};
+interface Scores {
+    /** (killed+timeout)/(killed+timeout+survived+no-coverage) */
+    rawScore: number | null;
+    /** raw denominator minus confirmed-equivalent survivors; null in Tier 0 */
+    triagedScore: number | null;
+    denominator: number;
+    errorCount: number;
+    confirmedEquivalent: number;
+    /** false until the human-labeled triage eval gate has passed — triaged numbers are unvalidated until then */
+    triageValidated: boolean;
+}
+/**
+ * The evidence schedule that produced this score. Pull-request and release scores are separate
+ * records at the same target SHA; no field exists for blending them.
+ *
+ * `diff-only` is deliberately explicit. Automatic impact expansion outside the diff is not part
+ * of this version: a release result must not imply that dependency analysis ran when it did not.
+ */
+interface EvidenceProfile {
+    kind: "pull-request" | "release";
+    scope: "diff-only";
+    testExecution: "engine-selected" | "full-suite-per-mutant";
+    staticMutants: "policy-controlled" | "included";
+    operatorSet: "configured";
+    sampling: {
+        mode: "uncapped";
+        stability: "not-applicable";
+    } | {
+        mode: "seeded-capped";
+        stability: "not-checked" | "verified" | "not-run";
+        algorithm: string;
+        seed: string;
+    };
+    /**
+     * "worst-of-packages": the gate is worst(pooled gate, per-package gates) over `packages[]` —
+     * a weak package can no longer hide inside the pooled score. Requires `packages[]`; the
+     * server refuses the literal without it and re-derives every per-package quantity itself.
+     */
+    scoreAggregation: "standalone" | "worst-of-packages";
+}
+/**
+ * Explicit lifecycle state shared by the optional Layer-1 feature blocks.
+ * - `completed`       — the feature ran and produced results;
+ * - `disabled`        — turned off by policy/CLI;
+ * - `disabled-by-tier`— an LLM-backed feature forced off because tier 0 permits no model calls;
+ * - `unavailable`     — prerequisites absent (command runner, missing dictionary, baseline abort…);
+ * - `not-run`         — mutation itself did not run, so there was nothing to analyze.
+ */
+type FeatureState = "completed" | "disabled" | "disabled-by-tier" | "unavailable" | "not-run";
+/** How completely per-test kill attribution could be resolved from the engine report(s). */
+type AttributionQuality = "complete" | "partial";
+type PerTestFindingKind = "asserts-nothing" | "duplicate-effectiveness" | "tautological-assertion";
+/** Structural per-test finding. The test NAME/FILE stay in the local sidecar; only the identity
+ *  DIGEST and counts are structural (Tier-1: names are customer-authored free text). */
+interface PerTestFinding {
+    /** sha256 of the canonical `<workdir-relative-file>::<fullName>` */
+    testIdentityDigest: string;
+    kind: PerTestFindingKind;
+    coveredCount: number;
+    creditedKillCount: number;
+    /** identifies the duplicate group (duplicate-effectiveness only) */
+    duplicateGroupDigest?: string;
+}
+type PerTestBlock = {
+    state: "completed";
+    analyzerVersion: string;
+    attribution: AttributionQuality;
+    findings: PerTestFinding[];
+    /** canonical digest over the sorted structural findings */
+    findingsDigest: string;
+} | {
+    state: Exclude<FeatureState, "completed">;
+    reason?: string;
+};
+type HandlerAntiPatternKind = "empty-catch" | "catch-all-abort" | "todo-in-handler";
+interface HandlerFinding {
+    file: string;
+    startLine: number;
+    endLine: number;
+    kind: HandlerAntiPatternKind;
+}
+type ErrorHandlersBlock = {
+    state: "completed";
+    analyzerVersion: string;
+    quality: "complete" | "partial";
+    changedHandlerCount: number;
+    untestedHandlerMutantCount: number;
+    antiPatterns: HandlerFinding[];
+    /** canonical digest over the source-side handler analysis (bound, not recomputed by the API) */
+    analysisDigest: string;
+} | {
+    state: Exclude<FeatureState, "completed">;
+    reason?: string;
+};
+/** The closed set of realistic-mutant categories the model may propose (shared by the triage
+ *  generator and the engine validator so they cannot drift). */
+declare const REALISTIC_CATEGORIES: readonly ["missing-await", "wrong-variable", "argument-order", "exception-swallow", "off-by-one", "wrong-constant"];
+type RealisticCategory = (typeof REALISTIC_CATEGORIES)[number];
+/** One LLM-proposed realistic mutant, before machine validation. Source-derived — stays local. */
+interface ProposedMutant {
+    /** workdir-relative file (must be in the mutation scope) */
+    file: string;
+    /** 1-based span coordinates of the region to replace */
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+    category: RealisticCategory;
+    /** the mutated text for the span */
+    replacement: string;
+}
+/** Deterministic production candidates beyond Stryker's built-in inventory. */
+type DeterministicMutantsBlock = {
+    state: "completed";
+    operatorVersion: string;
+    inventoryDigest: string;
+    eligible: number;
+    planned: number;
+    run: number;
+    skipped: number;
+    byCategory: Record<string, number>;
+    /** Structural digest of the local carrier evidence entries. */
+    evidenceDigest: string;
+} | {
+    state: Exclude<FeatureState, "completed">;
+    reason?: string;
+};
+type FixProofVerdict = "proven" | "target-proven" | "rejected" | "not-attempted-cap";
+interface FixProofSummary {
+    /** the survivor this candidate targets */
+    mutantId: string;
+    /** sha256 of the generated candidate test body (the body itself stays in the local sidecar) */
+    candidateDigest: string;
+    verdict: FixProofVerdict;
+    /** free string like target.runner — the schema is engine-agnostic; the proof names its driver */
+    runner: string;
+    model: string | null;
+    promptVersion: string;
+    /**
+     * Whole-suite outcome with the candidate present. `green` means the candidate was run against
+     * the ENTIRE suite and broke nothing — which is what makes a proven fix installable rather than
+     * merely mutation-detecting. `regressed` means it passed alone but broke other tests;
+     * `not-checked` means the check was disabled. A `proven` verdict requires `green`.
+     */
+    suite?: "green" | "regressed" | "pending" | "not-checked";
+}
+type FixLoopBlock = {
+    state: "completed";
+    proven: number;
+    /** Targeted differential proof succeeded; whole-suite confirmation is still pending. */
+    targetProven?: number;
+    rejected: number;
+    omitted: number;
+    summaries: FixProofSummary[];
+    /** sha256 of the local attest-fix-proofs.json sidecar */
+    proofsDigest: string;
+} | {
+    state: Exclude<FeatureState, "completed">;
+    reason?: string;
+};
+/**
+ * Classic-mutant budget sampling disclosure (policy `mutation.maxMutantsPerRun`). Present exactly
+ * when a cap was configured; a run without this block executed every eligible mutant. eligible vs
+ * sampled is the honest "how much of the plan ran" reading — mutantsPlanned/mutantsRun continue to
+ * describe the EXECUTED report (the certificate API recomputes those from mutant records and must
+ * keep matching), so a capped run is disclosed here rather than by redefining those counters.
+ */
+interface ClassicSamplingBlock {
+    /** sampling algorithm identifier, e.g. "line-first-rr-v1" */
+    algorithm: string;
+    /** run seed the plan derives from (replayable via --seed) */
+    seed: string;
+    cap: number;
+    /** every mutant the changed ranges allow */
+    eligible: number;
+    /** picked to run (== eligible when the diff fits under the cap) */
+    sampled: number;
+    /** changed lines bearing >=1 eligible mutant */
+    linesEligible: number;
+    /** lines with >=1 sampled mutant — breadth, the metric line-first maximizes */
+    linesProbed: number;
+}
+interface AttestResultsV2 {
+    schema: "attest-results/v2";
+    engine: {
+        name: string;
+        version: string;
+        /**
+         * Whether we patched the engine's vitest runner for stryker-js#6073, and why not when we did not.
+         *
+         * EVIDENCE ABOUT THE VERDICTS, not telemetry. Unpatched, a mutant run that executed zero tests
+         * is recorded by Stryker as SURVIVED — so an unpatched run's survivor count may contain mutants
+         * that never activated, and a reader must be able to tell the two situations apart. Absent when
+         * the runner is not vitest.
+         *
+         * LOCAL field: `FINDING_ALLOWED_FIELDS` and the summary allowlists do not carry it, so it stays
+         * on the customer's disk like `replacement` and the mutant columns.
+         */
+        runnerPatch?: {
+            state: "applied" | "already-applied" | "skipped";
+            reason?: string;
+        };
+        /** Exact digest of the engine-owned Stryker package trees and executable entry points. */
+        toolchainDigest?: string;
+    };
+    target: {
+        repo: string;
+        /** Exact merge-base commit used to derive the changed-line scope. Absent only on historical artifacts. */
+        baseSha?: string;
+        /** Exact measured HEAD commit. Retained as `sha` for control-plane compatibility. */
+        sha: string;
+        runner: string;
+        /**
+         * Repo-relative directory the run measured, null for the repository root. Always emitted by
+         * the current producer (absent only on historical artifacts) so a verifier reads a stated
+         * value, never interprets an absence. Key set is pinned by TARGET_ARTIFACT_KEYS in
+         * capability-registry.ts; the control-plane handoff target stays frozen at
+         * HANDOFF_TARGET_KEYS and never carries these fields.
+         */
+        directory?: string | null;
+        /** How `directory` was chosen. Closed vocabulary TARGET_SELECTION_KINDS. */
+        targetSelection?: TargetSelectionKind;
+    };
+    /** Explicit PR/release schedule; absent only on historical artifacts. */
+    evidenceProfile?: EvidenceProfile;
+    tier: 0 | 1 | 2;
+    scope: FileScope[];
+    /** Layer 0 — diff-coverage gate result. Always populated by the current producer. */
+    diffCoverage: DiffCoverageResult;
+    /** how Layer 1 (mutation) executed relative to Layer 0 */
+    mutationExecution: MutationExecution;
+    /** the scope actually handed to mutation — equals `scope` for a full run, the covered-only
+     *  reconstruction for a reduced run, and `[]` when mutation was skipped or not run. */
+    mutationScope: FileScope[];
+    mutantsPlanned: number;
+    mutantsRun: number;
+    counts: Counts;
+    scores: Scores;
+    /** evidence floor — null when mutation did not complete (skipped / not-run) */
+    floor: EvidenceFloor | null;
+    mutants: NormalizedMutant[];
+    wallMs: number;
+    /**
+     * How long the mutation phase took, on its own.
+     *
+     * `wallMs` above is the whole run and cannot answer "what did mutation cost me" — it also
+     * contains scope detection, the baseline, coverage acquisition, triage and every extension.
+     * Mutation is the phase that dominates a run's bill and the one a repository owner reduces
+     * scope to control, so it is measured separately. Optional: artifacts written before this
+     * existed have none, and the reader shows no duration rather than a zero.
+     */
+    mutationWallMs?: number;
+    /** How long survivor triage took. Null when no classifier ran (tier 0, or nothing survived). */
+    triageWallMs?: number | null;
+    /** Extension 2 — per-test verdicts (advisory) */
+    perTest?: PerTestBlock;
+    /** Extension 5 — changed error-handler analysis + anti-patterns */
+    errorHandlers?: ErrorHandlersBlock;
+    /** Production-candidate deterministic operators; disabled until benchmark-promoted. */
+    deterministicMutants?: DeterministicMutantsBlock;
+    /** Extension 3 — candidate killing-test fix-loop proof summaries */
+    fixLoop?: FixLoopBlock;
+    /** classic-mutant budget sampling disclosure — present iff policy set mutation.maxMutantsPerRun */
+    classicSampling?: ClassicSamplingBlock;
+    /**
+     * Per-package evidence rows for multi-package runs — COUNTS AND STATES ONLY, no line slices.
+     * The server re-derives each row's Layer-0 slice from the global bijection-validated `lines`
+     * by directory prefix, and each row's mutation quantities from `mutantRoster`, then compares
+     * claimed vs derived; a disagreement refuses the upload. Rows are disclosed on abort paths too
+     * (state + reason + reached stage, no counts). Absent (undefined) on single-target artifacts
+     * and on artifacts written before this field existed.
+     */
+    packages?: PackageEvidence[];
+    /**
+     * Bounded per-mutant roster — the server-side basis for per-package mutation verification.
+     * Egressing (file, status) pairs is a DELIBERATE carve-out of the mutants-stay-customer-side
+     * rule (Kenneth, 2026-08-04): without it, per-package killed counts are producer assertions a
+     * forger can shuffle between packages while every total still reconciles. File paths follow
+     * the scope canonicalization rules; entries are capped at MAX_MUTANT_ROSTER with mandatory
+     * truncation disclosure. Present iff `packages[]` is present.
+     */
+    mutantRoster?: MutantRosterEntry[];
+}
+interface MutantRosterEntry {
+    /** Repo-relative path, canonicalized like scope files; prefixed with the package directory. */
+    file: string;
+    /** The pooled counts bucket this mutant landed in — same closed set, drift-proof. */
+    status: MutantStatus;
+}
+/** Hard cap on roster entries; a run planning more discloses truncation, never silently drops. */
+declare const MAX_MUTANT_ROSTER = 20000;
+/** One measured (or honestly-unmeasured) package in a multi-package run. */
+interface PackageEvidence {
+    /** Workspace-relative package directory — normalized, unique, never nested under another row. */
+    directory: string;
+    /** This package's test runner (rows may differ under mixed-runner runs). */
+    runner: string;
+    diffCoverage: {
+        state: "completed" | "cannot-attest" | "not-applicable" | "not-run";
+        reason?: string;
+        /** Present iff state is "completed". */
+        counts?: DiffCoverageCounts;
+        provider?: CoverageProvider;
+        wallMs?: number;
+        acquisitionAttempts?: number;
+    };
+    mutation: {
+        state: "completed" | "cannot-attest" | "not-applicable" | "not-run";
+        reason?: string;
+        mutantsPlanned: number;
+        mutantsRun: number;
+        /** Present iff state is "completed"; derived server-side from `mutantRoster`. */
+        counts?: Counts;
+        /** Survivors confirmed equivalent by validated triage, attributable from findings. */
+        confirmedEquivalent?: number;
+    };
+    /** Per-package baseline identity disclosure (command runners have no per-test identities). */
+    baseline?: {
+        testCount: number;
+        testIdentityCount: number;
+        ambiguousIdentityCount: number;
+    };
+    /** sha256 of this package's environment contract (the contract itself never egresses). */
+    environmentContractDigest?: string;
+    /** Furthest stage this package reached before a run-level abort (abort artifacts only). */
+    reachedStage?: "detected" | "baselined" | "diffCoverageAxis" | "mutation";
+}
+
+/**
+ * One mapping from a layer's state to the execution axis every surface renders.
+ *
+ * There were three copies — `apps/cli/src/report-comment.ts`, `apps/api/src/github-delivery.ts`,
+ * `apps/api/src/v1-live.ts` — and they had already drifted. The Layer-0 mapper failed CLOSED
+ * (an unrecognised state became `unavailable`, so the row read "not measured"); the Layer-1 mapper
+ * failed OPEN (`return "completed"`), so a malformed or truncated artifact rendered
+ *
+ *     | Mutation score (mechanically verified) | — 0 bugs planted, 0 caught, 0 survived |
+ *
+ * which is the fabricated all-clear `buildCheckRunSummary`'s own docstring forbids. Nothing about
+ * that run had been measured; the default arm simply said it had.
+ *
+ * This is the same device, and the same reason, as `MUTATION_SCOPE_SURFACE` in `schema.ts` — whose
+ * comment records that three copies of THAT table existed, keyed on strings that were not members
+ * of the union, so only one key ever matched and every reduced-scope run was presented as a
+ * full-diff run. Keying on the union makes a new state a compile error instead of a silent
+ * overstatement.
+ */
+
+/** how a surface describes whether a layer ran */
+type ExecutionAxis = "completed" | "skipped" | "disabled" | "unavailable" | "not-applicable";
+/**
+ * Exhaustive by construction: adding a member to `DiffCoverageResult["state"]` without deciding
+ * how it renders is a build error, not a silent fall-through.
+ */
+declare const LAYER0_EXECUTION: Record<DiffCoverageResult["state"], ExecutionAxis>;
+declare const LAYER1_EXECUTION: Record<MutationExecution["state"], ExecutionAxis>;
+/** Layer 0. An unrecognised state is "we cannot tell", which is what the row must say. */
+declare function diffCoverageExecution(state: string | undefined | null): ExecutionAxis;
+/**
+ * Layer 1. ABSENT and UNRECOGNISED are different facts and must not share an answer.
+ *
+ * An artifact with no `mutationExecution` at all predates the block, and those runs mutated the
+ * full scope unconditionally — so absence honestly means `completed`. A state we do not recognise
+ * means the artifact is malformed or newer than us, and the only truthful answer is that we cannot
+ * tell. Collapsing the second into the first is what produced the all-clear above.
+ */
+declare function classicMutationExecution(state: string | undefined | null): ExecutionAxis;
+/**
+ * The exhaustiveness guard this repo wrote twice by hand and never shared
+ * (`engine-stryker/src/runner.ts`, where an unhandled runner silently produced a vitest command:
+ * no error, an empty report, and every result reading "test not found").
+ */
+declare function assertNever(value: never, context: string): never;
+
+declare const SOURCE_RE: RegExp;
+/** Python source. Passed via {@link ScopeOptions.sourceRe} rather than widening SOURCE_RE — the
+ *  JS and Python pipelines run separately and must not accidentally scope each other's files. */
+declare const PYTHON_SOURCE_RE: RegExp;
+/**
+ * Python's exclusions, mirroring EXCLUDE_RE's intent under Python's conventions.
+ *
+ * Python names tests `test_*.py` / `*_test.py` and puts them in `tests/`; packaging output lands
+ * in `build/` and `dist/`; virtualenvs (`.venv`, `venv`, `site-packages`) contain other people's
+ * code entirely. `conftest.py` is test infrastructure, and `__init__.py` is usually re-exports —
+ * but it is NOT excluded, because a package can legitimately hold logic there and excluding it
+ * would silently shrink the measured scope.
+ */
+declare const PYTHON_EXCLUDE_RE: RegExp;
+/**
+ * Excludes tests, type decls, config, docs, examples, benchmarks, vendored dot-dirs,
+ * build output. Generic directory names (tests/, scripts/, build/, tools/, …) match at
+ * the PATH START ONLY so nested source dirs like `src/tools/` stay in scope; __tests__,
+ * __mocks__, dot-segments, and test-file basename patterns match anywhere. The vitest
+ * match is config-file-shaped so `packages/vitest/src/*.ts` source stays in scope.
+ */
+declare const EXCLUDE_RE: RegExp;
+
+/**
+ * A `git diff` invocation failed (bad base/head ref, not a git repo, git missing). Distinct
+ * from a genuinely empty diff (which parses to zero scopes) so a failed acquisition can never
+ * masquerade as "no changed source lines" and yield a vacuous cannot-attest at exit 0.
+ */
+declare class DiffScopeError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+interface ScopeResult {
+    scopes: FileScope[];
+    totalLines: number;
+    /** changed files that were filtered out of scope, with the reason — disclosure, not silence */
+    excluded: Array<{
+        file: string;
+        reason: "not-source" | "excluded-pattern";
+    }>;
+    /**
+     * Extension 5 — the unfiltered added-line scope used by structural inspection. For the normal
+     * Layer-0 path this is identical to `scopes`; when a specialist caller explicitly asks to drop
+     * comments, this remains the complete scope. Blank/comment lines are retained here because
+     * omission and handler scanners may need their surrounding structure.
+     */
+    inspectionScopes: FileScope[];
+    /**
+     * Hunks that REMOVED source lines and added none — a pure deletion.
+     *
+     * These produce no entry in `scopes`, and correctly so: there is no new-side line to measure, and
+     * synthesizing one would fabricate coverage for text that no longer exists. But "no new line" is
+     * not "no behavioral change". Without this, a deletion-only commit reached the empty-scope path
+     * and was reported `not-applicable: empty-scope` — indistinguishable from a commit that changed
+     * nothing at all.
+     *
+     * Recorded so the caller can say which one happened, and route the change to patch-revert
+     * mutation (the carrier is the parent commit's version of the hunk) instead of silently
+     * attesting to an absence of work. Empty for every diff that adds at least one line.
+     */
+    deletions: Array<{
+        file: string;
+        oldStart: number;
+        oldLines: number;
+    }>;
+}
+interface ScopeOptions {
+    sourceRe?: RegExp;
+    excludeRe?: RegExp;
+    dropComments?: boolean;
+    /**
+     * Which side of the diff to report ranges for. Defaults to `"new"` — the lines that exist at HEAD,
+     * which is what mutation scoping needs, since you can only mutate code that is there.
+     *
+     * `"old"` reports the lines the diff REMOVED, numbered in the pre-change file. Corpus mining needs
+     * this: to find which commit introduced a bug, you blame the lines the fix deleted or replaced, at
+     * the fix's parent. Those lines do not exist at HEAD, so the new side cannot answer it.
+     *
+     * A fix that only ADDS lines has no old side at all. That is not a parser limitation — it means the
+     * bug was an omission, and there is nothing to blame. Such a file yields no ranges, and the caller
+     * must record it as a drop rather than silently attributing it to whatever sat nearby.
+     */
+    side?: "new" | "old";
+    /**
+     * Scope against the WORKING TREE instead of the head commit (`abloh run --uncommitted`).
+     *
+     * The default `base...head` form compares two COMMITS, but Layer 0 coverage and classic mutation
+     * read the source out of the working tree. When a developer runs the CLI with uncommitted edits
+     * those two disagree: the line numbers come from the committed diff and are applied to files that
+     * have since shifted, so a finding can name a line nobody touched. This option moves the scope
+     * half onto the same code the measurement half already reads.
+     *
+     * MERGE-BASE semantics are preserved (see {@link computeScope}): the merge base of `base` and HEAD
+     * is resolved first and diffed against the tree, which is `A...working-tree`. Plain two-dot
+     * `git diff <base>` would drag every commit landed on the base since divergence back in as
+     * reversed changes, in files the author never touched.
+     */
+    againstWorkingTree?: boolean;
+}
+/** Parse a `git diff -U0` unified diff into per-file changed-line ranges. See {@link ScopeOptions.side}. */
+declare function parseUnifiedDiff(diffText: string, opts?: ScopeOptions): ScopeResult;
+/**
+ * Run `git diff <base>...<head> -U0` in `cwd` and scope it.
+ *
+ * THREE dots, not two, and the difference is the whole meaning of the scope. `A..B` is "everything
+ * that differs between these two commits", which on a branch whose base has moved on includes every
+ * commit landed on the base since — as REVERSED changes, in files the author never touched. `A...B`
+ * is "what this branch introduces since it diverged", i.e. the diff from the merge base, which is
+ * exactly what GitHub shows in a pull request and exactly what its author is answerable for.
+ *
+ * Found on the first live PR: a branch cut from an older commit scoped 8 files and 18 lines instead
+ * of the 2 files and 8 lines it actually changed, and Layer 0 then refused the whole run because
+ * one of those unrelated files (a script no test imports) was absent from the coverage report.
+ *
+ * The two forms are identical whenever the base is an ancestor of the head, which is the common
+ * case, so this only ever changes the answer where the old answer was wrong.
+ */
+declare function computeScope(cwd: string, base: string, head?: string, opts?: ScopeOptions & {
+    pathspec?: string;
+}): Promise<ScopeResult>;
+
+/**
+ * Layer 0 — diff-coverage intersection (build plan Layer 0).
+ *
+ * Pure domain logic: given the authoritative changed-line set (`FileScope[]` from the
+ * diff-scoper) and a normalized per-line coverage map (produced by the engine adapter from
+ * the runner's Istanbul JSON), classify every changed line as covered / uncovered /
+ * not-instrumented. No git, no runner, no I/O — the engine collects coverage; core decides.
+ *
+ * Only aggregate execution is known: "some test executed this line", never which test.
+ */
+
+/**
+ * Normalized coverage: file → (line → hit count), keyed by repo-root-relative POSIX path
+ * matching `FileScope.file`. A line present with 0 is instrumented-but-unexecuted; a line
+ * absent is not-instrumented. A file absent entirely is an acquisition-integrity concern for
+ * the caller (→ cannot-attest via {@link missingScopedFiles}); the classifier below only maps
+ * whatever it is given and treats a missing file's lines as not-instrumented defensively.
+ */
+type NormalizedCoverage = Map<string, Map<number, number>>;
+/**
+ * Scope-of-claim disclosure for every Layer-0 result. Lives here, in the domain that defines the
+ * measurement, and is re-exported to the renderers rather than retyped in each — a sentence about
+ * Layer 0 copied into a renderer is how "v1 collects coverage for Jest/Vitest only" outlived the
+ * surface it described and reached signed certificates.
+ *
+ * What a `covered` line establishes: at least one test executed it during ONE aggregate coverage run
+ * at the measured commit. Three things it does not establish, none of them visible in the number:
+ *
+ *  - WHICH test executed the line — coverage here is aggregate hit counts, with no per-test
+ *    attribution (see this file's header).
+ *  - That the line is reached REPEATABLY. Coverage is collected once, so a flaky test that took a
+ *    different path — an early timeout, a lost race — could leave the same line unexecuted on the
+ *    next run with no code change in between. Fast PR verification runs one untouched-HEAD
+ *    baseline; historical full-suite observations and repeated finding proofs identify instability,
+ *    but neither can turn this one coverage observation into repeatable coverage evidence.
+ *  - That the executing test ASSERTS anything about the line. That is Layer 1's question, and the
+ *    reason Layer 0 is a precondition rather than a score.
+ *
+ * Stating this is the cheap half of the honesty problem. Strengthening the claim would mean repeated
+ * or per-test coverage collection — additional full instrumented suite runs — which is a cost
+ * decision, not a wording one.
+ */
+declare const LAYER0_SCOPE_DISCLOSURE: string;
+/** One instrumented function or branch arm: the line it starts on, and how often it ran. */
+interface StructuralSite {
+    line: number;
+    hits: number;
+}
+interface FileStructural {
+    /** function declarations, keyed by their DECLARATION line */
+    functions: StructuralSite[];
+    /** branch ARMS, keyed by each arm's own start line — never the branch point */
+    branches: StructuralSite[];
+}
+/** file → structural sites. A NULL StructuralCoverage means the provider carried none. */
+type StructuralCoverage = ReadonlyMap<string, FileStructural>;
+/**
+ * Advisory-only structural counts over the CHANGED scope: how many changed functions were invoked,
+ * and how many changed branch arms were taken.
+ *
+ * ADVISORY MEANS ADVISORY. These never enter the Layer-0 gate, the score, or the evidence floor.
+ * Layer 0's claim is "a test executed this line"; a function that was never invoked is a strictly
+ * stronger statement and the evidence for it is only as good as the provider's fn/branch tables.
+ * The change-based-coverage result this is motivated by (changed-branch coverage strongest in 7 of
+ * 12 version pairs) is three Java programs with seeded faults — enough for a benchmark arm, not for
+ * a blocking gate on JavaScript.
+ *
+ * Returns NULL when `structural` is null — the provider reported no such tables. Emitting
+ * `{invoked: 0, total: 0}` there would read as "no changed functions", which is a measurement, and
+ * nothing was measured. Same absent-vs-zero rule the rest of the schema is built on.
+ */
+interface ChangedStructuralCounts {
+    functions: {
+        total: number;
+        invoked: number;
+    };
+    branches: {
+        total: number;
+        taken: number;
+    };
+}
+declare function changedStructuralCoverage(scope: FileScope[], structural: StructuralCoverage | null): ChangedStructuralCounts | null;
+/** Upper bound on the number of changed lines this helper will expand — a guard so the exported
+ *  function itself cannot be driven into an unbounded/never-terminating loop by a huge or
+ *  unsafe-integer range (callers should also validate, but the helper is safe on its own). */
+declare const MAX_EXPANDED_LINES = 1000000;
+/** A separate cap on the input shape prevents a million duplicate/overlapping ranges from
+ * consuming unbounded sort/merge work while expanding to only a handful of unique lines. */
+declare const MAX_SCOPE_RANGES = 100000;
+/** Expand `FileScope[]` ranges into a de-duplicated, canonically ordered (file, line) list. */
+declare function expandScopeLines(scope: FileScope[]): Array<{
+    file: string;
+    line: number;
+}>;
+/** Files present in the changed-line scope but entirely absent from the coverage map. */
+declare function missingScopedFiles(scope: FileScope[], coverage: NormalizedCoverage): string[];
+/**
+ * Classify every changed line against the normalized coverage map. Returns one entry per
+ * unique changed line in canonical (file, then line) order, plus the tallied counts.
+ */
+declare function classifyDiffCoverage(scope: FileScope[], coverage: NormalizedCoverage): {
+    lines: DiffCoverageLine[];
+    counts: DiffCoverageCounts;
+};
+/**
+ * Is this line of source non-executable by construction — a comment, a blank, or pure punctuation?
+ *
+ * Coverage providers do not report such lines, and `classifyDiffCoverage` calls anything it cannot
+ * find `not-instrumented`, which counts as a Layer-0 gap. That is the right fail-closed default
+ * when the cause is unknown, but a comment is not an unknown: it can never execute, and counting it
+ * as untested code makes a diff fail for containing documentation.
+ *
+ * Measured on a real customer diff: 3 of 8 changed lines were flagged untested, and they were two
+ * lines of a JSDoc block and a closing brace. Every diff touches comments and braces, so this was
+ * not an edge case — it was the common one.
+ *
+ * The test is deliberately SYNTACTIC and conservative. `} else {` and `} catch (e) {` carry control
+ * flow and are not matched; only lines that are blank, comment-only, or nothing but closing
+ * punctuation are. Anything ambiguous stays in the denominator, where fail-closed belongs.
+ */
+declare function isNonExecutableLine(text: string, file?: string, line?: number): boolean;
+/**
+ * Re-state changed lines that cannot execute as `not-executable`, returning the full list and how
+ * many were marked. Nothing is removed: the control plane requires exactly one entry per changed
+ * line, and dropping entries would both break that check and let a producer omit lines silently.
+ * countsFromLines then leaves the marked lines out of the denominator.
+ */
+declare function markNonExecutable(lines: DiffCoverageLine[], sourceOf: (file: string) => string[] | null): {
+    lines: DiffCoverageLine[];
+    marked: number;
+};
+/** Tally a classified line list. `changed` is the total (the Layer-0 denominator). */
+declare function countsFromLines(lines: DiffCoverageLine[]): DiffCoverageCounts;
+/** Changed lines with no covering test (uncovered + not-instrumented) — the Layer-0 gap. */
+declare function uncoveredCount(counts: DiffCoverageCounts): number;
+/**
+ * Reconstruct the covered changed lines into merged `FileScope[]` ranges — the reduced scope
+ * for a diagnostic Layer-1 run after a Layer-0 failure (mutate only what a test at least runs).
+ */
+declare function coveredLinesToScope(lines: DiffCoverageLine[]): FileScope[];
+/**
+ * Validate a claimed classified line list against the authoritative scope (untrusted-input
+ * hardening for the control plane, Codex B-series): exactly one entry per expanded scoped
+ * line, no duplicates, no out-of-scope entries, and counts consistent with the entries.
+ * Throws `Error` on the first violation; returns the recomputed counts on success.
+ */
+declare function validateDiffCoverageLines(scope: FileScope[], lines: DiffCoverageLine[]): DiffCoverageCounts;
+
+/**
+ * Score and gate semantics — versioned, not vibes (build plan §4.3).
+ *
+ * raw   = (killed+timeout) / (killed+timeout+survived+no-coverage)
+ * triaged = (killed+timeout) / (that denominator − confirmed-equivalent)
+ * runtime-error/build-error are excluded from the denominator, reported separately.
+ * no-coverage counts AGAINST the score. `unclear` triage counts as a real gap (caller
+ * passes only confirmed-equivalent into confirmedEquivalent).
+ *
+ * The triaged score is REPORTED always and GATED ON only when `triageValidated` — see
+ * {@link evaluateGate}. Subtracting equivalents can only raise the score, so an unvalidated
+ * classifier deciding the gate would let an unchecked model talk a failing change into passing.
+ */
+
+declare function tallyCounts(mutants: NormalizedMutant[]): Counts;
+declare function denominatorOf(counts: Counts): number;
+declare function errorCountOf(counts: Counts): number;
+interface ScoreInput {
+    counts: Counts;
+    /** confirmed-equivalent survivors (customer-overridable, not just LLM-claimed) */
+    confirmedEquivalent?: number;
+    /** Tier 0 => triaged score absent */
+    tier?: 0 | 1 | 2;
+    /** has the human-labeled triage eval gate passed? stays false until it has */
+    triageValidated?: boolean;
+}
+declare function computeScores({ counts, confirmedEquivalent, tier, triageValidated }: ScoreInput): Scores;
+interface FloorPolicy {
+    minMutantsExecuted: number;
+    maxErrorRate: number;
+    minSamplingFraction: number;
+}
+declare const DEFAULT_FLOOR: FloorPolicy;
+/** Evidence-completeness floor — a gate precondition (§4.3). Breach ⇒ cannot-attest. */
+declare function evaluateFloor(counts: Counts, mutantsPlanned: number, mutantsRun: number, policy?: FloorPolicy): EvidenceFloor;
+type GateStatus = "pass" | "fail" | "cannot-attest";
+interface GateResult {
+    status: GateStatus;
+    score: number | null;
+    threshold: number;
+    reason: string;
+}
+/**
+ * Gate the score of changed code against a policy threshold. Tier 0 gates on raw score.
+ * Advisory mode is the caller's concern (report neutral); this returns the hard verdict.
+ */
+declare function evaluateGate(scores: Scores, floor: EvidenceFloor, opts: {
+    threshold: number;
+    tier?: 0 | 1 | 2;
+}): GateResult;
+/** Fixed Layer-0 threshold — every changed line must be covered. */
+declare const DIFF_COVERAGE_THRESHOLD = 100;
+/**
+ * Layer-0 gate. Returns a verdict only for a measured (`completed`) or `cannot-attest`
+ * result; `not-applicable` / `not-run` have no Layer-0 verdict and return `null` (the
+ * overall gate then follows Layer 1 or the empty-scope path — see {@link combineLayerGates}).
+ */
+declare function evaluateDiffCoverageGate(dc: DiffCoverageResult): GateResult | null;
+type DecisiveLayer = "layer-0" | "layer-1" | "none";
+interface CombinedGate {
+    overall: GateResult;
+    decisiveLayer: DecisiveLayer;
+}
+/**
+ * Combine the Layer-0 and Layer-1 gates into the overall verdict (build plan gate table):
+ *  - Layer-0 measured FAILURE is always the overall failure (decisive Layer 0), even when a
+ *    diagnostic mutation run still executed on the covered lines.
+ *  - Layer-0 acquisition failure (`cannot-attest`) is always overall cannot-attest.
+ *  - Layer-0 pass, or `not-applicable: unsupported-runner` (command runner), delegates to the
+ *    mutation gate exactly as today (decisive Layer 1).
+ *  - `not-applicable: empty-scope` preserves the existing no-scoreable cannot-attest.
+ * Reuses the mutation gate's own reason strings — it never invents a new gate reason.
+ */
+declare function combineLayerGates(diffCoverage: DiffCoverageResult, _diffCoverageGate: GateResult | null, mutationGate: GateResult | null, opts: {
+    threshold: number;
+}): CombinedGate;
+
+/**
+ * Classic-headroom ceiling — the cheapest falsifier in the benchmark, and it costs nothing.
+ *
+ * THE QUESTION. The Layer-1 extension claims an LLM finds test gaps that classic Stryker operators
+ * miss. Before paying a model to try, there is an arithmetic upper bound on how well it could
+ * possibly do: the fraction of known omissions that classic mutation ALREADY catches is the fraction
+ * no model can improve on. What is left is the entire headroom.
+ *
+ *     ceiling = qualified historical omissions classic MISSED / all qualified historical omissions
+ *
+ * If classic already catches nearly everything, the best conceivable model gains almost nothing, and
+ * that is knowable with zero API spend. Run classic mutation on the frozen corpus first, compute
+ * this, and compare it to the minimum useful margin declared in advance. If the ceiling cannot reach
+ * the margin, stop — no model result can rescue it.
+ *
+ * WHY THE BOUND, NOT THE POINT ESTIMATE. With a handful of omissions the point estimate is nearly
+ * meaningless: 3 of 8 is 37.5%, but so is 2 of 8 plus one coin flip. The stop rule therefore uses
+ * the UPPER confidence bound — stop only when even the optimistic end of the interval falls short,
+ * so a small corpus produces "inconclusive" rather than a false stop. A Wilson score interval is
+ * used because the normal approximation is badly wrong at these counts and at rates near 0 or 1,
+ * which is exactly where this measurement lands.
+ *
+ * The consequence is worth stating plainly: a small corpus will usually return `inconclusive`. That
+ * is the honest answer, and it is a finding about the corpus, not a failure of the test.
+ *
+ * ORDER MATTERS. The corpus is frozen before this runs, and classic-detected items are NEVER
+ * replaced after seeing the result. Swapping in fresh items once the ceiling looks bad is choosing
+ * the outcome, which is the whole reason the rule is written down before any data exists.
+ */
+/** One preregistered historical omission, and whether classic mutation caught it. */
+interface QualifiedOmission {
+    /** stable id from the frozen corpus manifest */
+    id: string;
+    /**
+     * Did CLASSIC (non-LLM) mutation detect this omission, under the detection definition in the
+     * plan — in the causal hunk, stable under both suites, and attributable to the removed assertion?
+     */
+    classicDetected: boolean;
+}
+type HeadroomVerdict = "stop" | "proceed" | "inconclusive";
+interface HeadroomResult {
+    /** qualified omissions in the frozen corpus */
+    total: number;
+    /** how many classic mutation MISSED — the only ones a model could ever claim */
+    classicMissed: number;
+    /** the maximum possible realistic-only rate, as a percentage; null when the corpus is empty */
+    ceilingPct: number | null;
+    /** Wilson score interval on that ceiling, as percentages */
+    lowerPct: number | null;
+    upperPct: number | null;
+    /** confidence used for the interval */
+    confidence: number;
+    /** the pre-declared minimum useful margin this was tested against */
+    marginPct: number;
+    verdict: HeadroomVerdict;
+    reason: string;
+}
+/**
+ * Wilson score interval for a binomial proportion. Chosen over the normal approximation because at
+ * these sample sizes, and at rates near 0 or 1, the normal interval can extend below 0 or above 1
+ * and badly understates uncertainty — which would turn "we cannot tell" into a confident stop.
+ */
+declare function wilsonInterval(successes: number, n: number, confidence?: number): {
+    lower: number;
+    upper: number;
+};
+/**
+ * Compute the ceiling and apply the pre-registered futility rule.
+ *
+ * `marginPct` is the minimum useful margin — the smallest realistic-only rate that would justify
+ * shipping the extension. It MUST be declared before any of this data exists; choosing it afterwards
+ * is choosing the answer.
+ */
+declare function classicHeadroom(omissions: readonly QualifiedOmission[], opts: {
+    marginPct: number;
+    confidence?: number;
+}): HeadroomResult;
+/**
+ * The rate that matters, and the rate the ceiling above does NOT bound.
+ *
+ *     conditional rate = omissions the method caught / omissions CLASSIC MISSED
+ *
+ * The unconditional figure (`caught / all omissions`) is the product of two things:
+ *
+ *     P(realistic-only) = P(classic misses) x P(method detects | classic misses)
+ *
+ * Only the SECOND term is a property of the method. The first is a property of the corpus, and this
+ * corpus is deliberately opportunity-enriched — selected to contain async and error-handling code
+ * that mechanical operators cannot reach. Its miss rate is therefore an artifact of selection, not a
+ * fact about real code, and multiplying by it yields a number shaped like product value that is not
+ * measuring the world. So the margin is declared against the CONDITIONAL rate, and the prevalence
+ * needed to turn that into product value must come from a representative sample, never from here.
+ *
+ * The consequence for the ceiling: it can no longer prove futility. A conditional rate can be 100%
+ * however small the headroom is. What headroom governs instead is POWER — with few classic-missed
+ * omissions there are few observations to estimate the conditional rate from, and no margin can be
+ * tested against one observation. {@link conditionalPower} answers that question.
+ */
+interface ConditionalPowerResult {
+    /** the informative N: only omissions classic MISSED can test the conditional rate */
+    informativeN: number;
+    marginPct: number;
+    confidence: number;
+    /** smallest detection count whose lower bound clears the margin; null if even a perfect run fails */
+    detectionsNeeded: number | null;
+    /** the lower bound a PERFECT run would produce — the ceiling on what this corpus can demonstrate */
+    bestPossibleLowerPct: number;
+    verdict: "adequate" | "underpowered";
+    reason: string;
+}
+/**
+ * Can this corpus test the declared margin on the conditional rate at all?
+ *
+ * Two ways it cannot. If even a perfect result's lower bound falls short of the margin, no outcome
+ * can succeed — the bar is unreachable by construction rather than by any failing of a model. And if
+ * ONLY a perfect result clears it, the experiment has no power against any realistic effect: one
+ * miss, from one flaky item, and a genuinely good method reads as a failure. Both are reported as
+ * underpowered, because both mean the answer was decided by the corpus rather than by the method.
+ */
+declare function conditionalPower(informativeN: number, opts: {
+    marginPct: number;
+    confidence?: number;
+}): ConditionalPowerResult;
+
+/**
+ * Historical-pair qualification and the perfect-proposer control — Stage A's remaining model-free
+ * checks. Both must pass before any model is called, and both can invalidate the benchmark outright.
+ *
+ * THE CORPUS. Each item is one real bug from a repository's history. Production source is frozen at
+ * the FIXED version. The STRONG suite includes the regression test that shipped with the fix; the
+ * WEAK suite has only that test's bug-specific assertion removed. The omission is then known from
+ * history rather than from somebody's judgement about what looks "plausibly weak".
+ *
+ * WHY QUALIFICATION IS NEEDED. That story can be false in ways that are invisible unless checked.
+ * The bug may already be covered by a second test, so removing the first creates no omission at all.
+ * The regression test may be flaky. It may fail for an unrelated reason — a timeout, a build error,
+ * a shared fixture it happened to set up. Any of those turns an item into noise that still LOOKS
+ * like a valid measurement, and a benchmark built on it measures nothing.
+ *
+ * So every item is run through a four-cell table with the REAL historical fault:
+ *
+ *                       strong suite      weak suite
+ *     fixed code        pass              pass
+ *     historical fault  FAIL, by the      PASS
+ *                       intended assertion
+ *
+ * Every cell is repeated, and every repeat must agree. The two cells that carry the argument:
+ *   - fault/weak must PASS. If the fault still fails under weak, removing that test did not create
+ *     the claimed omission, and the item proves nothing.
+ *   - fault/strong must fail BY THE INTENDED ASSERTION. A timeout or a build error is not detection;
+ *     it is the harness noticing that something broke, which any mutation would achieve.
+ *
+ * THE PERFECT-PROPOSER CONTROL. Qualification checks the corpus. This checks the INSTRUMENT. Inject
+ * the actual historical fault as though it were a proposed mutant and run it through the complete
+ * measurement pipeline. A perfect proposer — one that emits exactly the real bug — must land in
+ * strong-fail/weak-pass. If it does not, the pipeline cannot detect a known bug it was handed, and
+ * no model result measured through it means anything. That is a failure of the assay, not of a
+ * model, and it is strictly more serious than any individual item being rejected.
+ */
+/** What one suite run reported. `error` is a harness failure, never evidence about tests. */
+type SuiteOutcome = "pass" | "fail" | "error";
+/** Repeated runs of ONE cell. Repetition is what separates a real signal from a flaky test. */
+interface CellObservation {
+    /** one entry per repeat; all must agree or the cell is unstable */
+    outcomes: readonly SuiteOutcome[];
+    /**
+     * For the fault-under-strong cell only: did the suite fail because of the removed regression
+     * assertion, established by that test's canonical identity or by running it alone? A failure from
+     * a timeout, a build error, or an unrelated flaky test is not detection.
+     */
+    failedByIntendedAssertion?: boolean;
+}
+/** Proof that strong and weak differ by exactly one test hunk and nothing else. */
+interface PairIsolation {
+    /** digest of every file EXCEPT the differing test hunk, under strong */
+    strongDigestExcludingHunk: string;
+    /** the same digest under weak — must be identical, or the pair differs by more than one thing */
+    weakDigestExcludingHunk: string;
+    /** how many test hunks differ between the two trees; must be exactly 1 */
+    differingTestHunks: number;
+}
+interface HistoricalPair {
+    /** stable id from the frozen corpus manifest */
+    id: string;
+    isolation: PairIsolation;
+    fixedUnderStrong: CellObservation;
+    fixedUnderWeak: CellObservation;
+    faultUnderStrong: CellObservation;
+    faultUnderWeak: CellObservation;
+}
+type QualificationVerdict = "qualified" | "rejected";
+interface QualificationResult {
+    id: string;
+    verdict: QualificationVerdict;
+    /** every reason it failed — all of them, so one run of the table fixes everything at once */
+    reasons: string[];
+}
+/** The single outcome of a cell, or null when its repeats disagree (i.e. it is flaky). */
+declare function stableOutcome(cell: CellObservation): SuiteOutcome | null;
+/** Minimum repeats before a cell's outcome is treated as established rather than a single sample. */
+declare const MIN_CELL_REPEATS = 3;
+/**
+ * Qualify one historical pair against the four-cell table.
+ *
+ * Rejection is the safe direction and is never fatal to the benchmark — a rejected item is simply
+ * not used. Accepting a bad item IS fatal, because it enters the denominator and every rate computed
+ * from it is wrong, with nothing downstream able to notice.
+ */
+declare function qualifyHistoricalPair(pair: HistoricalPair, opts?: {
+    minRepeats?: number;
+}): QualificationResult;
+/** Where a mutant landed in the 2x2 the benchmark actually scores on. */
+type DetectionCell = "strong-fail-weak-pass" | "strong-fail-weak-fail" | "strong-pass-weak-pass" | "strong-pass-weak-fail";
+interface OracleObservation {
+    /** the pair this oracle mutant was built from */
+    pairId: string;
+    /** where the injected historical fault actually landed, measured through the FULL pipeline */
+    observed: DetectionCell;
+    /** did the pipeline attribute the strong-suite failure to the intended assertion? */
+    attributedToIntendedAssertion: boolean;
+    /** did the mutant survive every structural gate (carrier encoding, validation) and actually run? */
+    reachedExecution: boolean;
+}
+type AssayVerdict = "valid" | "invalid";
+interface AssayResult {
+    verdict: AssayVerdict;
+    checked: number;
+    failures: Array<{
+        pairId: string;
+        reason: string;
+    }>;
+    reason: string;
+}
+/** The only cell a perfect proposer may land in: caught by the strong suite, missed by the weak one. */
+declare const EXPECTED_ORACLE_CELL: DetectionCell;
+/**
+ * Run the perfect-proposer control over every qualified pair.
+ *
+ * A model that emitted exactly the real historical bug is the best any proposer could possibly do.
+ * If the pipeline cannot place THAT in the expected cell, it cannot detect a known bug handed to it
+ * on a plate, and every model number measured through it is meaningless. So this returns a verdict
+ * on the ASSAY: `invalid` means stop and fix the instrument, not "this model did badly".
+ *
+ * There is no tolerance threshold. One perfect mutant failing to reach the expected cell is a defect
+ * in the measurement, and a rate would only invite arguing about how much brokenness is acceptable.
+ */
+declare function evaluateAssay(observations: readonly OracleObservation[]): AssayResult;
+/** Convenience: qualify a whole corpus and report what survived. */
+declare function qualifyCorpus(pairs: readonly HistoricalPair[], opts?: {
+    minRepeats?: number;
+}): {
+    qualified: QualificationResult[];
+    rejected: QualificationResult[];
+};
+
+/**
+ * The frozen experiment manifest, and the gate that stands between it and any model spend.
+ *
+ * WHY THIS IS CODE AND NOT A DOCUMENT. Plan v2 said "no model data before these parameters are
+ * frozen". That is a promise, and a promise is not a preregistration — nothing stops a parameter
+ * being chosen after the first results are in, which is exactly how a null result becomes a positive
+ * one. Every value below is therefore a required field, validated, with the run refusing to start
+ * while any of them is missing or still a placeholder.
+ *
+ * The value this protects is specific. A benchmark's conclusions are only as trustworthy as the
+ * decisions made BEFORE the data existed: the minimum margin that would make the extension worth
+ * shipping, how models are selected, what counts as detection, what happens to failed calls. Each is
+ * a lever that can turn the same measurements into a different answer, and each is invisible in the
+ * final number.
+ *
+ * {@link canStartStageB} is the gate. It refuses while the manifest is unfrozen, while Stage A's
+ * model-free checks have not passed, and while the deterministic baseline has not been run — because
+ * a model result with no baseline cannot distinguish "the LLM is valuable" from "Stryker's operator
+ * set is incomplete and anything would have scored here".
+ */
+
+/** A model entered into the benchmark, named exactly — an alias can resolve to a dated version. */
+interface ManifestModel {
+    /** the identifier sent on the wire, e.g. "gpt-5.6-sol" */
+    id: string;
+    /** transport, so the cost basis of a cell is unambiguous */
+    provider: "hosted" | "anthropic" | "claude-cli";
+    /** effort level where the model exposes one; part of the cell identity, not a footnote */
+    effort?: string;
+}
+interface ExperimentManifest {
+    /** manifest schema version, so a later change to these fields is visible in the artifact */
+    schema: "attest-benchmark-manifest/v1";
+    /** ISO date the manifest was frozen, supplied by the caller — never generated at validation time */
+    frozenAt: string;
+    /** digest over the frozen corpus (repos, SHAs, the strong/weak hunks) */
+    corpusHash: string;
+    /** digest over the analysis code that turns observations into the reported number */
+    analysisCodeHash: string;
+    /** digest over the exact prompt text sent to proposers */
+    promptHash: string;
+    /** every model in the experiment, enumerated */
+    models: ManifestModel[];
+    /** how many independent repository clusters the corpus contains */
+    corpusClusters: number;
+    /** how many held-out clusters are reserved, and frozen before Stage B */
+    heldOutClusters: number;
+    /** independent draws per cell */
+    drawsPerCell: number;
+    /**
+     * The smallest realistic-only rate that would justify shipping the extension. THE most consequential
+     * number here: it decides whether any given result is a success, and choosing it after seeing data
+     * is choosing the answer.
+     */
+    minimumUsefulMarginPct: number;
+    /** confidence level for every interval and every stop rule */
+    confidence: number;
+    /** the fraction of eligible sites a model must return valid output on to clear Stage B */
+    stageBValidOutputFraction: number;
+    /** multiplicity correction across the declared comparison family */
+    multiplicityProcedure: "holm" | "bonferroni" | "none-single-comparison";
+    /** how finalists are picked, stated as a procedure rather than decided later */
+    topSelectionRule: string;
+    /** the blinded-reviewer agreement threshold above which a detection counts as realistic */
+    reviewerRealismThresholdPct: number;
+    /** per-category quotas, so category is not confounded with repository by accident */
+    categoryQuotas: Record<string, number>;
+    /** fixed proposal slots per omission — detection is "any mutant hits", so volume must not buy luck */
+    proposalSlotsPerOmission: number;
+    /**
+     * Order in which items are excluded or replaced when something fails. Declared in advance because
+     * replacing an inconvenient item AFTER seeing its result is the most direct way to fake a finding.
+     */
+    exclusionOrder: string[];
+    /** the exact conditions that stop the programme, in words that can be checked against the code */
+    stopRules: string[];
+}
+interface ManifestValidation {
+    frozen: boolean;
+    problems: string[];
+}
+/**
+ * Validate the manifest. Fails CLOSED: anything missing, blank, or obviously a placeholder makes the
+ * manifest unfrozen, and an unfrozen manifest cannot start a paid stage.
+ */
+declare function validateManifest(m: Partial<ExperimentManifest> | undefined): ManifestValidation;
+interface StageBReadiness {
+    /** the ONLY value that permits spending money */
+    ready: boolean;
+    /** every blocker, so one pass fixes all of them rather than discovering them one at a time */
+    blockers: string[];
+}
+interface StageBInputs {
+    manifest: Partial<ExperimentManifest> | undefined;
+    /** Stage A: the classic-headroom ceiling — informational, and the input to the power check */
+    headroom: HeadroomResult | undefined;
+    /**
+     * Stage A: can the corpus TEST the declared margin on the conditional rate? The ceiling cannot
+     * decide this — a conditional rate can be 100% however small the headroom is. What headroom
+     * governs is how many observations exist to establish that rate from.
+     */
+    power: ConditionalPowerResult | undefined;
+    /** Stage A: the perfect-proposer positive control */
+    assay: AssayResult | undefined;
+    /** Stage A: which historical pairs survived qualification */
+    qualification: {
+        qualified: QualificationResult[];
+        rejected: QualificationResult[];
+    } | undefined;
+    /** has the model-free deterministic baseline been run over the same corpus? */
+    deterministicBaselineRun: boolean;
+}
+/**
+ * Decide whether Stage B may begin. Refuses by default and names every blocker.
+ *
+ * The deterministic-baseline requirement is the one most likely to be argued with, so it is stated
+ * here: without it, a model result cannot distinguish "the LLM adds value" from "Stryker's built-in
+ * operators happen to omit these edits and any tool producing them would have scored the same". That
+ * distinction is the entire thesis, and it costs nothing to settle.
+ */
+declare function canStartStageB(inputs: StageBInputs): StageBReadiness;
+
+/**
+ * Layer 2 scenario-search contracts.
+ *
+ * The engine searches four lanes and records bounded counterexample evidence.
+ */
+declare const SCENARIO_LANES: readonly ["property", "value", "state", "failure"];
+type ScenarioLane = (typeof SCENARIO_LANES)[number];
+declare const SCENARIO_AUTHORITIES: readonly ["machine-sourced", "source-grounded", "corroborated", "code-inferred"];
+type ScenarioAuthority = (typeof SCENARIO_AUTHORITIES)[number];
+declare const SCENARIO_OUTCOMES: readonly ["confirmed-counterexample", "candidate-counterexample", "no-counterexample-found", "scenario-uncovered", "disagreement", "inconclusive", "not-applicable"];
+type ScenarioOutcome = (typeof SCENARIO_OUTCOMES)[number];
+declare const SCENARIO_SEARCH_STATES: readonly ["completed", "partial", "unavailable", "disabled", "disabled-by-tier", "not-run"];
+type ScenarioSearchState = (typeof SCENARIO_SEARCH_STATES)[number];
+declare const SCENARIO_SOURCE_KINDS: readonly ["contract", "schema", "documentation", "ticket", "test", "type", "example", "code", "trace"];
+type ScenarioSourceKind = (typeof SCENARIO_SOURCE_KINDS)[number];
+declare const SCENARIO_SOURCE_INDEPENDENCE: readonly ["independent", "derived-from-target", "unknown"];
+type ScenarioSourceIndependence = (typeof SCENARIO_SOURCE_INDEPENDENCE)[number];
+interface ScenarioSourceRef {
+    kind: ScenarioSourceKind;
+    repositoryPathOrExternalId: string;
+    revisionOrTimestamp: string;
+    startLine?: number;
+    endLine?: number;
+    contentDigest: string;
+    independence: ScenarioSourceIndependence;
+    /** Identifier of the deterministic policy rule that assigned authority. */
+    authorityRule: string;
+}
+interface ScenarioInputDomain {
+    /** Stable family name, such as `integer-range`, `schema-object`, or `operation-sequence`. */
+    kind: string;
+    /** Local source-derived explanation. It never belongs in the normalized artifact. */
+    description: string;
+    sourceRefs: ScenarioSourceRef[];
+}
+interface ScenarioOperationStep {
+    operation: string;
+    arguments: string[];
+    expectedState?: string;
+}
+interface ScenarioExpectedObservation {
+    kind: "equals" | "not-equals" | "throws" | "does-not-throw" | "resolves" | "rejects" | "predicate" | "state";
+    subject: string;
+    expected: string;
+}
+interface ScenarioIntentDraft {
+    schema: "attest-scenario-intent/v1";
+    id: string;
+    lane: ScenarioLane;
+    statement: string;
+    authority: ScenarioAuthority;
+    sourceRefs: ScenarioSourceRef[];
+    targetSymbols: string[];
+    setup: string[];
+    generatedInputs: ScenarioInputDomain[];
+    operations: ScenarioOperationStep[];
+    expectedObservation: ScenarioExpectedObservation;
+    cleanup: string[];
+    forbiddenAssumptions: string[];
+}
+interface ScenarioIntent extends ScenarioIntentDraft {
+    /** sha256 over every semantic field in ScenarioIntentDraft. */
+    intentDigest: string;
+}
+interface ScenarioSummary {
+    /** sha256 identity; source text and test text stay in the local sidecar. */
+    scenarioId: string;
+    lane: ScenarioLane;
+    authority: ScenarioAuthority;
+    outcome: ScenarioOutcome;
+    targetDigest: string;
+    intentDigest: string;
+    sourceSetDigest: string;
+    runs: number;
+    replayed?: number;
+    targetExecuted: boolean;
+    assertionExecuted: boolean;
+    runner: string;
+    model: string | null;
+    intentPromptVersion: string;
+    testPromptVersion: string;
+    toolVersion: string;
+    containerDigest: string;
+}
+interface ScenarioSearchCounts {
+    selectedTargets: number;
+    measuredTargets: number;
+    unmeasuredTargets: number;
+    byOutcome: Record<ScenarioOutcome, number>;
+    byLane: Record<ScenarioLane, number>;
+    byAuthority: Record<ScenarioAuthority, number>;
+}
+interface ScenarioSearchRestrictions {
+    containerRequired: true;
+    network: "none";
+    credentials: "none";
+    productionWrites: "denied";
+}
+interface ScenarioSearchProvenance {
+    engineVersion: string;
+    policyDigest: string;
+    evidencePackDigest: string;
+    proofsDigest: string;
+    containerImageDigest: string;
+    runnerAdapterVersion: string;
+    toolProtocolVersion: string;
+    models: string[];
+    llmCalls: number;
+    cacheHits: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number | null;
+    costUsd: number | null;
+    wallMs: number;
+    restrictions: ScenarioSearchRestrictions;
+}
+type ScenarioSearchMeasuredBlock = ScenarioSearchProvenance & {
+    state: "completed" | "partial";
+    counts: ScenarioSearchCounts;
+    summaries: ScenarioSummary[];
+};
+type ScenarioSearchBlock = ScenarioSearchMeasuredBlock | {
+    state: Exclude<ScenarioSearchState, "completed" | "partial">;
+    reason?: string;
+};
+declare function isScenarioLane(value: unknown): value is ScenarioLane;
+declare function isScenarioAuthority(value: unknown): value is ScenarioAuthority;
+declare function isScenarioOutcome(value: unknown): value is ScenarioOutcome;
+declare function isScenarioSearchState(value: unknown): value is ScenarioSearchState;
+/**
+ * Copy an untrusted summary into the closed normalized shape and validate the evidence claims that
+ * its outcome implies. Extra runtime fields are discarded, so source or test text cannot hitch a
+ * ride through a structurally typed object.
+ */
+declare function sanitizeScenarioSummary(input: ScenarioSummary): ScenarioSummary;
+declare function deriveScenarioSearchCounts(selectedTargets: number, inputSummaries: readonly ScenarioSummary[]): {
+    counts: ScenarioSearchCounts;
+    summaries: ScenarioSummary[];
+};
+interface BuildScenarioSearchBlockInput extends ScenarioSearchProvenance {
+    selectedTargets: number;
+    summaries: readonly ScenarioSummary[];
+}
+/**
+ * Build the only two measured block states. A run is completed exactly when every selected target
+ * has a closed summary; otherwise it is visibly partial.
+ */
+declare function buildScenarioSearchBlock(input: BuildScenarioSearchBlockInput): ScenarioSearchMeasuredBlock;
+
+declare const CI_PROPERTY_AUTHORITIES: readonly ["machine-sourced", "source-grounded"];
+type CiPropertyAuthority = (typeof CI_PROPERTY_AUTHORITIES)[number];
+declare const CI_PROPERTY_OUTCOMES: readonly ["pr-regression", "new-contract-counterexample", "source-grounded-test-gap", "pre-existing-counterexample", "possible-duplicate", "no-counterexample-found", "disagreement", "scenario-uncovered", "inconclusive", "not-applicable"];
+type CiPropertyOutcome = (typeof CI_PROPERTY_OUTCOMES)[number];
+declare const CI_PROPERTY_STATES: readonly ["completed", "partial", "unavailable", "disabled", "disabled-by-tier", "not-run"];
+type CiPropertyState = (typeof CI_PROPERTY_STATES)[number];
+declare const CI_RESIDUAL_STATES: readonly ["covered-existing", "proposed-closed", "open", "inconclusive"];
+type CiResidualState = (typeof CI_RESIDUAL_STATES)[number];
+declare const CI_PROPERTY_CAPS: readonly [1, 2, 4, 8];
+type CiPropertyCandidateCap = (typeof CI_PROPERTY_CAPS)[number];
+interface CiChangedRange {
+    startLine: number;
+    endLine: number;
+}
+interface CiResidualGapEntry {
+    /** Stable digest over the carrier or unsupported-site identity. */
+    gapIdentity: string;
+    kind: "classic" | "deterministic" | "realistic" | "error-path" | "patch-revert" | "unsupported-site";
+    headSha: string;
+    mergeBaseSha: string;
+    targetPath: string;
+    targetSymbol: string;
+    targetDigest: string;
+    sourceDigest: string;
+    changedRange: CiChangedRange;
+    state: CiResidualState;
+    mutantIdentity?: string;
+    patchUnitId?: string;
+    patchDigest?: string;
+    candidateDigest?: string;
+    candidateTestPath?: string;
+    candidateTestName?: string;
+    proofVerdict: "proven" | "rejected" | "not-attempted" | "not-applicable";
+    wholeSuiteVerdict: "green" | "regressed" | "not-checked" | "not-applicable";
+    producerVersion: string;
+}
+interface CiResidualGapLedger {
+    schema: "attest-ci-residual-ledger/v1";
+    headSha: string;
+    mergeBaseSha: string;
+    policyDigest: string;
+    entries: CiResidualGapEntry[];
+    ledgerDigest: string;
+}
+interface CiPropertySummary {
+    findingId: string;
+    outcome: CiPropertyOutcome;
+    authority: CiPropertyAuthority;
+    targetDigest: string;
+    intentDigest: string;
+    behaviourKey: string;
+    sourceSetDigest: string;
+    headReplays: number;
+    comparisonReplays: number;
+    targetExecuted: boolean;
+    assertionExecuted: boolean;
+    candidateDigest: string | null;
+}
+interface CiPropertyCounts {
+    selectedTargets: number;
+    validatedRules: number;
+    executedRules: number;
+    findings: number;
+    duplicatesSuppressed: number;
+    byOutcome: Record<CiPropertyOutcome, number>;
+}
+interface CiPropertyMeasuredBlock {
+    state: "completed" | "partial";
+    mode: "shadow" | "advisory";
+    candidateCap: CiPropertyCandidateCap;
+    counts: CiPropertyCounts;
+    summaries: CiPropertySummary[];
+    ledgerDigest: string;
+    evidencePackDigest: string;
+    proofsDigest: string;
+    containerDigests: string[];
+    models: string[];
+    llmCalls: number;
+    costUsd: number | null;
+    wallMs: number;
+}
+type CiPropertySearchBlock = CiPropertyMeasuredBlock | {
+    state: Exclude<CiPropertyState, "completed" | "partial">;
+    reason?: string;
+};
+declare function ciPropertyLedgerDigest(ledger: Omit<CiResidualGapLedger, "ledgerDigest">): string;
+declare function validateCiResidualGapLedger(input: CiResidualGapLedger): CiResidualGapLedger;
+declare function isCiPropertyCandidateCap(value: unknown): value is CiPropertyCandidateCap;
+declare function sanitizeCiPropertySummary(input: CiPropertySummary): CiPropertySummary;
+interface BuildCiPropertyBlockInput {
+    mode: "shadow" | "advisory";
+    candidateCap: CiPropertyCandidateCap;
+    selectedTargets: number;
+    validatedRules: number;
+    executedRules: number;
+    duplicatesSuppressed: number;
+    summaries: readonly CiPropertySummary[];
+    expectedSummaries: number;
+    ledgerDigest: string;
+    evidencePackDigest: string;
+    proofsDigest: string;
+    containerDigests: readonly string[];
+    models: readonly string[];
+    llmCalls: number;
+    costUsd: number | null;
+    wallMs: number;
+}
+declare function buildCiPropertySearchBlock(input: BuildCiPropertyBlockInput): CiPropertyMeasuredBlock;
+
+type FlakyPolicy = "quarantine" | "strict";
+/**
+ * Layer-0 (diff-coverage) policy. `shortCircuit` defaults to FALSE: on a Layer-0 failure the
+ * run still mutates the covered changed lines so the default advisory audience keeps its
+ * mutation findings (a single uncovered line must not silently suppress all of Layer 1).
+ * `shortCircuit: true` is the opt-in fail-fast — Layer 1 is skipped and every surface
+ * (CLI, Markdown, artifact, certificate) discloses that mutation was skipped.
+ */
+interface DiffCoveragePolicy {
+    shortCircuit: boolean;
+}
+interface DeterministicMutantsPolicy {
+    /**
+     * Production-candidate operators beyond Stryker's built-ins. Disabled until held-out
+     * cross-project replay promotes the inventory.
+     */
+    enabled: boolean;
+    /** Maximum carried deterministic mutants per run; unselected candidates remain disclosed. */
+    maxRun: number;
+}
+interface PerTestPolicy {
+    enabled: boolean;
+    /** Full-suite comparison sample; null until a held-out JavaScript benchmark freezes its size. */
+    fullSuiteAuditSampleSize: number | null;
+    /** Largest accepted mismatch fraction; null until benchmark-frozen. Both audit fields move together. */
+    fullSuiteMismatchTolerance: number | null;
+}
+interface FixLoopPolicy {
+    enabled: boolean;
+    /** max survivor gaps to attempt a candidate killing test for */
+    maxCandidates: number;
+    /**
+     * How many times each proof side (real / mutant) is re-run.
+     *
+     * The default is 2, not 1, and that is load-bearing rather than cautious: the executor ALTERNATES
+     * which side runs first on each repetition, so a candidate that only "works" because of state the
+     * previous run left behind cannot satisfy every repetition. With a single repetition there is
+     * nothing to alternate and that protection never engages — the very defence would be inert by
+     * default.
+     */
+    proofRepetitions: number;
+    /** Inline is shipping-default; deferred emits target-proven evidence for a separate same-PR lane. */
+    suiteConfirmation?: "inline" | "deferred";
+    /** Bounded literal non-secret values made available only inside fix proof containers. */
+    syntheticEnvironment?: Record<string, string>;
+    /**
+     * Hard wall-clock budget for candidate GENERATION (model calls), in ms (default at the use
+     * site: 12 min). Overrun ⇒ the block reports `unavailable: generation-budget-exceeded`.
+     */
+    generationDeadlineMs?: number;
+    /**
+     * Hard wall-clock budget for the PROOF phase (targeted runs + the suite check), in ms
+     * (default at the use site: 15 min). Overrun ⇒ unattempted candidates are reported
+     * not-attempted and suite-unverified candidates are REJECTED — fail-closed, never
+     * silently passed.
+     */
+    proofDeadlineMs?: number;
+    cacheDir?: string;
+}
+interface ErrorPathsPolicy {
+    /** run the static handler scanner (advisory) */
+    staticAnalysis: boolean;
+    /** opted-in gate: a changed handler with an untested (survived/no-coverage) mutant fails the gate */
+    failOnUntested: boolean;
+    /** opted-in gate: any detected handler anti-pattern fails the gate */
+    failOnAntiPattern: boolean;
+    /** force a handler mutant when a changed handler has no usable built-in Stryker mutant */
+    forceHandlerMutation: boolean;
+}
+/**
+ * Which model runs each Layer-1 task.
+ *
+ * NEVER a credential — one project endpoint and key come from the environment
+ * (`ATTEST_MODEL_ENDPOINT` / `ATTEST_MODEL_API_KEY`); only the model NAME differs between entries.
+ * Policy is checked into the customer's repository, so a key here would be committed and shared.
+ *
+ * Per TASK rather than per run, because the tasks are not alike: equivalence triage is a judgement
+ * call over a small context, proposal generation is creative work over a whole file, and test
+ * generation must produce code that compiles and runs. `default` covers any task not named.
+ */
+interface ModelChoicePolicy {
+    /** the local Claude CLI, or a model hosted on the configured project endpoint */
+    provider: "claude-cli" | "hosted";
+    /** model name as the project knows it (required for `hosted`) */
+    model?: string;
+    /** `default` (ATTEST_MODEL_ENDPOINT) or `alt` (ATTEST_MODEL_ENDPOINT_ALT) */
+    endpoint?: "default" | "alt";
+    /** USD per 1M tokens, so run spend is reported rather than fabricated */
+    pricePerMTokens?: {
+        input: number;
+        output: number;
+    };
+    temperature?: number;
+    /** reasoning effort, where the model supports it — benchmarked as its own axis */
+    /**
+     * "xhigh" is OpenAI's own top tier (none|low|medium|high|xhigh); "ultra" belongs to other
+     * harnesses' vocabularies. Both are accepted because the value passes through VERBATIM to the
+     * provider — mapping one to the other would make the recorded identity (model@effort, baked
+     * into every cache key and triage record) claim an effort that was never actually requested.
+     */
+    effort?: "low" | "medium" | "high" | "xhigh" | "ultra";
+    /**
+     * Generated-token ceiling; reasoning models need headroom for hidden reasoning.
+     *
+     * ```yaml
+     * classicMutation:
+     *   models:
+     *     fixLoop:
+     *       maxCompletionTokens: 8000
+     * ```
+     *
+     * The fix loop wants 8000 or more. Its prompt now carries the enclosing function, the route to
+     * it, and the resolved shapes of every type in both signatures, so the test it asks for is
+     * correspondingly longer. A reply that hits the ceiling is TRUNCATED, and a truncated reply
+     * truncates identically on retry — it is not retried, and the gap reports no candidate. Provider
+     * defaults differ sharply here (2000 on one, 32000 on another), so a ceiling that never bound
+     * one model can silently bind the next.
+     */
+    maxCompletionTokens?: number;
+    /**
+     * How long one model call may take, in ms. Default 240_000.
+     *
+     * Measured, not guessed: with the current prompt this model answers a fix-loop call in 40–50s,
+     * and the slowest gap observed on a real repository took 238s — two seconds under the old
+     * hardcoded ceiling. The ceiling was reachable and nothing could move it, because it lived in
+     * the provider source and no policy or environment path led to it.
+     *
+     * Bounded at 290_000. Node's own fetch abandons a request that has produced no response for
+     * ~300s regardless of what we ask for (measured: three calls died at 301.0s against a 15-minute
+     * setting, `UND_ERR_HEADERS_TIMEOUT`). Staying below it keeps our own abort the one that fires,
+     * and a larger number here would read as patience we cannot deliver.
+     */
+    timeoutMs?: number;
+}
+type ModelsPolicy = Partial<Record<"default" | "triage" | "counterfactual" | "fixLoop" | "naming" | "layer2Intent" | "layer2Test" | "layer2IntentFallback" | "layer2TestFallback" | "ciPropertyIntent" | "ciPropertyTest" | "ciPropertyIntentFallback" | "ciPropertyTestFallback", ModelChoicePolicy>>;
+interface ClassicMutationPolicy {
+    deterministicMutants: DeterministicMutantsPolicy;
+    perTest: PerTestPolicy;
+    fixLoop: FixLoopPolicy;
+    errorPaths: ErrorPathsPolicy;
+    /** per-task model selection; absent ⇒ the local Claude CLI, as before */
+    models?: ModelsPolicy;
+}
+/**
+ * Source-grounded Layer 2 search. This remains a research-only, advisory mechanism until the
+ * frozen natural-fault benchmark and overnight shadow both pass.
+ */
+interface ScenarioSearchPolicy {
+    enabled: boolean;
+    /** Only the research profile exists before benchmark promotion. */
+    profile: "research";
+    lanes: ScenarioLane[];
+    sourceModes: ScenarioAuthority[];
+    maxTargets: number;
+    maxCandidatesPerTarget: number;
+    maxAgentTurnsPerTarget: number;
+    maxModelCalls: number;
+    totalDeadlineMs: number;
+    executionDeadlineMs: number;
+    replayRepetitions: number;
+    /** Required true in v1: generated code is never executed on the host. */
+    requireContainer: true;
+    /** Optional user-owned cache directory override. */
+    cacheDir?: string;
+    /** Required false in v1: Layer 2 cannot affect a gate before promotion. */
+    failOnCounterexample: false;
+}
+/** Bounded pull-request property search. Disabled until benchmark and shadow promotion. */
+interface CiPropertySearchPolicy {
+    enabled: boolean;
+    mode: "shadow" | "advisory";
+    authorities: CiPropertyAuthority[];
+    maxTargets: number;
+    candidateCap: CiPropertyCandidateCap;
+    maxFindings: number;
+    claimPoolSize: number;
+    propertyRuns: number;
+    replayRepetitions: number;
+    setupRepairAttempts: number;
+    totalDeadlineMs: number;
+    perCandidateDeadlineMs: number;
+    maxEvidenceSources: number;
+    maxEvidenceBytes: number;
+    requireContainer: true;
+    failOnFinding: false;
+    cacheDir?: string;
+}
+/**
+ * Reverse-patch verification: revert a hunk of the pull request's OWN diff and re-run the suite.
+ * A suite that stays green proves no test pins that change — a gap the mutation score cannot see,
+ * because there is no mutant involved, only the author's real edit.
+ *
+ * BETA, and off by default. It is advisory in the strongest sense: it never changes the mutation
+ * score, never moves a gate, and cannot fail a build. What it costs is wall time, and the honest
+ * number is stated rather than hidden — measured on a seven-item cohort of real pull requests, a
+ * caught change adds about 0.4x the suite's own runtime and a reported gap about 2.2x, because a
+ * gap must be proven by running the complete suite twice.
+ *
+ * NOT tier-gated, unlike `scenarioSearch` and `ciPropertySearch`, which {@link researchTier}
+ * forces to `disabled-by-tier` at tier 0. Those two spend model budget and a tier-0 run has none;
+ * this lane spends only the customer's own test runner, so gating it by tier would withhold a
+ * capability that costs nothing to grant. Stated here rather than left as an absence, because the
+ * asymmetry is otherwise only visible by noticing which member is missing from ResearchTier.
+ *
+ * Beta limits, both deliberate: jest and vitest only (the comparison needs a per-test report),
+ * and single-package runs only (the lane binds one baseline and one working directory, so a
+ * multi-package run has nothing coherent to compare against and is refused by name).
+ */
+interface PatchRevertPolicy {
+    enabled: boolean;
+    /**
+     * Run the covering test files in ONE runner invocation to decide the common "a test catches
+     * this" case without a whole-suite run.
+     *
+     * On by default WHEN the lane is enabled, because it is what makes the cost bearable: measured
+     * across the cohort it took the caught case from 0.96x of a suite to 0.41x, and on the two
+     * realistic suite sizes (35s and 46s) to 0.05x. It cannot change a verdict — the screen may only
+     * conclude "a test caught this", and every other outcome runs the complete suite regardless.
+     */
+    batchedImpactScreen: boolean;
+}
+interface ResearchPolicy {
+    scenarioSearch: ScenarioSearchPolicy;
+    invariant: CiPropertySearchPolicy;
+}
+/** Classic-mutation cost controls (the sampling cap + static-mutant handling). */
+interface MutationPolicy {
+    /**
+     * Budget for classic mutants per run; null = uncapped (every mutant in the changed ranges runs
+     * — today's behavior). When set, the engine enumerates every eligible mutant, then runs a
+     * seeded line-first round-robin sample of this size: one mutant per changed line before any
+     * line gets a second, so breadth over changed lines is maximal by construction. The full
+     * eligible count, the sample, the seed, and line breadth are all disclosed in the artifact's
+     * classicSampling block — a capped run can never present as a full one. mutantsPlanned/Run keep
+     * describing the EXECUTED set (the server recomputes them from mutant records, so they cannot
+     * mean anything the records don't contain); whether the §4.3 sampling-fraction floor should
+     * read eligible-set instead is a frozen-plan amendment, deliberately not smuggled in here.
+     */
+    maxMutantsPerRun: number | null;
+    /**
+     * Skip "static" mutants (evaluated at module load; each needs a fresh process + full-suite
+     * run — Stryker measures 6-18% of mutants consuming 40-79% of run time). Skipped statics come
+     * back as skipped-by-cap in the accounting, so the exclusion is disclosed, never silent.
+     */
+    ignoreStatic: boolean;
+    /** Confirmation repetitions; null means uncertain mutation outcomes are excluded, never credited. */
+    recheckRepetitions: number | null;
+    /** Multiplier for the baseline-derived timeout factor; configured with recheckRepetitions. */
+    recheckTimeoutFactorMultiplier: number | null;
+}
+/**
+ * How several survivors in one place are presented as ONE finding.
+ *
+ * Declared here, in core, because it is a policy value the engine reads — the engine depends on
+ * core, never the reverse, so the closed set has to live on this side of that edge.
+ *
+ *  - `line`        — group by source line. Wrong in both directions: two operands of one `if` on
+ *                    separate lines render as two gaps, while two unrelated statements sharing a
+ *                    line render as one. Retained ONLY because the hosted control plane never
+ *                    receives source and so cannot do better.
+ *  - `structural`  — group by the smallest enclosing STATEMENT, with containment capped so a
+ *                    whole-function survivor cannot absorb everything inside it. A fact about the
+ *                    syntax tree, so no merge can be wrong. Fixes both of line's errors. THE DEFAULT.
+ *
+ * TWO STRATEGIES WERE REMOVED, both on measurement rather than taste:
+ *
+ *  - `data-flow` merged clusters sharing a resolved binding inside one function. On 189 real
+ *    survivors across 17 files it produced **2 merges beyond structural**, in 2 files. A setting
+ *    that changes nothing is worse than an absent one, because someone eventually enables it and
+ *    wonders why their output is identical. The scope resolver it was built on REMAINS — see
+ *    `engine-stryker/src/scope.ts`; the `wrong-variable` mutator depends on it to avoid substituting
+ *    a name that is not in scope, and nothing else can tell two same-named variables apart.
+ *  - `semantic` asked a model to merge. gpt-5.6-terra at `xhigh` also managed **2 merges** on the
+ *    same corpus — a mechanical analyser and the best available model independently agreeing there is
+ *    nothing to merge beyond the syntax tree. What the model IS good at is naming the gap, which is
+ *    now {@link FindingsPolicy.naming} and never touches the grouping.
+ *
+ * Every strategy keeps each mutant individually in the artifact and displays each cluster's member
+ * count, so no signed number depends on this setting.
+ */
+declare const CLUSTER_STRATEGIES: readonly ["line", "structural"];
+type ClusterStrategy = (typeof CLUSTER_STRATEGIES)[number];
+/** Narrow an untrusted value to a strategy. Lives beside the set it guards so the two cannot drift. */
+declare function isClusterStrategy(v: unknown): v is ClusterStrategy;
+interface FindingsPolicy {
+    clustering: ClusterStrategy;
+    /**
+     * Ask a model to NAME each test gap in plain English. Off by default — it costs one call per file.
+     *
+     * The model labels; it never groups. That distinction is the whole feature: `clustering` decides
+     * how many gaps there are and stays mechanical, while naming only adds a sentence to each one, so
+     * a bad reply costs a missing label and can never change a count.
+     *
+     * Measured on 63 real gaps from node-cron: gpt-5.6-terra at `xhigh` named 60 of them accurately.
+     * Asked instead to MERGE gaps, the same model managed 2 merges beyond structural across 4 files —
+     * which is why grouping-by-model was dropped and naming kept.
+     *
+     * Requires tier >= 1, like every other model-backed feature. The names are prose and stay
+     * CUSTOMER-SIDE: they reach the pull-request comment the CLI posts and never the control plane.
+     */
+    naming: boolean;
+}
+/** Proof-sandbox provisioning for fix-loop worktrees. */
+interface SandboxPolicy {
+    /**
+     * Repo-relative gitignored files to mirror into proof sandboxes (e.g. "packages/api/.env").
+     * Root-level .env conventions are auto-linked without configuration; this list is for nested
+     * paths only. Same-host ephemeral copies, wiped on dispose; content never egresses (the tier
+     * schema has no field for it) and never enters model prompts. Explicit by design so security
+     * review sees exactly which files proof runs may read.
+     */
+    envFiles: string[];
+}
+/**
+ * Identity and admission rules for the caller-prepared test environment.
+ *
+ * Callers invoke Abloh after their normal setup. Sandboxed HEAD/fault proofs never guess how to
+ * reconstruct that setup: the trusted base policy must declare the exact install directory,
+ * install command, and any setup commands. Missing or failing proof preparation is reported as
+ * incomplete while host baseline, coverage, and classic mutation remain usable.
+ */
+interface EnvironmentPolicy {
+    /**
+     * Immutable OCI image used to prepare the test environment for adversarial proofs.
+     * Omission uses Abloh's reviewed, digest-pinned Node image; a mutable tag is never accepted.
+     */
+    runtimeImage?: string;
+    /** Repository-relative directory in which the sandbox dependency install runs. */
+    installDirectory?: string;
+    /** Exact direct dependency-install command for sandbox proofs; no shell evaluation. */
+    installCommand?: string;
+    /** Optional local-only service presets. Every proof phase receives fresh isolated instances. */
+    services: Array<{
+        kind: "postgres" | "redis";
+        image: string;
+    }>;
+    /** Environment-variable names that must be present. Values are used by tests but never recorded. */
+    requiredVariables: string[];
+    /** Additional repo-relative regular files whose bytes identify the prepared environment. */
+    identityFiles: string[];
+    /**
+     * Optional direct commands run after the declared dependency install in the proof image.
+     * Each string is parsed as argv and is never evaluated by a shell.
+     */
+    setupCommands: string[];
+    /**
+     * Repo-relative files or directories setup may create or change. Their resulting bytes, modes,
+     * missing state, and contained symlinks are bound into the environment contract.
+     */
+    generatedFiles: string[];
+    /** Optional single, literal test command. Shell composition and inline environment values are refused. */
+    testCommand?: string;
+}
+interface AttestPolicy {
+    /** minimum score (of changed code) to pass the gate */
+    threshold: number;
+    /** advisory (neutral check) until true */
+    enforce: boolean;
+    /** data-flow tier (§4.1) — 0 = no LLM, 1 = in-CI triage, 2 = snippet egress */
+    tier: 0 | 1 | 2;
+    floor: FloorPolicy;
+    mutation: MutationPolicy;
+    sandbox: SandboxPolicy;
+    /** Repository-relative package selected by `abloh init`; absent means the repository root. */
+    target: {
+        directory?: string;
+    };
+    environment: EnvironmentPolicy;
+    /** Layer-0 diff-coverage behavior */
+    diffCoverage: DiffCoveragePolicy;
+    flaky: FlakyPolicy;
+    /** paths where "no new untriaged survivors" applies (optional rule) */
+    flaggedPaths: string[];
+    /**
+     * Multi-package gate aggregation. Default worst-of-packages (a weak package cannot hide in
+     * the pooled score). "standalone" is the raw-path escape hatch for a self-hosted server that
+     * does not yet verify per-package evidence — decided BEFORE measurement, so the artifact
+     * never claims a rule it also gated on.
+     */
+    scoreAggregation: "standalone" | "worst-of-packages";
+    /** certificate approvers; consumed by the control plane during issuance */
+    approvers: string[];
+    /** Classic-mutation extension policy: deterministic mutants, per-test, fix loop, error paths. */
+    classicMutation: ClassicMutationPolicy;
+    patchRevert: PatchRevertPolicy;
+    research: ResearchPolicy;
+    /** how survivors in one place are presented as one finding — presentation only, never a count */
+    findings: FindingsPolicy;
+}
+declare const DEFAULT_CLASSIC_MUTATION: ClassicMutationPolicy;
+declare const DEFAULT_MECHANISMS: {
+    scenarioSearch: ScenarioSearchPolicy;
+    ciPropertySearch: CiPropertySearchPolicy;
+    patchRevert: PatchRevertPolicy;
+};
+declare const DEFAULT_DIFF_COVERAGE: DiffCoveragePolicy;
+declare const DEFAULT_MUTATION: MutationPolicy;
+declare const DEFAULT_SANDBOX: SandboxPolicy;
+/** Reviewed multi-platform Node 22 base used only when a repository has not pinned its own image. */
+declare const DEFAULT_ENVIRONMENT_IMAGE_DIGEST = "6c74791e557ce11fc957704f6d4fe134a7bc8d6f5ca4403205b2966bd488f6b3";
+declare const DEFAULT_ENVIRONMENT_IMAGE_REF = "node:22.23.1-bookworm-slim@sha256:6c74791e557ce11fc957704f6d4fe134a7bc8d6f5ca4403205b2966bd488f6b3";
+declare const DEFAULT_ENVIRONMENT: EnvironmentPolicy;
+/**
+ * `structural` by default, not `line`.
+ *
+ * The line key is not a conservative baseline — it is actively wrong in both directions, and one of
+ * those directions (two operands of one guard shown as two separate gaps) inflates what we report
+ * about the customer. `structural` is a syntax-tree fact with no way for a merge to be incorrect,
+ * so it is the honest default. The two strategies that CAN merge wrongly are opt-in.
+ */
+declare const DEFAULT_FINDINGS: FindingsPolicy;
+declare const DEFAULT_POLICY: AttestPolicy;
+/** Validate an explicit CLI/action test command using the same rules as committed policy. */
+declare function validatePreparedTestCommand(value: unknown, label?: string): string;
+/** Parse the validated literal-command subset into the exact argv that engines must execute. */
+declare function parsePreparedTestCommand(value: unknown, label?: string): string[];
+/** Parse an engine-generated command string whose data arguments were already shell-quoted. */
+declare function parseLiteralArguments(command: string, label?: string): string[];
+/** Hard bound on generated/literal command argv length — preflight surfaces it up front. */
+declare const MAX_LITERAL_ARGUMENTS = 128;
+/** Hard byte bound on a whole generated/literal command line. */
+declare const MAX_LITERAL_COMMAND_BYTES: number;
+/**
+ * The resolved state of each Layer-1 feature after tier gating.
+ */
+interface ClassicMutationTier {
+    fixLoop: "enabled" | "disabled" | "disabled-by-tier";
+    perTest: "enabled" | "disabled";
+    errorPathStatic: "enabled" | "disabled";
+}
+/**
+ * `effectiveTier` is the tier the RUN actually operates at — the `--tier` override when one was
+ * passed, else the policy's. It must be threaded in explicitly: reading `policy.tier` here would
+ * let `--tier 0` emit a Tier-0 artifact while the model-backed extensions still ran (and, inversely,
+ * suppress features a `--tier 1` override enabled). The artifact's tier and the features that ran
+ * must always describe the same run.
+ */
+declare function classicMutationTier(policy: AttestPolicy, effectiveTier?: 0 | 1 | 2): ClassicMutationTier;
+/**
+ * The resolved state of source-grounded scenario search after tier gating. It is model-backed and
+ * is forced `disabled-by-tier` at tier 0. Same
+ * `effectiveTier` threading rule as {@link classicMutationTier}: the artifact's tier and the features that
+ * ran must always describe the same run.
+ */
+interface ResearchTier {
+    scenarioSearch: "enabled" | "disabled" | "disabled-by-tier";
+    ciPropertySearch: "enabled" | "disabled" | "disabled-by-tier";
+}
+declare function researchTier(policy: AttestPolicy, effectiveTier?: 0 | 1 | 2): ResearchTier;
+/**
+ * Validate a parsed policy document and merge it over defaults. Fail-closed: throws
+ * `invalid <path>: …` on any unknown key, wrong type, or out-of-range value.
+ */
+declare function validatePolicy(raw: unknown, path: string): AttestPolicy;
+/** Load and validate a policy file over defaults. Missing file ⇒ defaults. */
+declare function loadPolicy(path: string): AttestPolicy;
+
+/**
+ * worst-of-packages gate derivation — ONE implementation shared by the CLI's local gate and
+ * the server's recompute (draft.ts hard-rejects any mismatch between them, so two copies would
+ * turn drift into a customer-facing 400 outage).
+ */
+
+interface WorstOfRow {
+    directory: string;
+    l0State: "completed" | "cannot-attest" | "not-applicable" | "not-run";
+    l0Counts: ReturnType<typeof countsFromLines> | null;
+    mutationState: "completed" | "cannot-attest" | "not-applicable" | "not-run";
+    mutationCounts: Counts | null;
+    confirmedEquivalent: number;
+    scoreable: boolean;
+}
+interface WorstOfOutcome {
+    gate: GateResult;
+    /** null = the pooled gate decided; otherwise the directory of the deciding package. */
+    decisivePackage: string | null;
+}
+/**
+ * overall = worst(pooled combined gate, per-package gates) — the POOLED gate stays a member of
+ * the min so every existing forcing rule (flagged paths, error paths, anti-patterns) survives
+ * (panel C1). Rows without scoreable evidence never vote (panel C2). Per-package Layer-1 score
+ * is measured against the SAME global threshold with the same triage basis as the pooled gate.
+ */
+declare function deriveWorstOfGate(input: {
+    rows: readonly WorstOfRow[];
+    pooledGate: GateResult;
+    threshold: number;
+    tier: 0 | 1 | 2;
+    useTriagedBasis: boolean;
+}): WorstOfOutcome;
+
+/**
+ * Linear-time canonical-base64 validation.
+ *
+ * The obvious regular expression for this shape —
+ * `^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$` — is a trap. The grouped
+ * quantifier makes V8 record a backtracking frame per four-character group, so the engine
+ * overflows its stack on long inputs and throws `RangeError: Maximum call stack size exceeded`
+ * instead of returning false. That is not a slow refusal, it is a WRONG one: the caller was
+ * validating untrusted output, the throw escapes the validator, and the surrounding code reports
+ * an internal error rather than the refusal the input earned.
+ *
+ * Measured on ts-pattern (2026-08-04): the fix loop's artifact collector returned a few hundred
+ * kilobytes of legitimate base64 and the regex overflowed, surfacing as
+ * `restricted-environment-unavailable: Maximum call stack size exceeded` — a real repository made
+ * unmeasurable by its own valid output.
+ *
+ * This scan accepts exactly what that expression accepts (length a multiple of four, alphabet
+ * characters only, one or two `=` allowed at the very end) with no backtracking and no recursion,
+ * so the answer depends on input length only through a single pass.
+ */
+/** Accepts iff `value` is canonical, correctly padded standard base64 (empty string included). */
+declare function isCanonicalBase64(value: string): boolean;
+
+/**
+ * Findings model — the customer-facing "what the suite missed" list. Survivors and
+ * no-coverage mutants become gap findings; triage attaches a verdict + rationale ref.
+ */
+
+type TriageVerdict = "likely-equivalent" | "real-gap" | "unclear";
+/**
+ * Canonical closed reason-code enum (§4.1 egress schema) — the SINGLE source of truth. Both
+ * @abloh/triage (the producer) and @abloh/api (the validator) import this tuple instead of
+ * keeping private mirrors that can silently drift out of lockstep.
+ */
+declare const TRIAGE_REASON_CODES: readonly ["EQUIVALENT_NO_OBSERVABLE_EFFECT", "EQUIVALENT_DEAD_BRANCH", "EQUIVALENT_REDUNDANT_CONDITION", "GAP_MISSING_ASSERTION", "GAP_UNCOVERED_BRANCH", "GAP_BOUNDARY_UNTESTED", "GAP_ERROR_PATH_UNTESTED", "UNCLEAR_NEEDS_HUMAN"];
+type TriageReasonCode = (typeof TRIAGE_REASON_CODES)[number];
+/**
+ * The reason code a MECHANICALLY forced error-path gap carries (Extension 5). It is assigned by the
+ * engine when a survivor sits inside a changed error handler — never by the LLM — so such a gap is
+ * a real gap by construction and must never be folded into the confirmed-equivalent count.
+ */
+declare const MECHANICAL_ERROR_PATH_REASON: TriageReasonCode;
+/** A model-written description may never exceed this. */
+declare const MAX_FINDING_DESCRIPTION_LEN = 200;
+/**
+ * Accept a model-written description, or reject it entirely.
+ *
+ * Returns null when the sentence is unusable, and the caller then falls back to the
+ * mechanical template. Deliberately all-or-nothing: truncating or stripping a leaking
+ * sentence would produce a mangled half-quote that still carries source.
+ */
+declare function sanitizeFindingDescription(raw: unknown): string | null;
+/**
+ * The evidence sentence: what we did, and that nothing objected.
+ *
+ * This is the half that makes the headline credible. "No test covers the boundary case" is a
+ * claim; "we moved a comparison boundary and every test still passed" is the measurement
+ * behind it. Stated as fact — never "if this breaks", because code does not break, people
+ * edit it, and never a consequence we did not observe.
+ */
+declare function describeMutationEvidence(mutator: string | null | undefined, status?: string | null, location?: {
+    readonly file?: unknown;
+    readonly startLine?: unknown;
+} | null): string;
+/** Gloss for a reason code, or the bare token when it is not one we know. */
+declare function describeReasonCode(code: string | null | undefined): string | null;
+/**
+ * The header for one finding: what the test suite failed to check, in one line.
+ *
+ * Deliberately NOT "Surviving mutant: LogicalOperator in <file>" — that is a taxonomy token
+ * pasted into a sentence, and it is what this replaces.
+ *
+ * The classifier's own sentence wins when there is one, because it can name the specific condition
+ * nothing checks in THIS codebase's terms — "refunds above the daily cap are never rejected" says
+ * something a template cannot. The reason-code gloss is the fallback, and it is a fallback: there
+ * are eight of them, so a queue built on glosses alone shows the same eight headers over and over
+ * and a reader cannot tell two findings apart without opening both.
+ *
+ * NO file:line. It used to end in one, which meant every surface that rendered this — the run
+ * page's card, the queue row, the detail panel — printed the location twice, once inside the header
+ * and again in the location field directly beneath it. Where a finding is belongs to the location
+ * field; this sentence is what is wrong.
+ */
+declare function describeFinding(finding: {
+    readonly status?: unknown;
+    readonly triage?: {
+        readonly reasonCode?: unknown;
+        readonly description?: unknown;
+    } | null;
+}): string;
+interface TriageRecord {
+    verdict: TriageVerdict;
+    /** closed-enum reason code (§4.1 egress schema) */
+    reasonCode: string;
+    confidence: number;
+    /** free-text rationale — archived customer-side, referenced by digest in Tier 1 */
+    rationale?: string;
+    /**
+     * One egress-checked sentence: what the suite failed to check, in the codebase's own
+     * terms. Unlike {@link rationale} this DOES leave the runner — it is bounded, stripped
+     * of anything resembling code by {@link sanitizeFindingDescription}, and advisory: it
+     * never affects verdict, score or gate, and never appears on a certificate.
+     */
+    description?: string;
+    /**
+     * The consequence half of the same claim: what could change without a test failing.
+     *
+     * A SECOND bounded field rather than a longer {@link description}, because the two fail
+     * independently — a fumbled consequence would otherwise overrun the length cap and take the
+     * condition sentence down with it, which is exactly why p6 forbade explaining consequences at
+     * all. Advisory on the same terms: never affects verdict, score, gate or certificate.
+     */
+    impact?: string;
+    /** overridden by the customer to non-equivalent? */
+    overridden?: boolean;
+    /**
+     * Reasoning effort the classifier ran at, when one was configured.
+     *
+     * Part of the classifier IDENTITY, not telemetry: the same model and prompt score differently
+     * per effort (measured: gpt-5.6-terra made zero wrong equivalence calls at `high` and two at
+     * `medium`), so the registry pins it — and the server recomputes `triageValidated` from these
+     * records, so without this field a validated run cannot be distinguished from an unvalidated one.
+     */
+    effort?: string;
+    /**
+     * Assigned mechanically by the engine (Extension 5 error-path forcing), NOT by the LLM. A
+     * mechanical disposition is always a real gap and can never be counted equivalent — see
+     * {@link isConfirmedEquivalent}. It also marks a mutant that must skip LLM equivalence triage.
+     */
+    mechanical?: boolean;
+    /** model that produced the verdict (traceability) */
+    modelId?: string;
+    /** prompt template version that produced the verdict (traceability) */
+    promptVersion?: string;
+}
+/**
+ * Build the mechanical (non-LLM) error-path disposition for a survivor inside a changed handler.
+ * Real gap by construction; can never be confirmed equivalent and is never sent to the LLM.
+ */
+declare function mechanicalErrorPathDisposition(): TriageRecord;
+declare const FINDING_SEVERITIES: readonly ["low", "medium", "high", "critical"];
+type FindingSeverity = (typeof FINDING_SEVERITIES)[number];
+declare function findingSeverity(finding: {
+    /** "survived" | "no-coverage" — a no-coverage mutant is one nothing executed */
+    status?: string | null;
+    /** how many tests execute this mutant; null when the engine did not report it */
+    coveredBy?: number | null;
+    triage?: {
+        reasonCode?: unknown;
+        confidence?: unknown;
+    } | null;
+}): FindingSeverity;
+/**
+ * What KIND of hole a mutation finding is — the word the work queue groups and filters on.
+ *
+ * This was `status === "no-coverage" ? "uncovered-line" : "surviving-mutant"`: two values for a
+ * vocabulary of seven, so a queue that offered "error handling" as a filter could never return a
+ * row, and the run page's "Error-handling issues" tile linked somewhere permanently empty.
+ *
+ * The reason code is the only thing on a finding that says what the hole IS rather than how it was
+ * observed, so it decides — and only where it makes a claim this vocabulary can express. An
+ * unexercised error path is its own kind of problem and gets its own word; every other reason code
+ * describes an ordinary untested line, which is what the two observational kinds already say
+ * accurately. Inventing a distinct kind per reason code would restate the reason code as a
+ * category and split the queue into slices nobody asked for.
+ *
+ * Deliberately NOT mapped: GAP_MISSING_ASSERTION does not become "asserts-nothing". That kind
+ * names a TEST that asserts nothing at all — a per-test verdict about a whole test — whereas a
+ * missing-assertion gap says the tests covering one line do not check this particular behaviour.
+ * Folding them together would make the filter return two unrelated things under one name.
+ */
+declare function findingKind(finding: {
+    status?: string | null;
+    triage?: {
+        reasonCode?: unknown;
+    } | null;
+}): "uncovered-line" | "surviving-mutant" | "error-handler";
+interface GapFinding {
+    mutantId: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    mutator: string;
+    replacement: string | null;
+    status: "survived" | "no-coverage";
+    coveredBy: number;
+    triage?: TriageRecord;
+    /**
+     * Exact 1-based columns of the mutated span, and the source slice it replaced.
+     *
+     * TIER-2 ONLY, like `replacement` beside them. `FINDING_ALLOWED_FIELDS` in `apps/api/src/draft.ts`
+     * is a closed allowlist of seven structural names and lists none of these, so at tier 0 and tier 1
+     * the sanitizer drops them at the trust boundary and no signed digest can move. Tier 2 is the
+     * customer's explicit choice to let Abloh hold the evidence itself, and admits exactly these four
+     * through `TIER2_ADDITIONAL_FINDING_FIELDS` — see the note there for what still never egresses.
+     *
+     * They exist because a LINE cannot locate an AST node, and finding clustering needs to know
+     * which expression a mutant sits in — the difference between "two operands of one guard" and
+     * "two unrelated statements that share a line". `originalText` is what makes that location
+     * VERIFIABLE rather than assumed: the engine report's column base cannot be confirmed from the
+     * report itself, so the recorded slice is the oracle and a mismatch means refuse, not guess.
+     */
+    startColumn?: number;
+    endColumn?: number;
+    originalText?: string;
+}
+/**
+ * A survivor is a real gap unless triage confirms it equivalent and it isn't overridden. A
+ * mechanical disposition (error-path forcing) is a real gap by construction and can never be
+ * counted equivalent, even if some caller mislabels its verdict.
+ */
+declare function isConfirmedEquivalent(t: TriageRecord | undefined): boolean;
+/** Strip the free-text rationale before any egress — it stays archived customer-side. */
+declare function redactTriageForEgress(t: TriageRecord): Omit<TriageRecord, "rationale">;
+interface LineGroup {
+    /** the first member's mutant id — anchors the existing `finding=<id>` deep-link contract */
+    first: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    /** displayable mutator tokens, in first-seen order */
+    mutators: string[];
+    /** how many mutants this group represents — load-bearing, never decoration */
+    count: number;
+    /**
+     * Triage reason codes on this line, tallied, most common first.
+     *
+     * This is what makes a grouped annotation say what the SUITE failed to check rather than
+     * only what we changed. It needs no model call: each code was already decided per mutant
+     * during triage, so this is arithmetic over labels that exist.
+     */
+    /**
+     * Triage reasons on this line, tallied, most common first — each carrying one model
+     * sentence drawn from its OWN members.
+     *
+     * Per reason rather than per line: mutants sharing a reason code are mutations of the same
+     * behaviour, so their sentences say near-identical things and picking one is close to free
+     * of arbitrariness. Picking one for a whole 55-mutant line is not — it presents one
+     * member's opinion as the summary of everything on that line.
+     */
+    reasons: {
+        code: string;
+        count: number;
+        description?: string;
+    }[];
+    /**
+     * The model's own sentence, present ONLY when this group has exactly one member — the
+     * unambiguous case, where it is simply the best text available.
+     */
+    description?: string;
+}
+/**
+ * Group survivors by source LINE.
+ *
+ * This is the rule the HOSTED surfaces use, and it lives here because the control plane cannot use
+ * anything better: grouping by what a mutant actually breaks needs the syntax tree, and source
+ * never reaches Abloh — everything that touches source runs in the customer's CI. Customer-side,
+ * `@abloh/engine-stryker`'s `clusterMutants` does the real thing and calls this as its `line`
+ * strategy.
+ *
+ * It lives in ONE place because it had already drifted into three. `structuralFindings`
+ * (`apps/api/src/github-delivery.ts`) grouped correctly; `buildResolvedEvidence`
+ * (`apps/api/src/v1-live.ts`) emitted one finding per mutant and so re-created the exact defect
+ * grouping was introduced to remove — the live Cosmos delivery stacked six byte-identical
+ * "Surviving mutant" annotations on one line, six of something and nothing about what. The App
+ * documents that it accepts `count`/`mutators` precisely so that cannot happen; one of the two
+ * senders simply never set them.
+ *
+ * Confirmed-equivalent survivors are excluded by the CALLER, not here: the verdict shape differs
+ * between the artifact and the run record, and folding that in would give this function a second
+ * job it could get wrong quietly.
+ */
+declare function groupFindingsByLine(findings: readonly {
+    mutantId?: unknown;
+    file?: unknown;
+    startLine?: unknown;
+    endLine?: unknown;
+    mutator?: unknown;
+    triage?: {
+        reasonCode?: unknown;
+        description?: unknown;
+    } | null;
+}[]): LineGroup[];
+declare function toGapFindings(mutants: NormalizedMutant[]): GapFinding[];
+
+/**
+ * A NAME FOR A GAP THAT OUTLIVES THE RUN THAT FOUND IT.
+ *
+ * Every existing identifier for a mutant is deliberately run-scoped. `NormalizedMutant.id` says so
+ * on its own doc comment — unique within a run and nothing more. {@link mutantIdentity} is stable
+ * across runs but only at the same commit: it includes the start and end lines, because the caches
+ * it was built for compare two measurements of identical source and must not collide two mutants
+ * that differ only in span.
+ *
+ * A ledger needs the opposite trade. It follows one gap across commits, and the commonest thing a
+ * developer does between two runs is move the code: add an import, extract a helper, reformat. All
+ * of that shifts every line below it, and a key containing a line number renames every gap in the
+ * file — so the ledger would close them all as fixed and open a fresh set, on a commit that fixed
+ * nothing.
+ *
+ * WHAT IS AVAILABLE. Not much, on purpose. Below tier 2 a finding egresses only `file`, `mutator`,
+ * `status`, `coveredBy` and the line span — the mutated source text stays on the customer's runner,
+ * which is the whole point of the boundary. So the key is built from the two fields that survive an
+ * edit (`file`, `mutator`) plus an ORDINAL: which same-kind gap in that file this is, counting down
+ * the file.
+ *
+ * WHAT THAT COSTS. The ordinal is stable while the set of same-mutator gaps in a file keeps its
+ * order and size, which covers the case the ledger exists for — a developer writes a test and the
+ * source does not move at all. It is NOT stable when a new gap of the same kind appears earlier in
+ * the same file: everything below it shifts by one, and the ledger reads that as the old rows
+ * closing and new ones opening. That is a real limitation and it is bounded — one file, one mutator
+ * kind — and it fails toward noticing too much rather than too little, which is the safe direction
+ * for a list of things nobody has tested.
+ */
+/** The fields a gap key is built from. Deliberately the tier-0 subset — no source text. */
+interface GapKeyInput {
+    file: string;
+    mutator: string;
+    startLine: number;
+}
+/**
+ * Stable keys for one run's gaps, in the order the gaps were given.
+ *
+ * Ordinals are assigned per (file, mutator) by line order, NOT by the order the engine reported —
+ * a report's order depends on which mutants were sampled into the run, so keying on it would make
+ * a gap's name depend on its siblings.
+ */
+declare function gapKeys(gaps: readonly GapKeyInput[]): string[];
+
+/**
+ * Operator severity classification — "operator visibility" (Move 1).
+ *
+ * Every mutant carries a `mutator` name (Stryker's `mutatorName`, or one of our own
+ * custom-operator names). This maps that name to a SEVERITY CLASS so a survivor's
+ * significance is visible in the report: a surviving BlockStatement deletion ("a whole
+ * code block could be removed and no test noticed") is far more alarming than a surviving
+ * StringLiteral flip. Pure, deterministic, no I/O — safe to run anywhere, and it is
+ * PRESENTATIONAL ONLY: it never enters the normalized schema, the artifact, or the signed
+ * certificate, so it cannot affect scores or the two-layer evidence contract.
+ */
+type OperatorClass = "structural" | "operator" | "custom";
+/**
+ * Classify a mutator name into a severity class. Unknown names fall back to "operator":
+ * Stryker's remaining defaults (Arithmetic/Boolean/String/Unary/Update/Equality/Logical/
+ * Regex/Assignment) are all light operator/value flips, so "operator" is the safe default.
+ */
+declare function operatorClass(mutator: string): OperatorClass;
+/** Tally mutator names by severity class (deterministic key order). */
+declare function operatorClassBreakdown(mutators: string[]): Record<OperatorClass, number>;
+/**
+ * A short human phrase for a gap-severity breakdown, e.g. "2 structural, 1 operator".
+ * Omits zero classes; returns "none" for an all-zero breakdown. Order: structural first
+ * (the alarming ones lead), then custom, then operator.
+ */
+declare function operatorClassSummary(mutators: string[]): string;
+
+/**
+ * Shared Layer-1 gate overrides (Extension 5 — opted-in error-path enforcement).
+ *
+ * This runs identically in the CLI (which computes the gate from raw results) and in the API
+ * (which recomputes the gate server-side from submitted evidence), so both reach the same verdict.
+ *
+ * Rule: an opted-in error-path finding may turn a PASS into a FAIL, but must NEVER replace an
+ * existing `cannot-attest`. Insufficient evidence (cannot-attest) outranks a policy fail — a caller
+ * must not be able to convert "we could not attest" into a plain "fail" (or vice-versa) by toggling
+ * an error-path flag.
+ */
+
+interface Layer1GateInput {
+    /** the mutation gate already computed (pass | fail | cannot-attest) */
+    baseGate: GateResult;
+    /** opted-in: a changed handler with an untested (survived/no-coverage) mutant fails the gate */
+    failOnUntested: boolean;
+    /** opted-in: any detected handler anti-pattern fails the gate */
+    failOnAntiPattern: boolean;
+    /** count of untested changed-handler mutants (survived/no-coverage inside a changed handler) */
+    untestedHandlerMutantCount: number;
+    /**
+     * Number of detected handler anti-patterns (empty-catch / catch-all-abort / todo-in-handler).
+     * A COUNT, not the findings themselves, so both callers can satisfy this contract identically:
+     * the CLI holds the full findings locally, while the API only ever sees the sanitized aggregate
+     * (anti-pattern findings egress as counts by kind). The rule needs nothing more than the count.
+     */
+    antiPatternCount: number;
+}
+/**
+ * Apply the opted-in error-path gate overrides on top of the base mutation gate.
+ * `cannot-attest` is terminal and returned unchanged; otherwise, if an enabled rule matches, the
+ * gate becomes `fail` with an appended reason. When no rule matches, the base gate is returned
+ * verbatim (object identity preserved) so callers can detect "no override applied".
+ */
+declare function applyLayer1Gate(input: Layer1GateInput): GateResult;
+
+type TestVerdictKind = "asserts-nothing" | "duplicate-effectiveness";
+interface TestVerdict {
+    /** canonical `<file>::<fullName>` — the NAME stays local; egress carries only its digest */
+    test: string;
+    kind: TestVerdictKind;
+    coveredCount: number;
+    creditedKillCount: number;
+    /** stable digest of the duplicate group (duplicate-effectiveness only) */
+    duplicateGroupDigest?: string;
+}
+interface TestAnalysisInput {
+    /** post-quarantine mutants carrying canonical coveredByTests/killedByTests + final status */
+    mutants: readonly NormalizedMutant[];
+    /** canonical identities of tests the §4.9 baseline judged flaky */
+    flakyTests: ReadonlySet<string>;
+    /**
+     * Whether killer/coverage attribution was fully resolvable (the report carried a complete test
+     * dictionary and no ambiguous ids). When false, zero-credit covering tests are `unassessed`.
+     */
+    attributionComplete: boolean;
+}
+interface TestAnalysisResult {
+    verdicts: TestVerdict[];
+    /** covering tests that could not be assessed because attribution was incomplete */
+    unassessed: string[];
+    attribution: "complete" | "partial";
+}
+/**
+ * Analyze per-test effectiveness. Pure: same input → same output, sorted deterministically.
+ */
+declare function analyzeTestFindings(input: TestAnalysisInput): TestAnalysisResult;
+/** sha256 of a canonical test identity — the egress-safe reference (the name itself stays local). */
+declare function testIdentityDigest(canonical: string): string;
+
+/** Closed, policy-owned vocabulary for CI property obligations. */
+declare const CI_PROPERTY_FAMILIES: readonly ["round-trip", "idempotence", "order-preservation", "monotonicity", "normalization-equivalence", "partition-recombine", "serialization-preservation", "acceptance-boundary", "state-transition", "error-containment", "recovery-continuity", "non-mutation", "cache-coherence", "representation-boundary", "resource-lifecycle", "conservation"];
+type CiPropertyFamily = (typeof CI_PROPERTY_FAMILIES)[number];
+declare const CI_OBLIGATION_SIGNAL_AUTHORITIES: readonly ["explicit-contract", "mechanical-risk"];
+type CiObligationSignalAuthority = (typeof CI_OBLIGATION_SIGNAL_AUTHORITIES)[number];
+/**
+ * Deterministic source analysis may point the model at a risk, but never grants that risk source
+ * authority. A rule still has to cite behaviour-specific, pre-cutoff evidence.
+ */
+interface CiObligationSignal {
+    family: CiPropertyFamily;
+    trigger: string;
+    authority: CiObligationSignalAuthority;
+    path: string;
+    startLine: number;
+    endLine: number;
+    targetSymbols: string[];
+    searchTerms: string[];
+    strength: 1 | 2 | 3;
+    /**
+     * Which mutation operator survived, for a signal derived from a surviving mutant. The operator
+     * NAME is engine vocabulary; the mutated and original expressions are deliberately absent,
+     * because both are source text from the revision under review. Carrying them in prose — which
+     * this signal did until 2026-08-06 — handed the model the code it is supposed to be judging
+     * without ever appearing in a type.
+     */
+    mutator?: string;
+}
+
+/**
+ * Turn surviving mutants into obligation signals the intent stage can actually read.
+ *
+ * The intent prompt used to receive `openGapKinds` — a deduped list of kind strings such as
+ * `["classic"]` — while the ledger held, unhashed and in memory, the surviving mutant's operator,
+ * original text, replacement, and exact line. A surviving mutant is the one input in the whole
+ * system that is a PROVEN-undetected behaviour delta: the repository's own suite demonstrably
+ * cannot see it, so a property aimed at it cannot be vacuous about the suite the way a
+ * documentation-shaped property can. Reducing it to a kind string threw away precisely the part
+ * a rule could be aimed with.
+ *
+ * Authority is untouched by construction: these ride the existing `mechanical-risk` channel,
+ * whose prompt contract already states that risk signals direct WHERE to search and never
+ * establish expected behaviour — a rule still has to cite behaviour-specific, pre-cutoff
+ * evidence. Strength mirrors the operator-severity classes: a surviving structural or custom
+ * operator (a deleted block, a removed guard) outranks a surviving value flip.
+ */
+declare function survivingMutantObligationSignals(entries: readonly CiResidualGapEntry[]): CiObligationSignal[];
+declare function ciPropertyMutatorFamilies(mutantIdentity: string | undefined): readonly CiPropertyFamily[];
+interface CiPropertyTargetCandidate {
+    targetDigest: string;
+    path: string;
+    symbol: string;
+    changeKind: "addition" | "deletion" | "replacement";
+    runnerSupported: boolean;
+    hasIndependentEvidence: boolean;
+    publiclyReachable: boolean;
+    excludedChange: boolean;
+    generatedOrBinary: boolean;
+    requiresForbiddenExternalResource: boolean;
+    sourceConflict: boolean;
+    allKnownLayer1GapsClosed: boolean;
+    sourceIntroducesDifferentRule: boolean;
+    openLayer1Residuals: number;
+    mutationSiteAbsent: boolean;
+    changedBranchHasDirectTest: boolean;
+    supportedPropertyFamilies: number;
+    estimatedSetupCost: number;
+}
+interface CiPropertyTargetDecision {
+    target: CiPropertyTargetCandidate;
+    selected: boolean;
+    reasons: string[];
+}
+interface CiPropertyTargetPlan {
+    selected: CiPropertyTargetCandidate[];
+    decisions: CiPropertyTargetDecision[];
+}
+/**
+ * Union Layer 1 and independently sourced targets before applying the fixed CI budget. A source
+ * target may refine an existing Layer 1 target, but neither target family can erase the other.
+ */
+declare function buildCiPropertyTargetUniverse(input: {
+    layer1Targets: readonly CiPropertyTargetCandidate[];
+    sourceTargets: readonly CiPropertyTargetCandidate[];
+}): CiPropertyTargetCandidate[];
+/** Deterministic, bounded selector. It receives no fault label or model score. */
+declare function selectCiPropertyTargets(input: readonly CiPropertyTargetCandidate[], maxTargets?: number): CiPropertyTargetPlan;
+interface CiPropertyRuleCandidate {
+    intentDigest: string;
+    authority: CiPropertyAuthority;
+    targetDigest: string;
+    propertyFamily: string;
+    operationSequence: string[];
+    observation: {
+        kind: string;
+        subject: string;
+        expected: string;
+    };
+    inputDomainKinds: string[];
+    sourceSetDigest: string;
+    openLayer1Match: "exact" | "indirect" | "none";
+    templateSupported: boolean;
+    setupDependencyCount: number;
+    /** Behaviour-specific frozen evidence, not merely target-level evidence. */
+    evidenceSpecificity: 0 | 1 | 2 | 3;
+    /** Strength of a deterministic generic risk trigger matching this family. */
+    riskTriggerStrength: 0 | 1 | 2 | 3;
+    /** Confidence that schemas, types, examples, or fixtures constrain generated inputs. */
+    inputValidityConfidence: 0 | 1 | 2 | 3;
+    /** Order supplied by the model before deterministic policy ranking. */
+    modelPriority: number;
+}
+interface RankedCiPropertyRule extends CiPropertyRuleCandidate {
+    behaviourKey: string;
+}
+interface CiPropertyRuleDrop {
+    intentDigest: string;
+    reason: "duplicate-intent" | "duplicate-behaviour" | "closed-classicMutation" | "pool-cap";
+}
+declare function ciPropertyBehaviourKey(rule: Pick<CiPropertyRuleCandidate, "targetDigest" | "propertyFamily" | "operationSequence" | "observation" | "inputDomainKinds" | "sourceSetDigest">): string;
+declare function rankCiPropertyRules(input: readonly CiPropertyRuleCandidate[], options?: {
+    closedBehaviourKeys?: ReadonlySet<string>;
+    poolSize?: number;
+}): {
+    ranked: RankedCiPropertyRule[];
+    dropped: CiPropertyRuleDrop[];
+};
+
+/**
+ * Environment boundary between Abloh's control plane and untrusted repository code.
+ *
+ * Customer tests receive only the small portable runtime base plus variables explicitly named in
+ * committed policy. Engine credentials are reserved and can never be re-admitted by policy.
+ */
+declare function isReservedCustomerVariable(name: string): boolean;
+declare function customerEnvironmentNames(required: readonly string[]): string[];
+declare function buildCustomerProcessEnvironment(source?: NodeJS.ProcessEnv, required?: readonly string[], overrides?: Readonly<Record<string, string>>): Record<string, string>;
+declare function containsEngineCredential(environment: Readonly<Record<string, string | undefined>>): boolean;
+
+export { type AssayResult, type AssayVerdict, type AttestPolicy, type AttestResultsV2, type AttributionQuality, type BuildCiPropertyBlockInput, type BuildScenarioSearchBlockInput, CI_OBLIGATION_SIGNAL_AUTHORITIES, CI_PROPERTY_AUTHORITIES, CI_PROPERTY_CAPS, CI_PROPERTY_FAMILIES, CI_PROPERTY_OUTCOMES, CI_PROPERTY_STATES, CI_RESIDUAL_STATES, CLUSTER_STRATEGIES, type CellObservation, type ChangedStructuralCounts, type CiChangedRange, type CiObligationSignal, type CiObligationSignalAuthority, type CiPropertyAuthority, type CiPropertyCandidateCap, type CiPropertyCounts, type CiPropertyFamily, type CiPropertyMeasuredBlock, type CiPropertyOutcome, type CiPropertyRuleCandidate, type CiPropertyRuleDrop, type CiPropertySearchBlock, type CiPropertySearchPolicy, type CiPropertyState, type CiPropertySummary, type CiPropertyTargetCandidate, type CiPropertyTargetDecision, type CiPropertyTargetPlan, type CiResidualGapEntry, type CiResidualGapLedger, type CiResidualState, type ClassicMutationPolicy, type ClassicMutationTier, type ClassicSamplingBlock, type ClusterStrategy, type CombinedGate, type ConditionalPowerResult, type Counts, type CoverageProvider, DEFAULT_CLASSIC_MUTATION, DEFAULT_DIFF_COVERAGE, DEFAULT_ENVIRONMENT, DEFAULT_ENVIRONMENT_IMAGE_DIGEST, DEFAULT_ENVIRONMENT_IMAGE_REF, DEFAULT_FINDINGS, DEFAULT_FLOOR, DEFAULT_MECHANISMS, DEFAULT_MUTATION, DEFAULT_POLICY, DEFAULT_SANDBOX, DIFF_COVERAGE_THRESHOLD, type DecisiveLayer, type DetectionCell, type DeterministicMutantsBlock, type DeterministicMutantsPolicy, type DiffCoverageCounts, type DiffCoverageLine, type DiffCoverageLineState, type DiffCoverageNotApplicableReason, type DiffCoverageNotRunReason, type DiffCoveragePolicy, type DiffCoverageResult, DiffScopeError, EXCLUDE_RE, EXPECTED_ORACLE_CELL, type EnvironmentPolicy, type ErrorHandlersBlock, type ErrorPathsPolicy, type EvidenceFloor, type EvidenceProfile, type ExecutionAxis, type ExperimentManifest, FINDING_SEVERITIES, type FeatureState, type FileScope, type FileStructural, type FindingSeverity, type FindingsPolicy, type FixLoopBlock, type FixLoopPolicy, type FixProofSummary, type FixProofVerdict, type FlakyPolicy, type FloorPolicy, type GapFinding, type GapKeyInput, type GateResult, type GateStatus, HANDOFF_EVIDENCE_KEYS_V1, HANDOFF_EVIDENCE_KEYS_V2, HANDOFF_TARGET_KEYS, type HandlerAntiPatternKind, type HandlerFinding, type HeadroomResult, type HeadroomVerdict, type HistoricalPair, LAYER0_EXECUTION, LAYER0_SCOPE_DISCLOSURE, LAYER1_EXECUTION, type Layer1GateInput, type LineGroup, MAX_EXPANDED_LINES, MAX_FINDING_DESCRIPTION_LEN, MAX_LITERAL_ARGUMENTS, MAX_LITERAL_COMMAND_BYTES, MAX_MUTANT_ROSTER, MAX_SCOPE_RANGES, MECHANICAL_ERROR_PATH_REASON, MIN_CELL_REPEATS, MUTANT_STATUSES, MUTATION_SCOPE_SURFACE, type ManifestModel, type ManifestValidation, type ModelChoicePolicy, type ModelsPolicy, type MutantRosterEntry, type MutantStatus, type MutationExecution, type MutationMode, type MutationNotRunReason, type MutationPolicy, type MutationScopeKind, type MutationSkipReason, type NormalizedCoverage, type NormalizedMutant, type OperatorClass, type OracleObservation, PROVIDER_RAW_FORMAT, PYTHON_EXCLUDE_RE, PYTHON_SOURCE_RE, type PackageEvidence, type PairIsolation, type PatchRevertPolicy, type PerTestBlock, type PerTestFinding, type PerTestFindingKind, type PerTestPolicy, type ProposedMutant, type QualificationResult, type QualificationVerdict, type QualifiedOmission, REALISTIC_CATEGORIES, RUNNER_CAPABILITIES, type RankedCiPropertyRule, type RawCoverageFormat, type RawCoverageFormatName, type RealisticCategory, type ResearchPolicy, type ResearchTier, type RunnerCapability, type RunnerEcosystem, SCENARIO_AUTHORITIES, SCENARIO_LANES, SCENARIO_OUTCOMES, SCENARIO_SEARCH_STATES, SCENARIO_SOURCE_INDEPENDENCE, SCENARIO_SOURCE_KINDS, SOURCE_RE, type SandboxPolicy, type ScenarioAuthority, type ScenarioExpectedObservation, type ScenarioInputDomain, type ScenarioIntent, type ScenarioIntentDraft, type ScenarioLane, type ScenarioOperationStep, type ScenarioOutcome, type ScenarioSearchBlock, type ScenarioSearchCounts, type ScenarioSearchMeasuredBlock, type ScenarioSearchPolicy, type ScenarioSearchProvenance, type ScenarioSearchRestrictions, type ScenarioSearchState, type ScenarioSourceIndependence, type ScenarioSourceKind, type ScenarioSourceRef, type ScenarioSummary, type ScopeOptions, type ScopeResult, type ScoreInput, type Scores, type StageBInputs, type StageBReadiness, type StructuralCoverage, type StructuralSite, type SuiteOutcome, TARGET_ARTIFACT_KEYS, TARGET_SELECTION_KINDS, TRIAGE_REASON_CODES, type TargetSelectionKind, type TestAnalysisInput, type TestAnalysisResult, type TestVerdict, type TestVerdictKind, type TriageReasonCode, type TriageRecord, type TriageVerdict, type WorstOfOutcome, type WorstOfRow, analyzeTestFindings, applyLayer1Gate, assertNever, buildCiPropertySearchBlock, buildCiPropertyTargetUniverse, buildCustomerProcessEnvironment, buildScenarioSearchBlock, canStartStageB, capability, changedStructuralCoverage, ciPropertyBehaviourKey, ciPropertyLedgerDigest, ciPropertyMutatorFamilies, classicHeadroom, classicMutationExecution, classicMutationTier, classifyDiffCoverage, combineLayerGates, computeScope, computeScores, conditionalPower, containsEngineCredential, countsFromLines, coveredLinesToScope, customerEnvironmentNames, denominatorOf, deriveScenarioSearchCounts, deriveWorstOfGate, describeFinding, describeMutationEvidence, describeReasonCode, diffCoverageExecution, emptyCounts, errorCountOf, evaluateAssay, evaluateDiffCoverageGate, evaluateFloor, evaluateGate, expandScopeLines, findingKind, findingSeverity, gapKeys, groupFindingsByLine, isCanonicalBase64, isCiPropertyCandidateCap, isClusterStrategy, isConfirmedEquivalent, isNonExecutableLine, isReservedCustomerVariable, isScenarioAuthority, isScenarioLane, isScenarioOutcome, isScenarioSearchState, jsRunners, knownRunner, layer0EnabledRunners, loadPolicy, markNonExecutable, mechanicalErrorPathDisposition, missingScopedFiles, mutantIdentity, operatorClass, operatorClassBreakdown, operatorClassSummary, parseLiteralArguments, parsePreparedTestCommand, parseUnifiedDiff, qualifyCorpus, qualifyHistoricalPair, rankCiPropertyRules, recognizedProvidersFor, redactTriageForEgress, researchTier, sanitizeCiPropertySummary, sanitizeFindingDescription, sanitizeScenarioSummary, selectCiPropertyTargets, stableOutcome, strykerPluginRunners, survivingMutantObligationSignals, tallyCounts, testIdentityDigest, toGapFindings, uncoveredCount, validateCiResidualGapLedger, validateDiffCoverageLines, validateManifest, validatePolicy, validatePreparedTestCommand, wilsonInterval };