@glubean/runner 0.5.0 → 0.8.0

package/dist/load/sink.d.ts

@@ -0,0 +1,127 @@
+/**
+ * LoadSink — translates the engine's per-run wire events into the load
+ * `LoadEvent` fact stream and feeds the `LoadReducer`.
+ *
+ * One sink + one engine core serve every concurrent iteration: each iteration
+ * runs an engine TestDef whose `meta.id` is the unique iterationId, so wire
+ * events arrive tagged with `testId = iterationId` and the sink demuxes them
+ * back to the right iteration's attribution (no per-iteration core needed).
+ *
+ * Success requests feed only the reducer's aggregates; the sink stays bounded
+ * (per-iteration step-name maps are dropped at iteration end). Failure-trace
+ * sampling and producer-release events land in later milestones.
+ */
+import type { LoadEndReason, LoadErrorKind, LoadEvent, LoadReducer, LoadResolvedConfig } from "@glubean/sdk/load";
+/** Per-iteration attribution the sink stamps onto translated events. */
+export interface LoadIterationEnvelope {
+    scenarioId: string;
+    scenarioRefId?: string;
+    producerSlotId: string;
+    iterationId: string;
+}
+/** Distributive Omit — applied per union member so each LoadEvent variant keeps
+ *  its own discriminant-specific fields (a plain Omit over the union would keep
+ *  only the common envelope keys). */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+type LoadEventBody = DistributiveOmit<LoadEvent, "ts" | "seq" | "runId" | "runnerId">;
+export declare class LoadSink {
+    private readonly reducer;
+    private readonly runId;
+    private readonly runnerId;
+    private readonly now;
+    private seq;
+    private sealed;
+    private readonly envelopes;
+    private readonly stepNames;
+    private readonly phases;
+    private readonly iterSpan;
+    private sawUnreleasedTailPoll;
+    constructor(reducer: LoadReducer, runId: string, runnerId: string, now?: () => number);
+    /** Stamp envelope basics (ts / seq / runId / runnerId) and apply to the reducer.
+     *  A no-op once sealed (post-finalize), so abandoned continuations can't mutate
+     *  the already-built artifact. */
+    emit(body: LoadEventBody): void;
+    /** Stop forwarding events to the reducer (called once the run is finalized). */
+    seal(): void;
+    /** Whether any iteration ran a post-primary TAIL `.poll()` without requesting producer
+     *  release (a request before it, none after, and no release asked). Gates the
+     *  long-poll advisory — the closed-scheduling case it nudges toward release. */
+    get unreleasedTailPollRan(): boolean;
+    /** Flag the advisory if `span` shows a poll that HELD the slot: a request preceded it
+     *  (minReq < maxUnreleasedPoll) and no primary-phase request followed it
+     *  (maxPrimaryReq <= maxUnreleasedPoll — excludes a pre-primary readiness wait while
+     *  ignoring post-boundary continuation requests). The sentinels make a missing held poll
+     *  / request fail the first test. Idempotent — safe to call at release time AND at
+     *  endIteration (the spans are frozen once the primary boundary / release is reached). */
+    private markUnreleasedTailPoll;
+    /** Register an iteration's attribution before its engine run starts. */
+    beginIteration(env: LoadIterationEnvelope): void;
+    /** Drop an iteration's per-iteration buffers once it has finished. */
+    endIteration(iterationId: string): void;
+    /** The shared per-iteration attribution every translated event carries. Phase
+     *  starts "primary" and flips to "continuation" at the iteration's first
+     *  `primaryComplete` boundary (see `emitPrimaryCompleted`). */
+    private baseOf;
+    /** Emit `iteration:start` (the executor calls this right after beginIteration). */
+    emitIterationStart(env: LoadIterationEnvelope, opts?: {
+        inputKey?: string;
+        feederKeys?: Record<string, string>;
+    }): void;
+    /** Emit `iteration:end` (the executor calls this once the engine run resolves). */
+    emitIterationEnd(env: LoadIterationEnvelope, result: {
+        ok: boolean;
+        durationMs: number;
+        errorKind?: LoadErrorKind;
+    }): void;
+    /** A per-scenario-stable, leaf-unique step id. The engine's leaf `index` is
+     *  assigned in deterministic registry order (taken or skipped), so the same
+     *  logical step always gets the same index — folding it in disambiguates two
+     *  leaves that share a display name (the reducer keys aggregates by stepId). */
+    private stepIdOf;
+    /** Emit `report:checkpoint` (backs `ctx.report.checkpoint`). */
+    emitCheckpoint(env: LoadIterationEnvelope, checkpointId: string, data?: Record<string, unknown>): void;
+    /** Emit `producer:primaryCompleted` (backs the first `ctx.report.primaryComplete`)
+     *  and FLIP this iteration into its continuation phase immediately, so every
+     *  request / checkpoint the sink translates afterwards carries
+     *  `phase: "continuation"` (the API's contract). The boundary event itself is
+     *  stamped with the pre-flip ("primary") phase. A step that spans the boundary
+     *  still keeps a single phase because step:end uses its captured START phase
+     *  (see the `step_end` case). M5 records the measurement boundary only —
+     *  `releaseRequested` is forwarded for M6 scheduling, it does not release a slot. */
+    emitPrimaryCompleted(env: LoadIterationEnvelope, info: {
+        primaryId: string;
+        primaryDurationMs: number;
+        releaseRequested: boolean;
+    }): void;
+    /** Emit `producer:released` (M6): the producer slot was freed at this iteration's
+     *  primaryComplete boundary so a new primary can start; the rest of this iteration
+     *  runs as a continuation. `backpressureMs` is the wait the release incurred when
+     *  the continuation backlog was full. */
+    emitProducerReleased(env: LoadIterationEnvelope, info: {
+        releaseId: string;
+        primaryDurationMs: number;
+        continuationBacklog: number;
+        backpressureMs: number;
+    }): void;
+    /** Emit `producer:releaseRejected` (M6): a release was requested but not granted —
+     *  backlog full under `fail-iteration`, a duplicate, a parked release whose drain
+     *  bound expired (`drainTimeout`), or one cancelled by the run deadline. */
+    emitProducerReleaseRejected(env: LoadIterationEnvelope, info: {
+        releaseId: string;
+        reason: "continuationBacklogFull" | "duplicateRelease" | "drainTimeout" | "runDeadlineReached";
+        waitMs: number;
+        continuationBacklog: number;
+    }): void;
+    /** Emit `load:start` with the resolved config (orchestrator run boundary). */
+    emitLoadStart(config: LoadResolvedConfig): void;
+    /** Emit `load:end` with why the run stopped. */
+    emitLoadEnd(reason: LoadEndReason): void;
+    /** Emit `producerSlot:start` when a producer slot begins generating load. */
+    emitProducerSlotStart(producerSlotIndex: number): void;
+    /** Emit `producerSlot:end` with how many primary iterations the slot ran. */
+    emitProducerSlotEnd(producerSlotIndex: number, primaryIterations: number): void;
+    /** The engine-core sink callback: translate one wire event to LoadEvent(s). */
+    readonly handleWire: (wire: Record<string, unknown>) => void;
+}
+export {};
+//# sourceMappingURL=sink.d.ts.map

