ai-foreman 1.7.13 → 1.7.14

package/dist/workflowDb.d.ts

@@ -1,5 +1,6 @@
-import type { BuildRecoveryDecisionReceipt, ContextSample, ContinuityCheckpoint, ContinuityDelta, ContinuityEvent, ContinuityHead, ContinuityHeadState, HandoffLineage, HandoffManifestV1, LiveSettingsAcknowledgment, OperationLifecycle, PendingHumanDecision, ProviderSessionRefV1, RecoveryAttemptOutcome, RecoveryAttemptReceipt, ResolvedAutonomyPolicy, ResolvedAgentSettings, SessionUsageSample, StructuredInterruption, SupervisorState, WorkflowIssue } from "rafi-spec";
+import type { BuildRecoveryDecisionReceipt, ContextSample, ContinuityCheckpoint, ContinuityDelta, ContinuityEvent, ContinuityHead, ContinuityHeadState, HandoffLineage, HandoffAcceptanceReceiptV1, HandoffManifestV1, LiveSettingsAcknowledgment, OperationLifecycle, PendingHumanDecision, ProviderSessionRefV1, RecoveryAttemptOutcome, RecoveryAttemptReceipt, ResolvedAutonomyPolicy, ResolvedAgentSettings, SessionUsageSample, StructuredInterruption, SupervisorState, WorkflowIssue } from "rafi-spec";
 import type { BranchResumeSession } from "./branch/resume.js";
+import { type BuilderRemediationReceiptV2, type FrozenQaSourceStateV2, type HandoffAcceptanceReceiptV2, type QaPassCertificateV2, type QaReducerEventV2, type QaReducerStateV2, type QaReportDisposition, type QaReviewBasisV2, type QaTurnIntentV2, type QaTurnReceiptV2 } from "./qaProtocolV2.js";
 export declare const WORKFLOW_DB_FILE = ".rafi/recovery.sqlite3";
 export type WorkflowKind = "plan" | "ticket-plan" | "ticket-populate" | "uninstall" | "build" | "qa-remediation" | "recovery" | "legacy";
 export type WorkflowRunStatus = "running" | "paused" | "blocked" | "completed" | "failed" | "cancelled" | "superseded";
@@ -74,6 +75,121 @@ export interface RoleMutationLease {
     sessionKey?: string;
     movedAt: string;
 }
