@prismatic-io/lux 0.0.1

package/lib/core/exec.d.ts

@@ -0,0 +1,82 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+/**
+ * The single spawn primitive every Lux subprocess flows through — one tested
+ * place for the whole lifecycle instead of per-call-site subsets.
+ *
+ * Guarantees:
+ * - **Process-group kill.** The child is spawned `detached`, so a timeout
+ *   signals the whole group and reaps grandchildren, not just the direct
+ *   child.
+ * - **Escalation.** SIGTERM first; a child still alive after `killGraceMs`
+ *   gets SIGKILL, so a signal-ignoring process can't hang the run.
+ * - **Bounded memory.** stdout/stderr stop accumulating past `maxBuffer`.
+ * - **Settles once.** A missing binary (`error`) and a normal/killed exit
+ *   (`close`) both resolve/reject exactly one time.
+ * - **EPIPE-safe stdin.** Writing `input` to a child that already closed
+ *   its read end is swallowed, not thrown as an unhandled error.
+ */
+export type ExecOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Run through `/bin/sh -c`. Off by default; only `command-exits-zero` opts in. */
+    shell?: boolean;
+    /** Wall-clock cap. On expiry the group is signalled and `timedOut` is set. */
+    timeoutMs?: number;
+    /** Grace between SIGTERM and SIGKILL after a timeout. Default 5s. */
+    killGraceMs?: number;
+    /** Written to stdin then the stream is closed. Omit to leave stdin closed. */
+    input?: string;
+    /**
+     * Cap on retained stdout/stderr characters (each). Default 10M. Truncation
+     * slices at exactly `maxBuffer` characters, which can split a surrogate pair.
+     */
+    maxBuffer?: number;
+    /**
+     * Aborting terminates the process group like a timeout does (SIGTERM, then
+     * SIGKILL after `killGraceMs`). The promise still resolves normally via
+     * `close`; callers see the kill in the result's `signal`.
+     */
+    signal?: AbortSignal;
+};
+export type ExecResult = {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+    durationMs: number;
+    /** The timeout fired during the run; the exit itself may have another cause. */
+    timedOut: boolean;
+};
+export type ManagedProcessOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    shell?: boolean;
+    /** Grace between the process-group SIGTERM and SIGKILL. Default 5s. */
+    killGraceMs?: number;
+    /** Aborting terminates the process group. */
+    signal?: AbortSignal;
+};
+export type ManagedProcessExit = {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+};
+export type ManagedProcess = {
+    child: ChildProcessWithoutNullStreams;
+    /** Resolves only after the OS has accepted the spawn; rejects on spawn failure. */
+    spawned: Promise<void>;
+    /** Resolves after the child and its stdio handles have closed. */
+    exited: Promise<ManagedProcessExit>;
+    /** Idempotently terminates the whole process group and waits for closure. */
+    terminate: () => Promise<ManagedProcessExit>;
+    /** Immediately terminates the complete process tree. */
+    forceTerminate: () => Promise<void>;
+};
+/**
+ * Spawn an interactive process behind the same tree-lifecycle boundary as
+ * `exec()`. The caller owns the streams; this primitive owns the process group.
+ */
+export declare const spawnManagedProcess: (command: string, args?: string[], opts?: ManagedProcessOptions) => ManagedProcess;
+export declare const exec: (command: string, args?: string[], opts?: ExecOptions) => Promise<ExecResult>;
+//# sourceMappingURL=exec.d.ts.map

package/lib/core/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAGzE;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,8BAA8B,CAAC;IACtC,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpC,6EAA6E;IAC7E,SAAS,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC7C,wDAAwD;IACxD,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,YACrB,MAAM,SACT,MAAM,EAAE,SACR,qBAAqB,KAC1B,cAiFF,CAAC;AAEF,eAAO,MAAM,IAAI,YACN,MAAM,SACT,MAAM,EAAE,SACR,WAAW,KAChB,OAAO,CAAC,UAAU,CAoFjB,CAAC"}

package/lib/core/exec.js