package/dist/load/sink.d.ts.map

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

package/dist/load/sink.js

@@ -0,0 +1,351 @@
+import { resolveRouteKey } from "./route-key.js";
+export class LoadSink {
+    reducer;
+    runId;
+    runnerId;
+    now;
+    seq = 0;
+    // Once the run is finalized, events from continuations the drain timeout abandoned
+    // must not mutate reducer state (they'd land after the artifact was built).
+    sealed = false;
+    envelopes = new Map();
+    stepNames = new Map();
+    // Per-iteration phase: "primary" until that iteration's first primaryComplete
+    // boundary, "continuation" immediately after. Keyed by iterationId so concurrent
+    // iterations (one shared sink) flip independently. Every translated event carries
+    // this live phase, so post-boundary work (requests / assertions) is "continuation"
+    // — matching the public contract that `primaryComplete` switches the iteration
+    // into continuation. (Step aggregates stay coherent because the reducer keys steps
+    // by stepId, not by phase, so a step that spans the boundary is one row.)
+    phases = new Map();
+    // Per-iteration state for spotting a poll that held the producer slot without (timely)
+    // release — the long-poll advisory's target. All step indices are STEP-SCOPED; a poll's
+    // own attempt requests share its index, and unscoped setup/teardown requests (no
+    // stepIndex) don't enter the span. Two boundaries gate the spans separately:
+    //  - `primaryCompleted` (a bare OR releasing `primaryComplete`): after it, requests are
+    //    continuation-phase, so `maxPrimaryReq` (the latest PRIMARY-phase request) stops
+    //    advancing — a post-boundary request must not disqualify a held poll;
+    //  - `releaseRequested` (a releasing `primaryComplete`): after it the slot is FREED, so
+    //    `maxUnreleasedPoll` (the latest poll that ran while the slot was held) stops.
+    // Plus `minReq`, the earliest request. The advisory fires iff a request preceded the held
+    // poll (minReq < maxUnreleasedPoll) AND no primary-phase request followed it
+    // (maxPrimaryReq <= maxUnreleasedPoll) — the latter excludes a pre-primary readiness wait
+    // whose load comes later, while a post-boundary continuation request doesn't disqualify.
+    iterSpan = new Map();
+    // Whether any iteration ran a TAIL `.poll()` WITHOUT requesting producer release — the
+    // closed-scheduling case the long-poll advisory targets. Per-iteration (not run-wide):
+    // a row that releases doesn't mute the advisory for a sibling row that doesn't.
+    sawUnreleasedTailPoll = false;
+    constructor(reducer, runId, runnerId, now = () => Date.now()) {
+        this.reducer = reducer;
+        this.runId = runId;
+        this.runnerId = runnerId;
+        this.now = now;
+    }
+    /** Stamp envelope basics (ts / seq / runId / runnerId) and apply to the reducer.
+     *  A no-op once sealed (post-finalize), so abandoned continuations can't mutate
+     *  the already-built artifact. */
+    emit(body) {
+        if (this.sealed)
+            return;
+        this.reducer.apply({
+            ts: this.now(),
+            seq: this.seq++,
+            runId: this.runId,
+            runnerId: this.runnerId,
+            ...body,
+        });
+    }
+    /** Stop forwarding events to the reducer (called once the run is finalized). */
+    seal() {
+        this.sealed = true;
+    }
+    /** Whether any iteration ran a post-primary TAIL `.poll()` without requesting producer
+     *  release (a request before it, none after, and no release asked). Gates the
+     *  long-poll advisory — the closed-scheduling case it nudges toward release. */
+    get unreleasedTailPollRan() {
+        return this.sawUnreleasedTailPoll;
+    }
+    /** Flag the advisory if `span` shows a poll that HELD the slot: a request preceded it
+     *  (minReq < maxUnreleasedPoll) and no primary-phase request followed it
+     *  (maxPrimaryReq <= maxUnreleasedPoll — excludes a pre-primary readiness wait while
+     *  ignoring post-boundary continuation requests). The sentinels make a missing held poll
+     *  / request fail the first test. Idempotent — safe to call at release time AND at
+     *  endIteration (the spans are frozen once the primary boundary / release is reached). */
+    markUnreleasedTailPoll(span) {
+        if (span.minReq < span.maxUnreleasedPoll && span.maxPrimaryReq <= span.maxUnreleasedPoll) {
+            this.sawUnreleasedTailPoll = true;
+        }
+    }
+    /** Register an iteration's attribution before its engine run starts. */
+    beginIteration(env) {
+        this.envelopes.set(env.iterationId, env);
+        this.stepNames.set(env.iterationId, new Map());
+        this.phases.set(env.iterationId, "primary");
+        // Sentinels: no request (min +∞) and no primary request / held poll (max −∞) until seen.
+        this.iterSpan.set(env.iterationId, {
+            minReq: Infinity, maxPrimaryReq: -Infinity, maxUnreleasedPoll: -Infinity, primaryCompleted: false, releaseRequested: false,
+        });
+    }
+    /** Drop an iteration's per-iteration buffers once it has finished. */
+    endIteration(iterationId) {
+        // Catch the no-release case (the iteration ran to completion without ever asking for
+        // release, so its whole span is now final). Released iterations are evaluated earlier,
+        // at release time, so a later drain-abandoned continuation can't lose the advisory.
+        const span = this.iterSpan.get(iterationId);
+        if (span !== undefined)
+            this.markUnreleasedTailPoll(span);
+        this.envelopes.delete(iterationId);
+        this.stepNames.delete(iterationId);
+        this.phases.delete(iterationId);
+        this.iterSpan.delete(iterationId);
+    }
+    /** The shared per-iteration attribution every translated event carries. Phase
+     *  starts "primary" and flips to "continuation" at the iteration's first
+     *  `primaryComplete` boundary (see `emitPrimaryCompleted`). */
+    baseOf(env) {
+        return {
+            scenarioId: env.scenarioId,
+            ...(env.scenarioRefId !== undefined ? { scenarioRefId: env.scenarioRefId } : {}),
+            producerSlotId: env.producerSlotId,
+            iterationId: env.iterationId,
+            phase: this.phases.get(env.iterationId) ?? "primary",
+        };
+    }
+    /** Emit `iteration:start` (the executor calls this right after beginIteration). */
+    emitIterationStart(env, opts = {}) {
+        this.emit({
+            type: "iteration:start",
+            ...this.baseOf(env),
+            ...(opts.inputKey !== undefined ? { inputKey: opts.inputKey } : {}),
+            ...(opts.feederKeys !== undefined ? { feederKeys: opts.feederKeys } : {}),
+        });
+    }
+    /** Emit `iteration:end` (the executor calls this once the engine run resolves). */
+    emitIterationEnd(env, result) {
+        this.emit({
+            type: "iteration:end",
+            ...this.baseOf(env),
+            ok: result.ok,
+            durationMs: result.durationMs,
+            ...(result.errorKind !== undefined ? { errorKind: result.errorKind } : {}),
+        });
+    }
+    /** A per-scenario-stable, leaf-unique step id. The engine's leaf `index` is
+     *  assigned in deterministic registry order (taken or skipped), so the same
+     *  logical step always gets the same index — folding it in disambiguates two
+     *  leaves that share a display name (the reducer keys aggregates by stepId). */
+    stepIdOf(index, name) {
+        return `${index}:${name}`;
+    }
+    /** Emit `report:checkpoint` (backs `ctx.report.checkpoint`). */
+    emitCheckpoint(env, checkpointId, data) {
+        this.emit({
+            type: "report:checkpoint",
+            ...this.baseOf(env),
+            checkpointId,
+            ...(data !== undefined ? { data } : {}),
+        });
+    }
+    /** Emit `producer:primaryCompleted` (backs the first `ctx.report.primaryComplete`)
+     *  and FLIP this iteration into its continuation phase immediately, so every
+     *  request / checkpoint the sink translates afterwards carries
+     *  `phase: "continuation"` (the API's contract). The boundary event itself is
+     *  stamped with the pre-flip ("primary") phase. A step that spans the boundary
+     *  still keeps a single phase because step:end uses its captured START phase
+     *  (see the `step_end` case). M5 records the measurement boundary only —
+     *  `releaseRequested` is forwarded for M6 scheduling, it does not release a slot. */
+    emitPrimaryCompleted(env, info) {
+        this.emit({
+            type: "producer:primaryCompleted",
+            ...this.baseOf(env),
+            primaryId: info.primaryId,
+            primaryDurationMs: info.primaryDurationMs,
+            releaseRequested: info.releaseRequested,
+        });
+        // This is the PRIMARY BOUNDARY (bare or releasing): from here on, requests are
+        // continuation-phase and stop advancing `maxPrimaryReq`. A RELEASING boundary also
+        // frees the slot, so later polls stop extending `maxUnreleasedPoll`; but any poll that
+        // ALREADY ran still held the slot — a late release can't free it in hindsight. Since
+        // the spans are now frozen, evaluate the advisory at release time — the continuation
+        // may be abandoned by the drain timeout before endIteration runs, which would otherwise
+        // lose this misordered case. (A requested-but-rejected release still counts as "asked".)
+        const span = this.iterSpan.get(env.iterationId);
+        if (span !== undefined) {
+            span.primaryCompleted = true;
+            if (info.releaseRequested) {
+                span.releaseRequested = true;
+                this.markUnreleasedTailPoll(span);
+            }
+        }
+        this.phases.set(env.iterationId, "continuation");
+    }
+    /** Emit `producer:released` (M6): the producer slot was freed at this iteration's
+     *  primaryComplete boundary so a new primary can start; the rest of this iteration
+     *  runs as a continuation. `backpressureMs` is the wait the release incurred when
+     *  the continuation backlog was full. */
+    emitProducerReleased(env, info) {
+        this.emit({
+            type: "producer:released",
+            ...this.baseOf(env),
+            releaseId: info.releaseId,
+            primaryDurationMs: info.primaryDurationMs,
+            continuationBacklog: info.continuationBacklog,
+            ...(info.backpressureMs > 0 ? { continuationBackpressure: true } : {}),
+            backpressureMs: info.backpressureMs,
+        });
+    }
+    /** Emit `producer:releaseRejected` (M6): a release was requested but not granted —
+     *  backlog full under `fail-iteration`, a duplicate, a parked release whose drain
+     *  bound expired (`drainTimeout`), or one cancelled by the run deadline. */
+    emitProducerReleaseRejected(env, info) {
+        this.emit({
+            type: "producer:releaseRejected",
+            ...this.baseOf(env),
+            releaseId: info.releaseId,
+            reason: info.reason,
+            waitMs: info.waitMs,
+            continuationBacklog: info.continuationBacklog,
+        });
+    }
+    /** Emit `load:start` with the resolved config (orchestrator run boundary). */
+    emitLoadStart(config) {
+        this.emit({ type: "load:start", config });
+    }
+    /** Emit `load:end` with why the run stopped. */
+    emitLoadEnd(reason) {
+        this.emit({ type: "load:end", reason });
+    }
+    /** Emit `producerSlot:start` when a producer slot begins generating load. */
+    emitProducerSlotStart(producerSlotIndex) {
+        this.emit({ type: "producerSlot:start", producerSlotIndex });
+    }
+    /** Emit `producerSlot:end` with how many primary iterations the slot ran. */
+    emitProducerSlotEnd(producerSlotIndex, primaryIterations) {
+        this.emit({ type: "producerSlot:end", producerSlotIndex, primaryIterations });
+    }
+    /** The engine-core sink callback: translate one wire event to LoadEvent(s). */
+    handleWire = (wire) => {
+        const iterationId = wire.testId;
+        if (!iterationId)
+            return;
+        const env = this.envelopes.get(iterationId);
+        if (!env)
+            return; // not a tracked load iteration
+        const base = this.baseOf(env);
+        switch (wire.type) {
+            case "step_start": {
+                const index = wire.index;
+                const name = wire.name;
+                const group = wire.group;
+                this.stepNames.get(iterationId)?.set(index, name);
+                this.emit({
+                    type: "step:start",
+                    ...base,
+                    stepId: this.stepIdOf(index, name),
+                    stepName: name,
+                    ...(group !== undefined ? { groupId: group } : {}),
+                });
+                break;
+            }
+            case "step_end": {
+                const index = wire.index;
+                const name = wire.name;
+                const status = wire.status;
+                const group = wire.group;
+                this.emit({
+                    type: "step:end",
+                    ...base,
+                    stepId: this.stepIdOf(index, name),
+                    stepName: name,
+                    ok: status === "passed",
+                    durationMs: wire.durationMs ?? 0,
+                    ...(status === "skipped" ? { skipped: true } : {}),
+                    assertionFailures: wire.failedAssertions ?? 0,
+                    ...(wire.error !== undefined ? { errorKind: "stepError" } : {}),
+                    // Carries group for SKIPPED leaves (no step:start emitted for them).
+                    ...(group !== undefined ? { groupId: group } : {}),
+                });
+                break;
+            }
+            case "trace": {
+                const t = (wire.data ?? {});
+                const stepIndex = wire.stepIndex;
+                // Widen this iteration's request step-index span — ONLY for step-scoped requests.
+                // An unscoped setup/teardown HTTP call (no stepIndex) must not count as a request
+                // before a step, or a pre-primary readiness poll would look like a tail.
+                if (stepIndex !== undefined) {
+                    const span = this.iterSpan.get(iterationId);
+                    if (span !== undefined) {
+                        if (stepIndex < span.minReq)
+                            span.minReq = stepIndex;
+                        // Only PRIMARY-PHASE requests (before the boundary) bound the tail: a post-
+                        // boundary continuation request mustn't make an earlier held poll look pre-primary.
+                        if (!span.primaryCompleted && stepIndex > span.maxPrimaryReq)
+                            span.maxPrimaryReq = stepIndex;
+                    }
+                }
+                const stepName = stepIndex !== undefined ? this.stepNames.get(iterationId)?.get(stepIndex) : undefined;
+                // Resolve the routeKey. An EXACT route template from the trace (M8 — a
+                // `contract.http()` client / user `X-Glubean-Route` header, e.g. "GET /runs/:runId")
+                // wins and is exact (`contract-metadata`, not heuristic). Otherwise fall back to
+                // method + heuristic URL normalization (id-like segments → ":id", M3-e): the method
+                // is recovered from the trace `target` when explicit `method` is absent, so a
+                // target-only POST/PUT isn't mislabelled GET.
+                const exact = t.routeKey !== undefined && t.routeKey !== "";
+                const { method, routeKey } = resolveRouteKey(t.method, t.url, t.target, t.protocol, t.routeKey);
+                this.emit({
+                    type: "request:observed",
+                    ...base,
+                    ...(stepName !== undefined ? { stepId: this.stepIdOf(stepIndex, stepName) } : {}),
+                    method,
+                    url: t.url ?? "",
+                    routeKey,
+                    routeKeySource: exact ? "contract-metadata" : "normalized-url",
+                    routeKeyHeuristic: !exact,
+                    ...(t.status !== undefined ? { status: t.status } : {}),
+                    ok: t.ok ?? false,
+                    durationMs: t.durationMs ?? 0,
+                });
+                break;
+            }
+            case "assertion": {
+                const stepIndex = wire.stepIndex;
+                const stepName = stepIndex !== undefined ? this.stepNames.get(iterationId)?.get(stepIndex) : undefined;
+                this.emit({
+                    type: "assertion:observed",
+                    ...base,
+                    ...(stepName !== undefined ? { stepId: this.stepIdOf(stepIndex, stepName) } : {}),
+                    passed: wire.passed,
+                    ...(wire.message !== undefined ? { message: wire.message } : {}),
+                    // Diagnostic operands so a failure sample can show what value failed (the reducer
+                    // previews/bounds them — only retained for FAILED assertions). Presence checks, not
+                    // `!== undefined`, so a deliberately-`undefined` operand is preserved (codex).
+                    ...("actual" in wire ? { actual: wire.actual } : {}),
+                    ...("expected" in wire ? { expected: wire.expected } : {}),
+                });
+                break;
+            }
+            case "poll": {
+                // A poll step ran (the event fires after its attempt loop). Record its step
+                // index; whether it's a post-primary TAIL is decided in endIteration once the
+                // full request span is known (a later load request would disqualify it). No
+                // reducer mutation, so seal is irrelevant.
+                const pollIndex = wire.index;
+                const span = this.iterSpan.get(iterationId);
+                // Only a poll that ran while the slot was still HELD (no release yet) counts — a
+                // poll after release ran on a freed slot. Track the highest such index, so a later
+                // released poll can't erase an earlier held one.
+                if (span !== undefined && !span.releaseRequested && pollIndex > span.maxUnreleasedPoll) {
+                    span.maxUnreleasedPoll = pollIndex;
+                }
+                break;
+            }
+            // log / metric / action / event / warning / schema / branch / start / status /
+            // timeout: not part of the M3 closed-model aggregates.
+            default:
+                break;
+        }
+    };
+}
+//# sourceMappingURL=sink.js.map

