ai-foreman 1.7.28 → 2.0.0

package/dist/workflowDb.d.ts

@@ -1,3 +1,5 @@
+import { type CheckpointOrigin } from "./continuityOrigin.js";
+import { type SealedDispatchRecordV2 } from "./structuredDispatchRecord.js";
 import { type GraphDerivedAccess } from "./graph/derived.js";
 import { QaPreparationStore } from "./qaPreparationStore.js";
 import { GraphStore } from "./graph/storage.js";
@@ -84,6 +86,10 @@ export interface RoleMutationLease {
     sessionKey?: string;
     movedAt: string;
 }
+export interface FreshRecoveryValidation {
+    decisionDigest: string;
+    predecessor: RoleMutationLease;
+}
 export interface QaRecoveryHeadRecord {
     runId: string;
     ticketId: string;
@@ -235,8 +241,8 @@ export declare class WorkflowDb {
         text: string;
         ids: string[];
     };
-    verifyBuilderGuidance(ids: string[], certificate: Parameters<typeof verifyBuilderGuidance>[2], response: string, receiptDigest: string): void;
-    verifyGuidance(ids: string[], certificate: Parameters<typeof verifyGuidance>[2], response: string): void;
+    verifyBuilderGuidance(ids: string[], certificate: Parameters<typeof verifyBuilderGuidance>[2], response: string | readonly string[], receiptDigest: string): void;
+    verifyGuidance(ids: string[], certificate: Parameters<typeof verifyGuidance>[2], response: string | readonly string[]): void;
     hasQueuedBuilderGuidance(runId: string, workId: string): boolean;
     instruction(id: string): import("./buildInterventions.js").BuildInstruction | undefined;
     assertFinalizationControls(runId: string, workId: string): void;
@@ -368,6 +374,7 @@ export declare class WorkflowDb {
         sessionKey?: string;
     }, now?: Date): ContinuityEvent;
     continuityEvents(runId: string, afterSequence?: number): ContinuityEvent[];
+    providerCheckpoint(dispatchId: string, publicationKind: string): ContinuityCheckpoint | undefined;
     publishContinuityCheckpoint(input: {
         runId: string;
         role: "builder" | "qa";
@@ -376,6 +383,9 @@ export declare class WorkflowDb {
         authoritativeStateRevision: number;
         sessionRef?: ProviderSessionRefV1;
         sessionKey?: string;
+        origin?: CheckpointOrigin;
+        hostEventKind?: "role-baseline" | "operator-recovery" | "source-reconciliation";
+        inputCheckpointDigests?: string[];
     }, now?: Date): ContinuityCheckpoint;
     continuityCheckpoints(runId: string, role?: "builder" | "qa"): ContinuityCheckpoint[];
     latestContinuityCheckpoint(runId: string, role: "builder" | "qa"): ContinuityCheckpoint | undefined;
@@ -428,6 +438,41 @@ export declare class WorkflowDb {
         kind: string;
         intent: unknown;
     }, now?: Date): OperationRecord;