@@ -0,0 +1,168 @@
+import { launchProcess, processTreeFor } from "./platform-process.js";
+/**
+ * Spawn an interactive process behind the same tree-lifecycle boundary as
+ * `exec()`. The caller owns the streams; this primitive owns the process group.
+ */
+export const spawnManagedProcess = (command, args = [], opts = {}) => {
+    const child = launchProcess(command, args, {
+        ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+        ...(opts.env === undefined ? {} : { env: opts.env }),
+        ...(opts.shell === undefined ? {} : { shell: opts.shell }),
+    });
+    const tree = processTreeFor(child);
+    child.stdin.on("error", () => { });
+    let spawnSettled = false;
+    const spawned = new Promise((resolve, reject) => {
+        child.once("spawn", () => {
+            spawnSettled = true;
+            resolve();
+        });
+        child.once("error", (err) => {
+            if (spawnSettled)
+                return;
+            spawnSettled = true;
+            reject(new Error(`failed to spawn '${command}': ${err.message}`, { cause: err }));
+        });
+    });
+    let resolveExit = () => { };
+    const exited = new Promise((resolve) => {
+        resolveExit = resolve;
+    });
+    let killTimer;
+    let abortSignal = opts.signal;
+    let termination;
+    let closed = false;
+    let leaderExited = false;
+    const scheduleEscalation = () => {
+        killTimer ??= setTimeout(() => {
+            if (!leaderExited || tree.canReapAfterLeaderExit)
+                void tree.forceTerminate();
+            // A process that created a new session can escape the group while
+            // retaining inherited descriptors. Stop waiting on those descriptors
+            // after the group escalation has completed.
+            child.stdout.destroy();
+            child.stderr.destroy();
+        }, opts.killGraceMs ?? 5_000);
+    };
+    const terminate = () => {
+        if (termination)
+            return termination;
+        if (closed)
+            return exited;
+        tree.terminate();
+        scheduleEscalation();
+        termination = exited;
+        return termination;
+    };
+    const onAbort = () => {
+        void terminate();
+    };
+    if (abortSignal?.aborted)
+        onAbort();
+    else
+        abortSignal?.addEventListener("abort", onAbort, { once: true });
+    child.once("exit", () => {
+        leaderExited = true;
+        // POSIX group IDs remain addressable after the leader exits. Windows PIDs
+        // may already have been reused, so its adapter only kills while the owned
+        // leader is alive.
+        if (tree.canReapAfterLeaderExit)
+            void tree.forceTerminate();
+        // Killing the group closes inherited pipes. A descendant that deliberately
+        // escaped the group cannot be signalled, so bound how long its descriptors
+        // can delay process settlement.
+        scheduleEscalation();
+    });
+    child.once("close", (exitCode, signal) => {
+        closed = true;
+        if (killTimer)
+            clearTimeout(killTimer);
+        abortSignal?.removeEventListener("abort", onAbort);
+        abortSignal = undefined;
+        resolveExit({ exitCode, signal });
+    });
+    const forceTerminate = () => leaderExited && !tree.canReapAfterLeaderExit ? Promise.resolve() : tree.forceTerminate();
+    return { child, spawned, exited, terminate, forceTerminate };
+};
+export const exec = (command, args = [], opts = {}) => new Promise((resolve, reject) => {
+    const start = Date.now();
+    const maxBuffer = opts.maxBuffer ?? 10_000_000;
+    let stdout = "";
+    let stderr = "";
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let timedOut = false;
+    let settled = false;
+    const managed = spawnManagedProcess(command, args, {
+        shell: opts.shell ?? false,
+        ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+        ...(opts.env === undefined ? {} : { env: opts.env }),
+        ...(opts.killGraceMs === undefined ? {} : { killGraceMs: opts.killGraceMs }),
+        ...(opts.signal === undefined ? {} : { signal: opts.signal }),
+    });
+    const { child } = managed;
+    const terminate = () => {
+        void managed.terminate();
+    };
+    const timer = opts.timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => {
+            timedOut = true;
+            terminate();
+        }, opts.timeoutMs);
+    const cleanup = () => {
+        if (timer)
+            clearTimeout(timer);
+    };
+    // setEncoding buffers a multibyte character straddling a pipe-chunk
+    // boundary; decoding each Buffer independently would mangle it to U+FFFD.
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    // Keep draining the pipe after the cap so the child never stalls on
+    // backpressure; we simply stop retaining what we won't report.
+    const append = (buf, chunk) => ({
+        text: buf.length >= maxBuffer ? buf : (buf + chunk).slice(0, maxBuffer),
+        truncated: buf.length + chunk.length > maxBuffer,
+    });
+    child.stdout?.on("data", (c) => {
+        const appended = append(stdout, c);
+        stdout = appended.text;
+        stdoutTruncated ||= appended.truncated;
+    });
+    child.stderr?.on("data", (c) => {
+        const appended = append(stderr, c);
+        stderr = appended.text;
+        stderrTruncated ||= appended.truncated;
+    });
+    void managed.spawned.catch((err) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        reject(err);
+    });
+    void managed.exited.then(({ exitCode, signal }) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        resolve({
+            exitCode,
+            signal,
+            stdout,
+            stderr,
+            stdoutTruncated,
+            stderrTruncated,
+            durationMs: Date.now() - start,
+            timedOut,
+        });
+    });
+    if (opts.input !== undefined) {
+        // If the child exits before draining a large prompt the write hits a
+        // broken pipe; swallow it so it doesn't surface as an uncaught error.
+        child.stdin.end(opts.input);
+    }
+    else
+        child.stdin.end();
+});
+//# sourceMappingURL=exec.js.map

