orbit-bus 0.1.1

package/dist/src/orbit_actions.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import { createEnvelope, validateEnvelope } from "./envelope.js";
+import { OrbitError } from "./errors.js";
+import { decodeJson, encodeJson, osPut, publishSubject } from "./nats.js";
+import { loadServiceRecordDistributed } from "./registry.js";
+import { randomId } from "./util.js";
+import { validateActionPayload } from "./api_contract.js";
+import { executeRpcCall } from "./rpc_call.js";
+import { prefixedSubject } from "./subjects.js";
+export async function executeOrbitAction(config, nc, action, payload, actor) {
+    validateActionPayload(action, payload);
+    switch (action) {
+        case "ping":
+            return { ok: true, now: new Date().toISOString() };
+        case "call":
+            return executeCall(config, nc, payload, actor);
+        case "publish":
+            return executePublish(config, nc, payload, actor);
+        case "inspect":
+            return executeInspect(config, nc, payload);
+        default:
+            throw new OrbitError("BAD_ARGS", `unknown action: ${String(action)}`);
+    }
+}
+async function executeCall(config, nc, payload, actor) {
+    const target = String(payload.target ?? "");
+    if (!target.match(/^([a-zA-Z0-9_-]+)\.([a-zA-Z0-9_-]+)$/)) {
+        throw new OrbitError("BAD_TARGET", "target must be <service>.<method>");
+    }
+    return executeRpcCall(config, nc, {
+        target,
+        body: payload.body,
+        timeoutMs: Number(payload.timeoutMs ?? config.requestTimeoutMs),
+        retries: Number(payload.retries ?? config.retries),
+        runId: typeof payload.runId === "string" ? payload.runId : undefined,
+        packFile: typeof payload.packFile === "string" ? payload.packFile : undefined,
+        a2a: {
+            task_id: typeof payload.taskId === "string" ? payload.taskId : undefined,
+            thread_id: typeof payload.threadId === "string" ? payload.threadId : undefined,
+            parent_message_id: typeof payload.parentMessageId === "string" ? payload.parentMessageId : undefined,
+            capabilities: Array.isArray(payload.capabilities)
+                ? payload.capabilities.filter((v) => typeof v === "string" && Boolean(v))
+                : undefined,
+            traceparent: typeof payload.traceparent === "string" ? payload.traceparent : undefined,
+            dedupe_key: typeof payload.dedupeKey === "string" ? payload.dedupeKey : undefined
+        },
+        actor: `orbit-${actor}`,
+        traceStartEvent: "call_start"
+    });
+}
+async function executePublish(config, nc, payload, actor) {
+    const topic = String(payload.topic ?? "");
+    if (!topic)
+        throw new OrbitError("BAD_ARGS", "publish requires topic");
+    const runId = typeof payload.runId === "string" ? payload.runId : randomId();
+    const packFile = typeof payload.packFile === "string" ? payload.packFile : undefined;
+    const dataPackRef = packFile
+        ? {
+            bucket: config.objectStoreBucket,
+            key: `${runId}/pub/${Date.now()}-${randomId()}.bin`,
+            bytes: fs.statSync(packFile).size
+        }
+        : undefined;
+    if (packFile && dataPackRef) {
+        await osPut(nc, dataPackRef.bucket, dataPackRef.key, fs.readFileSync(packFile), {
+            description: `orbit event data pack for ${topic}`
+        });
+    }
+    const env = createEnvelope({
+        kind: "event",
+        runId,
+        payload: payload.body,
+        dataPack: dataPackRef,
+        provenance: { publisher: `orbit-${actor}`, topic },
+        a2a: {
+            task_id: typeof payload.taskId === "string" ? payload.taskId : undefined,
+            thread_id: typeof payload.threadId === "string" ? payload.threadId : undefined,
+            parent_message_id: typeof payload.parentMessageId === "string" ? payload.parentMessageId : undefined,
+            capabilities: Array.isArray(payload.capabilities)
+                ? payload.capabilities.filter((v) => typeof v === "string" && Boolean(v))
+                : undefined,
+            traceparent: typeof payload.traceparent === "string" ? payload.traceparent : undefined,
+            dedupe_key: typeof payload.dedupeKey === "string" ? payload.dedupeKey : undefined
+        }
+    });
+    const durable = typeof payload.durable === "boolean" ? payload.durable : config.runtime.publishDurableEnabled;
+    const dedupeKey = typeof payload.dedupeKey === "string" && payload.dedupeKey
+        ? payload.dedupeKey
+        : env.a2a?.dedupe_key;
+    await publishSubject(nc, topic, encodeJson(env), {
+        durable,
+        dedupeKey,
+        timeoutMs: config.runtime.publishDurableTimeoutMs
+    });
+    await nc.flush();
+    return { ok: true, topic, run_id: runId, durable };
+}
+async function executeInspect(config, nc, payload) {
+    const service = String(payload.service ?? "");
+    const timeoutMs = Number(payload.timeoutMs ?? config.requestTimeoutMs);
+    if (!service)
+        throw new OrbitError("BAD_ARGS", "inspect requires service");
+    try {
+        const msg = await nc.request(prefixedSubject(config, "inspect", service), encodeJson(createEnvelope({ kind: "request", payload: {} })), {
+            timeout: timeoutMs
+        });
+        const env = validateEnvelope(decodeJson(msg.data), { skipHashCheck: config.performance.trustedLocal });
+        return env.payload;
+    }
+    catch {
+        try {
+            const msg = await nc.request(`$SRV.INFO.${service}`, encodeJson({}), { timeout: timeoutMs });
+            return decodeJson(msg.data);
+        }
+        catch {
+            try {
+                const msg = await nc.request(prefixedSubject(config, "discovery", "query"), encodeJson({ service }), { timeout: timeoutMs });
+                const env = validateEnvelope(decodeJson(msg.data), { skipHashCheck: config.performance.trustedLocal });
+                return env.payload;
+            }
+            catch {
+                const local = await loadServiceRecordDistributed(config, service);
+                if (!local)
+                    throw new OrbitError("NOT_FOUND", `service ${service} not found`);
+                return local;
+            }
+        }
+    }
+}

