Durable execution

export declare class AwaitingDurableApproval extends Error {
    readonly approvalId: string;
    constructor(approvalId: string);
}

export interface DurableAction {
    id: string;
    preparedHash: string;
    connectorVersion: string;
    destination: string;
    args: DurableJSON;
    policyRevision: number;
    grantRefs: string[];
    idempotencyKey: string;
    state: DurableActionState;
    approvalId?: string;
    dispatchFence?: number;
    resultRef?: string;
    evidenceRef?: string;
}

export interface DurableActionConnector {
    /** Scoped host binding, including action implementation version. */
    version: string;
    dispatch(action: Readonly<DurableAction>, signal?: AbortSignal): Promise<{
        resultRef: string;
    }>;
    /** 'absent' must prove no effect can still occur; a transient 404 is insufficient. */
    reconcile?(action: Readonly<DurableAction>): Promise<{
        outcome: "confirmed";
        resultRef: string;
        evidenceRef: string;
    } | {
        outcome: "absent" | "unknown";
        evidenceRef: string;
    }>;
}

export interface DurableActionInput {
    id: string;
    connectorVersion: string;
    destination: string;
    args: DurableJSON;
    approval?: {
        actorId: string;
        expiresAt: number;
    };
}

/** Every dispatch is preceded by an atomic persisted intent. Not exactly-once execution. */
export declare class DurableActionLedger {
    readonly store: DurableTaskStore;
    readonly key: DurableTaskKey;
    readonly fence: DurableFence;
    readonly signal?: AbortSignal | undefined;
    quiesce(): Promise<void>;
    execute(input: DurableActionInput, connector: DurableActionConnector): Promise<{
        resultRef: string;
    }>;
    constructor(store: DurableTaskStore, key: DurableTaskKey, fence: DurableFence, signal?: AbortSignal | undefined);
    prepare(input: DurableActionInput): Promise<DurableAction>;
    reconcile(actionId: string, connector: DurableActionConnector): Promise<DurableAction>;
    /** Trusted host approval endpoint must authenticate/authorize the supplied actor. */
    static decide(store: DurableTaskStore, key: DurableTaskKey, input: {
        approvalId: string;
        actorId: string;
        preparedHash: string;
        approved: boolean;
    }): Promise<void>;
}

export type DurableActionState = "prepared" | "awaiting_approval" | "executing" | "confirmed" | "unknown" | "rejected" | "canceled";

export interface DurableApproval {
    id: string;
    actionId: string;
    actorId: string;
    preparedHash: string;
    policyRevision: number;
    expiresAt: number;
    decision: "pending" | "approved" | "denied";
    consumed: boolean;
}

export interface DurableArtifactReference {
    id: string;
    blobKey: string;
    digest: string;
    bytes: number;
    mimeType: string;
    expiresAt: number;
}

export interface DurableAttempt {
    id: string;
    workerId: string;
    fence: number;
    startedAt: number;
}

/** Host-owned object storage. put must never replace different bytes at an existing key. */
export interface DurableBlobStore {
    readonly durable: boolean;
    put(key: string, bytes: Uint8Array): Promise<void>;
    get(key: string): Promise<Uint8Array | null>;
    delete(key: string): Promise<void>;
}

export declare function durableCanonical(value: unknown): string;

export declare class DurableConflictError extends Error {
    constructor(message?: string);
}

export declare const durableDigest: (value: unknown) => string;

/** Host-owned Mongo collection; callers configure majority+journal acknowledgement. */
export interface DurableDocumentCollection {
    updateOne(filter: Record<string, unknown>, update: Record<string, unknown>, options: Record<string, unknown>): Promise<unknown>;
    findOne(filter: Record<string, unknown>): Promise<Record<string, unknown> | null>;
}

export declare class DurableEventGapError extends Error {
    readonly earliest: number;
    readonly latest: number;
    constructor(earliest: number, latest: number);
}

export interface DurableExecutionContext {
    task: DurableTaskRecord;
    lease: DurableLease;
    signal: AbortSignal;
    actions: DurableActionLedger;
    reserve(tokens: number, costMicros: number): Promise<void>;
}

export interface DurableFence {
    workerId: string;
    fence: number;
}

export interface DurableIdentity {
    tenantId: string;
    actorId: string;
    sessionId: string;
    runId: string;
    rootRunId: string;
    parentRunId?: string;
}

export type DurableJSON = null | boolean | number | string | DurableJSON[] | {
    [key: string]: DurableJSON;
};

export interface DurableLease {
    workerId: string;
    fence: number;
    expiresAt: number;
}