package/lib/core/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"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"}

package/lib/core/experiment.d.ts

@@ -0,0 +1,285 @@
+import { z } from "zod";
+import { TokenUsageSchema } from "./usage.js";
+export declare const ExperimentSelectorSchema: z.ZodObject<{
+    patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ExperimentSelector = z.output<typeof ExperimentSelectorSchema>;
+export declare const FileSetSubjectSchema: z.ZodObject<{
+    root: z.ZodString;
+    mutable: z.ZodArray<z.ZodString>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    validate: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        unsafeHostExecution: z.ZodLiteral<true>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type FileSetSubject = z.output<typeof FileSetSubjectSchema>;
+export declare const CandidateIdSchema: z.ZodString;
+export declare const ExperimentVariantSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    parentIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    components: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type ExperimentVariant = z.output<typeof ExperimentVariantSchema>;
+export declare const ExperimentConstraintSchema: z.ZodObject<{
+    metric: z.ZodString;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    profile: z.ZodOptional<z.ZodString>;
+    split: z.ZodDefault<z.ZodEnum<{
+        test: "test";
+        train: "train";
+        validation: "validation";
+    }>>;
+    confidence: z.ZodOptional<z.ZodObject<{
+        method: z.ZodEnum<{
+            hoeffding: "hoeffding";
+            "percentile-bootstrap": "percentile-bootstrap";
+            wilson: "wilson";
+        }>;
+        level: z.ZodDefault<z.ZodNumber>;
+        resamples: z.ZodDefault<z.ZodNumber>;
+        seed: z.ZodDefault<z.ZodNumber>;
+        minSamples: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ExperimentConstraint = z.output<typeof ExperimentConstraintSchema>;
+export declare const ExperimentObjectiveSchema: z.ZodObject<{
+    constraints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        metric: z.ZodString;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        profile: z.ZodOptional<z.ZodString>;
+        split: z.ZodDefault<z.ZodEnum<{
+            test: "test";
+            train: "train";
+            validation: "validation";
+        }>>;
+        confidence: z.ZodOptional<z.ZodObject<{
+            method: z.ZodEnum<{
+                hoeffding: "hoeffding";
+                "percentile-bootstrap": "percentile-bootstrap";
+                wilson: "wilson";
+            }>;
+            level: z.ZodDefault<z.ZodNumber>;
+            resamples: z.ZodDefault<z.ZodNumber>;
+            seed: z.ZodDefault<z.ZodNumber>;
+            minSamples: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    minimize: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        metric: z.ZodString;
+        profile: z.ZodOptional<z.ZodString>;
+        split: z.ZodDefault<z.ZodEnum<{
+            test: "test";
+            train: "train";
+            validation: "validation";
+        }>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ExperimentObjective = z.output<typeof ExperimentObjectiveSchema>;
+export declare const ExperimentBudgetSchema: z.ZodObject<{
+    maxCandidates: z.ZodDefault<z.ZodNumber>;
+    patience: z.ZodDefault<z.ZodNumber>;
+    maxMetricCalls: z.ZodDefault<z.ZodNumber>;
+    maxJudgeCalls: z.ZodDefault<z.ZodNumber>;
+    maxProposalCalls: z.ZodDefault<z.ZodNumber>;
+    maxTokens: z.ZodDefault<z.ZodNumber>;
+    maxCostUsd: z.ZodDefault<z.ZodNumber>;
+    maxUnpricedModelCalls: z.ZodDefault<z.ZodNumber>;
+    maxWallTimeMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type ExperimentBudget = z.infer<typeof ExperimentBudgetSchema>;
+export declare const ExperimentCampaignSchema: z.ZodObject<{
+    id: z.ZodString;
+    subject: z.ZodObject<{
+        root: z.ZodString;
+        mutable: z.ZodArray<z.ZodString>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        validate: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+            unsafeHostExecution: z.ZodLiteral<true>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    evaluation: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"agent">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"grader">;
+        annotations: z.ZodString;
+        allowedAssertionAdditions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        scoreTolerance: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>], "kind">>;
+    profiles: z.ZodArray<z.ZodString>;
+    splits: z.ZodObject<{
+        train: z.ZodOptional<z.ZodObject<{
+            patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        validation: z.ZodObject<{
+            patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        test: z.ZodOptional<z.ZodObject<{
+            patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    repetitions: z.ZodDefault<z.ZodObject<{
+        search: z.ZodDefault<z.ZodNumber>;
+        promotion: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    variants: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        parentIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        components: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>>;
+    objectives: z.ZodDefault<z.ZodObject<{
+        constraints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            metric: z.ZodString;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            profile: z.ZodOptional<z.ZodString>;
+            split: z.ZodDefault<z.ZodEnum<{
+                test: "test";
+                train: "train";
+                validation: "validation";
+            }>>;
+            confidence: z.ZodOptional<z.ZodObject<{
+                method: z.ZodEnum<{
+                    hoeffding: "hoeffding";
+                    "percentile-bootstrap": "percentile-bootstrap";
+                    wilson: "wilson";
+                }>;
+                level: z.ZodDefault<z.ZodNumber>;
+                resamples: z.ZodDefault<z.ZodNumber>;
+                seed: z.ZodDefault<z.ZodNumber>;
+                minSamples: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+        minimize: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            metric: z.ZodString;
+            profile: z.ZodOptional<z.ZodString>;
+            split: z.ZodDefault<z.ZodEnum<{
+                test: "test";
+                train: "train";
+                validation: "validation";
+            }>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    optimizer: z.ZodOptional<z.ZodObject<{
+        algorithm: z.ZodLiteral<"reflective">;
+        config: z.ZodOptional<z.ZodUnknown>;
+        candidateSelection: z.ZodDefault<z.ZodEnum<{
+            "current-best": "current-best";
+            pareto: "pareto";
+        }>>;
+        mergeFrontier: z.ZodDefault<z.ZodBoolean>;
+        promotionTopK: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    budget: z.ZodDefault<z.ZodObject<{
+        maxCandidates: z.ZodDefault<z.ZodNumber>;
+        patience: z.ZodDefault<z.ZodNumber>;
+        maxMetricCalls: z.ZodDefault<z.ZodNumber>;
+        maxJudgeCalls: z.ZodDefault<z.ZodNumber>;
+        maxProposalCalls: z.ZodDefault<z.ZodNumber>;
+        maxTokens: z.ZodDefault<z.ZodNumber>;
+        maxCostUsd: z.ZodDefault<z.ZodNumber>;
+        maxUnpricedModelCalls: z.ZodDefault<z.ZodNumber>;
+        maxWallTimeMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ExperimentCampaignInput = z.input<typeof ExperimentCampaignSchema>;
+export type ExperimentCampaign = z.output<typeof ExperimentCampaignSchema>;
+export declare const defineExperiment: (input: ExperimentCampaignInput) => ExperimentCampaign;
+export declare const CandidateSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    parentIds: z.ZodArray<z.ZodString>;
+    createdAt: z.ZodString;
+    proposer: z.ZodString;
+    baseSourceHash: z.ZodString;
+    candidateHash: z.ZodString;
+    components: z.ZodRecord<z.ZodString, z.ZodString>;
+    sourceBytes: z.ZodNumber;
+    rationale: z.ZodExactOptional<z.ZodString>;
+    proposalUsage: z.ZodExactOptional<z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        cacheCreation: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Candidate = z.infer<typeof CandidateSchema>;
+export declare const CandidateEvaluationSchema: z.ZodObject<{
+    profileId: z.ZodString;
+    split: z.ZodEnum<{
+        test: "test";
+        train: "train";
+        validation: "validation";
+    }>;
+    suiteDir: z.ZodExactOptional<z.ZodString>;
+    evidencePath: z.ZodExactOptional<z.ZodString>;
+    passRate: z.ZodNumber;
+    casePassRates: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    metrics: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    metricCalls: z.ZodExactOptional<z.ZodNumber>;
+    judgeCalls: z.ZodExactOptional<z.ZodNumber>;
+    unpricedModelCalls: z.ZodExactOptional<z.ZodNumber>;
+    usage: z.ZodExactOptional<z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        cacheCreation: z.ZodNumber;
+    }, z.core.$strip>>;
+    costUsd: z.ZodExactOptional<z.ZodNumber>;
+    samples: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodNumber>>>;
+    failedCases: z.ZodArray<z.ZodObject<{
+        caseId: z.ZodString;
+        score: z.ZodNullable<z.ZodNumber>;
+        feedback: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CandidateEvaluation = z.infer<typeof CandidateEvaluationSchema>;
+export declare const CandidateProposalSchema: z.ZodObject<{
+    updates: z.ZodRecord<z.ZodString, z.ZodString>;
+    rationale: z.ZodOptional<z.ZodString>;
+    usage: z.ZodOptional<z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        cacheCreation: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type CandidateProposal = z.infer<typeof CandidateProposalSchema>;
+export type OptimizerInput = {
+    campaign: ExperimentCampaign;
+    candidate: Candidate;
+    /** Complementary Pareto candidates available to a merge-aware proposer. */
+    alternatives?: Candidate[] | undefined;
+    /** Train observations explaining which examples each alternative preserves. */
+    alternativeObservations?: Record<string, CandidateEvaluation[]> | undefined;
+    observations: CandidateEvaluation[];
+    remainingCandidates: number;
+    cwd: string;
+    abortSignal?: AbortSignal | undefined;
+    /** Persist accounting immediately after each completed proposal-model call. */
+    recordModelCall?: (accounting: {
+        usage: z.infer<typeof TokenUsageSchema>;
+        costUsd?: number;
+    }) => Promise<void>;
+    /** Durable provider-attempt markers for hard-kill-safe proposal accounting. */
+    recordModelAttemptStart?: (kind: "proposal") => Promise<void>;
+    completeModelAttempts?: () => Promise<void>;
+};
+export interface Optimizer {
+    propose(input: OptimizerInput): Promise<CandidateProposal[]>;
+}
+//# sourceMappingURL=experiment.d.ts.map

package/lib/core/experiment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment.d.ts","sourceRoot":"","sources":["../../src/core/experiment.ts"],"names":[],"mappings":"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"}