package/dist/src/otel.d.ts

@@ -0,0 +1,2 @@
+import { OrbitConfig, TraceEvent } from "./types.js";
+export declare function exportTraceEvent(config: OrbitConfig, event: TraceEvent): Promise<void>;

package/dist/src/otel.js

@@ -0,0 +1,96 @@
+function toNanoTime(ts) {
+    const ms = Date.parse(ts);
+    return String(ms * 1_000_000);
+}
+const pendingByEndpoint = new Map();
+const flushTimers = new Map();
+function scheduleFlush(config) {
+    const endpoint = config.otel.endpoint;
+    if (!endpoint || flushTimers.has(endpoint))
+        return;
+    const timer = setTimeout(() => {
+        flushTimers.delete(endpoint);
+        void flushNow(config, endpoint);
+    }, config.performance.traceFlushIntervalMs);
+    timer.unref?.();
+    flushTimers.set(endpoint, timer);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+function calculateBackoffMs(attempt) {
+    const base = 100 * 2 ** attempt;
+    const jitter = Math.floor(Math.random() * 50);
+    return base + jitter;
+}
+async function flushNow(config, endpoint) {
+    const events = pendingByEndpoint.get(endpoint) ?? [];
+    if (events.length === 0)
+        return;
+    pendingByEndpoint.set(endpoint, []);
+    const spans = events.map((event) => ({
+        traceId: (event.run_id.replace(/-/g, "").padEnd(32, "0")).slice(0, 32),
+        spanId: (event.span_id.replace(/-/g, "").padEnd(16, "0")).slice(0, 16),
+        name: event.event,
+        kind: 1,
+        startTimeUnixNano: toNanoTime(event.ts),
+        endTimeUnixNano: toNanoTime(event.ts),
+        attributes: [
+            { key: "orbit.run_id", value: { stringValue: event.run_id } },
+            { key: "orbit.actor", value: { stringValue: event.actor } },
+            ...(event.svc ? [{ key: "orbit.service", value: { stringValue: event.svc } }] : []),
+            ...(event.method ? [{ key: "orbit.method", value: { stringValue: event.method } }] : []),
+            ...(event.retry !== undefined ? [{ key: "orbit.retry", value: { intValue: event.retry } }] : []),
+            ...(event.error_code ? [{ key: "orbit.error_code", value: { stringValue: event.error_code } }] : [])
+        ]
+    }));
+    const payload = {
+        resourceSpans: [
+            {
+                resource: { attributes: [{ key: "service.name", value: { stringValue: config.otel.serviceName } }] },
+                scopeSpans: [{ scope: { name: "orbit" }, spans }]
+            }
+        ]
+    };
+    const maxAttempts = 3;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(payload)
+            });
+            if (response.ok)
+                return;
+            if (!isRetryableStatus(response.status))
+                return;
+        }
+        catch {
+            // network failure; retry with backoff
+        }
+        if (attempt < maxAttempts - 1) {
+            await sleep(calculateBackoffMs(attempt));
+        }
+    }
+    // Preserve recent unsent trace events so transient OTLP outages don't silently drop data.
+    const queue = pendingByEndpoint.get(endpoint) ?? [];
+    const merged = [...events, ...queue];
+    pendingByEndpoint.set(endpoint, merged.slice(-config.performance.traceBufferMaxEvents));
+    scheduleFlush(config);
+}
+export async function exportTraceEvent(config, event) {
+    const endpoint = config.otel.endpoint;
+    if (!endpoint)
+        return;
+    const queue = pendingByEndpoint.get(endpoint) ?? [];
+    queue.push(event);
+    pendingByEndpoint.set(endpoint, queue);
+    if (queue.length >= 64) {
+        await flushNow(config, endpoint);
+        return;
+    }
+    scheduleFlush(config);
+}

