audit-tools 0.50.21 → 0.51.1

package/dist/shared/reporting/lensCoverage.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The ONE derivation of `lens_coverage` — what each lens the operator selected
+ * actually delivered.
+ *
+ * Single-sourced because FOUR places need the same answer and a hand copy in any
+ * of them would be a map that contradicts the findings beside it: the synthesis
+ * boundary that mints it, the re-normalizer that carries it through a
+ * re-synthesis, the approved-subset projection that must re-derive it over the
+ * surviving findings, and the validator that refuses a map its own inputs do not
+ * derive. The validator is a CONSUMER of this function, so "what the report
+ * claims" and "what the gate checks" cannot drift.
+ */
+import type { Finding } from "../types/finding.js";
+import type { LensCoverageEntry } from "../types/finding.js";
+import type { MeasuredOutcome } from "../measurement/measuredOutcome.js";
+/**
+ * What one lens's count means, given whether ANY lens-open channel was ingested.
+ *
+ * `clean` is the load-bearing distinction: it may be read as "asked, and there
+ * was nothing there", so it is reachable only when a channel that carried the
+ * operator's selection actually came back. With no such channel, zero findings
+ * means the lens was never exercised — `not_run` — which is true, and is the
+ * whole point of the field.
+ */
+export declare function lensOutcome(findingsCount: number, lensOpenChannelIngested: boolean): MeasuredOutcome;
+/**
+ * Whether ONE entry's outcome contradicts its own count — the check a consumer
+ * holding the map but not the run that produced it can actually establish.
+ *
+ * It deliberately does NOT re-decide `clean` versus `not_run`. Which of the two
+ * a zero-count lens deserves depends on whether a lens-open channel was
+ * ingested, and that is not in the report — so a validator that picked one would
+ * refuse legitimate output rather than catch a defect. Abstaining there is the
+ * verdict; what it refuses is the contradiction: a lens with findings that is
+ * not `findings`, or a lens with none that is.
+ */
+export declare function lensCoverageEntryContradictsCount(entry: Pick<LensCoverageEntry, "findings_count" | "outcome">): boolean;
+/**
+ * Derive the coverage map for a resolved selection.
+ *
+ * Order is `selectedLenses`' own — `resolveIntentLensSelection` emits canonical
+ * registry order then the operator's custom lenses in input order, which is
+ * content-derived and stable. A lens that produced findings while NOT being
+ * selected is appended after them, sorted, so the map never silently omits a
+ * lens the report counts.
+ */
+export declare function deriveLensCoverage(params: {
+    readonly selectedLenses: readonly string[];
+    readonly findings: readonly Finding[];
+    readonly lensOpenChannelIngested: boolean;
+}): LensCoverageEntry[];
+/**
+ * Re-derive an EXISTING map's counts and outcomes over a (possibly narrowed)
+ * finding set, preserving each entry's membership and `selected` flag.
+ *
+ * Used wherever the findings change but the SELECTION cannot be recovered: a
+ * re-synthesis of a promoted report, and the approved-subset projection. Copying
+ * the map through unchanged there would leave it contradicting a re-derived
+ * `lens_breakdown`, and the projection validates itself at the write boundary —
+ * so a subset that drops every finding of one lens would throw at the remediate
+ * intake that requests it.
+ *
+ * Whether a lens was EXERCISED is read PER ENTRY, from the outcome the parent
+ * map already recorded — an entry that was `findings` or `clean` was exercised,
+ * and filtering findings out of a subset cannot un-exercise it. Re-deciding it
+ * globally would turn a lens whose only finding the subset dropped into
+ * `not_run`, which claims the run never looked.
+ */
+export declare function reprojectLensCoverage(coverage: readonly LensCoverageEntry[], findings: readonly Finding[]): LensCoverageEntry[];
+//# sourceMappingURL=lensCoverage.d.ts.map

package/dist/shared/reporting/lensCoverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lensCoverage.d.ts","sourceRoot":"","sources":["../../../src/shared/reporting/lensCoverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAezE;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,aAAa,EAAE,MAAM,EACrB,uBAAuB,EAAE,OAAO,GAC/B,eAAe,CAGjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,GAAG,SAAS,CAAC,GAC3D,OAAO,CAIT;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;CAC3C,GAAG,iBAAiB,EAAE,CA2BtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,iBAAiB,EAAE,CAUrB"}

package/dist/shared/reporting/lensCoverage.js

