@fro.bot/systematic 3.18.3 → 3.18.4

package/dist/lib/review-pipeline.d.ts

@@ -0,0 +1,812 @@
+import type { z } from 'zod';
+import type { HarnessSchema } from './review-artifact-schema.js';
+import { type AdjudicationEnvelopeSchema, type FinalizeInputSchema, FinalizeOutputSchema, MergeOutputSchema, type PipelineRoute, type PlanAssessmentEnvelopeSchema, PrepareOutputSchema, ScreenOutputSchema, type ValidatorLifecycleResultsSchema } from './review-pipeline-contract.js';
+/**
+ * Normalizes a repo-relative path for grouping, sorting, and any later
+ * surface comparison. Collapses `\`-style separators to `/`, then applies
+ * POSIX lexical normalization (redundant slashes, `.` segments, and a
+ * leading `./`). Never touches the filesystem or the process environment --
+ * this is a pure string transform.
+ */
+export declare function normalizeRepoRelativePath(filePath: string): string;
+/**
+ * Pure, side-effect-free admission of one reviewer's raw `ce:review` return.
+ *
+ * Binds the parsed return to the parent-expected persona and validates its
+ * structure. Never reads `process.env`, the filesystem, or the clock --
+ * admission depends only on the payload itself.
+ *
+ * Reuses `validateReviewReturnValue` from `review-return-validator.ts` for
+ * the underlying `SubAgentReturnSchema` structural check rather than
+ * re-validating shape by hand.
+ */
+export type ScreenOutput = ReturnType<typeof ScreenOutputSchema.parse>;
+/** Raw screen input. `raw_return` is intentionally `unknown`: a reviewer's
+ * return may arrive as an unparsed JSON string (a raw subprocess payload) or
+ * as an already-decoded value; this is the boundary that admits it. */
+export interface ScreenReviewReturnInput {
+    readonly raw_return: unknown;
+    readonly expected_reviewer: string;
+    readonly invoking_harness: z.infer<typeof HarnessSchema>;
+}
+/**
+ * Admit one reviewer's raw return and bind it to the parent-expected
+ * persona.
+ *
+ * Rejection is whole-payload only: a schema-invalid return, a reviewer
+ * identity mismatch, or malformed JSON rejects everything. Findings that
+ * pass structural validation are admitted with a stable
+ * `<reviewer>#<original-index>` input ID derived from their position in the
+ * original payload.
+ */
+export declare function screenReviewReturn(input: ScreenReviewReturnInput): ScreenOutput;
+export type PrepareOutput = ReturnType<typeof PrepareOutputSchema.parse>;
+/** Raw prepare input. `raw_input` is intentionally `unknown`: the aggregate
+ * payload may arrive as an unparsed JSON string (a raw stdin payload) or as
+ * an already-decoded value; this is the boundary that admits it. */
+export interface PrepareReviewCandidatesInput {
+    readonly raw_input: unknown;
+}
+type PrepareRejectReason = 'aggregate payload exceeds byte cap' | 'malformed JSON' | 'schema validation' | 'duplicate persona outcome' | 'duplicate input id' | 'unselected persona screen result' | 'missing screen result for selected dispatch';
+/** One bounded, payload-safe rejection diagnostic: a fixed reason code and a
+ * safe JSON path only. Never payload content, never exception text. */
+export interface PrepareRejection {
+    readonly path: string;
+    readonly reason: PrepareRejectReason;
+}
+export type PrepareReviewCandidatesResult = {
+    readonly ok: true;
+    readonly value: PrepareOutput;
+} | {
+    readonly ok: false;
+    readonly rejection: PrepareRejection;
+};
+/**
+ * Consumes every selected persona's screen result plus the dispatch metadata
+ * the parent selected them under, applies the confidence gate, and forms
+ * candidate groups for the model to adjudicate.
+ *
+ * Rejection is whole-payload only, with a fixed reason code and a safe JSON
+ * path -- never payload content or exception text. Every count in the
+ * output is recomputed from the admitted arrays themselves; no count
+ * supplied by the input is trusted.
+ */
+export declare function prepareReviewCandidates(input: PrepareReviewCandidatesInput): PrepareReviewCandidatesResult;
+type AdjudicationDecisions = z.infer<typeof AdjudicationEnvelopeSchema>['decisions'];
+type MergeDecision = AdjudicationDecisions[number];
+type MergedMergeDecision = Extract<MergeDecision, {
+    disposition: 'merged';
+}>;
+type DeclinedMergeDecision = Extract<MergeDecision, {
+    disposition: 'declined';
+}>;
+/** One validated merge group: the model's merge decision plus the file its
+ * members were grouped under, so a later derivation step does not need to
+ * re-scan the candidate groups to recover it. */
+export interface ValidatedMergedGroup {
+    readonly decision: MergedMergeDecision;
+    readonly file: string;
+}
+/** One validated declined singleton: the model's decline decision plus the
+ * file its input finding was grouped under. */
+export interface ValidatedDeclinedSingleton {
+    readonly decision: DeclinedMergeDecision;
+    readonly file: string;
+}
+/** The validated partition: every eligible candidate accounted for, plus the
+ * true singletons passed through untouched. Sorted by `decision_id` /
+ * input ID so the result is byte-identical regardless of input decision
+ * order. */
+export interface ValidatedAdjudication {
+    readonly merged: readonly ValidatedMergedGroup[];
+    readonly declined: readonly ValidatedDeclinedSingleton[];
+    readonly singletons: readonly string[];
+}
+type AdjudicationRejectReason = 'unknown input id' | 'suppressed input id' | 'duplicate input id citation' | 'omitted eligible input id' | 'cross-group input id citation' | 'representative line mismatch' | 'unexpected decisions for empty candidate set' | 'duplicate merged group decision id' | 'duplicate declined decision id' | 'duplicate passthrough singleton input id' | 'declined decision id collides with merged group decision id' | 'declined decision id collides with passthrough singleton input id' | 'passthrough singleton input id collides with merged group decision id';
+/** One bounded, payload-safe rejection diagnostic: a fixed reason code and a
+ * safe JSON path only. Never payload content, never a finding title, never
+ * exception text. */
+export interface AdjudicationRejection {
+    readonly path: string;
+    readonly reason: AdjudicationRejectReason;
+}
+export type ValidateAdjudicationResult = {
+    readonly ok: true;
+    readonly value: ValidatedAdjudication;
+} | {
+    readonly ok: false;
+    readonly rejection: AdjudicationRejection;
+};
+/**
+ * Validates that the model's adjudication decisions form a valid partition
+ * over `prepared`'s eligible candidate set: every eligible input ID (one
+ * that appears in a candidate group) is cited by exactly one decision --
+ * either inside a merge group or as a declined singleton. Never repairs a
+ * malformed partition; any violation rejects the whole envelope with no
+ * partial output, since a repaired partition would silently invent a merge
+ * decision the model never made.
+ *
+ * A decision set is required to be empty when there are no candidate groups
+ * (a legitimate, non-error state); a non-empty decision set against zero
+ * candidates is rejected. This function never computes merged-finding
+ * fields (severity, confidence, provenance, routing) -- only structural
+ * partition validity.
+ */
+export declare function validateAdjudication(prepared: PrepareOutput, decisions: AdjudicationDecisions): ValidateAdjudicationResult;
+type SurvivingFinding = PrepareOutput['surviving_findings'][number];
+/** A candidate group always has at least two members
+ * (`CandidateGroupSchema.members` is `.min(2)`), so the contributing set for
+ * one merge decision is a non-empty tuple by construction rather than a
+ * plain array that would need a defensive empty check on every derivation
+ * below. */
+export type MergeContributingFindings = readonly [
+    SurvivingFinding,
+    SurvivingFinding,
+    ...SurvivingFinding[]
+];
+/** The model-owned fields for one merge decision that this derivation
+ * consumes: the representative line it picked (already checked by
+ * `validateAdjudication` against the group's real member lines), any
+ * additional reviewers it claims agreed, and an optional narrower route with
+ * the reason narrowing requires. */
+export interface MergedFindingModelDecision {
+    readonly line: number;
+    readonly eligible_agreement_credit?: readonly string[];
+    readonly proposed_route?: PipelineRoute;
+    readonly route_narrowing_reason?: string;
+}
+export interface DeriveMergedFindingInput {
+    readonly contributing: MergeContributingFindings;
+    readonly decision: MergedFindingModelDecision;
+    /** Every reviewer whose `SubAgentReturn` was actually admitted for this
+     * run -- the eligibility set agreement credit is checked against. */
+    readonly returned_reviewers: readonly string[];
+}
+export interface DerivedMergedFindingFields {
+    readonly severity: SurvivingFinding['severity'];
+    readonly submitters: readonly string[];
+    readonly confidence: number;
+    readonly agreement_credit: readonly string[];
+    readonly pre_existing: boolean;
+    readonly fingerprint: string;
+    readonly route: PipelineRoute;
+}
+type MergedFindingRejectReason = 'route widening' | 'route narrowing missing reason' | 'duplicate agreement credit reviewer' | 'agreement credit reviewer already a submitter' | 'agreement credit reviewer did not return';
+/** One bounded, payload-safe rejection diagnostic: a fixed reason code and a
+ * safe JSON path only. Never payload content, never a finding title, never
+ * exception text. */
+export interface MergedFindingRejection {
+    readonly path: string;
+    readonly reason: MergedFindingRejectReason;
+}
+export type DeriveMergedFindingResult = {
+    readonly ok: true;
+    readonly value: DerivedMergedFindingFields;
+} | {
+    readonly ok: false;
+    readonly rejection: MergedFindingRejection;
+};
+/**
+ * Derives one merged finding's mechanical fields -- severity, submitters,
+ * confidence, agreement credit, `pre_existing`, fingerprint, and route --
+ * from its contributing surviving findings plus the model's decision fields
+ * for that group. Assumes `validateAdjudication` already confirmed the
+ * partition; never re-validates group membership. Rejection is
+ * whole-decision only: an invalid agreement-credit claim or a route
+ * widening attempt rejects the whole derivation with a fixed reason code
+ * and a safe JSON path, never payload content.
+ */
+export declare function deriveMergedFindingFields(input: DeriveMergedFindingInput): DeriveMergedFindingResult;
+export type MergeOutput = ReturnType<typeof MergeOutputSchema.parse>;
+/** Raw application input: the prepared candidate state plus the model's
+ * adjudication decisions, matching `MergeInputSchema`'s two fields exactly. */
+export interface ApplyReviewAdjudicationInput {
+    readonly prepared: PrepareOutput;
+    readonly decisions: AdjudicationDecisions;
+}
+export type ApplyReviewAdjudicationResult = {
+    readonly ok: true;
+    readonly value: MergeOutput;
+} | {
+    readonly ok: false;
+    readonly rejection: AdjudicationRejection | MergedFindingRejection;
+};
+/**
+ * The top-level merge phase: validates the adjudication partition, derives
+ * every merged finding (one per merge group, one per declined singleton, one
+ * per passthrough singleton) via `deriveMergedFindingFields`, emits the
+ * mechanical validator request set, sorts everything stably, and parses the
+ * assembled result through `MergeOutputSchema` before returning success.
+ *
+ * Rejection is whole-phase only: a partition violation from
+ * `validateAdjudication` or a field-derivation violation from
+ * `deriveMergedFindingFields` (for any single group or singleton) aborts
+ * immediately with no partial output -- this function never accumulates
+ * merged findings past the first rejection, and never calls
+ * `MergeOutputSchema.parse` until every finding derived successfully. A
+ * `finding_id` collision across the three assembly sources -- a merge
+ * group's or declined singleton's model-chosen `decision_id`, or a
+ * passthrough singleton's carried-through `input_id` -- also rejects before
+ * parsing (`checkNoDuplicateAssembledFindingIds`), never silently
+ * namespaced or rewritten.
+ *
+ * The top-level `disagreement_facts` collects every decision's own
+ * `disagreement_facts`, plus every declined decision's `declined_reason` --
+ * the "why these were not merged" narrative that has no dedicated field on
+ * `MergedFindingSchema` itself.
+ */
+export declare function applyReviewAdjudication(input: ApplyReviewAdjudicationInput): ApplyReviewAdjudicationResult;
+type ValidatorLifecycleResults = z.infer<typeof ValidatorLifecycleResultsSchema>;
+/** One merged finding carrying its reconciled validation state. `validated`
+ * is `true` when a validator confirmed the finding, `false` when a
+ * validator disproved it, and *absent* -- never coerced to either boolean
+ * -- both when the finding was never requested for validation and when its
+ * validator run failed or was unavailable. A consumer distinguishes those
+ * two absent cases by cross-referencing `lifecycle_failures`: a finding_id
+ * present there was requested but left uncertain by a `failed` or
+ * `unavailable` outcome; a finding_id absent from both `lifecycle_failures`
+ * and carrying no `validated` field was never requested at all. */
+export type ReconciledFinding = MergeOutput['merged_findings'][number] & {
+    readonly validated?: boolean;
+    /** The disproving validator's own reason, carried onto the finding only
+     * when `validated` is `false` -- satisfies the artifact's
+     * `validation_reason` requirement at source instead of losing the reason
+     * on the way from the lifecycle result to the reconciled finding. Absent
+     * whenever `validated` is not `false`. */
+    readonly validation_reason?: string;
+};
+/** One recorded validator lifecycle failure: a requested finding whose
+ * validator run ended in uncertainty (`failed` or `unavailable`) rather
+ * than a definite answer. The `outcome` discriminant distinguishes a
+ * timeout/error from a validator that was never reachable at all. */
+export interface ValidatorLifecycleFailure {
+    readonly finding_id: string;
+    readonly outcome: 'failed' | 'unavailable';
+    readonly reason: string;
+}
+export interface ReconcileValidatorResultsOutput {
+    readonly findings: readonly ReconciledFinding[];
+    readonly filtered_finding_ids: readonly string[];
+    readonly filtered_input_ids: readonly string[];
+    readonly lifecycle_failures: readonly ValidatorLifecycleFailure[];
+    readonly degraded: boolean;
+}
+type ReconcileValidatorResultsRejectReason = 'missing validator result' | 'duplicate validator result' | 'unrequested validator result';
+/** One bounded, payload-safe rejection diagnostic: a fixed reason code and a
+ * safe JSON path only. Never payload content, never a finding title. */
+export interface ReconcileValidatorResultsRejection {
+    readonly path: string;
+    readonly reason: ReconcileValidatorResultsRejectReason;
+}
+export interface ReconcileValidatorResultsInput {
+    readonly merge: MergeOutput;
+    readonly validator_lifecycle_results: ValidatorLifecycleResults;
+}
+export type ReconcileValidatorResultsResult = {
+    readonly ok: true;
+    readonly value: ReconcileValidatorResultsOutput;
+} | {
+    readonly ok: false;
+    readonly rejection: ReconcileValidatorResultsRejection;
+};
+/**
+ * Reconciles the finding-validator lifecycle results against the merge
+ * output's validator request set, classifying every merged finding as
+ * validated, filtered, or left uncertain (see `ReconciledFinding` for the
+ * full state table). Rejection is whole-payload only: a missing result, a
+ * duplicate result, or a result for a finding that was never requested
+ * rejects everything, with a fixed reason code and a safe JSON path -- never
+ * payload content or a finding title.
+ *
+ * This reconciles validator results only -- it never builds action queues,
+ * disposition counts, risk coverage, plan-assessment routing, or the final
+ * artifact; those are separate slices. Never reads `process.env`, the
+ * filesystem, or the clock.
+ */
+export declare function reconcileValidatorResults(input: ReconcileValidatorResultsInput): ReconcileValidatorResultsResult;
+export type FinalizeInputValue = ReturnType<typeof FinalizeInputSchema.parse>;
+type FinalizeScreenResults = FinalizeInputValue['screen_results'];
+type FinalizeDispatchRecords = FinalizeInputValue['dispatch_records'];
+type FinalizeDispatchRecord = FinalizeDispatchRecords[number];
+type FinalizeParentRunMetadata = FinalizeInputValue['parent_run_metadata'];
+export interface DeriveFinalizeContextInput {
+    readonly merge: MergeOutput;
+    readonly prepared: PrepareOutput;
+    readonly screen_results: FinalizeScreenResults;
+    readonly dispatch_records: FinalizeDispatchRecords;
+    readonly parent_run_metadata: Pick<FinalizeParentRunMetadata, 'selected_dispatches' | 'validation'>;
+}
+export interface FinalizeContext {
+    readonly rejected_payloads: readonly RejectedPayloadWeight[];
+    readonly lost_risk_critical_personas: readonly LostRiskCriticalPersona[];
+}
+type FinalizeContextRejectReason = 'duplicate merged finding ID' | 'merged finding references unknown survivor' | 'survivor missing from merge inputs' | 'survivor claimed by multiple merged findings' | 'validator request references unknown merged finding' | 'dispatch record mismatch' | 'duplicate selection surface entry' | 'screen result missing for selected persona' | 'unexpected screen result for persona' | 'screen result outcome does not match dispatch record' | 'merged finding fields diverge from derivation' | 'confidence disposition references unscreened finding' | 'merged finding cites input from unavailable reviewer' | 'merged finding submitter not a cited reviewer' | 'merged finding agreement credit overlaps submitters' | 'surviving finding diverges from its screened finding' | 'surviving finding references unscreened input' | 'duplicate confidence disposition' | 'validation must be not_attempted at finalize';
+export interface FinalizeContextRejection {
+    readonly path: string;
+    readonly reason: FinalizeContextRejectReason;
+}
+export type DeriveFinalizeContextResult = {
+    readonly ok: true;
+    readonly value: FinalizeContext;
+} | {
+    readonly ok: false;
+    readonly rejection: FinalizeContextRejection;
+};
+/**
+ * Validates the finalize envelope's cross-phase joins and derives the two
+ * inputs only finalize can compute: rejected-payload weights (from screen
+ * summaries) and lost risk-critical personas (from the loss rules in
+ * `synthesis-artifact-contract.md`). Rejection is whole-envelope only, with
+ * a fixed reason and a safe JSON path, never payload content -- and always
+ * happens before any derivation runs.
+ */
+export declare function deriveFinalizeContext(input: DeriveFinalizeContextInput): DeriveFinalizeContextResult;
+/** The final disposition of one admitted raw input: suppressed by the
+ * confidence gate, filtered by a disproven validation, folded into a
+ * synthesized (multi-input) finding, or surviving as its own finding.
+ * Mutually exclusive and exhaustive over every entry in
+ * `PrepareOutput['confidence_dispositions']` -- a rejected input never
+ * reaches this vocabulary at all, since whole-payload rejection happens
+ * before the `prepare` phase and is counted separately (see
+ * `FinalDispositionCounts.rejected`). */
+export type FinalInputDisposition = 'suppressed' | 'filtered' | 'merged' | 'surviving';
+/** One admitted raw input's final disposition. `reason` carries the
+ * confidence-gate suppression reason when present; every other disposition
+ * has no reason of its own to report here. */
+export interface FinalizedInputDisposition {
+    readonly input_id: string;
+    readonly disposition: FinalInputDisposition;
+    readonly reason?: string;
+}
+/** One rejected reviewer payload's weight for the disposition-count total:
+ * the number of findings a whole-payload rejection discarded, exactly as
+ * `screenReviewReturn` recorded it in `ScreenRejectedSummarySchema`. A
+ * rejected payload contributes one weighted entry here, never one row per
+ * discarded finding -- so the disposition-count total stays anchored to
+ * findings actually observed rather than to ledger row count. */
+export interface RejectedPayloadWeight {
+    readonly rejected_finding_count: number;
+}
+/** Every admitted-plus-rejected disposition count, weighted by findings
+ * observed rather than by ledger rows. `rejected` sums every
+ * `RejectedPayloadWeight.rejected_finding_count`; the other four fields each
+ * count one `FinalizedInputDisposition` entry, excluding any entry owned by
+ * a `validation_unavailable` persona -- the same exclusion
+ * `buildAdmittedLedgerRows` applies to the ledger, so the four admitted-
+ * weight fields always sum to the admitted row count in the ledger
+ * `finalizeReview` builds alongside it. That invariant is asserted by
+ * `checkDispositionCountsReconcileLedger` in `finalizeReview`, not left
+ * aspirational. */
+export interface FinalDispositionCounts {
+    readonly surviving: number;
+    readonly merged: number;
+    readonly suppressed: number;
+    readonly filtered: number;
+    readonly rejected: number;
+}
+/** Where one actionable, surviving finding routes to: a fixer can take it
+ * directly (`owner: 'review-fixer'`), it needs a human or a downstream
+ * resolver (`owner: 'downstream-resolver' | 'human'`), or it is terminal and
+ * report-only (`owner: 'release'`). Derived solely from the finding's own
+ * mechanically-computed `owner` field -- never from anything a model
+ * proposed beyond the narrowing `deriveMergedFindingFields` already
+ * validated. */
+export type FindingActionRoute = 'fixer' | 'residual' | 'report_only';
+/** One finding placed in an action queue, or reported via `new_findings` /
+ * `pre_existing_findings` outside any queue. A finding whose validator run
+ * failed or was unavailable (present in `reconciled.lifecycle_failures`) is
+ * excluded from every action queue entirely -- nobody disproved it, but
+ * nobody confirmed it either, so `partitionFindings` will not auto-action
+ * it. It still surfaces through `new_findings` (or `pre_existing_findings`)
+ * with `unconfirmed: true`, and `reconcileValidatorResults`'s degraded
+ * validator lifecycle keeps the run from reaching a clean verdict
+ * (`deriveVerdict`'s `validator lifecycle degraded` blocking reason). As a
+ * consequence, `unconfirmed` is always `false` on every entry actually
+ * placed in `queues.fixer` / `queues.residual` / `queues.report_only` --
+ * see `partitionFindings`'s `an unconfirmed finding never enters an action
+ * queue` test. */
+export interface QueuedFinding {
+    readonly finding_id: string;
+    readonly unconfirmed: boolean;
+}
+/** One reported finding that is not in any action queue because it predates
+ * the current change: every one of its contributing raw inputs was already
+ * `pre_existing`. Still reported, but not the same actionable class as a
+ * newly introduced finding. */
+export interface PreExistingFinding {
+    readonly finding_id: string;
+    readonly unconfirmed: boolean;
+}
+export interface FinalizeReviewDispositionsInput {
+    readonly prepared: PrepareOutput;
+    readonly reconciled: ReconcileValidatorResultsOutput;
+    readonly rejected_payloads: readonly RejectedPayloadWeight[];
+    readonly screen_results: FinalizeScreenResults;
+    readonly dispatch_records: FinalizeDispatchRecords;
+}
+export interface FinalizeReviewDispositionsOutput {
+    readonly input_dispositions: readonly FinalizedInputDisposition[];
+    readonly disposition_counts: FinalDispositionCounts;
+    readonly pre_existing_findings: readonly PreExistingFinding[];
+    readonly new_findings: readonly QueuedFinding[];
+    readonly queues: {
+        readonly fixer: readonly QueuedFinding[];
+        readonly residual: readonly QueuedFinding[];
+        readonly report_only: readonly QueuedFinding[];
+    };
+}
+type FinalizeReviewDispositionsRejectReason = 'survivor missing from merged findings';
+export interface FinalizeReviewDispositionsRejection {
+    readonly path: string;
+    readonly reason: FinalizeReviewDispositionsRejectReason;
+}
+export type FinalizeReviewDispositionsResult = {
+    readonly ok: true;
+    readonly value: FinalizeReviewDispositionsOutput;
+} | {
+    readonly ok: false;
+    readonly rejection: FinalizeReviewDispositionsRejection;
+};
+/**
+ * The finalize-phase dispositions, counts, and action-queue step: derives
+ * every admitted input's final disposition, the weighted disposition
+ * counts (including the rejected-payload weight), the pre-existing/new
+ * finding split, and the three mutually exclusive, collectively exhaustive
+ * action queues (`fixer`, `residual`, `report_only`) that partition every
+ * surviving actionable finding by its mechanically-derived `owner`.
+ *
+ * Every list is sorted by a stable key (`input_id` or `finding_id`), so
+ * identical input in a different order always produces byte-identical
+ * output. This step never builds risk coverage, plan-assessment routing, or
+ * the final artifact -- those are separate slices. Never reads
+ * `process.env`, the filesystem, or the clock.
+ */
+export declare function finalizeReviewDispositions(input: FinalizeReviewDispositionsInput): FinalizeReviewDispositionsResult;
+/** One risk-critical persona whose dispatch was lost, paired with the
+ * selection surface it was recorded as covering. */
+export interface LostRiskCriticalPersona {
+    readonly persona: string;
+    readonly selection_surface: readonly string[];
+}
+export interface DeriveRiskCoverageInput {
+    readonly lost_risk_critical_personas: readonly LostRiskCriticalPersona[];
+    readonly prepared: PrepareOutput;
+    readonly reconciled: ReconcileValidatorResultsOutput;
+}
+/** One lost persona's coverage verdict. `finding_id` and `input_finding_id`
+ * are present only when `satisfied` is `true`: `finding_id` names the
+ * reconciled finding whose evidence covers the lost surface, and
+ * `input_finding_id` names the specific admitted input row -- owned by a
+ * different persona than the lost one -- that finding cites as its cross-
+ * persona evidence. */
+export interface RiskCoverageDerivation {
+    readonly persona: string;
+    readonly satisfied: boolean;
+    readonly finding_id?: string;
+    readonly input_finding_id?: string;
+}
+/**
+ * Derives risk-critical replacement coverage for every lost risk-critical
+ * persona: whether a *different* persona's validated, on-surface evidence
+ * independently covers the surface the lost persona was selected for. This
+ * step never identifies which personas are risk-critical or lost, never
+ * builds plan-assessment routing, and never assembles the final artifact --
+ * those are separate slices. Never reads `process.env`, the filesystem, or
+ * the clock.
+ */
+export declare function deriveRiskCoverage(input: DeriveRiskCoverageInput): readonly RiskCoverageDerivation[];
+/** One plan-assessment result the model produced while checking the plan's
+ * stated requirements against the work. `explicit_unmet_requirement` is a
+ * requirement the plan stated outright and the work demonstrably did not
+ * meet -- residual actionable work that gates the verdict.
+ * `inferred_gap` is something the model suspects is missing but the plan
+ * never stated outright -- advisory output only, and never gates the
+ * verdict by itself. Deliberately carries no persona, no evidence, and no
+ * input ID: unlike a reviewer's finding, nobody reviewed a line of code to
+ * produce it, so it must never be mistaken for one. */
+export type PlanAssessmentResult = z.infer<typeof PlanAssessmentEnvelopeSchema>['results'][number];
+export interface RoutePlanAssessmentInput {
+    /** Every plan-assessment result the model returned. Empty when the run
+     * had no plan to assess against -- never fabricated, and never a reason
+     * to silently relax the verdict gate. */
+    readonly results: readonly PlanAssessmentResult[];
+}
+export interface RoutedPlanAssessment {
+    readonly residual_actionable_work: readonly string[];
+    readonly advisory_outputs: readonly string[];
+    readonly gated_by_explicit_unmet_requirement: boolean;
+}
+/**
+ * Routes plan-assessment results into their two output channels: explicit
+ * unmet requirements become residual actionable work and gate the verdict;
+ * inferred gaps become advisory-only output and never gate the verdict on
+ * their own. A run with no plan assessment (`results` empty) produces empty
+ * output on both channels and an ungated verdict -- never fabricated
+ * entries, never a silently relaxed gate. `PlanAssessmentResult` has no
+ * persona or input-ID field to carry, so a plan-assessment result can never
+ * be attributed to a reviewer or cross-referenced against the input ledger
+ * by construction, and this function never touches a findings collection.
+ * Output is sorted for determinism, so identical input in a different order
+ * always produces byte-identical output.
+ */
+export declare function routePlanAssessment(input: RoutePlanAssessmentInput): RoutedPlanAssessment;
+export interface RunReviewPipelineInput {
+    readonly merge: MergeOutput;
+    readonly validator_lifecycle_results: ValidatorLifecycleResults;
+    readonly prepared: PrepareOutput;
+    readonly rejected_payloads: readonly RejectedPayloadWeight[];
+    readonly lost_risk_critical_personas: readonly LostRiskCriticalPersona[];
+    readonly plan_assessment: RoutePlanAssessmentInput;
+    readonly screen_results: FinalizeScreenResults;
+    readonly dispatch_records: FinalizeDispatchRecords;
+}
+/** One fact that withheld a clean verdict. Each `kind` is a distinct,
+ * independently-triggered block -- never collapsed into a shared shape --
+ * so a reader can always tell which of the three gating conditions fired
+ * and, within `explicit_unmet_plan_requirement` and
+ * `unsatisfied_risk_coverage`, which specific requirement or persona is
+ * responsible. */
+export type VerdictBlockingReason = {
+    readonly kind: 'explicit_unmet_plan_requirement';
+    readonly description: string;
+} | {
+    readonly kind: 'unsatisfied_risk_coverage';
+    readonly persona: string;
+} | {
+    readonly kind: 'degraded_validator_lifecycle';
+    readonly finding_id: string;
+    readonly outcome: 'failed' | 'unavailable';
+};
+export interface ReviewRunVerdict {
+    readonly clean: boolean;
+    readonly blocking_reasons: readonly VerdictBlockingReason[];
+}
+export interface RunReviewPipelineOutput {
+    readonly reconciled: ReconcileValidatorResultsOutput;
+    readonly finalized: FinalizeReviewDispositionsOutput;
+    readonly risk_coverage: readonly RiskCoverageDerivation[];
+    readonly plan_assessment: RoutedPlanAssessment;
+    readonly verdict: ReviewRunVerdict;
+}
+export type RunReviewPipelineResult = {
+    readonly ok: true;
+    readonly value: RunReviewPipelineOutput;
+} | {
+    readonly ok: false;
+    readonly rejection: ReconcileValidatorResultsRejection | FinalizeReviewDispositionsRejection;
+};
+/**
+ * Runs the full synthesis pipeline's finalize-and-verdict slice: calls
+ * `reconcileValidatorResults`, `finalizeReviewDispositions`,
+ * `deriveRiskCoverage`, and `routePlanAssessment` in order, then derives the
+ * run's verdict from their already-computed output. Never re-derives
+ * anything those four steps compute -- this is composition, not a fifth
+ * derivation. A rejection from `reconcileValidatorResults` aborts the whole
+ * run and is returned unchanged, with no partial output from the later
+ * steps. This step never builds the final artifact or the
+ * writing/report-only discriminated output -- that is a separate slice.
+ * Never reads `process.env`, the filesystem, or the clock.
+ */
+export declare function runReviewPipeline(input: RunReviewPipelineInput): RunReviewPipelineResult;
+type BuildInputLedgerScreenResult = FinalizeScreenResults[number];
+type BuildInputLedgerRejectedSummary = NonNullable<BuildInputLedgerScreenResult['result']['rejected_summary']>;
+/** One admitted raw input's ledger row: its owning reviewer, the confidence
+ * the reviewer reported, its final disposition, and a required reason --
+ * the confidence-gate reason for `suppressed`, the disproving validator's
+ * reason for `filtered`, and a fixed phrase for `surviving`/`merged`. */
+export interface AdmittedInputLedgerRow {
+    readonly record_type: 'admitted';
+    readonly input_id: string;
+    readonly reviewer: string;
+    readonly confidence: number;
+    readonly disposition: FinalInputDisposition;
+    readonly reason: string;
+}
+/** One whole-payload rejection's ledger row. Only emitted when the screen
+ * result actually carried a `rejected_summary` -- an unknowable rejected
+ * count (KTD21) produces no row at all. */
+export interface RejectedInputLedgerRow {
+    readonly record_type: 'rejected_summary';
+    readonly reviewer: string;
+    readonly dispatch_outcome: BuildInputLedgerRejectedSummary['dispatch_outcome'];
+    readonly rejected_finding_count: number;
+    readonly rejected_severities: BuildInputLedgerRejectedSummary['rejected_severities'];
+    readonly disposition: 'rejected';
+    readonly reason: string;
+}
+export type InputLedgerRow = AdmittedInputLedgerRow | RejectedInputLedgerRow;
+export interface BuildInputLedgerInput {
+    readonly prepared: PrepareOutput;
+    readonly screen_results: FinalizeScreenResults;
+    readonly dispatch_records: FinalizeDispatchRecords;
+    readonly finalized: FinalizeReviewDispositionsOutput;
+    readonly reconciled: ReconcileValidatorResultsOutput;
+}
+/**
+ * Builds the artifact's input-finding ledger: one admitted row per
+ * `prepared.confidence_dispositions` entry, sorted by input ID, followed by
+ * one rejected-summary row per screen result that carried a
+ * `rejected_summary`, sorted by reviewer. A `validation_unavailable`
+ * persona contributes no row of either kind, and a rejection with no
+ * summary (KTD21) contributes no row at all -- never a fabricated count.
+ * Never reads `process.env`, the filesystem, or the clock.
+ */
+export declare function buildInputLedger(input: BuildInputLedgerInput): readonly InputLedgerRow[];
+export interface BuildReviewCoverageInput {
+    readonly dispatch_records: FinalizeDispatchRecords;
+    readonly validator_lifecycle_results: ValidatorLifecycleResults;
+    readonly screen_results: FinalizeScreenResults;
+    readonly reconciled: ReconcileValidatorResultsOutput;
+    readonly merge: MergeOutput;
+}
+export interface ReviewCoverageSummary {
+    readonly reviewers: number;
+    readonly validators: number;
+    readonly residual_risks: readonly string[];
+    readonly testing_gaps: readonly string[];
+    readonly failed_reviewers: readonly string[];
+    readonly validator_failures: readonly string[];
+    readonly intent_uncertainty: readonly string[];
+}
+type BuildReviewCoverageRejectReason = 'coverage array exceeds bound';
+export interface BuildReviewCoverageRejection {
+    readonly path: string;
+    readonly reason: BuildReviewCoverageRejectReason;
+}
+export type BuildReviewCoverageResult = {
+    readonly ok: true;
+    readonly value: ReviewCoverageSummary;
+} | {
+    readonly ok: false;
+    readonly rejection: BuildReviewCoverageRejection;
+};
+/**
+ * Aggregates screen-phase and validator-phase evidence into the artifact's
+ * `coverage` shape: deduped, sorted unions of residual risks and testing
+ * gaps; the personas whose dispatch outcome was `malformed`,
+ * `never_returned`, or `validation_unavailable`; the disproving reasons for
+ * every requested validator that never answered; and the merge phase's
+ * disagreement facts, carried through unchanged. Every array is checked
+ * against `MAX_PERSONAS` before assembly -- an overflow rejects rather than
+ * silently truncating. Never reads `process.env`, the filesystem, or the
+ * clock.
+ */
+export declare function buildReviewCoverage(input: BuildReviewCoverageInput): BuildReviewCoverageResult;
+export interface SynthesizedFindingProvenanceProjection {
+    readonly fingerprint: string;
+    readonly submitters: readonly string[];
+    readonly agreement_credit: readonly string[];
+}
+export interface SynthesizedFindingProjection {
+    readonly title: string;
+    readonly severity: ReconciledFinding['severity'];
+    readonly file: string;
+    readonly line: number;
+    readonly why_it_matters: string;
+    readonly autofix_class: ReconciledFinding['autofix_class'];
+    readonly owner: ReconciledFinding['owner'];
+    readonly requires_verification: boolean;
+    readonly confidence: number;
+    readonly evidence: ReconciledFinding['evidence'];
+    readonly pre_existing: boolean;
+    readonly suggested_fix?: ReconciledFinding['suggested_fix'];
+    readonly validated?: boolean;
+    readonly validation_reason?: string;
+    readonly input_finding_ids: readonly string[];
+    readonly provenance: SynthesizedFindingProvenanceProjection;
+}
+export interface ProjectSynthesizedFindingsInput {
+    readonly findings: readonly ReconciledFinding[];
+}
+/**
+ * Projects every reconciled finding into the artifact's synthesized-finding
+ * shape, in the reconciled order. Nests `fingerprint`, `submitters`, and
+ * `agreement_credit` under `provenance` (absent `agreement_credit` projects
+ * to an empty list, never omitted), carries `validated`/`validation_reason`
+ * through unchanged, and never emits the flat, helper-only `finding_id`.
+ * This is projection only -- it never re-validates referential integrity
+ * against the input ledger; `ReviewArtifactSchema.parse` is the actual
+ * enforcement point for that. Never reads `process.env`, the filesystem, or
+ * the clock.
+ */
+export declare function projectSynthesizedFindings(input: ProjectSynthesizedFindingsInput): readonly SynthesizedFindingProjection[];
+export type FinalizeReviewInput = FinalizeInputValue;
+type FinalizeOutputValue = ReturnType<typeof FinalizeOutputSchema.parse>;
+type FinalizeReviewRejection = FinalizeContextRejection | ReconcileValidatorResultsRejection | FinalizeReviewDispositionsRejection | BuildReviewCoverageRejection | RiskCoverageSemanticsRejection | DispositionLedgerReconciliationRejection | {
+    readonly path: string;
+    readonly reason: 'artifact failed schema validation';
+} | {
+    readonly path: string;
+    readonly reason: 'finalize output failed schema validation';
+};
+export type FinalizeReviewResult = {
+    readonly ok: true;
+    readonly value: FinalizeOutputValue;
+} | {
+    readonly ok: false;
+    readonly rejection: FinalizeReviewRejection;
+};
+interface ArtifactDispatchEntry {
+    readonly persona: string;
+    readonly dispatch_outcome: FinalizeDispatchRecord['dispatch_outcome'];
+    readonly input_finding_count: number;
+    readonly rejection_reason?: string;
+    readonly selection_surface?: readonly string[];
+    readonly selection_reason?: string;
+}
+interface ArtifactRiskCoverageEntry {
+    readonly persona: string;
+    readonly satisfied: boolean;
+    readonly input_finding_id?: string;
+}
+interface RiskCoverageSemanticsInput {
+    readonly dispatches: readonly ArtifactDispatchEntry[];
+    readonly findings: readonly SynthesizedFindingProjection[];
+    readonly risk_coverage?: readonly ArtifactRiskCoverageEntry[];
+}
+interface RiskCoverageSemanticsRejection {
+    readonly path: string;
+    readonly reason: 'satisfied risk coverage must cite a validated finding on the lost persona selection surface';
+}
+type RiskCoverageSemanticsResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly rejection: RiskCoverageSemanticsRejection;
+};
+/**
+ * Defensive pipeline-side assertion that every satisfied risk-coverage entry
+ * cites a validated finding on the lost persona's recorded selection
+ * surface. `deriveRiskCoverage` already guarantees this at derivation time
+ * -- `isEligibleRiskCoverageCandidate` enforces the on-surface rule and
+ * `isValidationBandEligible` enforces the validation-band rule before a
+ * candidate can ever be cited -- so this check restates that guarantee at
+ * the pipeline boundary rather than deriving it independently, protecting
+ * against a future regression in artifact assembly. Surfaces compare
+ * through `normalizeRepoRelativePath` so alternate spellings (mixed
+ * separators, dot segments) of the same surface entry still match. This is
+ * the pipeline-owned counterpart to `ReviewArtifactSchema`'s structural
+ * `risk_coverage` refinement, which only checks referential integrity.
+ * Never reads `process.env`, the filesystem, or the clock.
+ */
+export declare function checkRiskCoverageSemantics(artifactCandidate: RiskCoverageSemanticsInput): RiskCoverageSemanticsResult;
+interface DispositionLedgerReconciliationRejection {
+    readonly path: string;
+    readonly reason: 'disposition counts do not reconcile with the admitted input ledger';
+}
+type DispositionLedgerReconciliationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly rejection: DispositionLedgerReconciliationRejection;
+};
+/**
+ * Defensive pipeline-side assertion that `disposition_counts`' four
+ * admitted-weight fields (`surviving` + `merged` + `suppressed` +
+ * `filtered`) sum to the number of `record_type: 'admitted'` rows in the
+ * independently-derived input ledger -- the documented invariant on
+ * `FinalDispositionCounts` ("the five fields always sum to the total
+ * findings observed"), restated here as the actual verifier instead of left
+ * aspirational. `disposition_counts` (via `deriveInputDispositions`) and
+ * the ledger (via `buildAdmittedLedgerRows`) both exclude
+ * `validation_unavailable` personas by construction, so this should never
+ * trip in a correctly wired pipeline; it exists to catch a future
+ * regression that lets the two derivations drift apart, the same role
+ * `checkRiskCoverageSemantics` plays for risk coverage. Never reads
+ * `process.env`, the filesystem, or the clock.
+ */
+export declare function checkDispositionCountsReconcileLedger(dispositionCounts: FinalDispositionCounts, ledger: readonly InputLedgerRow[]): DispositionLedgerReconciliationResult;
+/**
+ * Runs the full finalize envelope: `deriveFinalizeContext`, then
+ * `runReviewPipeline`, then the input ledger, review coverage, and
+ * synthesized-finding projections, then assembles the report projection
+ * both output kinds share. A `report-only` run returns that projection
+ * directly; every other mode also builds and parses the full
+ * `ReviewArtifactSchema` artifact, returning a rejection with the failing
+ * Zod path (never the message or input) and no partial output if it fails
+ * to parse. The whole result is parsed through `FinalizeOutputSchema`
+ * before returning. Any rejection from any step aborts the run with no
+ * partial output. Never reads `process.env`, the filesystem, or the clock.
+ */
+export declare function finalizeReview(input: FinalizeReviewInput): FinalizeReviewResult;
+export {};