package/dist/src/registry.d.ts

@@ -0,0 +1,10 @@
+import { OrbitConfig, ServiceSpec } from "./types.js";
+export interface ServiceRegistryRecord {
+    service: string;
+    registered_at: string;
+    spec: ServiceSpec;
+}
+export declare function saveServiceRecord(config: OrbitConfig, service: string, spec: ServiceSpec): void;
+export declare function saveServiceRecordDistributed(config: OrbitConfig, service: string, spec: ServiceSpec): Promise<void>;
+export declare function loadServiceRecord(config: OrbitConfig, service: string): ServiceRegistryRecord | null;
+export declare function loadServiceRecordDistributed(config: OrbitConfig, service: string): Promise<ServiceRegistryRecord | null>;

package/dist/src/registry.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+import fs from "node:fs";
+import { writeJsonFile } from "./util.js";
+import { closeBus, connectBus, kvGet, kvPut } from "./nats.js";
+export function saveServiceRecord(config, service, spec) {
+    const rec = {
+        service,
+        registered_at: new Date().toISOString(),
+        spec
+    };
+    const filePath = path.join(config.servicesDir, `${service}.json`);
+    writeJsonFile(filePath, rec);
+}
+export async function saveServiceRecordDistributed(config, service, spec) {
+    saveServiceRecord(config, service, spec);
+    try {
+        const nc = await connectBus(config.natsUrl);
+        const rec = {
+            service,
+            registered_at: new Date().toISOString(),
+            spec
+        };
+        try {
+            await kvPut(nc, config.kvBucket, service, rec);
+        }
+        finally {
+            await closeBus(config.natsUrl);
+        }
+    }
+    catch {
+        // local file registry remains authoritative fallback when JetStream/KV is unavailable.
+    }
+}
+export function loadServiceRecord(config, service) {
+    const filePath = path.join(config.servicesDir, `${service}.json`);
+    if (!fs.existsSync(filePath))
+        return null;
+    const text = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(text);
+}
+export async function loadServiceRecordDistributed(config, service) {
+    try {
+        const nc = await connectBus(config.natsUrl);
+        try {
+            const rec = await kvGet(nc, config.kvBucket, service);
+            if (rec)
+                return rec;
+        }
+        finally {
+            await closeBus(config.natsUrl);
+        }
+    }
+    catch {
+        // no-op fallback to local registry below
+    }
+    return loadServiceRecord(config, service);
+}

