intentdna 1.9.0 → 1.9.3

package/dist/runtime/push-driver.d.ts

@@ -0,0 +1,184 @@
+import type { AcquireAttemptRequest, AcquireAttemptResponse, AttemptExecutionSubmission, AttemptLease, AttemptView, AttachAttemptRequest, HeartbeatRequest, LeaseView, RunView, SettleDriverFailureRequest, SubmitAttemptRequest, SubmitResponse } from "./canonical-run-service.js";
+import type { DriverCapabilities, WorkerNode } from "./executable-run-plan.js";
+import type { ExecutionProvider } from "./execution-provider.js";
+import type { CanonicalAttemptOutcome, CanonicalEvidenceRef, CanonicalResultDigest, RunId, StepOutput, StepPacket, TerminalOutcome, WorkerSessionId } from "./run-contracts.js";
+import { type RunBindingPayload } from "./run-binding.js";
+import { executeWorkerAttempt, type WorkerExecutionAuthorityBinding, type WorkerExecutionWithEvents, type WorkerExecutorOptions } from "./worker-executor.js";
+export type PushDriverErrorCode = "invalid_configuration" | "invalid_service_response" | "invalid_execution_result" | "invalid_provider_output" | "unsupported_output_contract" | "unsupported" | "attempt_relaunch" | "attach_indeterminate" | "authority_preparation_abandon_failed" | "driver_failure_settlement_failed" | "wait_stopped";
+export declare class PushDriverError extends Error {
+    readonly code: PushDriverErrorCode;
+    constructor(code: PushDriverErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class PushDriverIndeterminateAttachError extends PushDriverError {
+    readonly disposition: "retain_preparation";
+    constructor(attemptId: string, cause: unknown);
+}
+export interface PushDriverService {
+    inspect(runId: RunId): Promise<RunView>;
+    resume(runId: RunId): Promise<RunView>;
+    cancel(runId: RunId, reason?: string | null): Promise<RunView>;
+    acquireAttempt(request: AcquireAttemptRequest): Promise<AcquireAttemptResponse>;
+    attachAttempt(request: AttachAttemptRequest): Promise<AttemptView>;
+    heartbeat(request: HeartbeatRequest): Promise<LeaseView>;
+    submitAttempt(request: SubmitAttemptRequest): Promise<SubmitResponse>;
+    settleDriverFailure(request: SettleDriverFailureRequest): Promise<RunView>;
+}
+export interface PushDriverProviderContext {
+    readonly run: RunView;
+    readonly binding: RunBindingPayload;
+    readonly node: WorkerNode;
+    readonly packet: StepPacket;
+}
+export type PushDriverProviderFactory = (context: PushDriverProviderContext) => ExecutionProvider | Promise<ExecutionProvider>;
+export interface PushDriverAttemptContext extends PushDriverProviderContext {
+    readonly lease: AttemptLease;
+    readonly attached: AttemptView;
+    readonly worker_session_id: WorkerSessionId;
+}
+export interface PushDriverExecutionAuthorityPreparationContext {
+    readonly run: RunView;
+    readonly binding: RunBindingPayload;
+    readonly node: WorkerNode;
+    readonly lease: AttemptLease;
+    readonly worker_session_id: WorkerSessionId;
+    readonly execution_claim_epoch: number;
+}
+export interface PushDriverExecutionAuthorityContext extends PushDriverAttemptContext {
+    readonly started_at: string;
+    readonly execution_claim_epoch: number;
+}
+export type PushDriverExecutionAuthorityResolution = {
+    readonly kind: "launch";
+    readonly binding: WorkerExecutionAuthorityBinding;
+} | {
+    readonly kind: "observe";
+    readonly binding: WorkerExecutionAuthorityBinding;
+};
+export interface PushDriverExecutionAuthorityCoordinator {
+    prepare(context: PushDriverExecutionAuthorityPreparationContext): unknown | Promise<unknown>;
+    abandon(context: PushDriverExecutionAuthorityPreparationContext, preparation: unknown): void | Promise<void>;
+    bind(context: PushDriverExecutionAuthorityContext, preparation: unknown): WorkerExecutionAuthorityBinding | Promise<WorkerExecutionAuthorityBinding>;
+    recover(context: PushDriverExecutionAuthorityContext): PushDriverExecutionAuthorityResolution | Promise<PushDriverExecutionAuthorityResolution>;
+}
+export interface PushDriverCallerAttestationRequest {
+    readonly run_id: RunId;
+    readonly step_id: string;
+    readonly activation_id: string;
+    readonly attempt_id: string;
+    readonly claim_epoch: number;
+    readonly worker_session_id: WorkerSessionId;
+    readonly provider_session_id: string | null;
+    readonly submission_key_digest: CanonicalResultDigest;
+    readonly execution_digest: CanonicalResultDigest;
+}
+export interface PushDriverCallerAttestationAuthority {
+    readonly authority_id: string;
+    attest(request: PushDriverCallerAttestationRequest): Extract<CanonicalEvidenceRef, {
+        kind: "caller_attestation";
+    }> | Promise<Extract<CanonicalEvidenceRef, {
+        kind: "caller_attestation";
+    }>>;
+}
+export interface PushDriverAttemptLifecycleHooks {
+    before_execute?(context: PushDriverAttemptContext): Promise<void> | void;
+    after_execute?(context: PushDriverAttemptContext, execution: WorkerExecutionWithEvents): Promise<void> | void;
+    after_submit?(context: PushDriverAttemptContext, execution: WorkerExecutionWithEvents, response: SubmitResponse): Promise<void> | void;
+    on_attempt_error?(context: PushDriverAttemptContext | null, error: unknown): Promise<void> | void;
+}
+export type PushDriverRecoverableWaitReason = "attempt_active" | "dependencies_pending" | "retry_backoff" | "run_cancelling";
+export interface PushDriverWaitContext {
+    readonly reason_code: string;
+    readonly run: RunView;
+    readonly active_attempts: number;
+}
+export type PushDriverWaitDecision = {
+    readonly action: "continue";
+    readonly delay_ms: number;
+} | {
+    readonly action: "stop";
+    readonly reason: string | null;
+};
+export type PushDriverWaitStrategy = (context: PushDriverWaitContext) => PushDriverWaitDecision | Promise<PushDriverWaitDecision>;
+export type PushDriverDiagnostic = {
+    readonly type: "wait";
+    readonly run_id: RunId;
+    readonly reason_code: string;
+    readonly delay_ms: number | null;
+} | {
+    readonly type: "attempt_acquired";
+    readonly run_id: RunId;
+    readonly attempt_id: string;
+    readonly step_id: string;
+} | {
+    readonly type: "attempt_attached";
+    readonly run_id: RunId;
+    readonly attempt_id: string;
+    readonly worker_session_id: WorkerSessionId;
+} | {
+    readonly type: "heartbeat_failed";
+    readonly run_id: RunId;
+    readonly attempt_id: string;
+    readonly error: unknown;
+} | {
+    readonly type: "submission_replayed";
+    readonly run_id: RunId;
+    readonly attempt_id: string;
+} | {
+    readonly type: "attempt_failed";
+    readonly run_id: RunId;
+    readonly attempt_id: string | null;
+    readonly error: unknown;
+};
+export type PushDriverDiagnosticSink = (diagnostic: PushDriverDiagnostic) => Promise<void> | void;
+export interface PushDriverOptions {
+    readonly service: PushDriverService;
+    readonly provider_factory: PushDriverProviderFactory;
+    readonly capabilities?: Partial<DriverCapabilities>;
+    readonly execution_authority?: PushDriverExecutionAuthorityCoordinator;
+    readonly caller_attestation_authority?: PushDriverCallerAttestationAuthority;
+    readonly lifecycle_hooks?: PushDriverAttemptLifecycleHooks;
+    readonly diagnostic_sink?: PushDriverDiagnosticSink;
+    readonly max_concurrency?: number;
+    readonly heartbeat_interval_ms?: number;
+    readonly wait_poll_ms?: number;
+    readonly wait_strategy?: PushDriverWaitStrategy;
+    readonly driver_id?: string;
+    readonly create_worker_session_id?: () => WorkerSessionId;
+    readonly execute_attempt?: typeof executeWorkerAttempt;
+    readonly worker_options?: Omit<WorkerExecutorOptions, "cancellationSignal" | "cancellationReason" | "execution_authority" | "startedAt">;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+}
+export interface PushDriverRunOptions {
+    readonly resume?: boolean;
+    readonly initial_view?: RunView;
+}
+export declare function mapProviderOutputsToSubmission(node: WorkerNode, outputs: readonly StepOutput[], requireRequiredOutputs: boolean): AttemptExecutionSubmission["outputs"];
+export declare function terminalOutcomeToCanonicalAttemptOutcome(process: TerminalOutcome): CanonicalAttemptOutcome;
+export declare class PushDriver {
+    readonly capabilities: Readonly<DriverCapabilities>;
+    private readonly service;
+    private readonly providerFactory;
+    private readonly executionAuthority;
+    private readonly callerAttestationAuthority;
+    private readonly lifecycleHooks;
+    private readonly diagnosticSink;
+    private readonly maxConcurrency;
+    private readonly heartbeatIntervalMs;
+    private readonly waitStrategy;
+    private readonly driverId;
+    private readonly createWorkerSessionId;
+    private readonly executeAttempt;
+    private readonly workerOptions;
+    private readonly sleep;
+    constructor(options: PushDriverOptions);
+    private emit;
+    private attemptError;
+    private assertHeartbeatLease;
+    private startHeartbeat;
+    private attachIsDefinitivelyFenced;
+    private abandonPreparation;
+    private reconcilePreparedAttach;
+    private driveAttempt;
+    private trackAttempt;
+    run(runId: RunId, options?: PushDriverRunOptions): Promise<RunView>;
+}