@smthrs/gateway 0.35.0 → 1.0.0-rc.4

package/dist/esm/RuntimeBridge.d.ts.map

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

package/dist/esm/RuntimeBridge.js

@@ -0,0 +1,659 @@
+/**
+ * Versioned JSON boundary between the Go product backend and the canonical
+ * TypeScript Flow/Control host.
+ *
+ * This module adapts HTTP-shaped commands to `Control`. It owns no graph,
+ * scheduler, journal, or lifecycle state of its own.
+ *
+ * @since 1.0.0
+ */
+import { Control } from "@smthrs/control/Control";
+import * as ControlError from "@smthrs/control/ControlError";
+import { ControlExecutor } from "@smthrs/control/ControlExecutor";
+import { ApprovalPayload, ControlEvent, MessageSteer, Receipt, RunSummary, SignalPayload } from "@smthrs/control/ControlSchema";
+import * as Fault from "@smthrs/flow/Fault";
+import { Effect, Layer, Schema, Stream } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { RunSummaryRow } from "./GatewayProjection.js";
+import * as Projections from "./Projections.js";
+import { monitorFromJournal } from "./RunTrace.js";
+/**
+ * The only protocol version accepted by this host.
+ * @since 1.0.0
+ * @category constants
+ */
+export const protocol = "smithers.flow-runtime/v1";
+const Sha256 = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/));
+const SourceRevision = Schema.String.check(Schema.isPattern(/^[0-9a-f]{40}$/));
+const PositiveSafeInteger = Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+const RequestId = Schema.NonEmptyString.check(Schema.isMaxLength(1024));
+// A decimal consumes a whole journal entry. v1 preserves an expansion offset;
+// the empty seed consumes nothing, including sequence zero.
+const observationCursorPattern = /^(?:(0|[1-9][0-9]*)|v1:(0|[1-9][0-9]*):(0|[1-9][0-9]*))?(?![\s\S])/;
+/**
+ * Non-secret identity published by readiness for startup compatibility.
+ * @since 1.0.0
+ * @category models
+ */
+export const Identity = Schema.Struct({
+    protocol: Schema.Literal(protocol),
+    runtimeArtifactDigest: Sha256,
+    sourceRevision: SourceRevision,
+    ownerGeneration: PositiveSafeInteger
+});
+const common = {
+    protocol: Schema.Literal(protocol),
+    applicationRequestId: RequestId,
+    ownerGeneration: PositiveSafeInteger
+};
+// The version a launch must run: a flow, the source commit it was chosen
+// from and that flow's execution digest. A pinned launch runs only a plan
+// with that exact identity.
+const LaunchPin = Schema.Struct({
+    flow: Schema.NonEmptyString,
+    sourceCommit: SourceRevision,
+    executionDigest: Sha256
+});
+/**
+ * Launches one immutable named flow. Planning and running stay in Control.
+ * @since 1.0.0
+ * @category models
+ */
+export const LaunchCommand = Schema.Struct({
+    ...common,
+    operation: Schema.Literal("launch"),
+    attempt: PositiveSafeInteger,
+    runId: Schema.optional(Schema.NonEmptyString),
+    runtimeArtifactDigest: Sha256,
+    sourceRevision: SourceRevision,
+    flowId: Schema.NonEmptyString,
+    payload: Schema.Json,
+    pin: Schema.optional(LaunchPin)
+});
+/**
+ * Submits an approval or denial payload produced by the same Control host.
+ * @since 1.0.0
+ * @category models
+ */
+export const DecisionCommand = Schema.Struct({
+    ...common,
+    operation: Schema.Literals(["approve", "deny"]),
+    approval: ApprovalPayload
+});
+/**
+ * Delivers one durable named signal.
+ * @since 1.0.0
+ * @category models
+ */
+export const SignalCommand = Schema.Struct({
+    ...common,
+    operation: Schema.Literal("signal"),
+    runId: Schema.NonEmptyString,
+    signal: SignalPayload
+});
+const Steer = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("Message"), body: Schema.String }),
+    Schema.Struct({ kind: Schema.Literal("Seat"), seat: Schema.NonEmptyString }),
+    Schema.Struct({
+        kind: Schema.Literal("Thinking"),
+        thinking: Schema.Literals(["none", "minimal", "low", "medium", "high", "xhigh"])
+    }),
+    Schema.Struct({ kind: Schema.Literal("Tools"), toolNames: Schema.NonEmptyArray(Schema.NonEmptyString) })
+]);
+/**
+ * Enqueues one steer for the runtime's next turn boundary.
+ * @since 1.0.0
+ * @category models
+ */
+export const SteerCommand = Schema.Struct({
+    version: Schema.optional(Schema.Number),
+    ...common,
+    operation: Schema.Literal("steer"),
+    runId: Schema.NonEmptyString,
+    messageId: Schema.NonEmptyString,
+    createdAt: Schema.Number,
+    attribution: MessageSteer.fields.attribution,
+    steer: Steer
+});
+/**
+ * Requests cancellation, explicit resume, or completion of a retained run.
+ * @since 1.0.0
+ * @category models
+ */
+export const LifecycleCommand = Schema.Struct({
+    ...common,
+    /** Completion is a host-only lifecycle operation. @since 1.0.0 */
+    operation: Schema.Literals(["cancel", "resume", "complete"]),
+    runId: Schema.NonEmptyString,
+    reason: Schema.optional(Schema.String)
+});
+/**
+ * Every mutating operation accepted by the bridge.
+ * @since 1.0.0
+ * @category models
+ */
+export const Command = Schema.Union([
+    LaunchCommand,
+    DecisionCommand,
+    SignalCommand,
+    SteerCommand,
+    LifecycleCommand
+]);
+/**
+ * A bounded, reconnectable read of one canonical runtime execution.
+ * @since 1.0.0
+ * @category models
+ */
+export const ObserveRequest = Schema.Struct({
+    protocol: Schema.Literal(protocol),
+    runId: Schema.NonEmptyString,
+    afterCursor: Schema.optional(Schema.String.check(Schema.isPattern(observationCursorPattern))),
+    limit: Schema.optional(PositiveSafeInteger)
+});
+/**
+ * A process result recorded by installed host equipment, never by a flow result.
+ * @since 1.0.0
+ * @category models
+ */
+export const CommandReceipt = Schema.Struct({
+    runId: Schema.NonEmptyString,
+    operationId: Schema.NonEmptyString,
+    status: Schema.Literals(["running", "completed"]),
+    argv: Schema.NonEmptyArray(Schema.String),
+    exitCode: Schema.optionalKey(Schema.Int),
+    stderr: Schema.optionalKey(Schema.String),
+    fault: Schema.optionalKey(Schema.Literals(["factory", "infra"]))
+});
+/**
+ * Stable bridge-only failures. Control failures retain their own code.
+ * @since 1.0.0
+ * @category errors
+ */
+export class BridgeError extends Schema.TaggedError()("@smthrs/gateway/RuntimeBridgeError", {
+    code: Schema.Literals([
+        "invalid_request",
+        "artifact_mismatch",
+        "source_mismatch",
+        "stale_owner",
+        "run_not_found",
+        "resource_limit",
+        "unavailable",
+        "internal"
+    ]),
+    message: Schema.String,
+    retryable: Schema.Boolean
+}) {
+}
+const decodeCommand = Schema.decodeUnknownEffect(Command);
+const decodeObserve = Schema.decodeUnknownEffect(ObserveRequest);
+const terminal = new Set(["completed", "failed", "cancelled"]);
+const retryableCodes = new Set(["transport_error", "unavailable", "persistence_failed", "launch_failed"]);
+const notFoundCodes = new Set(["run_not_found", "flow_not_found", "plan_not_found"]);
+const conflictCodes = new Set(["stale_owner", "artifact_mismatch", "source_mismatch", "conflict"]);
+const defaultEventLimit = 250;
+const maximumEventLimit = 1_000;
+// Host generation fences who may execute a delivery, but it is not part of
+// the durable product request identity. A replacement owner must reconcile a
+// lost acknowledgement against the same Control command keys.
+const idempotencyKey = (input, suffix) => `bridge:v1:${input.applicationRequestId}:${suffix}`;
+const validateOwner = (config, input) => input.ownerGeneration === config.ownerGeneration
+    ? Effect.void
+    : Effect.fail(new BridgeError({ code: "stale_owner", message: "Runtime owner generation is stale", retryable: true }));
+/**
+ * Executes one decoded command exclusively through the canonical Control API.
+ * @since 1.0.0
+ * @category constructors
+ */
+export const execute = (config, control, principal, input) => Effect.gen(function* () {
+    yield* validateOwner(config, input);
+    switch (input.operation) {
+        case "launch": {
+            if (input.runtimeArtifactDigest !== config.runtimeArtifactDigest) {
+                return yield* Effect.fail(new BridgeError({
+                    code: "artifact_mismatch",
+                    message: "Runtime artifact digest does not match the owning host",
+                    retryable: false
+                }));
+            }
+            if (input.sourceRevision !== config.sourceRevision) {
+                return yield* Effect.fail(new BridgeError({
+                    code: "source_mismatch",
+                    message: "Flow source revision does not match the owning host",
+                    retryable: false
+                }));
+            }
+            // Every launch of a pinned attempt (its composition and the engine's
+            // launches) runs from the pinned source commit: a host serving any
+            // other source refuses before planning imports anything.
+            if (input.pin !== undefined && input.pin.sourceCommit !== config.sourceRevision) {
+                return yield* Effect.fail(new BridgeError({
+                    code: "source_mismatch",
+                    message: "Flow source revision does not match the pinned launch",
+                    retryable: false
+                }));
+            }
+            const plan = yield* control.plan({
+                flowId: input.flowId,
+                input: input.payload,
+                idempotencyKey: idempotencyKey(input, "plan")
+            });
+            // Graphs are optional for valid Flow declarations. Only a verified
+            // native catalog snapshot can supply the missing provenance; the
+            // configured/wire identity by itself cannot stand in for that proof.
+            const plannedSource = plan.graph?.sourceRevision ?? config.verifiedCatalogSourceRevision;
+            if (plannedSource !== input.sourceRevision) {
+                return yield* Effect.fail(new BridgeError({
+                    code: "source_mismatch",
+                    message: "Flow source revision does not match the immutable request",
+                    retryable: false
+                }));
+            }
+            // A pinned launch runs nothing but its pin: a plan with no execution
+            // identity, or the pinned flow planned as other code, never starts.
+            if (input.pin !== undefined &&
+                (plan.executionDigest === undefined ||
+                    (input.pin.flow === input.flowId && plan.executionDigest !== input.pin.executionDigest))) {
+                return yield* Effect.fail(new BridgeError({
+                    code: "source_mismatch",
+                    message: "Flow execution digest does not match the pinned launch",
+                    retryable: false
+                }));
+            }
+            const receipt = yield* control.run({
+                _tag: "Plan",
+                planId: plan.planId,
+                digest: plan.digest,
+                envelope: plan.envelope,
+                idempotencyKey: idempotencyKey(input, `run:${input.runId ?? input.attempt}`),
+                principal,
+                ...(input.runId === undefined ? {} : { reservedRunId: input.runId })
+            });
+            return {
+                operation: input.operation,
+                applicationRequestId: input.applicationRequestId,
+                ownerGeneration: input.ownerGeneration,
+                runtimeArtifactDigest: config.runtimeArtifactDigest,
+                sourceRevision: input.sourceRevision,
+                planId: plan.planId,
+                planDigest: plan.digest,
+                ...(plan.executionDigest === undefined ? {} : { executionDigest: plan.executionDigest }),
+                envelope: plan.envelope,
+                approval: plan.approval,
+                receipt
+            };
+        }
+        case "approve":
+        case "deny": {
+            const request = {
+                ...input.approval,
+                idempotencyKey: idempotencyKey(input, input.operation),
+                principal
+            };
+            const receipt = yield* input.operation === "approve" ? control.approve(request) : control.deny(request);
+            return { operation: input.operation, applicationRequestId: input.applicationRequestId, receipt };
+        }
+        case "signal": {
+            const receipt = yield* control.signal({
+                runId: input.runId,
+                signal: input.signal,
+                idempotencyKey: idempotencyKey(input, "signal"),
+                principal
+            });
+            return { operation: input.operation, applicationRequestId: input.applicationRequestId, receipt };
+        }
+        case "steer": {
+            const receipt = yield* control.steer({
+                runId: input.runId,
+                idempotencyKey: idempotencyKey(input, "steer"),
+                ...(input.version === undefined ? {} : { version: input.version }),
+                message: {
+                    ...input.steer,
+                    runId: input.runId,
+                    messageId: input.messageId,
+                    createdAt: input.createdAt,
+                    ...(input.attribution === undefined ? {} : { attribution: input.attribution }),
+                    principal
+                }
+            });
+            return { operation: input.operation, applicationRequestId: input.applicationRequestId, receipt };
+        }
+        // This authenticated host bridge is not a catalog or public Control
+        // verb. The executor validates the completed native child and resumes
+        // its retained parent to settle from that child's committed result.
+        case "complete": {
+            const executor = yield* Effect.serviceOption(ControlExecutor);
+            const complete = config.requestComplete ??
+                (executor._tag === "Some" ? executor.value.requestComplete : undefined);
+            if (complete === undefined) {
+                return yield* Effect.fail(new BridgeError({
+                    code: "unavailable",
+                    message: "Completed-module settlement is unavailable",
+                    retryable: true
+                }));
+            }
+            const receipt = yield* complete({ runId: input.runId, receiptId: idempotencyKey(input, "complete") });
+            return { operation: input.operation, applicationRequestId: input.applicationRequestId, receipt };
+        }
+        case "cancel":
+        case "resume": {
+            const request = {
+                runId: input.runId,
+                idempotencyKey: idempotencyKey(input, input.operation),
+                ...(input.reason === undefined ? {} : { reason: input.reason }),
+                principal
+            };
+            const receipt = yield* input.operation === "cancel" ? control.cancel(request) : control.resume(request);
+            return { operation: input.operation, applicationRequestId: input.applicationRequestId, receipt };
+        }
+    }
+});
+const cursorPosition = (cursor) => {
+    if (cursor === undefined || cursor === "")
+        return Effect.succeed(undefined);
+    const match = observationCursorPattern.exec(cursor);
+    const sequence = Number(match?.[1] ?? match?.[2]);
+    const offset = match?.[3] === undefined ? undefined : Number(match[3]);
+    const valid = (value) => Number.isSafeInteger(value) && value >= 0 && value < Number.MAX_SAFE_INTEGER;
+    return match !== null && valid(sequence) && (offset === undefined || valid(offset))
+        ? Effect.succeed({ sequence, ...(offset === undefined ? {} : { offset }) })
+        : Effect.fail(new BridgeError({
+            code: "invalid_request",
+            message: "Observation cursor is invalid or out of range",
+            retryable: false
+        }));
+};
+const encodedCursor = (cursor) => cursor.offset === undefined ? String(cursor.sequence) : `v1:${cursor.sequence}:${cursor.offset}`;
+/**
+ * Reads a bounded event replay and current canonical run projection.
+ * @since 1.0.0
+ * @category constructors
+ */
+export const observe = (control, input, receipts) => Effect.gen(function* () {
+    const after = yield* cursorPosition(input.afterCursor);
+    const limit = Math.min(input.limit ?? defaultEventLimit, maximumEventLimit);
+    const listed = yield* control.list({ _tag: "runs", filters: { runId: input.runId }, limit: 1 });
+    const summary = listed._tag === "runs" ? listed.items[0] : undefined;
+    if (summary === undefined) {
+        return yield* Effect.fail(new BridgeError({ code: "run_not_found", message: "Runtime execution was not found", retryable: true }));
+    }
+    const events = Array.from(yield* Stream.runCollect(Stream.take(control.watch({
+        runId: input.runId,
+        ...(after === undefined
+            ? {}
+            : after.offset === undefined
+                ? { afterSequence: after.sequence }
+                : { afterCursor: after }),
+        follow: false
+    }), limit + 1)));
+    const page = events.slice(0, limit);
+    const last = page.at(-1);
+    // Typed Flow results use the same committed root projection as the app.
+    // A terminal status alone never supplies a result, and a bounded event
+    // page cannot reconstruct a root result that precedes its cursor.
+    let finalOutput;
+    let failure = {};
+    if (terminal.has(summary.status)) {
+        const projections = yield* Projections.make(control);
+        const snapshot = yield* projections.snapshot({ _tag: "run-summary", runId: input.runId });
+        const row = snapshot.rows.find(Schema.is(RunSummaryRow));
+        if (row === undefined || row.runId !== summary.runId || row.flowId !== summary.flowId ||
+            row.status !== summary.status || row.planId !== summary.planId || row.planDigest !== summary.planDigest) {
+            return yield* Effect.fail(new BridgeError({ code: "internal", message: "Terminal result observation changed", retryable: true }));
+        }
+        finalOutput = row.finalOutput;
+        failure = {
+            ...(row.failureFault === undefined ? {} : { failureFault: row.failureFault }),
+            ...(row.failureTag === undefined ? {} : { failureTag: row.failureTag })
+        };
+    }
+    // Keep the private receipt out of every repository-controlled projection.
+    const hostSummary = yield* Schema.decodeUnknownEffect(RunSummary)(summary);
+    const commandReceipt = receipts === undefined ? undefined : yield* receipts(input.runId);
+    if (commandReceipt !== undefined && commandReceipt.runId !== input.runId) {
+        return yield* Effect.fail(new BridgeError({ code: "internal", message: "Host command receipt names another run", retryable: false }));
+    }
+    return {
+        run: {
+            ...hostSummary,
+            ...(commandReceipt === undefined ? {} : { commandReceipt }),
+            ...(finalOutput === undefined ? {} : { finalOutput }),
+            ...failure
+        },
+        events: page,
+        nextCursor: last === undefined
+            ? input.afterCursor ?? ""
+            : encodedCursor(last.cursor ?? { sequence: last.sequence }),
+        hasMore: events.length > limit,
+        terminal: terminal.has(summary.status)
+    };
+});
+// Disposable raw journal prefixes for Inspect. This stores no run state: the
+// existing monitor fold still derives every answer from journal records. Bound
+// retention across all runs of one control service, and rebuild after eviction.
+const monitorJournals = new WeakMap();
+const monitorJournalBytes = 64 * 1024 * 1024;
+/** Read an existing run and its committed journal without invoking any execution door.
+ * @since 1.0.0
+ * @category constructors
+ */
+export const monitor = (control, runId, at) => Effect.gen(function* () {
+    const listed = yield* control.list({ _tag: "runs", filters: { runId }, limit: 1 });
+    const run = listed._tag === "runs" ? listed.items[0] : undefined;
+    if (run === undefined || run.runId !== runId) {
+        return yield* new BridgeError({
+            code: "run_not_found",
+            message: "Runtime execution was not found",
+            retryable: false
+        });
+    }
+    const cache = monitorJournals.get(control) ??
+        new Map();
+    monitorJournals.set(control, cache);
+    const cached = cache.get(runId);
+    const last = cached?.records.at(-1)?.sequence;
+    // Replay the final entry because one entry may expand into several events.
+    const consumed = last === undefined ? 0 : cached.records.filter((row) => row.sequence === last).length;
+    let skipped = 0;
+    const suffix = Array.from(yield* Stream.runCollect(control.watch({
+        runId,
+        follow: false,
+        ...(last === undefined || last === 0 ? {} : { afterSequence: last - 1 })
+    }).pipe(Stream.filter((row) => last === undefined || row.sequence > last || row.sequence === last && skipped++ >= consumed), Stream.take(Projections.maxEventsScanned + 1))));
+    const records = [...(cached?.records ?? []), ...suffix];
+    if (records.length > Projections.maxEventsScanned) {
+        return yield* new BridgeError({
+            code: "resource_limit",
+            message: "Run journal exceeds the inspection limit",
+            retryable: false
+        });
+    }
+    const bytes = (cached?.bytes ?? 0) +
+        suffix.reduce((sum, row) => sum + new TextEncoder().encode(JSON.stringify(row)).byteLength, 0);
+    const current = cache.get(runId);
+    // A slower reader cannot overwrite a longer committed prefix.
+    if (bytes <= monitorJournalBytes && (current === undefined || current.records.length <= records.length)) {
+        cache.delete(runId);
+        cache.set(runId, { records, bytes });
+        let total = [...cache.values()].reduce((sum, entry) => sum + entry.bytes, 0);
+        while (cache.size > 32 || total > monitorJournalBytes) {
+            const oldest = cache.keys().next().value;
+            total -= cache.get(oldest).bytes;
+            cache.delete(oldest);
+        }
+    }
+    const folded = monitorFromJournal({ runId, flowId: run.flowId, status: run.status }, records, at);
+    // The journal is read page by page when its tab opens (run-events). Only a
+    // replay frame carries its own journal prefix. The extent bounds the run.
+    let start = Infinity;
+    let end = 0;
+    for (const row of records) {
+        if (row.occurredAt > 0) {
+            start = Math.min(start, row.occurredAt);
+            end = Math.max(end, row.occurredAt);
+        }
+    }
+    const value = {
+        ...folded,
+        ...(end === 0 ? {} : { extent: { start: new Date(start).toISOString(), end: new Date(end).toISOString() } })
+    };
+    if (at === undefined)
+        delete value.journal;
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > Projections.maxProjectionBytes) {
+        return yield* new BridgeError({
+            code: "resource_limit",
+            message: "Run monitor exceeds the inspection limit",
+            retryable: false
+        });
+    }
+    return value;
+});
+/**
+ * Successful command response on the JSON wire.
+ * @since 1.0.0
+ * @category models
+ */
+export const CommandResponse = Schema.Struct({
+    protocol: Schema.Literal(protocol),
+    ok: Schema.Literal(true),
+    value: Schema.Struct({
+        operation: Schema.String,
+        applicationRequestId: Schema.String,
+        ownerGeneration: Schema.optional(PositiveSafeInteger),
+        runtimeArtifactDigest: Schema.optional(Sha256),
+        sourceRevision: Schema.optional(SourceRevision),
+        planId: Schema.optional(Schema.String),
+        planDigest: Schema.optional(Sha256),
+        executionDigest: Schema.optional(Sha256),
+        envelope: Schema.optional(Schema.Json),
+        approval: Schema.optional(ApprovalPayload),
+        receipt: Receipt
+    })
+});
+/**
+ * Successful observation response on the JSON wire.
+ * @since 1.0.0
+ * @category models
+ */
+export const ObserveResponse = Schema.Struct({
+    protocol: Schema.Literal(protocol),
+    ok: Schema.Literal(true),
+    value: Schema.Struct({
+        run: Schema.Struct({
+            ...RunSummary.fields,
+            finalOutput: Schema.optional(Schema.String),
+            failureFault: Schema.optional(Fault.Class),
+            failureTag: Schema.optional(Schema.String),
+            commandReceipt: Schema.optionalKey(CommandReceipt)
+        }),
+        events: Schema.Array(ControlEvent),
+        nextCursor: Schema.String,
+        hasMore: Schema.Boolean,
+        terminal: Schema.Boolean
+    })
+});
+/**
+ * Stable sanitized failure response on the JSON wire.
+ * @since 1.0.0
+ * @category models
+ */
+export const ErrorResponse = Schema.Struct({
+    protocol: Schema.Literal(protocol),
+    ok: Schema.Literal(false),
+    error: Schema.Struct({ code: Schema.String, message: Schema.String, retryable: Schema.Boolean })
+});
+const errorResponse = (cause) => {
+    const known = Schema.is(ControlError.ControlErrorSchema)(cause);
+    const code = cause instanceof BridgeError || known ? cause.code : "internal";
+    const retryable = cause instanceof BridgeError
+        ? cause.retryable
+        : cause instanceof ControlError.TransportError
+            ? cause.retryable
+            : retryableCodes.has(code);
+    // Control errors can contain storage paths, SQL diagnostics, or executor
+    // output. The bridge publishes their stable code, never that backend text.
+    const message = cause instanceof BridgeError ? cause.message : "Runtime bridge failed";
+    const status = code === "unauthorized" ?
+        401
+        : notFoundCodes.has(code) ?
+            404
+            : conflictCodes.has(code) ?
+                409
+                : retryable ?
+                    503
+                    : code === "internal" ?
+                        500
+                        : 400;
+    return HttpServerResponse.jsonUnsafe({ protocol, ok: false, error: { code, message, retryable } }, { status });
+};
+/**
+ * Answers a failed bridge request with its sanitized response, logging it first.
+ *
+ * The wire carries only the stable code. The operator log carries the full
+ * cause of every failure the caller did not cause, so a launch that failed in
+ * storage or in the executor can be diagnosed from the host.
+ */
+const respondToFailure = (operation) => (cause) => {
+    const response = errorResponse(cause);
+    if (cause instanceof BridgeError)
+        return Effect.succeed(response);
+    const code = Schema.is(ControlError.ControlErrorSchema)(cause) ? cause.code : "internal";
+    return Effect.logError({ message: "Runtime bridge request failed", operation, code, cause }).pipe(Effect.as(response));
+};
+const readJson = Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const text = yield* request.text;
+    return yield* Effect.try({
+        try: () => JSON.parse(text),
+        catch: () => new BridgeError({ code: "invalid_request", message: "Request body must be JSON", retryable: false })
+    });
+});
+const authenticated = (config, effect) => Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const principal = yield* config.authenticate(request.headers);
+    return yield* effect(principal);
+});
+/**
+ * Mounts the authenticated JSON bridge beside the existing gateway RPCs.
+ * @since 1.0.0
+ * @category layers
+ */
+export const layer = (config) => {
+    const command = authenticated(config, (principal) => Effect.gen(function* () {
+        const body = yield* readJson;
+        const input = yield* decodeCommand(body).pipe(Effect.mapError(() => new BridgeError({
+            code: "invalid_request",
+            message: "Request does not match the runtime bridge contract",
+            retryable: false
+        })));
+        const control = yield* Control;
+        const value = yield* execute(config, control, principal, input);
+        return HttpServerResponse.jsonUnsafe({ protocol, ok: true, value });
+    })).pipe(Effect.catch(respondToFailure("runtime-bridge.command")), Effect.withSpan("runtime-bridge.command"));
+    const observation = authenticated(config, () => Effect.gen(function* () {
+        const body = yield* readJson;
+        const input = yield* decodeObserve(body).pipe(Effect.mapError(() => new BridgeError({
+            code: "invalid_request",
+            message: "Request does not match the observation contract",
+            retryable: false
+        })));
+        const control = yield* Control;
+        const value = yield* observe(control, input, config.commandReceipt);
+        return HttpServerResponse.jsonUnsafe({ protocol, ok: true, value });
+    })).pipe(Effect.catch(respondToFailure("runtime-bridge.observe")), Effect.withSpan("runtime-bridge.observe"));
+    const inspection = authenticated(config, () => Effect.gen(function* () {
+        const body = yield* readJson;
+        const input = yield* Schema.decodeUnknownEffect(Schema.Struct({
+            protocol: Schema.Literal(protocol),
+            runId: Schema.NonEmptyString,
+            at: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
+        }))(body).pipe(Effect.mapError(() => new BridgeError({ code: "invalid_request", message: "Invalid monitor request", retryable: false })));
+        const control = yield* Control;
+        return HttpServerResponse.jsonUnsafe({
+            protocol,
+            ok: true,
+            value: yield* monitor(control, input.runId, input.at)
+        });
+    })).pipe(Effect.catch(respondToFailure("runtime-bridge.observe")));
+    return HttpRouter.add("POST", "/runtime/v1/command", command).pipe(Layer.merge(HttpRouter.add("POST", "/runtime/v1/monitor", inspection)), Layer.merge(HttpRouter.add("POST", "/runtime/v1/observe", observation)));
+};
+//# sourceMappingURL=RuntimeBridge.js.map