+export interface QaRecoveryHeadRecord {
+    runId: string;
+    ticketId: string;
+    packetId: string;
+    packetPath: string;
+    packetDigest: string;
+    reviewedStateDigest: string;
+    revision: number;
+    correctionTurns: number;
+    pendingAction: string;
+    updatedAt: string;
+}
+export interface QaPacketProjectionRecord {
+    runId: string;
+    ticketId: string;
+    packetRevision: number;
+    packetDigest: string;
+    path: string;
+    /** Exact canonical manifest bytes needed to finish an interrupted filesystem publication. */
+    manifestJson?: string;
+    status: "intended" | "published";
+    createdAt: string;
+}
+export interface QaFinalizationStepRecord {
+    operationId: string;
+    runId: string;
+    ticketId: string;
+    certificateId: string;
+    kind: string;
+    status: "intended" | "completed" | "invalidated";
+    intent: {
+        expectedSourceStateDigest: string;
+        expectedGitTree: string;
+        allowedProjectionPaths: string[];
+        reducerRevision: number;
+    };
+    receipt?: unknown;
+}
+export interface QaReviewAttemptRecord {
+    attemptId: string;
+    runId: string;
+    ticketId: string;
+    reviewNumber: number;
+    cycle: number;
+    remediationGeneration: number;
+    sourceDigest: string;
+    status: "started" | "passed" | "failed" | "interrupted";
+    reportDigest?: string;
+    findingIds?: string[];
+    namespacedFindingIds?: string[];
+    detail?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface QaRemediationAttemptRecord {
+    attemptId: string;
+    runId: string;
+    ticketId: string;
+    reviewAttemptId: string;
+    generation: number;
+    mode: "validated-report" | "planner-remediation";
+    status: "intended" | "started" | "succeeded" | "failed" | "uncertain";
+    requestDigest: string;
+    responseDigest?: string;
+    summaryDigest?: string;
+    detail?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export type QaFailureHandoffState = "prepared" | "delivery-intended" | "delivery-uncertain" | "response-invalid" | "builder-blocked" | "remediation-reported" | "recheck-required" | "source-drift";
+export interface QaFailureHandoffRecord {
+    handoffId: string;
+    operationId: string;
+    runId: string;
+    ticketId: string;
+    reviewAttemptId: string;
+    reportDigest: string;
+    generation: number;
+    reviewedContentDigest: string;
+    reviewBasisDigest: string;
+    state: QaFailureHandoffState;
+    handoffDigest: string;
+    hostInstructionDigest: string;
+    builderSession?: ProviderSessionRefV1;
+    providerTurnId?: string;
+    receiptDigest?: string;
+    responseDigest?: string;
+    parsedResponseDigest?: string;
+    postSourceDigest?: string;
+    detail?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface QaTransitionRecordV2 {
+    sequence: number;
+    runId: string;
+    ticketId: string;
+    fromRevision: number;
+    toRevision: number;
+    event: QaReducerEventV2;
+    state: QaReducerStateV2;
+    createdAt: string;
+}
+export interface QaReportRecordV2 {
+    reportDigest: string;
+    runId: string;
+    ticketId: string;
+    reviewNumber: number;
+    sourceStateDigest: string;
+    reviewBasisDigest: string;
+    disposition: QaReportDisposition;
+    report: unknown;
+    createdAt: string;
+    updatedAt: string;
+}
 /** Authoritative persistence for every resumable workflow in a project. */
 export declare class WorkflowDb {
     readonly projectDir: string;
@@ -185,8 +301,135 @@ export declare class WorkflowDb {
     operations(runId: string): OperationRecord[];
     putEvidence(kind: "handoff" | "diff" | "test" | "qa", value: string | Buffer, now?: Date): string;
     getEvidence(digest: string): Buffer | undefined;
+    putQaRecoveryHead(input: Omit<QaRecoveryHeadRecord, "updatedAt">, now?: Date): QaRecoveryHeadRecord;
+    qaRecoveryHead(runId: string, ticketId?: string): QaRecoveryHeadRecord | undefined;
+    pendingQaRecoveryHeads(runId: string): QaRecoveryHeadRecord[];
+    beginQaReviewAttempt(input: Omit<QaReviewAttemptRecord, "status" | "createdAt" | "updatedAt">, now?: Date): QaReviewAttemptRecord;
+    finishQaReviewAttempt(attemptId: string, patch: Pick<QaReviewAttemptRecord, "status"> & Partial<Pick<QaReviewAttemptRecord, "reportDigest" | "findingIds" | "namespacedFindingIds" | "detail">>, now?: Date): QaReviewAttemptRecord;
+    qaReviewAttempts(runId: string, ticketId: string): QaReviewAttemptRecord[];
+    qaReviewAttempt(attemptId: string): QaReviewAttemptRecord | undefined;
+    beginQaRemediationAttempt(input: Omit<QaRemediationAttemptRecord, "status" | "createdAt" | "updatedAt">, now?: Date): QaRemediationAttemptRecord;
+    commitQaRemediationIntent(expectedRevision: number, recovery: RecoveryAttemptReceipt, remediation: Omit<QaRemediationAttemptRecord, "status" | "createdAt" | "updatedAt">, now?: Date): QaReducerStateV2;
+    updateQaRemediationAttempt(attemptId: string, status: QaRemediationAttemptRecord["status"], patch?: Partial<Pick<QaRemediationAttemptRecord, "responseDigest" | "summaryDigest" | "detail">>, now?: Date): QaRemediationAttemptRecord;
+    qaRemediationAttempts(runId: string, ticketId: string): QaRemediationAttemptRecord[];
+    qaRemediationAttempt(attemptId: string): QaRemediationAttemptRecord | undefined;
+    recordQaFailureHandoffPrepared(input: {
+        handoffId: string;
+        operationId: string;
+        runId: string;
+        ticketId: string;
+        reviewAttemptId: string;
+        reportDigest: string;
+        generation: number;
+        reviewedContentDigest: string;
+        reviewBasisDigest: string;
+        handoffDigest: string;
+        hostInstructionDigest: string;
+    }, now?: Date): QaFailureHandoffRecord;
+    markQaFailureHandoffDeliveryIntended(handoffId: string, builderSession: ProviderSessionRefV1, now?: Date): QaFailureHandoffRecord;
+    transitionQaFailureHandoff(handoffId: string, state: QaFailureHandoffState, patch?: Partial<Pick<QaFailureHandoffRecord, "builderSession" | "providerTurnId" | "receiptDigest" | "responseDigest" | "parsedResponseDigest" | "postSourceDigest" | "detail">>, now?: Date): QaFailureHandoffRecord;
+    qaFailureHandoff(handoffId: string): QaFailureHandoffRecord | undefined;
+    qaFailureHandoffs(runId: string, ticketId: string): QaFailureHandoffRecord[];
+    qaTicketHead(runId: string, ticketId: string): QaReducerStateV2;
+    pendingQaTicketHeads(runId: string): QaReducerStateV2[];
+    /** Compare-and-swap the authoritative QA reducer head and append its event atomically. */
+    transitionQa(runId: string, ticketId: string, expectedRevision: number, event: QaReducerEventV2, now?: Date): QaReducerStateV2;
+    qaTransitions(runId: string, ticketId: string): QaTransitionRecordV2[];
+    assertQaRunFinalizable(runId: string): void;
+    putQaSourceState(state: FrozenQaSourceStateV2): void;
+    putQaReviewBasis(runId: string, ticketId: string, basis: QaReviewBasisV2, now?: Date): void;
+    commitQaReviewReady(source: FrozenQaSourceStateV2, basis: QaReviewBasisV2, session: ProviderSessionRefV1, confinement: {
+        digest: string;
+    }, attempt: {
+        attemptId: string;
+        cycle: number;
+        remediationGeneration: number;
+    }, expectedRevision: number, now?: Date): QaReducerStateV2;
+    recordQaHandoffReceipt(receipt: HandoffAcceptanceReceiptV2): void;
+    qaHandoffReceipt(operationId: string): HandoffAcceptanceReceiptV2 | undefined;
+    beginQaTurn(intent: QaTurnIntentV2): void;
+    commitQaTurnIntent(intent: QaTurnIntentV2, expectedRevision: number): QaReducerStateV2;
+    finishQaTurn(receipt: QaTurnReceiptV2): void;
+    recordQaReport(input: Omit<QaReportRecordV2, "disposition" | "createdAt" | "updatedAt">, findingIds: string[], now?: Date): QaReportRecordV2;
+    commitQaFailure(input: Omit<QaReportRecordV2, "disposition" | "createdAt" | "updatedAt">, findingIds: string[], expectedRevision: number, now?: Date): QaReducerStateV2;
+    /** Accept a failed verdict, its exact attempt outcome, report, findings, and reducer edge atomically. */
+    commitQaFailureAttempt(attemptId: string, input: Omit<QaReportRecordV2, "disposition" | "createdAt" | "updatedAt">, rawFindingIds: string[], namespacedFindingIds: string[], detail: string, expectedRevision: number, now?: Date): QaReducerStateV2;
+    qaReportChains(reportDigest: string): Array<{
+        predecessorReportDigest: string;
+        successorReportDigest: string;
+        relation: string;
+        createdAt: string;
+    }>;
+    qaReport(reportDigest: string): QaReportRecordV2 | undefined;
+    unresolvedQaReports(runId: string, ticketId: string): QaReportRecordV2[];
+    setQaReportDisposition(reportDigest: string, disposition: QaReportDisposition, reason: string, now?: Date): void;
+    markQaReportsRecheckRequired(runId: string, ticketId: string, reason: string, now?: Date): void;
+    resolveQaReportsAfterPass(runId: string, ticketId: string, now?: Date): void;
+    commitQaWaiver(runId: string, ticketId: string, expectedRevision: number, reason: string, now?: Date): QaReducerStateV2;
+    recordBuilderRemediationReceipt(receipt: BuilderRemediationReceiptV2): void;
+    commitBuilderRemediationSuccess(receipt: BuilderRemediationReceiptV2, expectedRevision: number, now?: Date): QaReducerStateV2;
+    commitQaRemediationOutcome(input: {
+        recoveryAttemptId: string;
+        remediationAttemptId: string;
+        outcome: "succeeded" | "failed" | "uncertain";
+        detail?: string;
+        responseDigest?: string;
+        summaryDigest?: string;
+        receipt?: BuilderRemediationReceiptV2;
+        expectedRevision: number;
+    }, now?: Date): QaReducerStateV2;
+    issueQaPassCertificate(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, now?: Date): QaPassCertificateV2;
+    commitQaPass(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, expectedRevision: number, now?: Date): QaPassCertificateV2;
+    /** Accept a passing verdict, its review-attempt outcome, report resolution, certificate, and reducer edge atomically. */
+    commitQaPassAttempt(attemptId: string, input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, detail: string, expectedRevision: number, now?: Date): QaPassCertificateV2;
+    consumeQaPassCertificate(runId: string, ticketId: string, certificateId: string, consumer: string, now?: Date): QaPassCertificateV2;
+    invalidateUnconsumedQaPassCertificates(runId: string, ticketId: string, reason: string, now?: Date): void;
+    invalidateQaPassBeforeFinalization(input: {
+        runId: string;
+        ticketId: string;
+        certificateId: string;
+        expectedSourceStateDigest: string;
+        expectedRevision: number;
+        reason: string;
+    }, now?: Date): QaReducerStateV2;
+    beginQaFinalization(input: {
+        runId: string;
+        ticketId: string;
+        certificateId: string;
+        consumer: string;
+        expectedSourceStateDigest: string;
+        expectedGitTree: string;
+        allowedProjectionPaths: string[];
+        expectedRevision: number;
+        operationId: string;
+    }, now?: Date): QaReducerStateV2;
+    planQaFinalizationStep(input: {
+        operationId: string;
+        runId: string;
+        ticketId: string;
+        certificateId: string;
+        kind: string;
+        intent: unknown;
+    }, now?: Date): void;
+    finishQaFinalizationStep(operationId: string, receipt: unknown, now?: Date): void;
+    finishPendingQaFinalizationSteps(runId: string, ticketId: string, receipt: unknown, now?: Date): void;
+    qaFinalizationSteps(runId: string, ticketId: string): QaFinalizationStepRecord[];
+    invalidateQaFinalization(runId: string, ticketId: string, expectedRevision: number, reason: string, branch?: string, now?: Date): QaReducerStateV2;
+    completeQaFinalization(runId: string, ticketId: string, expectedRevision: number, receipt: unknown, now?: Date): QaReducerStateV2;
+    planQaPacketProjection(input: {
+        runId: string;
+        ticketId: string;
+        qaRevision: number;
+        packetDigest: string;
+        path: string;
+        manifestJson: string;
+    }, now?: Date): void;
+    finishQaPacketProjection(runId: string, ticketId: string, packetDigest: string): void;
+    qaPacketProjection(packetDigest: string): QaPacketProjectionRecord | undefined;
+    qaPacketProjectionsAtPath(path: string): QaPacketProjectionRecord[];
+    pendingQaPacketProjections(runId: string): QaPacketProjectionRecord[];
     stageHandoff(manifest: HandoffManifestV1, markdown: string): HandoffLineage;
-    acceptHandoff(runId: string, generation: number, successor: string | ProviderSessionRefV1, now?: Date): HandoffLineage;
+    acceptHandoff(runId: string, generation: number, successor: string | ProviderSessionRefV1, now?: Date, receipt?: HandoffAcceptanceReceiptV1): HandoffLineage;
     /** Fence the initial role owner without overwriting a lease already moved by a handoff. */
     claimInitialRoleLease(runId: string, role: "builder" | "qa", providerSession: string | ProviderSessionRefV1, now?: Date): RoleMutationLease;
     roleMutationLease(runId: string, role: "builder" | "qa"): RoleMutationLease | undefined;