@@ -0,0 +1,108 @@
+import { compareCodeUnits } from "../compareCodeUnits.js";
+/**
+ * Count findings per lens. The same `countBy` shape `lens_breakdown` uses, kept
+ * here so the coverage map and the breakdown can never be counted differently.
+ */
+function countByLens(findings) {
+    const counts = new Map();
+    for (const finding of findings) {
+        counts.set(finding.lens, (counts.get(finding.lens) ?? 0) + 1);
+    }
+    return counts;
+}
+/**
+ * What one lens's count means, given whether ANY lens-open channel was ingested.
+ *
+ * `clean` is the load-bearing distinction: it may be read as "asked, and there
+ * was nothing there", so it is reachable only when a channel that carried the
+ * operator's selection actually came back. With no such channel, zero findings
+ * means the lens was never exercised — `not_run` — which is true, and is the
+ * whole point of the field.
+ */
+export function lensOutcome(findingsCount, lensOpenChannelIngested) {
+    if (findingsCount > 0)
+        return "findings";
+    return lensOpenChannelIngested ? "clean" : "not_run";
+}
+/**
+ * Whether ONE entry's outcome contradicts its own count — the check a consumer
+ * holding the map but not the run that produced it can actually establish.
+ *
+ * It deliberately does NOT re-decide `clean` versus `not_run`. Which of the two
+ * a zero-count lens deserves depends on whether a lens-open channel was
+ * ingested, and that is not in the report — so a validator that picked one would
+ * refuse legitimate output rather than catch a defect. Abstaining there is the
+ * verdict; what it refuses is the contradiction: a lens with findings that is
+ * not `findings`, or a lens with none that is.
+ */
+export function lensCoverageEntryContradictsCount(entry) {
+    return entry.findings_count > 0
+        ? entry.outcome !== "findings"
+        : entry.outcome === "findings";
+}
+/**
+ * Derive the coverage map for a resolved selection.
+ *
+ * Order is `selectedLenses`' own — `resolveIntentLensSelection` emits canonical
+ * registry order then the operator's custom lenses in input order, which is
+ * content-derived and stable. A lens that produced findings while NOT being
+ * selected is appended after them, sorted, so the map never silently omits a
+ * lens the report counts.
+ */
+export function deriveLensCoverage(params) {
+    const counts = countByLens(params.findings);
+    const selected = new Set(params.selectedLenses);
+    const entries = params.selectedLenses.map((lens) => {
+        const findingsCount = counts.get(lens) ?? 0;
+        return {
+            lens,
+            selected: true,
+            findings_count: findingsCount,
+            outcome: lensOutcome(findingsCount, params.lensOpenChannelIngested),
+        };
+    });
+    const unselected = [...counts.keys()]
+        .filter((lens) => !selected.has(lens))
+        .sort(compareCodeUnits);
+    for (const lens of unselected) {
+        const findingsCount = counts.get(lens);
+        entries.push({
+            lens,
+            selected: false,
+            findings_count: findingsCount,
+            // A lens nobody selected that nonetheless produced findings is
+            // `findings`; it cannot be `clean`, because nothing asked for it.
+            outcome: findingsCount > 0 ? "findings" : "not_run",
+        });
+    }
+    return entries;
+}
+/**
+ * Re-derive an EXISTING map's counts and outcomes over a (possibly narrowed)
+ * finding set, preserving each entry's membership and `selected` flag.
+ *
+ * Used wherever the findings change but the SELECTION cannot be recovered: a
+ * re-synthesis of a promoted report, and the approved-subset projection. Copying
+ * the map through unchanged there would leave it contradicting a re-derived
+ * `lens_breakdown`, and the projection validates itself at the write boundary —
+ * so a subset that drops every finding of one lens would throw at the remediate
+ * intake that requests it.
+ *
+ * Whether a lens was EXERCISED is read PER ENTRY, from the outcome the parent
+ * map already recorded — an entry that was `findings` or `clean` was exercised,
+ * and filtering findings out of a subset cannot un-exercise it. Re-deciding it
+ * globally would turn a lens whose only finding the subset dropped into
+ * `not_run`, which claims the run never looked.
+ */
+export function reprojectLensCoverage(coverage, findings) {
+    const counts = countByLens(findings);
+    return coverage.map((entry) => {
+        const findingsCount = counts.get(entry.lens) ?? 0;
+        return {
+            ...entry,
+            findings_count: findingsCount,
+            outcome: lensOutcome(findingsCount, entry.outcome !== "not_run"),
+        };
+    });
+}
+//# sourceMappingURL=lensCoverage.js.map

