@allocator-one/rcl 4.4.19

package/dist/dispatch/checkpoint.d.ts

@@ -0,0 +1,329 @@
+import { z } from 'zod';
+import { type VerificationIntent, type VerificationNotDispatched, type VerificationPlanInput, type VerificationResult, type VerificationState, type VerificationTerminal } from './checkpoint-verification.js';
+import { type NativeTargetOwnership } from '../converge/target-ownership.js';
+export declare const MAX_CHECKPOINT_PROOF_BYTES: number;
+declare const bindingNameSchema: z.ZodEnum<{
+    operation: "operation";
+    source: "source";
+    "captured-inputs": "captured-inputs";
+    launch: "launch";
+    "supplemental-async": "supplemental-async";
+}>;
+/** Strict raw blocking-review wire schema, shared by supplemental async capture. */
+export declare const blockingCheckpointReviewSchema: z.ZodObject<{
+    model: z.ZodString;
+    role: z.ZodString;
+    provider: z.ZodString;
+    findings: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        suggestedFix: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        severity: z.ZodEnum<{
+            critical: "critical";
+            important: "important";
+            minor: "minor";
+            nitpick: "nitpick";
+        }>;
+        category: z.ZodString;
+        locationProvenance: z.ZodOptional<z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            source: z.ZodLiteral<"parser">;
+            reason: z.ZodLiteral<"reversed_range">;
+            originalStartLine: z.ZodNumber;
+            originalEndLine: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    durationMs: z.ZodNumber;
+    status: z.ZodEnum<{
+        error: "error";
+        success: "success";
+        timeout: "timeout";
+        parse_failed: "parse_failed";
+        canceled: "canceled";
+    }>;
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    error: z.ZodOptional<z.ZodString>;
+    droppedFindings: z.ZodOptional<z.ZodNumber>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    async: z.ZodOptional<z.ZodLiteral<false>>;
+    adapterAttempts: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+declare const verificationLateRecordSchema: z.ZodObject<{
+    sequence: z.ZodNumber;
+    previousDigest: z.ZodString;
+    digest: z.ZodString;
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"late-verification-result">;
+    verificationTerminalDigest: z.ZodString;
+    result: z.ZodObject<{
+        batchIndex: z.ZodNumber;
+        attemptId: z.ZodString;
+        finishedAtMs: z.ZodNumber;
+        answerBytes: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CheckpointLateVerificationRecord = DeepReadonly<z.infer<typeof verificationLateRecordSchema>>;
+declare const lateRecordSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"late-result">;
+    planDigest: z.ZodString;
+    finalizationDigest: z.ZodString;
+    intentDigest: z.ZodString;
+    reviewSha256: z.ZodString;
+    reviewBytes: z.ZodString;
+    cell: z.ZodString;
+    paidAttempt: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            unknown: "unknown";
+            paid: "paid";
+        }>;
+    }, z.core.$strict>;
+    sequence: z.ZodNumber;
+    previousDigest: z.ZodString;
+    digest: z.ZodString;
+}, z.core.$strict>;
+export type CheckpointLane = 'blocking' | 'secondary';
+export interface CheckpointPlanInput {
+    /** Version1 is historical lane-less evidence; version2 binds every original lane. */
+    version?: 1 | 2;
+    target: string;
+    headSha: string;
+    mergeBaseSha: string;
+    patchSha256: string;
+    configSha256: string;
+    specSha256: string;
+    contextSha256: string;
+    toolsSha256: string;
+    parser: {
+        name: string;
+        version: number;
+    };
+    roster: Array<{
+        seat: string;
+        model: string;
+        role: string;
+        route: string;
+        lane?: CheckpointLane;
+    }>;
+    chunks: Array<{
+        index: number;
+        total: number;
+        digest: string;
+    }>;
+    prompts: Array<{
+        seat: string;
+        chunk: number;
+        systemSha256: string;
+        userSha256: string;
+    }>;
+}
+export interface CheckpointCell {
+    id: string;
+    seat: string;
+    chunk: number;
+    route: string;
+    model: string;
+    role: string;
+    chunkDigest: string;
+    systemPromptSha256: string;
+    userPromptSha256: string;
+}
+export interface FrozenCheckpointPlan extends CheckpointPlanInput {
+    version: 1 | 2;
+    cells: CheckpointCell[];
+    digest: string;
+}
+export interface PaidAttempt {
+    id: string;
+    kind: 'paid' | 'unknown';
+}
+export type CheckpointBindingName = z.infer<typeof bindingNameSchema>;
+export type CheckpointBindings = Partial<Record<CheckpointBindingName, string>>;
+export type CheckpointResult = {
+    kind: 'success';
+    chunk: number;
+    reviewBytes: string;
+} | {
+    kind: 'failure';
+    chunk: number;
+    reviewBytes: string;
+    possiblyBilled: boolean;
+};
+export interface JournalRecord {
+    sequence: number;
+    previousDigest: string;
+    digest: string;
+    type: 'binding' | 'intent' | 'result' | 'uncertain' | 'finalization';
+    binding?: {
+        name: CheckpointBindingName;
+        file: string;
+        sha256: string;
+    };
+    cell?: string;
+    paidAttempt?: PaidAttempt;
+    result?: {
+        kind: 'success' | 'failure';
+        chunk: number;
+        reviewSha256: string;
+        resultFile: string;
+        possiblyBilled?: boolean;
+    };
+    reason?: string;
+    finalizedDigest?: string;
+}
+export interface CheckpointState {
+    records: JournalRecord[];
+    outcomes: Array<{
+        cell: string;
+        paidAttempt: PaidAttempt;
+        result: CheckpointResult;
+    }>;
+    successes: Array<{
+        cell: string;
+        paidAttempt: PaidAttempt;
+        reviewBytes: string;
+    }>;
+    uncertain: Array<{
+        cell: string;
+        paidAttempt: PaidAttempt;
+    }>;
+    finalized: boolean;
+}
+type DeepReadonly<T> = T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+export type CheckpointLateAuditRecord = DeepReadonly<z.infer<typeof lateRecordSchema>>;
+export interface TerminalCheckpointReport {
+    readonly reportBytes: string;
+    readonly reviewerArtifactBytes: string;
+    readonly reportSha256: string;
+    readonly reviewerArtifactSha256: string;
+}
+export type CheckpointProof = DeepReadonly<{
+    version: 1;
+    bytes: string;
+    digest: string;
+    plan: FrozenCheckpointPlan;
+    state: CheckpointState;
+    bindings: CheckpointBindings;
+}>;
+export declare function checkpointPath(commonDir: string, target: string, namespace: string): string;
+export declare function freezeCheckpointPlan(input: CheckpointPlanInput): FrozenCheckpointPlan;
+/** Original seat IDs, never merged model-role opinions, define retained quorum. */
+export declare function blockingCheckpointSeatIds(plan: FrozenCheckpointPlan): string[];
+/** Keep wire cells unchanged; bind internal eligibility to their immutable roster lane. */
+export declare function checkpointRecoveryCells(plan: FrozenCheckpointPlan): Array<CheckpointCell & {
+    lane: CheckpointLane;
+}>;
+/** Old bytes remain inspectable, but cannot authorize a new retained operation. */
+export declare function requireReviewerLaneBinding(plan: FrozenCheckpointPlan): void;
+/** Structural integrity only: this brand does not attest providers or source authority. */
+export declare function isCheckpointProof(value: unknown): value is CheckpointProof;
+/** Decode canonical portable bytes using the same plan, chain and outcome validation as disk reads. */
+export declare function decodeCheckpointProof(bytes: string, expectedPlan?: FrozenCheckpointPlan | CheckpointProof['plan']): CheckpointProof;
+/** Export only a validated sealed journal. No live provider or lineage authority is inferred. */
+export declare function exportCheckpointProof(journal: CheckpointJournal): Promise<CheckpointProof>;
+export declare class CheckpointJournal {
+    private readonly path;
+    private readonly plan;
+    private readonly commonDir?;
+    private needsResync;
+    private verificationAcknowledgment?;
+    private verificationPrefixCache?;
+    private constructor();
+    static create(input: {
+        commonDir: string;
+        namespace: string;
+        plan: FrozenCheckpointPlan;
+        ownership: NativeTargetOwnership;
+    }): Promise<CheckpointJournal>;
+    static openRead(path: string, expected: FrozenCheckpointPlan): Promise<CheckpointJournal>;
+    /**
+     * Structural inspection only: validate the stored plan and complete history.
+     * This supplies no freshness, source authority or recovery eligibility proof.
+     * Callers needing an expected input binding must still use openRead(expected).
+     */
+    static inspectRead(path: string): Promise<CheckpointJournal>;
+    static openWrite(input: {
+        commonDir: string;
+        namespace: string;
+        plan: FrozenCheckpointPlan;
+        ownership: NativeTargetOwnership;
+    }): Promise<CheckpointJournal>;
+    getPlan(): FrozenCheckpointPlan;
+    read(): Promise<CheckpointState>;
+    /** Exact immutable metadata bytes; validates the entire journal without writing. */
+    readBindings(): Promise<CheckpointBindings>;
+    /**
+     * Freeze a distinct, explicitly capped verifier phase after reviewer sealing.
+     * This storage contract never expands reviewer-cell caps or establishes spend,
+     * capture, provider or server authority. The executor must regenerate the plan
+     * from validated captures, authorize its separate cap and disable SDK retries.
+     */
+    beginVerification(input: VerificationPlanInput, ownership: NativeTargetOwnership): Promise<void>;
+    /**
+     * True only for a newly durable intent. False means a prior intent exists and
+     * must NEVER be launched again, even when its first fsync acknowledgment failed.
+     * A true result is a storage claim, not independent provider launch authority.
+     */
+    recordVerificationIntent(input: VerificationIntent, ownership: NativeTargetOwnership, afterIntent?: (intent: VerificationIntent) => VerificationNotDispatched | void): Promise<boolean>;
+    /** Late verifier answers are audit-only and never change the sealed verifier proof. */
+    readLateVerificationAudit(): Promise<readonly CheckpointLateVerificationRecord[]>;
+    recordLateVerificationResult(input: VerificationResult, ownership: NativeTargetOwnership): Promise<void>;
+    private readLateVerificationAuditValidated;
+    /** Exact observed adapter bytes; failed/late answers remain physical history. */
+    recordVerificationResult(input: VerificationResult, ownership: NativeTargetOwnership): Promise<void>;
+    /** A terminal storage outcome, never a finding verdict or approval. */
+    finalizeVerification(input: VerificationTerminal, ownership: NativeTargetOwnership): Promise<void>;
+    readVerification(): Promise<VerificationState | undefined>;
+    exportVerificationProof(): Promise<{
+        bytes: string;
+        digest: string;
+    }>;
+    private verificationContext;
+    private readVerificationValidated;
+    private readVerificationValidatedForAppend;
+    private appendVerification;
+    /**
+     * Retain opaque terminal bytes after sealing, under the caller's ownership.
+     * Exact orphan payloads can resume; no existing bytes are replaced. The final
+     * manifest publishes the pair and does not confer producer authority.
+     */
+    retainTerminalReport(input: {
+        reportBytes: string;
+        reviewerArtifactBytes: string;
+    }, ownership: NativeTargetOwnership): Promise<void>;
+    /** Exact private payloads only after complete publication; no report semantics are inferred. */
+    readTerminalReport(): Promise<TerminalCheckpointReport | undefined>;
+    private terminalReportEntries;
+    private readTerminalReportValidated;
+    /** Late observations are audit-only and never enter the sealed main proof or accounting. */
+    readLateAudit(): Promise<readonly CheckpointLateAuditRecord[]>;
+    private readLateAuditValidated;
+    private syncLateRecord;
+    /** Caller retains live original ownership while draining; no ownership is created here. */
+    recordLateResult(cell: string, paidAttempt: PaidAttempt, rawReviewBytes: string, ownership: NativeTargetOwnership): Promise<void>;
+    exportProof(): Promise<CheckpointProof>;
+    private readValidated;
+    private write;
+    private syncRecord;
+    private syncHistory;
+    private append;
+    private cell;
+    /** Bind opaque UTF-8 bytes before work begins. Identical replay re-establishes durability. */
+    bind(name: CheckpointBindingName, bytes: string, ownership: NativeTargetOwnership): Promise<void>;
+    recordIntent(cell: string, paidAttempt: PaidAttempt, ownership: NativeTargetOwnership): Promise<void>;
+    recordUncertain(cell: string, paidAttempt: PaidAttempt, reason: string, ownership: NativeTargetOwnership): Promise<void>;
+    recordResult(cell: string, paidAttempt: PaidAttempt, result: CheckpointResult, ownership: NativeTargetOwnership): Promise<void>;
+    finalize(ownership: NativeTargetOwnership): Promise<void>;
+}
+export {};