package/dist/src/retry.d.ts

@@ -0,0 +1,9 @@
+export interface RetryOptions {
+    retries: number;
+    timeoutMs: number;
+    onRetry?: (attempt: number, err: unknown) => void;
+}
+export declare function withRetries<T>(work: (attempt: number) => Promise<T>, options: RetryOptions): Promise<{
+    value: T;
+    attempts: number;
+}>;

package/dist/src/retry.js

@@ -0,0 +1,32 @@
+import { OrbitError } from "./errors.js";
+async function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new OrbitError("TIMEOUT", `Timed out after ${ms}ms`));
+        }, ms);
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+export async function withRetries(work, options) {
+    const totalAttempts = Math.max(1, options.retries + 1);
+    let lastErr;
+    for (let attempt = 1; attempt <= totalAttempts; attempt += 1) {
+        try {
+            const value = await withTimeout(work(attempt), options.timeoutMs);
+            return { value, attempts: attempt };
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt < totalAttempts)
+                options.onRetry?.(attempt, err);
+        }
+    }
+    throw lastErr ?? new OrbitError("UNKNOWN", "retry failed");
+}

package/dist/src/rpc_call.d.ts

@@ -0,0 +1,22 @@
+import { NatsConnection } from "nats";
+import { OrbitConfig } from "./types.js";
+interface ExecuteRpcCallOptions {
+    target: string;
+    body: unknown;
+    timeoutMs?: number;
+    retries?: number;
+    runId?: string;
+    packFile?: string;
+    a2a?: {
+        task_id?: string;
+        thread_id?: string;
+        parent_message_id?: string;
+        capabilities?: string[];
+        traceparent?: string;
+        dedupe_key?: string;
+    };
+    actor: string;
+    traceStartEvent?: string;
+}
+export declare function executeRpcCall(config: OrbitConfig, nc: NatsConnection, opts: ExecuteRpcCallOptions): Promise<unknown>;
+export {};