+    /** Seal a previously persisted non-authoritative preparation intent.  This
+     * is intentionally legal only before provider content dispatch begins. */
+    sealPlannedOperationIntent(idempotencyKey: string, intent: unknown, now?: Date): OperationRecord;
+    /** Called in the gateway's sealing transaction, before the send capability exists. */
+    sealStructuredOwnerDispatch(key: string, tuple: import("rafi-spec").SelectedDispatchTupleV2, renderedInstruction: string): void;
+    structuredOwnerDispatch(key: string): SealedDispatchRecordV2;
+    assertStructuredDispatchAdmission(runId: string, dispatchId: string, parentId: string | undefined, operation: string): void;
+    beginStructuredHandoff(predecessorId: string): void;
+    linkStructuredHandoffDispatch(dispatchId: string, parentId: string | undefined, operation: string): void;
+    planStructuredContinuation(predecessorId: string, successor: ProviderSessionRefV1): string;
+    structuredContinuation(runId: string, role: "builder" | "qa"): {
+        predecessorId: string;
+        continuationId: string;
+        state: string;
+        successor: ProviderSessionRefV1;
+    } | undefined;
+    finishStructuredContinuation(dispatchId: string): void;
+    private assertAcceptedStructuredSuccessor;
+    requireStructuredPostprocessing(dispatchId: string, context: unknown): void;
+    structuredProcessingContext(dispatchId: string): {
+        instruction: string;
+        policy: import("./adapters/types.js").TurnRequest;
+    };
+    failStructuredPostprocessing(dispatchId: string, error: string): void;
+    completeStructuredPostprocessing(dispatchId: string): void;
+    pendingStructuredPostprocessing(runId: string): string[];
+    retainedStructuredTurn(dispatchId: string): import("./adapters/types.js").TurnResult;
+    /** A claim is never recycled, even if transport fails before writing bytes. */
+    claimStructuredSubmission(tuple: import("rafi-spec").SelectedDispatchTupleV2, session?: ProviderSessionRefV1): string;
+    consumeStructuredSubmission(tuple: import("rafi-spec").SelectedDispatchTupleV2, claimId: string, session?: ProviderSessionRefV1): void;
+    assertNativeRunAdmission(runId: string): void;
+    recordCommunicationEvidenceRefs(ownerId: string, digests: string[]): void;
+    replayStructuredDispatch<T>(key: string, contract: import("rafi-spec").OutputContract<T>): T;
+    private assertStructuredProviderTurn;
+    private verifyRetainedStructuredDispatch;
     updateOperation(idempotencyKey: string, status: OperationLifecycle, details?: {
         result?: unknown;
         externalId?: string;
@@ -438,6 +483,38 @@ export declare class WorkflowDb {
     operation(idempotencyKey: string): OperationRecord | undefined;
     operations(runId: string): OperationRecord[];
     putEvidence(kind: "handoff" | "diff" | "test" | "qa", value: string | Buffer, now?: Date): string;
+    /** Create an append-only provider page artifact before its first dispatch. */
+    populationPageRecords(artifactId: string): string[];
+    populationPageLedger(artifactId: string): {
+        tupleDigest: string;
+        state: string;
+        pageCount: number;
+    } | undefined;
+    beginPageLedger(input: {
+        artifactId: string;
+        runId: string;
+        lineageId: string;
+        tupleDigest: string;
+        leaseId: string;
+    }, now?: Date): void;
+    /**
+     * Atomically appends a page.  Duplicate delivery is accepted only when every
+     * immutable byte and linkage field agrees; a provider cannot fill gaps,
+     * rewrite history, or append after the terminal page.
+     */
+    appendPageLedger(input: {
+        artifactId: string;
+        lineageId: string;
+        tupleDigest: string;
+        leaseId: string;
+        ordinal: number;
+        predecessorDigest: string | null;
+        content: string;
+        terminal: boolean;
+    }, now?: Date): {
+        digest: string;
+        duplicate: boolean;
+    };
     registerGraphEvidence(value: string | Buffer, access: GraphDerivedAccess | GraphDerivedAccess[]): void;
     getEvidence(digest: string): Buffer | undefined;
     putQaRecoveryHead(input: Omit<QaRecoveryHeadRecord, "updatedAt">, now?: Date): QaRecoveryHeadRecord;
@@ -504,6 +581,12 @@ export declare class WorkflowDb {
     }, expectedRevision: number, now?: Date): QaReducerStateV2;
     recordQaHandoffReceipt(receipt: HandoffAcceptanceReceiptV2): void;
     qaHandoffReceipt(operationId: string): HandoffAcceptanceReceiptV2 | undefined;
+    /**
+     * Structured authority is admitted only after the one-way v2 cutover has
+     * committed.  Keeping this at the common admission boundary prevents a
+     * caller that opens WorkflowDb directly from bypassing the migration.
+     */
+    enableStructuredCommunication(): void;
     beginQaTurn(intent: QaTurnIntentV2): void;
     /** Retire an interrupted, proven read-only review transport, never a QA pass
      * or Builder remediation. A fresh immutable review must still run afterward. */
@@ -535,8 +618,10 @@ export declare class WorkflowDb {
     authorizeContractQaWaiver(runId: string, workId: string, decisionId: string): string;
     commitQaWaiver(runId: string, ticketId: string, expectedRevision: number, reason: string, now?: Date, authorizationRef?: string): QaReducerStateV2;
     builderRemediationReceipt(operationId: string): BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3 | undefined;
+    verifiedBuilderRemediationReceipt(operationId: string): BuilderRemediationReceiptV3 | undefined;
     hasConfirmedQaRemediationForRecheck(runId: string, ticketId: string): boolean;
     recordBuilderRemediationReceipt(receipt: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3): void;
+    private assertBuilderRemediationReceipt;
     commitBuilderRemediationSuccess(receipt: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3, expectedRevision: number, now?: Date): QaReducerStateV2;
     commitQaRemediationOutcome(input: {
         recoveryAttemptId: string;
@@ -548,6 +633,7 @@ export declare class WorkflowDb {
         receipt?: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3;
         expectedRevision: number;
     }, now?: Date): QaReducerStateV2;
+    private assertNativeQaCertificate;
     private assertContractCertificate;
     issueQaPassCertificate(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, now?: Date): QaPassCertificateV2;
     commitQaPass(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, expectedRevision: number, now?: Date): QaPassCertificateV2;
@@ -574,6 +660,7 @@ export declare class WorkflowDb {
         expectedRevision: number;
         operationId: string;
     }, now?: Date): QaReducerStateV2;
+    assertQaFinalizationAuthority(runId: string, ticketId: string): void;
     planQaFinalizationStep(input: {
         operationId: string;
         runId: string;
@@ -636,6 +723,9 @@ export declare class WorkflowDb {
     compactionAttempt(idempotencyKey: string): CompactionAttemptRecord | undefined;
     unresolvedCompactions(runId: string, role: "builder" | "qa", sessionKey: string): CompactionAttemptRecord[];
     successfulCompactionCount(runId: string, role: "builder" | "qa", providerSession?: string | ProviderSessionRefV1): number;
+    freshRecoveryValidation(runId: string, role: "builder" | "qa"): FreshRecoveryValidation;
+    /** This grants one response-only initialization, never ownership or business work. */
+    assertFreshRecoveryValidation(dispatchId: string, session: ProviderSessionRefV1): void;
     recordRecoveryDecision(receipt: BuildRecoveryDecisionReceipt): void;
     recoveryDecisions(runId: string): BuildRecoveryDecisionReceipt[];
     /**
@@ -663,5 +753,13 @@ export declare class WorkflowDb {
     private refreshRunContinuityHead;
     private insertEvent;
     private migrate;
+    /**
+     * One-way cutover fence.  We deliberately do not attempt to convert an old
+     * receipt into authority: any pre-existing run with legacy state or a
+     * provider dispatch that lacks a sealed tuple is terminally superseded.
+     * User/project artifacts remain in their own tables; only workflow authority
+     * is fenced.  The marker is committed atomically with the classification.
+     */
+    private applyStructuredCommunicationV2Cutover;
     private ensureColumn;
 }