package/dist/shared/reporting/lensCoverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lensCoverage.js","sourceRoot":"","sources":["../../../src/shared/reporting/lensCoverage.ts"],"names":[],"mappings":"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"}

package/dist/shared/submission/hostResultOutcomes.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared recording and trailing-state diagnostics for host-result ingestion.
+ *
+ * The audit and remediation draws classify different domain failures, but the
+ * host boundary has one durable story: a submission was refused, or a prior
+ * refusal was subsequently accepted. This module owns that story and keeps
+ * the ledger reader separate from each draw's message renderer.
+ */
+import { type SubmissionLedgerEvent } from "./submissionLedger.js";
+import type { SubmissionIssue } from "./submissionClassifier.js";
+/** The accepted/rejected pair supplied by either host-result boundary. */
+export interface HostResultOutcomes<TIssueCode extends string = string> {
+    readonly issues: readonly SubmissionIssue<TIssueCode>[];
+    readonly acceptedIds: readonly string[];
+}
+/** A refusal whose ingest state has not subsequently been cleared. */
+export type TrailingSubmissionRefusal = SubmissionLedgerEvent<string>;
+/**
+ * Read trailing refusals once for a batch. Non-ingest rows (`expected`,
+ * `dispatched`, and `lane_outcome`) do not alter the answer; an acceptance,
+ * recovery, or operator withdrawal clears a prior rejection.
+ */
+export declare function readTrailingSubmissionRefusals(artifactsDir: string, submissionIds?: readonly string[], options?: {
+    readonly runId?: string;
+}): Promise<ReadonlyMap<string, TrailingSubmissionRefusal>>;
+/**
+ * Add the prior substantive refusal to a currently missing issue.
+ *
+ * Historic codes stay in the message as evidence. The caller supplies the
+ * current draw's shared `submission_rejected` replacement code, so an
+ * untrusted ledger value is never asserted into a draw-specific enum.
+ */
+export declare function enrichMissingSubmissionIssues<TIssueCode extends string>(issues: readonly SubmissionIssue<TIssueCode>[], refusals: ReadonlyMap<string, TrailingSubmissionRefusal>, replacementCode: TIssueCode): SubmissionIssue<TIssueCode>[];
+/**
+ * Record raw host-ingest outcomes. The caller must pass the un-enriched issue
+ * list so a missing poll that carries an old diagnostic cannot recursively
+ * rewrite that diagnostic into the ledger. History is read once per batch.
+ */
+export declare function recordHostResultOutcomes<TIssueCode extends string = string>(artifactsDir: string, runId: string, outcomes: HostResultOutcomes<TIssueCode>, options?: {
+    readonly scopeToRunId?: string;
+}): Promise<void>;
+//# sourceMappingURL=hostResultOutcomes.d.ts.map

package/dist/shared/submission/hostResultOutcomes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostResultOutcomes.d.ts","sourceRoot":"","sources":["../../../src/shared/submission/hostResultOutcomes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB,CAAC,UAAU,SAAS,MAAM,GAAG,MAAM;IACpE,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,CAAC,UAAU,CAAC,EAAE,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,sEAAsE;AACtE,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;GAIG;AACH,wBAAsB,8BAA8B,CAClD,YAAY,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,EACjC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACpC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAkBzD;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,SAAS,MAAM,EACrE,MAAM,EAAE,SAAS,eAAe,CAAC,UAAU,CAAC,EAAE,EAC9C,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACxD,eAAe,EAAE,UAAU,GAC1B,eAAe,CAAC,UAAU,CAAC,EAAE,CAgB/B;AAUD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,UAAU,SAAS,MAAM,GAAG,MAAM,EAC/E,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,kBAAkB,CAAC,UAAU,CAAC,EACxC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,IAAI,CAAC,CAiEf"}

package/dist/shared/submission/hostResultOutcomes.js