package/dist/src/rpc_call.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import { createEnvelope, validateEnvelope } from "./envelope.js";
+import { withRetries } from "./retry.js";
+import { decodeJson, encodeJson, osPut } from "./nats.js";
+import { appendTraceEvent } from "./trace.js";
+import { randomId } from "./util.js";
+import { afterCallAttempt, beforeCall, onCallFailure, onCallSuccess } from "./call_protection.js";
+import { prefixedSubject } from "./subjects.js";
+import { OrbitError } from "./errors.js";
+import { incCounter, observeHistogram } from "./metrics.js";
+export async function executeRpcCall(config, nc, opts) {
+    const m = opts.target.match(/^([a-zA-Z0-9_-]+)\.([a-zA-Z0-9_-]+)$/);
+    if (!m)
+        throw new OrbitError("BAD_TARGET", "target must be <service>.<method>");
+    const [, svc, method] = m;
+    const timeoutMs = opts.timeoutMs ?? config.requestTimeoutMs;
+    const retries = opts.retries ?? config.retries;
+    const runId = opts.runId ?? randomId();
+    const dataPackRef = opts.packFile
+        ? {
+            bucket: config.objectStoreBucket,
+            key: `${runId}/${svc}.${method}/${Date.now()}-${randomId()}.bin`,
+            bytes: fs.statSync(opts.packFile).size
+        }
+        : undefined;
+    if (opts.packFile && dataPackRef) {
+        await osPut(nc, dataPackRef.bucket, dataPackRef.key, fs.readFileSync(opts.packFile), {
+            description: `orbit data pack for ${svc}.${method}`
+        });
+    }
+    const reqEnv = createEnvelope({
+        kind: "request",
+        runId,
+        payload: opts.body,
+        dataPack: dataPackRef,
+        provenance: { caller: opts.actor, target: opts.target },
+        a2a: opts.a2a
+    });
+    const spanId = reqEnv.id;
+    appendTraceEvent(config, {
+        span_id: spanId,
+        run_id: runId,
+        ts: new Date().toISOString(),
+        actor: opts.actor,
+        event: opts.traceStartEvent ?? "call_start",
+        svc,
+        method
+    });
+    const subject = prefixedSubject(config, "rpc", svc, method);
+    const started = Date.now();
+    beforeCall(config, opts.target);
+    try {
+        const { value, attempts } = await withRetries(async (attempt) => {
+            const msg = await nc.request(subject, encodeJson(reqEnv), { timeout: timeoutMs });
+            appendTraceEvent(config, {
+                span_id: spanId,
+                run_id: runId,
+                ts: new Date().toISOString(),
+                actor: opts.actor,
+                event: "attempt_reply",
+                svc,
+                method,
+                retry: attempt - 1
+            });
+            return msg;
+        }, {
+            retries,
+            timeoutMs,
+            onRetry: (attempt, err) => {
+                onCallFailure(config, opts.target);
+                appendTraceEvent(config, {
+                    span_id: spanId,
+                    run_id: runId,
+                    ts: new Date().toISOString(),
+                    actor: opts.actor,
+                    event: "retry",
+                    svc,
+                    method,
+                    retry: attempt,
+                    error_code: err.code ?? "RETRY"
+                });
+            }
+        });
+        const env = validateEnvelope(decodeJson(value.data), { skipHashCheck: config.performance.trustedLocal });
+        const payload = env.payload;
+        if (payload?.ok === false) {
+            onCallFailure(config, opts.target);
+        }
+        else {
+            onCallSuccess(opts.target);
+        }
+        appendTraceEvent(config, {
+            span_id: spanId,
+            run_id: runId,
+            ts: new Date().toISOString(),
+            actor: opts.actor,
+            event: "call_end",
+            svc,
+            method,
+            latency_ms: Date.now() - started,
+            retry: attempts - 1
+        });
+        const durationMs = Date.now() - started;
+        observeHistogram("orbit_rpc_call_duration_ms", durationMs, { target: opts.target, outcome: "ok" });
+        incCounter("orbit_rpc_calls_total", 1, { target: opts.target, outcome: "ok" });
+        return env.payload;
+    }
+    catch (err) {
+        onCallFailure(config, opts.target);
+        const code = err.code ?? "ERROR";
+        const durationMs = Date.now() - started;
+        observeHistogram("orbit_rpc_call_duration_ms", durationMs, { target: opts.target, outcome: "error", code });
+        incCounter("orbit_rpc_calls_total", 1, { target: opts.target, outcome: "error", code });
+        throw err;
+    }
+    finally {
+        afterCallAttempt(opts.target);
+    }
+}

package/dist/src/service_adapter.d.ts

@@ -0,0 +1,7 @@
+import { ServiceMethodSpec } from "./types.js";
+interface WorkerExecutionPolicy {
+    poolSize: number;
+    maxPendingPerWorker: number;
+}
+export declare function executeMethod(methodSpec: ServiceMethodSpec, requestPayload: unknown, defaultTimeoutMs: number, workerPolicy?: WorkerExecutionPolicy): Promise<unknown>;
+export {};

package/dist/src/service_adapter.js