export declare class DurableLeaseError extends DurableConflictError {
    constructor();
}

export interface DurableReader {
    tenantId: string;
    actorId: string;
}

export declare class DurableRecoveryRequiredError extends Error {
    constructor();
}

export interface DurableRunEvent {
    sequence: number;
    type: string;
    at: number;
    attemptId: string | null;
    data: DurableJSON;
}

/** A single task aggregate holds sequenced events and immutable object references.
 * Blobs are written first: a failed fenced reference commit can leave an orphan blob,
 * never a committed reference to bytes that have not been stored. Hosts own orphan GC.
 */
export declare class DurableRunRecords {
    readonly store: DurableTaskStore;
    constructor(store: DurableTaskStore, blobs: DurableBlobStore, options?: {
        maxEvents?: number;
        maxEventBytes?: number;
        maxArtifactBytes?: number;
        now?: () => number;
    });
    append(key: DurableTaskKey, fence: DurableFence, type: string, data: DurableJSON): Promise<DurableRunEvent>;
    events(key: DurableTaskKey, identity: DurableReader, after?: number): Promise<DurableRunEvent[]>;
    putArtifact(key: DurableTaskKey, fence: DurableFence, artifact: {
        id: string;
        bytes: Uint8Array;
        mimeType: string;
        ttlMs: number;
    }): Promise<DurableArtifactReference>;
    artifact(key: DurableTaskKey, identity: DurableReader, id: string): Promise<Uint8Array>;
    checkpoint(key: DurableTaskKey, fence: DurableFence, id: string, snapshot: DurableJSON, ttlMs: number): Promise<string>;
    snapshot(key: DurableTaskKey, identity: DurableReader, id: string): Promise<DurableJSON>;
}

/** Stable admitted definition, excluding mutable extension/audit state. */
export declare function durableTaskDefinition(input: DurableTaskInput): DurableTaskInput;

export declare const durableTaskDigest: (input: DurableTaskInput) => string;

export type DurableTaskHandler = (context: DurableExecutionContext) => Promise<{
    state?: "completed" | "stopped";
    resultRef?: string;
} | void>;

export interface DurableTaskInput {
    id: string;
    identity: DurableIdentity;
    manifestHash: string;
    inputRef: string;
    policyRevision: number;
    grantRefs: string[];
    driver?: {
        id: string;
        version: number;
    };
    input?: DurableJSON;
    budget?: {
        maxAttempts?: number;
        maxTokens?: number;
        maxCostMicros?: number;
    };
    extensions?: Record<string, DurableJSON>;
}

export interface DurableTaskKey {
    tenantId: string;
    taskId: string;
}

export interface DurableTaskRecord extends Omit<DurableTaskInput, "extensions" | "budget"> {
    schemaVersion: 1;
    state: DurableTaskState;
    revision: number;
    fence: number;
    createdAt: number;
    updatedAt: number;
    lease?: DurableLease;
    attempts: DurableAttempt[];
    budget: {
        maxAttempts: number;
        maxTokens: number;
        maxCostMicros: number;
    };
    reservedTokens: number;
    reservedCostMicros: number;
    actions: Record<string, DurableAction>;
    approvals: Record<string, DurableApproval>;
    extensions: Record<string, DurableJSON>;
    resultRef?: string;
    failure?: string;
    cancelReason?: string;
}

export type DurableTaskState = "queued" | "running" | "awaiting_approval" | "cancel_requested" | "completed" | "failed" | "canceled" | "stopped";

/** Trusted host API. Tenant IDs must come from verified admission, never payload claims.
 * Updates are atomic within ONE bounded task aggregate; no cross-task transactions.
 */
export interface DurableTaskStore {
    readonly capabilities: {
        durable: boolean;
        atomicTaskUpdates: true;
        compareAndSet: true;
        fencing: true;
        durableOutbox: boolean;
    };
    create(input: DurableTaskInput): Promise<DurableTaskRecord>;
    get(key: DurableTaskKey): Promise<DurableTaskRecord | null>;
    /** Pure synchronous callback; CAS conflicts can cause re-evaluation. No network/effects here. */
    update(key: DurableTaskKey, mutate: (draft: DurableTaskRecord, now: number) => void, guard?: DurableFence): Promise<DurableTaskRecord>;
}

