/**
 * Copyright (c) 2025 Elara AI Pty Ltd
 * Licensed under BSL 1.1. See LICENSE for details.
 */
/**
 * Graph-free, persistence-free execution — the shared primitive behind
 * `e3.function` calls and one-shot execution.
 *
 * runDetached: marshal inputs → run a body IR on a chosen runner → return
 * the result value inline; write nothing durable. No task object, no output
 * object, no execution record, no logs, no dataset ref. The only disk write
 * is the transient scratch directory, removed on completion.
 */
import type { StorageBackend } from '../storage/index.js';
import { type RunnerValue } from '@elaraai/e3-types';
/**
 * Specification of a detached run.
 */
export interface DetachedSpec {
    /** function: from FunctionObject; one-shot: from request */
    bodyIr: Uint8Array;
    /** positional arg values (beast2), already validated for arity */
    args: Uint8Array[];
    /** wire runner variant — resolved to argv via buildRunnerArgv */
    runner: RunnerValue;
    /** execution limits (all required — the caller applies defaults/clamps) */
    limits: {
        timeoutMs: number;
        maxResultBytes: number;
        maxLogBytes: number;
    };
    /** environment spec object hash (FunctionObject.environment); the runner
     *  materializes it and prepends its bin dir to the child PATH */
    environment?: string;
}
/**
 * Result of a detached run.
 *
 * - `success`: the runner's output file bytes (beast2), under the size cap
 * - `failed`: the process exited non-zero (or failed to spawn)
 * - `too_large`: output over `maxResultBytes` — the bytes are never loaded
 * - `timed_out`: the process group was killed at `timeoutMs`
 */
export type DetachedResult = {
    kind: 'success';
    value: Uint8Array;
    stdout: string;
    stderr: string;
    stdoutTruncated: boolean;
    stderrTruncated: boolean;
} | {
    kind: 'failed';
    exitCode: number;
    stdout: string;
    stderr: string;
    stdoutTruncated: boolean;
    stderrTruncated: boolean;
} | {
    kind: 'too_large';
    bytes: number;
    limit: number;
    stdout: string;
    stderr: string;
    stdoutTruncated: boolean;
    stderrTruncated: boolean;
} | {
    kind: 'timed_out';
    ms: number;
    stdout: string;
    stderr: string;
    stdoutTruncated: boolean;
    stderrTruncated: boolean;
};
/**
 * Options for {@link runDetached}.
 */
export interface DetachedRunOptions {
    /** AbortSignal for cancellation (kills the process group). */
    signal?: AbortSignal;
    /** Anchor directory for the runner-binary PATH walk (replaces the task
     *  path's "walk up from repo dir" — one-shot has no repo path). The
     *  process cwd is always searched as well. */
    runnerSearchDir?: string;
    /** Executable dirs prepended to the child PATH (a materialized
     *  environment's bin dir). */
    extraBins?: string[];
    /** Storage backend for materializing `spec.environment` (local runner);
     *  required when the spec declares an environment. */
    storage?: StorageBackend;
    /** Pass `-v` to the runner (known runtimes only) so it prints timing/perf
     *  to stderr. Runtime-only: applied to the built argv just before spawn. */
    verbose?: boolean;
}
/**
 * Run a body IR on a runner, returning the result inline.
 *
 * mkScratch → write bodyIr → marshal args → build argv → spawnAndCapture
 * (bounded-tail stdout/stderr) → on exit 0: fs.stat the output BEFORE
 * reading; size > maxResultBytes ⇒ too_large (bytes never loaded); else
 * success(readOutputFile) → finally rm scratch.
 *
 * NEVER writes to the object store, execution records, or logs.
 */
export declare function runDetached(spec: DetachedSpec, options?: DetachedRunOptions): Promise<DetachedResult>;
//# sourceMappingURL=runDetached.d.ts.map