@@ -0,0 +1,163 @@
+import { spawn } from "node:child_process";
+import { OrbitError } from "./errors.js";
+import { assertJsonSchema } from "./json_schema.js";
+import { WorkerPool } from "./worker_pool.js";
+function readPath(obj, segments) {
+    if (segments.length === 0)
+        return undefined;
+    let curr = obj;
+    for (const key of segments) {
+        if (!curr || typeof curr !== "object" || !(key in curr))
+            return undefined;
+        curr = curr[key];
+    }
+    return curr;
+}
+const templateCache = new Map();
+function compileTemplate(input) {
+    const cached = templateCache.get(input);
+    if (cached)
+        return cached;
+    const parts = [];
+    const regex = /\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = regex.exec(input))) {
+        if (match.index > lastIndex)
+            parts.push({ literal: input.slice(lastIndex, match.index) });
+        parts.push({ path: match[1].split(".") });
+        lastIndex = regex.lastIndex;
+    }
+    if (lastIndex < input.length)
+        parts.push({ literal: input.slice(lastIndex) });
+    templateCache.set(input, parts);
+    return parts;
+}
+function template(input, ctx) {
+    const parts = compileTemplate(input);
+    let out = "";
+    for (const part of parts) {
+        if (part.literal !== undefined) {
+            out += part.literal;
+            continue;
+        }
+        const val = readPath(ctx, part.path ?? []);
+        if (val === undefined || val === null)
+            continue;
+        if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
+            out += String(val);
+            continue;
+        }
+        out += JSON.stringify(val);
+    }
+    return out;
+}
+const workerPool = new WorkerPool();
+async function executeHttpMethod(methodSpec, requestPayload, timeoutMs) {
+    const endpoint = methodSpec.http_endpoint ? template(methodSpec.http_endpoint, requestPayload) : "";
+    if (!endpoint)
+        throw new OrbitError("METHOD_BAD_HTTP_SPEC", "http transport requires http_endpoint");
+    const method = methodSpec.http_method ?? "POST";
+    const templatedHeaders = {};
+    for (const [k, v] of Object.entries(methodSpec.headers ?? {})) {
+        templatedHeaders[k] = template(v, requestPayload);
+    }
+    const headers = {
+        "content-type": "application/json",
+        ...templatedHeaders
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    try {
+        const res = await fetch(endpoint, {
+            method,
+            headers,
+            body: method === "GET" ? undefined : JSON.stringify(requestPayload ?? {}),
+            signal: controller.signal
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new OrbitError("METHOD_HTTP_ERROR", `http method failed with status ${res.status}`, {
+                status: res.status,
+                body: text
+            });
+        }
+        if (!text.trim())
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { body: text };
+        }
+    }
+    catch (err) {
+        if (err.name === "AbortError") {
+            throw new OrbitError("METHOD_TIMEOUT", `http method timed out after ${timeoutMs}ms`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function executeMethod(methodSpec, requestPayload, defaultTimeoutMs, workerPolicy) {
+    const timeoutMs = methodSpec.timeout_ms ?? defaultTimeoutMs;
+    const transport = methodSpec.transport ?? "worker";
+    assertJsonSchema(requestPayload, methodSpec.request_schema, "method request");
+    let result;
+    if (transport === "http") {
+        result = await executeHttpMethod(methodSpec, requestPayload, timeoutMs);
+        assertJsonSchema(result, methodSpec.response_schema, "method response");
+        return result;
+    }
+    if (!methodSpec.command) {
+        throw new OrbitError("METHOD_BAD_SPEC", `transport ${transport} requires command`);
+    }
+    const cmd = template(methodSpec.command, requestPayload);
+    const args = (methodSpec.args ?? []).map((v) => template(v, requestPayload));
+    if (transport === "worker") {
+        result = await workerPool.execute(cmd, args, requestPayload, timeoutMs, {
+            poolSize: Math.max(1, workerPolicy?.poolSize ?? 1),
+            maxPendingPerWorker: Math.max(1, workerPolicy?.maxPendingPerWorker ?? 64)
+        });
+        assertJsonSchema(result, methodSpec.response_schema, "method response");
+        return result;
+    }
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+        stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += String(chunk);
+    });
+    const exitCode = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(new OrbitError("METHOD_TIMEOUT", `method command timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref?.();
+        child.on("error", (err) => reject(new OrbitError("METHOD_SPAWN_ERROR", "failed to spawn method command", { err })));
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            resolve(code ?? 0);
+        });
+    });
+    if (exitCode !== 0) {
+        throw new OrbitError("METHOD_EXIT_NONZERO", `method exited with code ${exitCode}`, { stderr, stdout, exitCode });
+    }
+    const text = stdout.trim();
+    if (!text)
+        return {};
+    try {
+        result = JSON.parse(text);
+    }
+    catch {
+        result = { stdout: text, stderr: stderr.trim(), exit_code: exitCode };
+    }
+    assertJsonSchema(result, methodSpec.response_schema, "method response");
+    return result;
+}

package/dist/src/spec.d.ts

@@ -0,0 +1,2 @@
+import { ServiceSpec } from "./types.js";
+export declare function loadServiceSpec(specPath: string): ServiceSpec;