/** Leases fence local commits, not requests already sent to external connectors. */
export declare class DurableTaskSupervisor {
    readonly store: DurableTaskStore;
    readonly leaseMs: number;
    constructor(store: DurableTaskStore, options?: {
        leaseMs?: number;
        pollMs?: number;
    });
    create(input: DurableTaskInput): Promise<DurableTaskRecord>;
    get(key: DurableTaskKey): Promise<DurableTaskRecord | null>;
    claim(key: DurableTaskKey, workerId: string): Promise<DurableTaskRecord | null>;
    renew(key: DurableTaskKey, lease: DurableFence): Promise<DurableTaskRecord>;
    release(key: DurableTaskKey, lease: DurableFence): Promise<void>;
    cancel(key: DurableTaskKey, reason?: string): Promise<DurableTaskRecord>;
    acknowledgeCancellation(key: DurableTaskKey, lease: DurableFence): Promise<DurableTaskRecord>;
    run(key: DurableTaskKey, workerId: string, execute: DurableTaskHandler): Promise<DurableTaskRecord>;
}

/** Local deterministic adapter. Never advertises process-crash durability. */
export declare class InMemoryDurableTaskStore implements DurableTaskStore {
    readonly capabilities: {
        readonly durable: false;
        readonly atomicTaskUpdates: true;
        readonly compareAndSet: true;
        readonly fencing: true;
        readonly durableOutbox: false;
    };
    constructor(options?: {
        now?: () => number;
        maxBytes?: number;
    });
    create(input: DurableTaskInput): Promise<DurableTaskRecord>;
    get(key: DurableTaskKey): Promise<DurableTaskRecord | null>;
    update(key: DurableTaskKey, mutate: (draft: DurableTaskRecord, now: number) => void, guard?: DurableFence): Promise<DurableTaskRecord>;
}

export declare const isDurableTerminal: (state: DurableTaskState) => boolean;

/** Add lifecycle events in the SAME atomic update as task state. Use this wrapped
 * store for both the supervisor and record services to retain one authoritative log. */
export declare class JournaledDurableTaskStore implements DurableTaskStore {
    readonly capabilities: DurableTaskStore["capabilities"];
    constructor(inner: DurableTaskStore, maxEvents?: number);
    create(input: DurableTaskInput): Promise<DurableTaskRecord>;
    get(key: DurableTaskKey): Promise<DurableTaskRecord | null>;
    update(key: DurableTaskKey, mutate: (draft: DurableTaskRecord, now: number) => void, guard?: DurableFence): Promise<DurableTaskRecord>;
}

/** Append-only Mongo document effect with an atomic unique _id and readable receipt.
 * Destination is host-bound. It does not provide email/payment idempotency.
 */
export declare class MongoDBDurableDocumentConnector implements DurableActionConnector {
    readonly version = "mongodb-document@1";
    constructor(collection: DurableDocumentCollection, destination: string);
    dispatch(action: Readonly<DurableAction>, signal?: AbortSignal): Promise<{
        resultRef: string;
    }>;
    reconcile(action: Readonly<DurableAction>): Promise<{
        outcome: "confirmed";
        resultRef: string;
        evidenceRef: string;
    } | {
        outcome: "unknown";
        evidenceRef: string;
    }>;
}

/** Single-document CAS adapter: task, action ledger and extension outbox commit together.
 * No cross-task transaction guarantee. MongoDB must provide majority+journal writes.
 */
export declare class MongoDBDurableTaskStore implements DurableTaskStore {
    readonly capabilities: {
        readonly durable: true;
        readonly atomicTaskUpdates: true;
        readonly compareAndSet: true;
        readonly fencing: true;
        readonly durableOutbox: true;
    };
    constructor(uri: string, options?: {
        database?: string;
        collection?: string;
        maxBytes?: number;
        maxConflicts?: number;
    });
    initialize(): Promise<void>;
    create(input: DurableTaskInput): Promise<DurableTaskRecord>;
    get(key: DurableTaskKey): Promise<DurableTaskRecord | null>;
    update(key: DurableTaskKey, mutate: (draft: DurableTaskRecord, now: number) => void, guard?: DurableFence): Promise<DurableTaskRecord>;
    close(): Promise<void>;
}

/** Immutable content storage for bounded artifacts. Clients are optional and loaded
 * only on construction. Use a dedicated collection; Mongo's _id index is the CAS. */
export declare class MongoDurableBlobStore implements DurableBlobStore {
    readonly durable = true;
    constructor(uri: string, options?: {
        database?: string;
        collection?: string;
        maxBytes?: number;
    });
    initialize(): Promise<void>;
    put(key: string, bytes: Uint8Array): Promise<void>;
    get(key: string): Promise<Uint8Array | null>;
    delete(key: string): Promise<void>;
    close(): Promise<void>;
}