/**
 * Vocabulary types for the code-execution seam: what a caller hands a
 * {@link ../index.ts | CodeRuntime} and what it gets back. Pure types — no
 * runtime code lives here.
 *
 * @module @deepseek-ai/dsh-code-runtime/src/types
 */
/**
 * One host-side function exposed to the program as an async callable. The
 * runtime bridges calls to it (possibly across a serialization boundary), so
 * `args` and the resolution value MUST be lossless JSON. A runtime rejects a
 * lossy or non-cloneable value with a descriptive error rather than corrupting
 * the run. No seam-level byte cap applies to a binding resolution. A rejection
 * of this function surfaces inside the program as a rejection of the
 * corresponding call.
 */
export type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>;
/** A lossless JSON value transferable through the dependency-light Service Definition. */
export type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | {
    [key: string]: CodeJsonValue;
};
/**
 * Program-visible typed rejection for one binding namespace. The runtime
 * injects a real error constructor under `name`; rejected member calls become
 * its instances and expose the exact member name through
 * `memberNameProperty`. Both strings are runtime data rather than knowledge
 * of a particular consumer such as Code Mode.
 */
export interface CodeBindingErrorClass {
    /** Constructor global and resulting `Error.name`; same portable identifier rule as {@link CodeBindingNamespace.global}. */
    name: string;
    /**
     * Non-empty own property for the member name. The portable exclusion set is
     * `RESERVED_ERROR_MEMBERS` plus dunder-form names (`__x__`, non-empty
     * middle), enforced identically by every backend; any other name —
     * identifiers or not — is accepted everywhere.
     */
    memberNameProperty: string;
}
/**
 * A named group of {@link CodeBindingFunction}s the runtime exposes to the
 * program as one global object (e.g. `tools`). Function names are arbitrary
 * strings — a runtime must treat names like `__proto__` or `constructor` as
 * ordinary own properties (null-prototype construction), never as prototype
 * collisions.
 */
export interface CodeBindingNamespace {
    /**
     * The global identifier the program sees. Must match the LANGUAGE-PORTABLE
     * identifier subset `[A-Za-z_][A-Za-z0-9_]*` and no language's reserved
     * words, so the same namespace list works against every backend regardless
     * of `language` — a JS-only spelling like `$tools` is rejected by design,
     * not just by the Python backend. Names that satisfy the identifier rule but
     * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`,
     * `__dsh_main__`) are also refused everywhere; see its declaration for the
     * exact set and why each entry is reserved.
     */
    global: string;
    /** The callable members, keyed by the exact name the program calls. */
    functions: Record<string, CodeBindingFunction>;
    /** Optional program-visible typed rejection contract for this namespace. */
    errorClass?: CodeBindingErrorClass;
}
/**
 * One run: the program source plus everything the runtime acts on. Per the
 * explicit-over-implicit convention, defaulting (time budgets, output caps)
 * is the implementation's validated config — a request carries no optional
 * tuning knobs for a hidden `??` to fill in.
 */
export interface CodeRunRequest {
    /**
     * The program source, in the runtime's {@link ../index.ts | language}. It
     * runs as the body of an async function: top-level `await` and `return`
     * are available, and the completion value becomes
     * {@link CodeRunResult.value}.
     */
    program: string;
    /** Host functions exposed to the program, one global object per namespace. */
    bindings: CodeBindingNamespace[];
    /**
     * Abort the run: the runtime stops the program (hard, even mid-loop) and
     * resolves with a {@link CodeRunFailure} of kind `'abort'`. In-flight
     * binding calls are the CALLER's to settle — the runtime only stops asking.
     */
    signal?: AbortSignal;
}
/**
 * Why a run failed. The kinds are orthogonal outcomes reported independently
 * (per docs/defensive-patterns.md): a budget expiry is not an exception, an
 * abort is not a timeout, and a substrate death is neither.
 *
 * - `'exception'` — the program threw or failed to parse/transform.
 * - `'timeout'` — an implementation-owned budget expired; the message says which.
 * - `'abort'` — {@link CodeRunRequest.signal} fired.
 * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
 * - `'invalid-output'` — the completion value was not lossless JSON.
 * - `'output-limit'` — the serialized outer logs/value/diagnostic exceeded the configured cap.
 */
export interface CodeRunFailure {
    /** The failure class (see the interface doc for each kind's meaning). */
    kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit';
    /** Human-readable detail, suitable for feeding back to a model to self-correct. */
    message: string;
}
/**
 * The outcome of one run. An error is a FIELD on a resolved result, never a
 * rejection of `run()` — reporting a failed program is the caller's job, not
 * an exception path.
 */
export interface CodeRunResult {
    /**
     * The program's completion value (its top-level `return`), when it ran to
     * completion and the value crossed the runtime's lossless-JSON boundary.
     * Invalid or over-limit completions fail the run instead of substituting a
     * rendered string; a failed or value-less run leaves this absent.
     */
    value?: CodeJsonValue;
    /** Text the program emitted, in order, bounded only as part of the outer result. */
    logs: string[];
    /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
    error?: CodeRunFailure;
}
//# sourceMappingURL=types.d.ts.map