@@ -0,0 +1,129 @@
+/**
+ * Shared recording and trailing-state diagnostics for host-result ingestion.
+ *
+ * The audit and remediation draws classify different domain failures, but the
+ * host boundary has one durable story: a submission was refused, or a prior
+ * refusal was subsequently accepted. This module owns that story and keeps
+ * the ledger reader separate from each draw's message renderer.
+ */
+import { appendSubmissionEvent, isIngestEvent, readSubmissionLedger, SUBMISSION_LEDGER_EVENT_CONTRACT_VERSION, } from "./submissionLedger.js";
+/**
+ * Read trailing refusals once for a batch. Non-ingest rows (`expected`,
+ * `dispatched`, and `lane_outcome`) do not alter the answer; an acceptance,
+ * recovery, or operator withdrawal clears a prior rejection.
+ */
+export async function readTrailingSubmissionRefusals(artifactsDir, submissionIds, options) {
+    const wanted = submissionIds === undefined ? undefined : new Set(submissionIds);
+    const last = new Map();
+    for (const event of await readSubmissionLedger(artifactsDir)) {
+        if (wanted !== undefined && !wanted.has(event.submission_id))
+            continue;
+        if (options?.runId !== undefined && event.run_id !== options.runId)
+            continue;
+        if (!isIngestEvent(event.kind))
+            continue;
+        if (event.kind === "rejected") {
+            // A repeated missing observation is not substantive history and must
+            // never erase a prior malformed/contract/domain refusal.
+            if (event.issue_code !== "submission_missing") {
+                last.set(event.submission_id, event);
+            }
+        }
+        else {
+            last.delete(event.submission_id);
+        }
+    }
+    return last;
+}
+/**
+ * Add the prior substantive refusal to a currently missing issue.
+ *
+ * Historic codes stay in the message as evidence. The caller supplies the
+ * current draw's shared `submission_rejected` replacement code, so an
+ * untrusted ledger value is never asserted into a draw-specific enum.
+ */
+export function enrichMissingSubmissionIssues(issues, refusals, replacementCode) {
+    return issues.map((issue) => {
+        if (issue.code !== "submission_missing")
+            return issue;
+        const submissionId = issue.work_item_id ?? issue.submission_id;
+        if (submissionId === undefined)
+            return issue;
+        const refusal = refusals.get(submissionId);
+        if (refusal === undefined)
+            return issue;
+        return {
+            ...issue,
+            message: `${issue.message}; the previous submission was refused` +
+                ` (${refusal.issue_code ?? "unknown"})` +
+                `${refusal.message ? `: ${refusal.message}` : ""}`,
+            code: replacementCode,
+        };
+    });
+}
+function eventSignature(kind, issueCode, message) {
+    return [kind, issueCode ?? "", message ?? ""].join("|");
+}
+/**
+ * Record raw host-ingest outcomes. The caller must pass the un-enriched issue
+ * list so a missing poll that carries an old diagnostic cannot recursively
+ * rewrite that diagnostic into the ledger. History is read once per batch.
+ */
+export async function recordHostResultOutcomes(artifactsDir, runId, outcomes, options) {
+    if (outcomes.issues.length === 0 && outcomes.acceptedIds.length === 0)
+        return;
+    const last = new Map();
+    for (const event of await readSubmissionLedger(artifactsDir)) {
+        if (options?.scopeToRunId !== undefined &&
+            event.run_id !== options.scopeToRunId) {
+            continue;
+        }
+        if (isIngestEvent(event.kind))
+            last.set(event.submission_id, event);
+    }
+    const append = async (submissionId, event) => {
+        const previous = last.get(submissionId);
+        if (previous !== undefined &&
+            eventSignature(previous.kind, previous.issue_code, previous.message) ===
+                eventSignature(event.kind, event.issue_code, event.message)) {
+            return;
+        }
+        const recorded = {
+            contract_version: SUBMISSION_LEDGER_EVENT_CONTRACT_VERSION,
+            run_id: runId,
+            submission_id: submissionId,
+            lane: submissionId,
+            ...event,
+            recorded_at: new Date().toISOString(),
+        };
+        await appendSubmissionEvent(artifactsDir, recorded);
+        last.set(submissionId, recorded);
+    };
+    for (const submissionId of outcomes.acceptedIds) {
+        // A first-try acceptance has no drift to record. Rejection and withdrawal
+        // need a new acceptance; an existing recovery must never be relabelled clean.
+        const priorKind = last.get(submissionId)?.kind;
+        if (priorKind !== "rejected" && priorKind !== "removed_by_operator")
+            continue;
+        await append(submissionId, { kind: "accepted" });
+    }
+    for (const issue of outcomes.issues) {
+        const submissionId = issue.work_item_id ?? issue.submission_id;
+        if (submissionId === undefined)
+            continue;
+        const prior = last.get(submissionId);
+        // Missing is an observation, not a new substantive refusal. Preserve the
+        // prior reason while the host has not yet rewritten the bound file.
+        if (issue.code === "submission_missing" &&
+            prior?.kind === "rejected" &&
+            prior.issue_code !== "submission_missing") {
+            continue;
+        }
+        await append(submissionId, {
+            kind: "rejected",
+            issue_code: issue.code,
+            message: issue.message,
+        });
+    }
+}
+//# sourceMappingURL=hostResultOutcomes.js.map