package/dist/load/sink.js.map

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

package/dist/load/subprocess.d.ts

@@ -0,0 +1,83 @@
+import type { LoadArtifact, LoadPlan } from "@glubean/sdk/load";
+/**
+ * Marker prefixed to every harness protocol line on stdout. The user's load file
+ * + plugins share stdout, whose `console.log` may itself print JSON; gating on
+ * this token stops a stray `{"type":"error",...}` log from spoofing an outcome or
+ * a failure. It leads with the ASCII Unit Separator (0x1F) — a control byte that
+ * ordinary text logs never emit — so collision is negligible. Lines without it
+ * are forwarded to the parent's stdout as ordinary user output.
+ *
+ * (stdout, not a dedicated fd: tsx re-spawns an inner node process and forwards
+ * only fd 0/1/2, so an extra protocol fd wouldn't reach the harness.)
+ */
+export declare const WIRE_PREFIX = "\u001Fglubean-load-wire\u001F";
+/**
+ * One NDJSON line (after `WIRE_PREFIX`) emitted by `load-harness`. `artifact`
+ * carries a completed plan's finalized `LoadArtifact`; `error` carries a per-file
+ * import failure or a per-plan run failure; `done` is the terminal sentinel
+ * proving the harness finished its own logic cleanly (its absence at child exit
+ * means the child crashed before completing).
+ */
+export type LoadHarnessMessage = {
+    type: "artifact";
+    runnerId: string;
+    artifact: LoadArtifact;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "done";
+};
+/**
+ * Collect every LoadPlan exported by a module namespace (flattening `.each()`
+ * arrays of plans).
+ */
+export declare function collectLoadPlans(ns: Record<string, unknown>): LoadPlan[];
+/**
+ * Wrap an env map so a missing key falls back to `process.env` — the same
+ * shell/CI env semantics the test harness gives `ctx.vars` / `ctx.secrets`, so
+ * `BASE_URL=... glubean load ...` resolves even without a `.env` entry.
+ *
+ * Applied INSIDE the child (which inherits the parent's `process.env`): the
+ * parent ships the raw resolved `{ vars, secrets }` over stdin — a Proxy can't
+ * survive JSON serialization, so the fallback must be re-established where
+ * `process.env` is actually present. Spreading the proxy (for `ctx.vars.all()`)
+ * still yields only the explicit map's own keys, not the whole environment.
+ */
+export declare function withProcessEnvFallback(map: Record<string, string>): Record<string, string>;
+/** One plan's completed run, parsed from the child's `artifact` message. */
+export interface LoadSubprocessOutcome {
+    runnerId: string;
+    artifact: LoadArtifact;
+}
+/** A per-file or per-plan failure, parsed from the child's `error` message. */
+export interface LoadSubprocessError {
+    message: string;
+}
+/** Result of running one `.load.ts` file in a child process. */
+export interface RunLoadFileResult {
+    outcomes: LoadSubprocessOutcome[];
+    errors: LoadSubprocessError[];
+}
+/** Options for a single-file subprocess load run. */
+export interface RunLoadFileOptions {
+    /** Resolved environment vars (raw — env fallback is applied in the child). */
+    vars: Record<string, string>;
+    /** Resolved secrets (raw — env fallback is applied in the child). */
+    secrets: Record<string, string>;
+    /** Working dir for the child (the project root) — drives runner resolution. */
+    cwd: string;
+}
+/**
+ * Run one `.load.ts` file's plans in a child process and collect their
+ * artifacts. Spawns `load-harness.js` (project-local when the project ships a
+ * built runner with it, else the CLI's bundled copy) through tsx so the harness
+ * and the user file resolve the same `@glubean/sdk`. The raw `{ vars, secrets }`
+ * are written to the child's stdin; the child applies the process.env fallback.
+ *
+ * Mirrors the in-process contract: a file's import failure or a plan's run
+ * failure becomes an `errors[]` entry (never throws), so other files/plans still
+ * produce results.
+ */
+export declare function runLoadFileInSubprocess(file: string, opts: RunLoadFileOptions): Promise<RunLoadFileResult>;
+//# sourceMappingURL=subprocess.d.ts.map

package/dist/load/subprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../src/load/subprocess.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAKhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,kCAA8B,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAarB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,EAAE,CAUxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiB1F;AAID,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,MAAM,EAAE,mBAAmB,EAAE,CAAC;CAC/B;AAED,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;CACb;AA8BD;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CA+F5B"}