@wenathlan/saddle 2.0.151 → 2.0.153

package/dist/execution.d.ts

@@ -0,0 +1,529 @@
+/**
+ * execution.ts — runtime, runner, queue, dispatch and session execution planning.
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (runners, runtime) into the single
+ * root-level domain file of the saddle family standard: one optimized
+ * TypeScript file per correlated domain, ordinal sections, JSDoc on every
+ * block, intra-domain imports dissolved, cross-domain imports rewritten to
+ * ./<domain>.js. Every capability of every source file is preserved here;
+ * the pure re-export barrels (none in this domain) folded their surface into this file directly.
+ */
+/**
+ * the in process runner is the deterministic baseline for local execution.
+ */
+export declare function inprocess(options?: {}): {
+    descriptor(): {
+        id: any;
+        name: any;
+        priority: any;
+        maxconcurrent: any;
+        capabilities: any;
+        status: string;
+    };
+    setavailable(value: any): void;
+    canrun(): Promise<boolean>;
+    execute(context: any, handler: any): Promise<any>;
+};
+/**
+ * runner health checks describe provider capacity without selecting infrastructure.
+ */
+/** Checks provider readiness and returns a serializable health report. */
+export declare function runnerhealth(provider: any, job?: {}): Promise<{
+    id: string;
+    status: any;
+    healthy: boolean;
+    checkedat: number;
+    capacity: {
+        maxconcurrent: any;
+        capabilities: any[];
+    };
+    error?: undefined;
+} | {
+    id: string;
+    status: string;
+    healthy: boolean;
+    checkedat: number;
+    capacity: {
+        maxconcurrent: any;
+        capabilities: any[];
+    };
+    error: {
+        code: string;
+        message: string;
+    };
+}>;
+/** Checks a provider list in stable order and summarizes available capacity. */
+export declare function runnerhealthall(providers?: any[], job?: {}): Promise<{
+    checkedat: number;
+    reports: any[];
+    available: number;
+    total: number;
+}>;
+/**
+ * heartbeat manages cooperative liveness signals for long-running local or remote jobs.
+ */
+/** Creates a heartbeat controller with manual ticks and optional interval execution. */
+export declare function heartbeat(options?: {}): {
+    tick: (input?: {}) => Promise<{
+        id: string;
+        sequence: number;
+        at: number;
+        status: string;
+        metadata: any;
+    }>;
+    on: (listener: any) => () => boolean;
+    start: (input?: {}) => boolean;
+    stop: () => boolean;
+    status: () => {
+        running: boolean;
+        interval: number;
+        sequence: number;
+        last: any;
+    };
+};
+/**
+ * provider chains rank caller-authorized execution candidates without dispatching remote work.
+ */
+/** Creates a stable provider chain over declarative capability reports. */
+export declare function providerchain(input?: {}): Readonly<{
+    select(request?: {}): Readonly<{
+        version: 1;
+        selected: Readonly<{
+            id: any;
+            priority: any;
+            capabilities: readonly any[];
+            architecture: any;
+            operatingSystem: any;
+            networkpolicy: any;
+            storagepolicy: any;
+            cpu: any;
+            memorybytes: any;
+            maxmilliseconds: any;
+        }>;
+        rejected: readonly any[];
+        request: Readonly<{
+            capabilities: readonly string[];
+            preferredids: readonly string[];
+            architecture: string;
+            operatingSystem: string;
+            networkpolicy: string;
+            storagepolicy: string;
+            mincpu: number;
+            minmemorybytes: number;
+            minmilliseconds: number;
+        }>;
+    }>;
+    dispatchplan(request?: {}): Readonly<{
+        version: 1;
+        state: "caller-dispatches";
+        provider: Readonly<{
+            id: any;
+            priority: any;
+            capabilities: readonly any[];
+            architecture: any;
+            operatingSystem: any;
+            networkpolicy: any;
+            storagepolicy: any;
+            cpu: any;
+            memorybytes: any;
+            maxmilliseconds: any;
+        }>;
+        request: Readonly<{
+            capabilities: readonly string[];
+            preferredids: readonly string[];
+            architecture: string;
+            operatingSystem: string;
+            networkpolicy: string;
+            storagepolicy: string;
+            mincpu: number;
+            minmemorybytes: number;
+            minmilliseconds: number;
+        }>;
+        rejected: readonly any[];
+    }>;
+    providers: () => {
+        capabilities: string[];
+        id: string;
+        priority: number;
+        status: string;
+        architecture: string;
+        operatingSystem: string;
+        networkpolicy: string;
+        storagepolicy: string;
+        cpu: number;
+        memorybytes: number;
+        maxmilliseconds: number;
+    }[];
+}>;
+/** Selects the first eligible provider under stable priority and returns every exclusion reason. */
+export declare function selectprovider(providers: any, request?: {}): Readonly<{
+    version: 1;
+    selected: Readonly<{
+        id: any;
+        priority: any;
+        capabilities: readonly any[];
+        architecture: any;
+        operatingSystem: any;
+        networkpolicy: any;
+        storagepolicy: any;
+        cpu: any;
+        memorybytes: any;
+        maxmilliseconds: any;
+    }>;
+    rejected: readonly any[];
+    request: Readonly<{
+        capabilities: readonly string[];
+        preferredids: readonly string[];
+        architecture: string;
+        operatingSystem: string;
+        networkpolicy: string;
+        storagepolicy: string;
+        mincpu: number;
+        minmemorybytes: number;
+        minmilliseconds: number;
+    }>;
+}>;
+/** Produces a verified runner-to-storage handoff record without writing an artifact. */
+export declare function artifacthandoff(input?: {}): Readonly<{
+    version: 1;
+    key: string;
+    sha256: string;
+    sizebytes: number;
+    providerid: string;
+    retention: string;
+    state: "caller-transfers";
+}>;
+/** Creates a cancellation intent without claiming that a remote runner has stopped or cleaned up. */
+export declare function cancellationplan(input?: {}): Readonly<{
+    version: 1;
+    runid: string;
+    providerid: string;
+    reason: string;
+    state: "caller-cancels";
+    remotestate: "unknown";
+    compensation: "caller-evaluates" | "not-requested";
+}>;
+/** Renders a caller-dispatches plan through an injected forge adapter without sending it. */
+export declare function renderdispatch(plan: any, adapter: any): Promise<any>;
+/**
+ * scheduling uses stable priority order and selects the first available runner.
+ */
+export declare function scheduler(providers: any): {
+    select(job: any): Promise<any>;
+    list(): any[];
+};
+/**
+ * runtime detection uses standard globals and keeps node specific modules outside the core.
+ */
+export declare function runtimename(scope?: typeof globalThis): "browser" | "bun" | "deno" | "node" | "unknown";
+export declare function runtimefeatures(scope?: typeof globalThis): {
+    runtime: string;
+    fetch: boolean;
+    streams: boolean;
+    crypto: boolean;
+    websocket: boolean;
+    filesystem: boolean;
+};
+/**
+ * the engine coordinates job intent, working memory, runner execution, and commit.
+ */
+export declare function engine(options: any): {
+    events: any;
+    run(spec: any, handler: any): Promise<{
+        job: {
+            id: any;
+            name: any;
+            input: any;
+            priority: any;
+            outputkey: any;
+            metadata: any;
+            status: string;
+            createdat: any;
+        };
+        output: any;
+        runnerid: any;
+        artifact: any;
+        sync: any;
+    }>;
+};
+/**
+ * abort helpers unify deadlines without depending on a server framework.
+ */
+export declare function deadline(milliseconds: any, parent: any): {
+    signal: AbortSignal;
+    cancel(): void;
+};
+/**
+ * retry context groups transient retry policy and circuit protection for runners,
+ * storage adapters and network-facing surfaces.
+ */
+/** Creates bounded exponential retry behavior for retryable failures. */
+export declare function retrypolicy(options?: {}): {
+    run(handler: any): Promise<any>;
+};
+/** Creates a circuit breaker that opens after repeated handler failures. */
+export declare function circuitbreaker(options?: {}): {
+    execute: (handler: any) => Promise<any>;
+    status(): {
+        state: string;
+        failures: number;
+        openedat: number;
+    };
+    reset(): void;
+};
+/**
+ * job queue groups concurrency retry timeout and idempotency at one boundary.
+ */
+export declare function jobqueue(options?: {}): {
+    add(payload: any, handler: any, options?: {}): Promise<unknown>;
+    size(): number;
+    active(): number;
+    idle(): Promise<void>;
+};
+/**
+ * idempotency keys prevent duplicate delivery from at least once transports.
+ */
+export declare function idempotency(): {
+    has(key: any): boolean;
+    get(key: any): any;
+    set(key: any, value: any): any;
+    delete(key: any): void;
+};
+/**
+ * saga executes compensations in reverse order when a multi step operation fails.
+ */
+export declare function saga(steps: any, context?: {}): Promise<any[]>;
+/**
+ * resumable runs keep remote execution state explicit and recoverable across process restarts.
+ */
+export declare const runstatuses: readonly string[];
+/** Creates a validated run record with explicit transition history. */
+export declare function runrecord(input?: {}): {
+    version: number;
+    requestid: string;
+    name: string;
+    status: any;
+    runid: any;
+    attempt: number;
+    createdat: number;
+    updatedat: number;
+    history: any;
+    metadata: any;
+};
+/** Moves a run through a legal state transition and appends an auditable event. */
+export declare function transitionrun(record: any, status: any, options?: {}): {
+    version: number;
+    requestid: string;
+    name: string;
+    createdat: number;
+    metadata: any;
+    status: any;
+    runid: any;
+    attempt: number;
+    updatedat: number;
+    history: any[];
+};
+/** Coordinates submit, status, resume and cancel operations through an injected remote adapter. */
+export declare function resumablerun(adapter: any, input?: {}): {
+    submit: () => Promise<{
+        version: number;
+        requestid: string;
+        name: string;
+        status: any;
+        runid: any;
+        attempt: number;
+        createdat: number;
+        updatedat: number;
+        history: any;
+        metadata: any;
+        response: any;
+    }>;
+    resume: () => Promise<{
+        version: number;
+        requestid: string;
+        name: string;
+        status: any;
+        runid: any;
+        attempt: number;
+        createdat: number;
+        updatedat: number;
+        history: any;
+        metadata: any;
+        response: any;
+    }>;
+    cancel: (options?: {}) => Promise<{
+        version: number;
+        requestid: string;
+        name: string;
+        status: any;
+        runid: any;
+        attempt: number;
+        createdat: number;
+        updatedat: number;
+        history: any;
+        metadata: any;
+        compensation: {
+            status: string;
+        };
+    } | {
+        version: number;
+        requestid: string;
+        name: string;
+        status: any;
+        runid: any;
+        attempt: number;
+        createdat: number;
+        updatedat: number;
+        history: any;
+        metadata: any;
+        response: any;
+        compensation: {
+            status: string;
+        };
+    }>;
+    get: () => {
+        version: number;
+        requestid: string;
+        name: string;
+        status: any;
+        runid: any;
+        attempt: number;
+        createdat: number;
+        updatedat: number;
+        history: any;
+        metadata: any;
+    };
+};
+/**
+ * workflow dispatch keeps remote execution explicit and records a stable request identity.
+ */
+export declare function workflowdispatch(adapter: any, options?: {}): {
+    submit(spec: any): Promise<any>;
+    get(requestid: any): any;
+};
+export declare function waitforrun(adapter: any, owner: any, repository: any, runid: any, options?: {}): Promise<any>;
+/**
+ * replay maps validated session events to an injected browser adapter.
+ */
+export declare function replay(session: any, adapter: any, options?: {}): Promise<{
+    events: any;
+    duration: number;
+    contextswitches: number;
+}>;
+/**
+ * worker bridge translates message events through an injected dispatcher without owning a worker runtime.
+ */
+/** Attaches a bounded message bridge to a caller-owned worker scope. */
+export declare function workerbridge(options?: {}): {
+    event: string;
+    listener: (message: any) => Promise<void>;
+    close(): void;
+};
+/**
+ * persistent queue stores job state in a caller selected file.
+ * running items return to queued when a process restores after a crash.
+ */
+/** Creates a crash recoverable queue with idempotent item identifiers. */
+export declare function persistentqueue(options?: {}): {
+    restore: () => Promise<{
+        version: number;
+        items: any[];
+    }>;
+    enqueue: (payload: any, metadata?: {}) => Promise<any>;
+    claim: (claimoptions?: {}) => Promise<any>;
+    renew: (id: any, leasems?: any) => Promise<any>;
+    complete: (id: any, result: any) => Promise<any>;
+    fail: (id: any, error: any) => Promise<any>;
+    list: (filter: any) => Promise<any[]>;
+};
+/**
+ * file session persistence writes one validated JSON document per session.
+ */
+export declare function filesessions(root: any): {
+    save(session: any): Promise<{
+        version: number;
+        id: any;
+        agentname: any;
+        originurl: any;
+        seed: any;
+        status: any;
+        startedat: any;
+        finishedat: any;
+        events: any;
+    }>;
+    load(id: any): Promise<{
+        version: number;
+        id: any;
+        agentname: any;
+        originurl: any;
+        seed: any;
+        status: any;
+        startedat: any;
+        finishedat: any;
+        events: any;
+    }>;
+};
+/**
+ * jsonl session storage keeps append only traces independent from browser adapters.
+ */
+export declare function sessionstore(root: any): {
+    append(session: any): Promise<{
+        version: number;
+        id: any;
+        agentname: any;
+        originurl: any;
+        seed: any;
+        status: any;
+        startedat: any;
+        finishedat: any;
+        events: any;
+    }>;
+    read(id: any): Promise<{
+        version: number;
+        id: any;
+        agentname: any;
+        originurl: any;
+        seed: any;
+        status: any;
+        startedat: any;
+        finishedat: any;
+        events: any;
+    }[]>;
+};
+/**
+ * compatibility contracts describe core capabilities without importing a runtime-specific adapter.
+ */
+export declare const corecapabilities: readonly string[];
+/** Reports the runtime capabilities expected by the transport-neutral root entry. */
+export declare function runtimecontract(scope?: typeof globalThis): {
+    runtime: string;
+    core: boolean;
+    capabilities: {
+        esm: boolean;
+        fetch: boolean;
+        streams: boolean;
+        textencoding: boolean;
+        webcrypto: boolean;
+    };
+    nodeonly: {
+        filesystem: boolean;
+        server: boolean;
+    };
+};
+/** Returns a structured unsupported-mode error for a missing runtime capability. */
+export declare function unsupportedruntime(feature: any, contract?: {
+    runtime: string;
+    core: boolean;
+    capabilities: {
+        esm: boolean;
+        fetch: boolean;
+        streams: boolean;
+        textencoding: boolean;
+        webcrypto: boolean;
+    };
+    nodeonly: {
+        filesystem: boolean;
+        server: boolean;
+    };
+}): Error;