package/dist/shared/submission/hostResultOutcomes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostResultOutcomes.js","sourceRoot":"","sources":["../../../src/shared/submission/hostResultOutcomes.ts"],"names":[],"mappings":"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"}

package/dist/shared/submission/ingestionChecks.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The ONE declared list of checks result ingestion performs before it accepts a
+ * host result — the source `docs/audit-pkg/contracts.md`'s check block is
+ * RENDERED from (`scripts/shared/generate-ingestion-checks.mjs`).
+ *
+ * WHY THIS EXISTS. The check set used to be written out by hand in three docs
+ * (the contracts page, the operator guide, the concurrent-runs design), and the
+ * three lists disagreed: only one named the result path, only one the strict
+ * result schema, only one the workload version. Nothing reconciled them, so
+ * whoever added a check added it to whichever doc they had open. Owner decision
+ * 2026-09-05 (nightly item l1-4): derive the list from the validator itself.
+ *
+ * The registry is LOAD-BEARING, not a fourth prose copy: every refusal a draw's
+ * ingestion emits cites one of these ids (`refuse(check, detail)`,
+ * `invalidResult(check, reason)`, a `check:` on an issue), the id type below
+ * refuses an unregistered citation at compile time, and
+ * `tests/shared/ingestion-checks-drift.test.ts` extracts the citations
+ * structurally and pins them against the declared `draws` in both directions —
+ * a row nothing cites is dead, and a citation nothing declares is an
+ * undocumented check.
+ *
+ * `cited_by` says WHERE the citation lives. The shared submission scan
+ * (`submissionScan.ts`) owns the path, read and duplicate checks for both
+ * draws; everything else is cited from the draw's own host-handoff module. Row
+ * order is the render order: envelope and binding first, then per-draw content
+ * checks, then corroboration, then the ledger.
+ *
+ * Keep every field a plain literal: the generator reads this file as TEXT
+ * through the TypeScript compiler API (no build, no import), and refuses a
+ * value it cannot read rather than rendering without it.
+ */
+export declare const INGESTION_DRAWS: readonly [{
+    readonly id: "audit";
+    readonly source: "src/audit/cli/dispatch/hostHandoff.ts";
+}, {
+    readonly id: "remediate";
+    readonly source: "src/remediate/steps/dispatch/hostHandoff.ts";
+}];
+export type IngestionDraw = (typeof INGESTION_DRAWS)[number]["id"];
+/** Where the shared-cited checks live. */
+export declare const INGESTION_SHARED_SOURCE = "src/shared/submission/submissionScan.ts";
+export interface IngestionCheck {
+    readonly id: string;
+    /** One sentence, host-facing: what must hold for the result to be accepted. */
+    readonly verifies: string;
+    readonly draws: readonly IngestionDraw[];
+    /** `shared`: cited from the shared scan; `draw`: cited from each listed draw's module. */
+    readonly cited_by: "shared" | "draw";
+}
+export declare const INGESTION_CHECKS: readonly [{
+    readonly id: "result_path";
+    readonly verifies: "The submission is read only from the tool-derived bound path (`<run dir>/<sha256(work item id)>.json`) inside the run's artifacts directory; a result written anywhere else is never consulted.";
+    readonly draws: readonly ["audit", "remediate"];
+    readonly cited_by: "shared";
+}, {
+    readonly id: "result_json";
+    readonly verifies: "The bytes at the bound path parse as JSON.";
+    readonly draws: readonly ["audit", "remediate"];
+    readonly cited_by: "shared";
+}, {
+    readonly id: "result_envelope";
+    readonly verifies: "The top-level key set is exactly the draw's result contract and `contract_version` is the version the workload was issued under.";
+    readonly draws: readonly ["audit", "remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "identity_binding";
+    readonly verifies: "`run_id` is the run that emitted the workload, `work_item_id` is the work item the result was read for, and `prompt_sha256` is the digest of the prompt that work item was issued with — an answer to another run, item or a stale prompt is refused.";
+    readonly draws: readonly ["audit", "remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "workload_binding";
+    readonly verifies: "The persisted workload, result map and task bindings still derive from this run (versions, bound paths, prompt digests, scopes); a result cannot be accepted against a binding the tool cannot re-derive.";
+    readonly draws: readonly ["audit", "remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "file_coverage";
+    readonly verifies: "`file_coverage` names exactly the assigned files, each fully reviewed, with `total_lines` equal to the line count bound at dispatch.";
+    readonly draws: readonly ["audit"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "findings_contract";
+    readonly verifies: "Every finding satisfies the audit finding contract (lens, ids, evidence shape).";
+    readonly draws: readonly ["audit"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "result_schema";
+    readonly verifies: "The bound result converts to the persisted `AuditResult` schema (`schemas/audit_result.schema.json`).";
+    readonly draws: readonly ["audit"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "result_validation";
+    readonly verifies: "The per-result content rules hold before acceptance (evidence present, line spans inside the file, line counts matching disk); warnings ride an advisory channel and never refuse.";
+    readonly draws: readonly ["audit"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "outcome_shape";
+    readonly verifies: "A decision result's `outcome` carries exactly the fields its status requires (`resolved_no_change` evidence, `blocked` failure reason, `needs_clarification` question).";
+    readonly draws: readonly ["remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "write_scope";
+    readonly verifies: "`changed_files` is non-empty, sorted, unique and normalized, lies within the prompt-bound `allowed_files`, and equals the files the landed commit actually changed.";
+    readonly draws: readonly ["remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "commit_evidence";
+    readonly verifies: "`commit_evidence` binds the workload baseline to a distinct landed commit; both exist, the baseline is an ancestor of the landed commit (waived only under a genuinely orphaned baseline in recovery), and the landed commit is reachable from HEAD.";
+    readonly draws: readonly ["remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "test_evidence";
+    readonly verifies: "`test_evidence` carries exactly one passed entry per required test echoing the bound command, and the tool's own mechanical rerun of those tests passes.";
+    readonly draws: readonly ["remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "obligation_evidence";
+    readonly verifies: "`obligation_evidence` cites non-empty evidence for every prompt-bound obligation, none twice, and none the work item does not bind.";
+    readonly draws: readonly ["remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "worktree_evidence";
+    readonly verifies: "`worktree_evidence` binds the workload baseline and the same changed-file list, and no landed file overlaps dirt that pre-dated the run.";
+    readonly draws: readonly ["remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "landing_attestation";
+    readonly verifies: "`acceptance` and `merge` both attest a completed landing.";
+    readonly draws: readonly ["remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "no_change_corroboration";
+    readonly verifies: "A `resolved_no_change` claim is corroborated against git and the persisted write-scope binding; attestation-only acceptance is refused.";
+    readonly draws: readonly ["remediate"];
+    readonly cited_by: "draw";
+}, {
+    readonly id: "duplicate_result";
+    readonly verifies: "`result_id` has not already been accepted this run: a byte-identical replay is a no-op, a different body under an accepted id is refused.";
+    readonly draws: readonly ["audit", "remediate"];
+    readonly cited_by: "shared";
+}];
+export type IngestionCheckId = (typeof INGESTION_CHECKS)[number]["id"];
+/** The ids a draw declares, in registry order — draw-cited and shared-cited alike. */
+export declare function ingestionCheckIdsFor(draw: IngestionDraw): readonly IngestionCheckId[];
+/** The ids whose citation lives in the given place, in registry order. */
+export declare function ingestionCheckIdsCitedBy(citedBy: IngestionCheck["cited_by"], draw?: IngestionDraw): readonly IngestionCheckId[];
+//# sourceMappingURL=ingestionChecks.d.ts.map

package/dist/shared/submission/ingestionChecks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingestionChecks.d.ts","sourceRoot":"","sources":["../../../src/shared/submission/ingestionChecks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,eAAO,MAAM,eAAe;;;;;;EAGlB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAEnE,0CAA0C;AAC1C,eAAO,MAAM,uBAAuB,4CAA4C,CAAC;AAEjF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;CACtC;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4HiB,CAAC;AAE/C,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAEvE,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,gBAAgB,EAAE,CAIrF;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,cAAc,CAAC,UAAU,CAAC,EACnC,IAAI,CAAC,EAAE,aAAa,GACnB,SAAS,gBAAgB,EAAE,CAM7B"}