@oatscenter/trellis 0.100.0-rc.1

package/session.js

@@ -0,0 +1,3407 @@
+import { jetstream, jetstreamManager, } from "@nats-io/jetstream";
+import { createInbox, headers as natsHeaders, } from "@nats-io/nats-core";
+import { boundApiSubject, feedControlSubject, routeQueueGroup, } from "./participant_runtime/api.js";
+import { encodeEventSubjectParameterToken } from "./helpers.js";
+import { buildEventProofInput } from "./auth/proof.js";
+import { AuthorizationProviderCache, } from "./auth/authorization_context.js";
+import { AuthorizationProviderUnavailableError } from "./auth/authorization/provider_cache.js";
+import { AsyncResult, BaseError, err, isErr, ok, Result, } from "@oatscenter/result";
+import { context, createNatsHeaderCarrier, extractTraceContext, injectTraceContext, recordTrellisError, SpanStatusCode, startClientSpan, startServerSpan, trace, withSpanAsync, } from "./telemetry/mod.js";
+import { Type } from "typebox";
+import { AssertError, Pointer } from "typebox/value";
+import { ulid } from "ulid";
+import { encodeSchema, parse, parseSchema, parseUnknownSchema, } from "./codec.js";
+import { AuthError, BUILTIN_RPC_ERRORS, getBuiltinRpcError, machineErrorCode, SchemaValidationError, TransferError, TransportError, UnexpectedError, ValidationError, } from "./errors/index.js";
+import { RemoteError } from "./errors/RemoteError.js";
+import { logger } from "./globals.js";
+import { TypedKV, } from "./kv.js";
+import { TrellisErrorDataSchema } from "./errors/RemoteError.js";
+import { OperationInvoker, } from "./operations.js";
+import { API as STATE_API, Conflict as StateRpcConflict, } from "./internal_sdk/generated/apis/state/mod.js";
+import { API as EVENTS_API } from "./internal_sdk/generated/apis/events/mod.js";
+import { createTransferHandle, } from "./transfer.js";
+import { TrellisTasks } from "./tasks.js";
+import { TrellisConnection } from "./connection.js";
+class EventVerificationAuthError extends AuthError {
+    retryable;
+    constructor(retryable) {
+        super({
+            reason: retryable ? "authorization_unavailable" : "invalid_signature",
+        });
+        this.retryable = retryable;
+    }
+}
+/** Verifies one received request or event through the provider-local WASM cache. */
+export async function verifyLocalAuthorization(args) {
+    if (!args.permission && !(args.kind === "request" && args.identityOnly)) {
+        return err(new AuthError({ reason: "insufficient_permissions" }));
+    }
+    if (!args.cache) {
+        return err(new AuthError({ reason: "invalid_signature" }));
+    }
+    const proof = args.message.headers?.get("proof");
+    const contextDigest = args.message.headers?.get("authorization-context");
+    const sessionKey = args.message.headers?.get("session-key");
+    if (!proof || !contextDigest || !sessionKey) {
+        return err(new AuthError({ reason: "missing_proof" }));
+    }
+    let result;
+    try {
+        if (args.kind === "request") {
+            const iatHeader = args.message.headers?.get("iat");
+            const requestId = args.message.headers?.get("request-id");
+            const reply = args.message.reply;
+            const iat = Number(iatHeader);
+            if (!Number.isSafeInteger(iat) || !requestId || !reply) {
+                return err(new AuthError({ reason: "invalid_signature" }));
+            }
+            const request = {
+                contextDigest,
+                sessionKey,
+                subject: args.message.subject,
+                reply,
+                payload: args.proofPayload ??
+                    new Uint8Array(args.message.data ?? new Uint8Array()),
+                iat,
+                requestId,
+                proof,
+                requiredPermissions: args.permission
+                    ? [toVerifierPermission(args.permission)]
+                    : [],
+                requiredCapabilities: [...args.requiredCapabilities],
+            };
+            result = await args.cache.verifyRequest(request);
+        }
+        else {
+            const eventId = args.message.headers?.get("Nats-Msg-Id");
+            const eventTime = args.message.headers?.get("Trellis-Event-Time");
+            const descriptorIdentity = args.message.headers?.get("Trellis-Event-Descriptor");
+            if (!eventId || !eventTime || descriptorIdentity !== args.descriptorIdentity) {
+                return err(new AuthError({ reason: "invalid_signature" }));
+            }
+            const event = {
+                contextDigest,
+                sessionKey,
+                descriptorIdentity,
+                subject: args.message.subject,
+                payload: new Uint8Array(args.message.data ?? new Uint8Array()),
+                eventId,
+                eventTime,
+                proof,
+                requiredCapabilities: [...args.requiredCapabilities],
+            };
+            result = await args.cache.verifyEvent(event);
+        }
+    }
+    catch (error) {
+        if (error instanceof AuthorizationProviderUnavailableError) {
+            return err(args.kind === "event"
+                ? new EventVerificationAuthError(true)
+                : new AuthError({ reason: "authorization_unavailable" }));
+        }
+        return err(new AuthError({ reason: "invalid_signature" }));
+    }
+    if (!result.ok) {
+        return err(new AuthError({
+            reason: localAuthorizationErrorReason(result.error.code),
+        }));
+    }
+    return ok(toVerifiedCaller(result.contextDigest, result.context));
+}
+function toVerifierPermission(permission) {
+    if (permission.surfaceKind === "operation" && permission.action === "control") {
+        const separator = permission.surfaceName.lastIndexOf(".");
+        if (separator <= 0 || separator === permission.surfaceName.length - 1) {
+            throw new Error("operation signal permission is invalid");
+        }
+        return {
+            target: {
+                kind: "operationSignal",
+                api: `${permission.apiId}@${permission.apiVersion}`,
+                operation: permission.surfaceName.slice(0, separator),
+                signal: permission.surfaceName.slice(separator + 1),
+            },
+            action: permission.action,
+        };
+    }
+    return {
+        target: {
+            kind: "apiSurface",
+            api: `${permission.apiId}@${permission.apiVersion}`,
+            surface: permission.surfaceKind,
+            name: permission.surfaceName,
+        },
+        action: permission.action,
+    };
+}
+function toVerifiedCaller(contextDigest, projection) {
+    return {
+        type: "verified",
+        sessionKey: projection.sessionKey,
+        principalId: projection.principalId,
+        principalKind: projection.principalKind,
+        participantId: projection.participantId,
+        contextDigest,
+        connectionId: projection.connectionId,
+        loginSessionId: projection.loginSessionId,
+        identityKeyId: projection.identityKeyId,
+        deploymentId: projection.deploymentId,
+        instanceId: projection.instanceId,
+        grantRevision: projection.grantRevision,
+        platformPrivileges: [...projection.platformPrivileges],
+        inboxPrefix: projection.inboxPrefix,
+    };
+}
+function localAuthorizationErrorReason(code) {
+    switch (code) {
+        case "PermissionDenied":
+            return "insufficient_permissions";
+        case "ReplySubjectMismatch":
+            return "reply_subject_mismatch";
+        case "ProofIatOutOfRange":
+            return "iat_out_of_range";
+        case "ContextExpired":
+        case "EventRevoked":
+            return "session_expired";
+        default:
+            return "invalid_signature";
+    }
+}
+/**
+ * Safely extract JSON from a NATS message.
+ * The .json() method can throw if the message data is not valid JSON.
+ */
+export function safeJson(msg) {
+    return Result.try(() => msg.json());
+}
+function transportCauseContext(cause) {
+    if (cause instanceof Error) {
+        return {
+            causeName: cause.name,
+            causeMessage: cause.message,
+        };
+    }
+    return { cause: String(cause) };
+}
+function createTransportError(args) {
+    return new TransportError({
+        code: args.code,
+        message: args.message,
+        hint: args.hint,
+        cause: args.cause,
+        context: {
+            ...(args.context ?? {}),
+            ...(args.cause === undefined ? {} : transportCauseContext(args.cause)),
+        },
+    });
+}
+function requestFailedTransportError(args) {
+    return createTransportError({
+        code: args.code,
+        message: args.message,
+        hint: args.hint,
+        cause: args.cause,
+        context: {
+            subject: args.subject,
+            ...(args.method === undefined ? {} : { method: args.method }),
+            ...(args.context ?? {}),
+        },
+    });
+}
+function classifyRequestTransportFailure(args) {
+    const message = args.cause instanceof Error
+        ? args.cause.message
+        : String(args.cause);
+    const isNoResponders = message.includes("no responders");
+    const isNatsPermission = args.cause instanceof Error &&
+        [
+            "PermissionViolationError",
+            "AuthorizationError",
+            "UserAuthenticationExpiredError",
+        ]
+            .includes(args.cause.name);
+    return requestFailedTransportError({
+        code: isNoResponders
+            ? "trellis.request.unavailable"
+            : isNatsPermission
+                ? "trellis.request.denied"
+                : "trellis.request.failed",
+        message: isNoResponders
+            ? "Trellis could not reach the requested capability."
+            : isNatsPermission
+                ? "Trellis denied this request."
+                : "Trellis could not complete the request.",
+        hint: isNoResponders
+            ? "Check that the target service is installed and reachable, then try again."
+            : isNatsPermission
+                ? "Sign in with a profile that has the required capability, then try again."
+                : "Retry the request. If it keeps failing, check Trellis runtime health.",
+        cause: args.cause,
+        method: args.method,
+        subject: args.subject,
+        context: {
+            ...(args.callerCapabilities === undefined
+                ? {}
+                : { requiredCapabilities: args.callerCapabilities }),
+            noResponders: isNoResponders,
+            lowLevelMessage: message,
+        },
+    });
+}
+/** Creates the existing typed transport error for an unavailable optional action. */
+export function createActionUnavailableError(action, capabilities) {
+    return requestFailedTransportError({
+        code: "trellis.request.unavailable",
+        message: "Trellis could not reach the requested capability.",
+        hint: "Wait for the optional capability to become available, then try again.",
+        subject: action,
+        context: { action, capabilities },
+    });
+}
+function encodeRuntimeSchema(schema, data) {
+    if (schema && typeof schema === "object" &&
+        typeof Reflect.get(schema, "encode") === "function") {
+        try {
+            const encoded = schema.encode(data);
+            const json = JSON.stringify(encoded);
+            if (json === undefined) {
+                throw new TypeError("Codec encoded no JSON value");
+            }
+            return ok(json);
+        }
+        catch (cause) {
+            return err(new UnexpectedError({ cause }));
+        }
+    }
+    return encodeSchema(schema, data);
+}
+function parseRuntimeSchema(schema, data) {
+    if (schema && typeof schema === "object" &&
+        typeof Reflect.get(schema, "decode") === "function") {
+        try {
+            return ok(schema.decode(data));
+        }
+        catch (cause) {
+            return err(new UnexpectedError({ cause }));
+        }
+    }
+    return parseUnknownSchema(schema, data);
+}
+export function base64urlEncode(data) {
+    const b64 = btoa(String.fromCharCode(...data));
+    return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+export function base64urlDecode(s) {
+    const normalized = s.replace(/-/g, "+").replace(/_/g, "/");
+    const padLen = (4 - (normalized.length % 4)) % 4;
+    const padded = normalized + "=".repeat(padLen);
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+export function toArrayBuffer(data) {
+    const buf = data.buffer;
+    if (buf instanceof ArrayBuffer) {
+        return buf.slice(data.byteOffset, data.byteOffset + data.byteLength);
+    }
+    const copy = new Uint8Array(data.byteLength);
+    copy.set(data);
+    return copy.buffer;
+}
+export async function sha256(data) {
+    const digest = await crypto.subtle.digest("SHA-256", toArrayBuffer(data));
+    return new Uint8Array(digest);
+}
+export function buildProofInput(contextDigest, subject, reply, payloadHash, iat, requestId) {
+    const enc = new TextEncoder();
+    const contextDigestBytes = base64urlDecode(contextDigest);
+    if (contextDigestBytes.length !== 32) {
+        throw new Error("authorization context digest must encode 32 bytes");
+    }
+    if (reply.length === 0) {
+        throw new Error("request reply subject must not be empty");
+    }
+    const domainBytes = enc.encode("trellis.authorization-request-proof.v1");
+    const subjectBytes = enc.encode(subject);
+    const replyBytes = enc.encode(reply);
+    const iatBytes = enc.encode(String(iat));
+    const requestIdBytes = enc.encode(requestId);
+    const components = [
+        domainBytes,
+        contextDigestBytes,
+        subjectBytes,
+        replyBytes,
+        payloadHash,
+        iatBytes,
+        requestIdBytes,
+    ];
+    const total = components.reduce((sum, value) => sum + 4 + value.length, 0);
+    const buf = new Uint8Array(total);
+    const view = new DataView(buf.buffer);
+    let offset = 0;
+    for (const component of components) {
+        view.setUint32(offset, component.length);
+        offset += 4;
+        buf.set(component, offset);
+        offset += component.length;
+    }
+    return buf;
+}
+/**
+ * Returns true when a handler result explicitly leaves operation completion to
+ * an external control path.
+ */
+export function isOperationDeferred(value) {
+    return !!value && typeof value === "object" &&
+        "kind" in value && value.kind === "deferred";
+}
+/** State CAS failure with the authoritative current value, when present. */
+export class StateConflictError extends BaseError {
+    name = "StateConflictError";
+    current;
+    constructor(current) {
+        super("State revision conflict");
+        this.current = current;
+    }
+    toSerializable() {
+        return this.baseSerializable();
+    }
+}
+/** Raised when an optional participant resource is not installed. */
+export class ResourceUnavailableError extends BaseError {
+    kind;
+    resourceName;
+    name = "ResourceUnavailableError";
+    /** Construct an unavailable-resource failure. */
+    constructor(kind, resourceName) {
+        super(`${kind} resource '${resourceName}' is unavailable`);
+        this.kind = kind;
+        this.resourceName = resourceName;
+    }
+    toSerializable() {
+        return this.baseSerializable();
+    }
+}
+export function isResultLike(value) {
+    return value instanceof Result;
+}
+function compactHandlerErrorContext(context) {
+    return Object.fromEntries(Object.entries(context).filter(([key, value]) => key !== "traceId" && value !== undefined));
+}
+function sanitizeHandlerErrorContext(error) {
+    delete error.getContext().subject;
+}
+export function annotateHandlerBoundaryError(cause, context) {
+    const error = cause instanceof BaseError && !(cause instanceof RemoteError)
+        ? cause
+        : new UnexpectedError({ cause });
+    sanitizeHandlerErrorContext(error);
+    error.withContext(compactHandlerErrorContext(context));
+    error.withTraceId(context.traceId);
+    return error;
+}
+function recordRuntimeError(error, attributes) {
+    recordTrellisError(error, {
+        messagingSystem: "nats",
+        ...attributes,
+    });
+}
+const DurableOperationSignalSchema = Type.Object({
+    operationId: Type.String(),
+    sequence: Type.Number(),
+    requestId: Type.String(),
+    signal: Type.String(),
+    input: Type.Optional(Type.Any()),
+    acceptedAt: Type.String(),
+    acknowledged: Type.Boolean(),
+});
+const DurableOperationSnapshotSchema = Type.Object({
+    id: Type.String(),
+    service: Type.String(),
+    operation: Type.String(),
+    revision: Type.Number(),
+    state: Type.Union([
+        Type.Literal("pending"),
+        Type.Literal("running"),
+        Type.Literal("completed"),
+        Type.Literal("failed"),
+        Type.Literal("cancelled"),
+    ]),
+    createdAt: Type.String(),
+    updatedAt: Type.String(),
+    completedAt: Type.Optional(Type.String()),
+    progress: Type.Optional(Type.Any()),
+    transfer: Type.Optional(Type.Object({
+        chunkIndex: Type.Number(),
+        chunkBytes: Type.Number(),
+        transferredBytes: Type.Number(),
+    })),
+    output: Type.Optional(Type.Any()),
+    error: Type.Optional(Type.Object({
+        id: Type.Optional(Type.String()),
+        type: Type.String(),
+        message: Type.String(),
+        context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+        traceId: Type.Optional(Type.String()),
+    })),
+});
+export const DurableOperationRecordSchema = Type.Object({
+    invocationId: Type.String(),
+    callerSessionKey: Type.String(),
+    apiId: Type.String(),
+    operation: Type.String(),
+    input: Type.Any(),
+    ownerInstanceId: Type.String(),
+    ownerConnectionId: Type.String(),
+    ownerEpoch: Type.Number(),
+    leaseExpiresAt: Type.String(),
+    cancelRequestedAt: Type.Optional(Type.String()),
+    transferGrant: Type.Optional(Type.Any()),
+    sequence: Type.Number(),
+    signalSequence: Type.Number(),
+    signals: Type.Array(DurableOperationSignalSchema),
+    snapshot: DurableOperationSnapshotSchema,
+});
+export function buildRuntimeOperationSnapshot(runtime, state, patch) {
+    const updatedAt = new Date().toISOString();
+    const completedAt = state === "completed" || state === "failed" || state === "cancelled"
+        ? (patch?.completedAt ?? updatedAt)
+        : patch?.completedAt;
+    return {
+        id: runtime.id,
+        service: runtime.service,
+        operation: runtime.operation,
+        revision: patch?.revision ?? runtime.snapshot.revision + 1,
+        state,
+        createdAt: patch?.createdAt ?? runtime.snapshot.createdAt,
+        updatedAt,
+        ...(completedAt ? { completedAt } : {}),
+        ...(patch?.progress !== undefined
+            ? { progress: patch.progress }
+            : runtime.snapshot.progress !== undefined
+                ? { progress: runtime.snapshot.progress }
+                : {}),
+        ...(patch?.transfer !== undefined
+            ? { transfer: patch.transfer }
+            : runtime.snapshot.transfer !== undefined
+                ? { transfer: runtime.snapshot.transfer }
+                : {}),
+        ...(patch?.output !== undefined
+            ? { output: patch.output }
+            : runtime.snapshot.output !== undefined
+                ? { output: runtime.snapshot.output }
+                : {}),
+        ...(patch?.error
+            ? { error: patch.error }
+            : runtime.snapshot.error
+                ? { error: runtime.snapshot.error }
+                : {}),
+    };
+}
+function isRuntimeOperationSnapshot(value) {
+    return !!value && typeof value === "object" &&
+        typeof value.id === "string" &&
+        typeof value.service === "string" &&
+        typeof value.operation === "string" &&
+        typeof value.revision === "number" &&
+        typeof value.state === "string" &&
+        typeof value.createdAt === "string" &&
+        typeof value.updatedAt === "string";
+}
+export function isTerminalRuntimeOperationSnapshot(value) {
+    return isRuntimeOperationSnapshot(value) && (value.state === "completed" || value.state === "failed" ||
+        value.state === "cancelled");
+}
+const FEED_CANCEL_TOMBSTONE_MS = 30_000;
+const MAX_FEED_CANCEL_TOMBSTONES = 1_024;
+const MAX_OPERATION_INPUT_BYTES = 256 * 1024;
+const MAX_OPERATION_PROGRESS_BYTES = 64 * 1024;
+const MAX_OPERATION_OUTPUT_BYTES = 512 * 1024;
+const MAX_OPERATION_ERROR_BYTES = 32 * 1024;
+const MAX_OPERATION_SIGNALS = 100;
+const MAX_OPERATION_SIGNAL_BYTES = 64 * 1024;
+const MAX_OPERATION_RECORD_BYTES = 1024 * 1024;
+function createEventListenerContext(args) {
+    const messageId = readMessageHeader(args.message, "Nats-Msg-Id");
+    const messageTime = readMessageHeader(args.message, "Trellis-Event-Time");
+    const sequence = Reflect.get(args.message, "seq");
+    return {
+        id: messageId ?? "",
+        time: new Date(messageTime ?? 0),
+        subject: args.subject,
+        mode: args.mode,
+        ...(args.group ? { group: args.group } : {}),
+        ...(typeof sequence === "number" ? { sequence } : {}),
+    };
+}
+function readMessageHeader(message, key) {
+    const headers = Reflect.get(message, "headers");
+    if (typeof headers !== "object" || headers === null)
+        return undefined;
+    const get = Reflect.get(headers, "get");
+    if (typeof get !== "function")
+        return undefined;
+    const value = get.call(headers, key);
+    return typeof value === "string" ? value : undefined;
+}
+function eventConsumerGroupEvents(group) {
+    const events = new Set();
+    for (const groupEvents of Object.values(group.uses ?? {})) {
+        for (const event of groupEvents)
+            events.add(event);
+    }
+    for (const event of group.self ?? [])
+        events.add(event);
+    return [...events].sort();
+}
+function jetStreamDeliveryProof(message) {
+    const raw = Reflect.get(message, "msg");
+    const reply = raw && typeof raw === "object"
+        ? Reflect.get(raw, "reply")
+        : undefined;
+    if (typeof reply !== "string" || !reply.startsWith("$JS.ACK.")) {
+        throw new Error("JetStream delivery has no acknowledgement subject");
+    }
+    return reply;
+}
+function isConsumerNotFoundError(error) {
+    return error instanceof Error && (error.name === "ConsumerNotFoundError" ||
+        error.message.includes("consumer not found"));
+}
+const internalEventConsumers = Symbol("trellis.internal.eventConsumers");
+const internalApiBindings = Symbol("trellis.internal.apiBindings");
+/**
+ * Creates a Trellis runtime with bootstrap-resolved bindings.
+ *
+ * @internal
+ */
+export function createTrellisInternal(name, nats, auth, opts) {
+    const { eventConsumers, apiBindings, inboxPrefix, ...publicOpts } = opts ?? {};
+    const internalOpts = {
+        ...publicOpts,
+        [internalEventConsumers]: eventConsumers,
+        [internalApiBindings]: apiBindings,
+    };
+    return new Trellis(name, nats, auth, internalOpts, inboxPrefix);
+}
+function surfaceGroupName(key) {
+    return lowerCamelIdent(key.split(".")[0] ?? key);
+}
+function surfaceLeafName(key) {
+    const parts = key.split(".");
+    parts.shift();
+    return lowerCamelIdent(parts.length === 0 ? key : parts.join("."));
+}
+function lowerCamelIdent(value) {
+    const pascal = value
+        .split(/[^A-Za-z0-9]+/)
+        .filter((part) => part.length > 0)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join("");
+    return pascal.length === 0 ? "_" : pascal[0].toLowerCase() + pascal.slice(1);
+}
+function addSurfaceLeaf(surface, key, leaf) {
+    const group = surfaceGroupName(key);
+    surface[group] ??= {};
+    surface[group][surfaceLeafName(key)] = leaf;
+}
+function natsSubjectMatches(pattern, subject) {
+    const patternParts = pattern.split(".");
+    const subjectParts = subject.split(".");
+    for (let index = 0; index < patternParts.length; index += 1) {
+        const part = patternParts[index];
+        if (part === ">")
+            return true;
+        const subjectPart = subjectParts[index];
+        if (subjectPart === undefined)
+            return false;
+        if (part !== "*" && part !== subjectPart)
+            return false;
+    }
+    return patternParts.length === subjectParts.length;
+}
+const STATE_RUNTIME_RPC = {
+    Get: {
+        subject: "rpc.v1.state.Get",
+        input: STATE_API.actions["rpc:Get"].input,
+        output: STATE_API.actions["rpc:Get"].output,
+        callerCapabilities: [],
+        errors: STATE_API.actions["rpc:Get"].errors.map((error) => error.type),
+        declaredErrorTypes: STATE_API.actions["rpc:Get"].errors.map((error) => error.type),
+        runtimeErrors: STATE_API.actions["rpc:Get"].errors,
+    },
+    Put: {
+        subject: "rpc.v1.state.Put",
+        input: STATE_API.actions["rpc:Put"].input,
+        output: STATE_API.actions["rpc:Put"].output,
+        callerCapabilities: [],
+        errors: STATE_API.actions["rpc:Put"].errors.map((error) => error.type),
+        declaredErrorTypes: STATE_API.actions["rpc:Put"].errors.map((error) => error.type),
+        runtimeErrors: STATE_API.actions["rpc:Put"].errors,
+    },
+    Delete: {
+        subject: "rpc.v1.state.Delete",
+        input: STATE_API.actions["rpc:Delete"].input,
+        output: STATE_API.actions["rpc:Delete"].output,
+        callerCapabilities: [],
+        errors: STATE_API.actions["rpc:Delete"].errors.map((error) => error.type),
+        declaredErrorTypes: STATE_API.actions["rpc:Delete"].errors.map((error) => error.type),
+        runtimeErrors: STATE_API.actions["rpc:Delete"].errors,
+    },
+};
+/** Typed handle for one generated single-value State resource. */
+export class StateHandle {
+    #resourceName;
+    #definition;
+    #migrations;
+    #isCurrent;
+    #isAvailable;
+    #calls;
+    /** Construct a handle from generated metadata and settled State transport calls. */
+    constructor(args) {
+        this.#resourceName = args.resourceName;
+        this.#definition = args.definition;
+        this.#migrations = args.migrations ?? {};
+        this.#isCurrent = args.isCurrent ?? (() => true);
+        this.#isAvailable = args.isAvailable ?? (() => true);
+        this.#calls = args.calls;
+    }
+    async #project(entry) {
+        const version = Number(entry.representationVersion);
+        const encoded = JSON.parse(new TextDecoder().decode(entry.value));
+        let value;
+        if (version === this.#definition.version) {
+            value = this.#definition.codec.decode(encoded);
+        }
+        else {
+            const historicCodec = this.#definition.migrations[version];
+            const migrate = this.#migrations[version];
+            if (!historicCodec || !migrate) {
+                throw new Error(`Unsupported State representation version ${version}`);
+            }
+            const migrated = await migrate(historicCodec.decode(encoded));
+            value = this.#definition.codec.decode(this.#definition.codec.encode(migrated instanceof Result ? migrated.orThrow() : migrated));
+        }
+        return {
+            value,
+            revision: entry.revision,
+            createdAt: entry.createdAt,
+            updatedAt: entry.updatedAt,
+        };
+    }
+    #assertCurrent() {
+        if (!this.#isAvailable()) {
+            throw new ResourceUnavailableError("State", this.#resourceName);
+        }
+        if (!this.#isCurrent()) {
+            throw new Error(`State resource '${this.#resourceName}' has a stale generation`);
+        }
+    }
+    async #conflict(error) {
+        return Result.err(new StateConflictError(error.data.current
+            ? await this.#project(error.data.current)
+            : undefined));
+    }
+    #write(value, mode, expectedRevision) {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                const result = await this.#calls.set({
+                    resourceName: this.#resourceName,
+                    representationVersion: BigInt(this.#definition.version),
+                    value: new TextEncoder().encode(JSON.stringify(this.#definition.codec.encode(value))),
+                    mode,
+                    ...(expectedRevision === undefined
+                        ? {}
+                        : { revision: expectedRevision }),
+                });
+                if (result.isErr()) {
+                    return result.error instanceof StateRpcConflict
+                        ? await this.#conflict(result.error)
+                        : result;
+                }
+                return Result.ok(await this.#project(result.unwrapOrElse(() => {
+                    throw new Error("State set unexpectedly failed");
+                }).entry));
+            }
+            catch (cause) {
+                return Result.err(cause instanceof BaseError ? cause : new UnexpectedError({ cause }));
+            }
+        })());
+    }
+    /** Read the current value, migrating only in memory when required. */
+    get() {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                const result = await this.#calls.get({
+                    resourceName: this.#resourceName,
+                });
+                if (result.isErr())
+                    return result;
+                const response = result.unwrapOrElse(() => {
+                    throw new Error("State get unexpectedly failed");
+                });
+                return Result.ok(response.entry ? await this.#project(response.entry) : undefined);
+            }
+            catch (cause) {
+                return Result.err(cause instanceof BaseError ? cause : new UnexpectedError({ cause }));
+            }
+        })());
+    }
+    /** Create the value only when no live value exists. */
+    create(value) {
+        return this.#write(value, "create");
+    }
+    /** Unconditionally replace the current value. */
+    set(value) {
+        return this.#write(value, "set");
+    }
+    /** Replace the value only while `revision` remains current. */
+    replace(revision, value) {
+        return this.#write(value, "replace", revision);
+    }
+    /** Delete unconditionally or only while `revision` remains current. */
+    delete(revision) {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                const result = await this.#calls.delete({
+                    resourceName: this.#resourceName,
+                    ...(revision === undefined ? {} : { revision }),
+                });
+                if (result.isErr()) {
+                    return result.error instanceof StateRpcConflict
+                        ? await this.#conflict(result.error)
+                        : result;
+                }
+                return Result.ok(result.unwrapOrElse(() => {
+                    throw new Error("State delete unexpectedly failed");
+                }).deleted);
+            }
+            catch (cause) {
+                return Result.err(cause instanceof BaseError ? cause : new UnexpectedError({ cause }));
+            }
+        })());
+    }
+}
+const DEFAULT_NO_RESPONDER_MAX_RETRIES = 2;
+const DEFAULT_NO_RESPONDER_RETRY_MS = 200;
+function activeTraceId(span) {
+    const traceId = span.spanContext().traceId;
+    return traceId === "00000000000000000000000000000000" ? undefined : traceId;
+}
+function traceIdFromTraceparent(traceparent) {
+    const [version, traceId, parentId, flags, extra] = traceparent?.split("-") ??
+        [];
+    if (extra !== undefined ||
+        !/^[0-9a-f]{2}$/u.test(version ?? "") ||
+        version === "ff" ||
+        !/^[0-9a-f]{32}$/u.test(traceId ?? "") ||
+        traceId === "00000000000000000000000000000000" ||
+        !/^[0-9a-f]{16}$/u.test(parentId ?? "") ||
+        parentId === "0000000000000000" ||
+        !/^[0-9a-f]{2}$/u.test(flags ?? "")) {
+        return undefined;
+    }
+    return traceId;
+}
+const EMPTY_TRELLIS_API = {
+    rpc: {},
+    operations: {},
+    events: {},
+    feeds: {},
+    subjects: {},
+};
+function isBrowserAuthRequiredError(error) {
+    return machineErrorCode(error) === "session_not_found";
+}
+function isDeclaredRpcError(errorNames, type) {
+    return !!errorNames?.includes(type);
+}
+function isRuntimeRpcErrorDesc(value) {
+    return !!value &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof Reflect.get(value, "type") === "string" &&
+        typeof Reflect.get(value, "fromSerializable") === "function";
+}
+const payloadSizeEncoder = new TextEncoder();
+function payloadByteLength(payload) {
+    return typeof payload === "string"
+        ? payloadSizeEncoder.encode(payload).byteLength
+        : payload.byteLength;
+}
+function causeMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function causeLogData(cause) {
+    return cause instanceof Error
+        ? { message: cause.message, stack: cause.stack, name: cause.name }
+        : cause;
+}
+function reconstructDeclaredRpcError(errorNames, runtimeErrors, data, json) {
+    if (!isDeclaredRpcError(errorNames, data.type)) {
+        return null;
+    }
+    const runtimeError = getBuiltinRpcError(data.type) ??
+        runtimeErrors?.find((candidate) => candidate.type === data.type);
+    if (!runtimeError) {
+        return null;
+    }
+    const parsed = runtimeError.schema
+        ? parseRuntimeSchema(runtimeError.schema, json).take()
+        : data;
+    if (isErr(parsed)) {
+        return parsed.error instanceof ValidationError ||
+            parsed.error instanceof UnexpectedError
+            ? parsed.error
+            : new UnexpectedError({ cause: parsed.error });
+    }
+    try {
+        const reconstructed = runtimeError.fromSerializable(parsed);
+        if (reconstructed instanceof BaseError) {
+            return reconstructed;
+        }
+        return new UnexpectedError({
+            cause: new Error(`RPC error '${data.type}' reconstructed to a non-Trellis error instance`),
+        });
+    }
+    catch (cause) {
+        return new UnexpectedError({ cause });
+    }
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class Trellis {
+    name;
+    timeout;
+    stream;
+    state;
+    rpc;
+    event;
+    feed;
+    operation;
+    handle;
+    /** Framework-neutral lifecycle handle for this Trellis runtime connection. */
+    connection;
+    contractId;
+    contractDigest;
+    #nats;
+    #js;
+    #auth;
+    #inboxPrefix;
+    api;
+    #log;
+    #tasks;
+    #hasExplicitApi;
+    #noResponderMaxRetries;
+    #noResponderRetryMs;
+    #onSessionNotFound;
+    #operationStore;
+    #operationDeploymentId;
+    #feedOwnerId;
+    #eventConsumers;
+    #apiBindings;
+    #durableEventLoops = new Map();
+    #durableEventListenersStopped = false;
+    #activeFeeds = new Map();
+    #pendingFeedCancels = new Map();
+    #resourceGeneration;
+    #resourceAvailability;
+    #stateMigrations;
+    constructor(name, // Must be unique for a service
+    nats, auth, opts, inboxPrefix = "_INBOX") {
+        const internalOpts = opts;
+        const api = opts?.api;
+        this.name = name;
+        this.#nats = nats;
+        this.#js = jetstream(this.#nats);
+        this.#auth = auth;
+        this.#feedOwnerId = auth.sessionKey;
+        this.#inboxPrefix = inboxPrefix;
+        this.api = (api ?? EMPTY_TRELLIS_API);
+        this.#log = (opts?.log ?? logger).child({ lib: "trellis" });
+        this.timeout = opts?.timeout ?? 3000;
+        this.stream = opts?.stream ?? "trellis";
+        this.contractId = opts?.contractId;
+        this.contractDigest = opts?.contractDigest;
+        this.#hasExplicitApi = api !== undefined;
+        this.#noResponderMaxRetries = opts?.noResponderRetry?.maxAttempts ??
+            DEFAULT_NO_RESPONDER_MAX_RETRIES;
+        this.#noResponderRetryMs = opts?.noResponderRetry?.baseDelayMs ??
+            DEFAULT_NO_RESPONDER_RETRY_MS;
+        this.#onSessionNotFound = opts?.onSessionNotFound;
+        this.#resourceGeneration = opts?.resourceGeneration ?? (() => 0);
+        this.#resourceAvailability = opts?.resourceAvailability ?? (() => true);
+        this.#stateMigrations = opts?.stateMigrations ?? {};
+        this.#eventConsumers = internalOpts?.[internalEventConsumers] ?? {};
+        this.#apiBindings = internalOpts?.[internalApiBindings] ?? {};
+        this.connection = opts?.connection ??
+            new TrellisConnection({ kind: "client" });
+        this.#tasks = new TrellisTasks({ log: this.#log });
+        this.state = this.#createStateFacade(opts?.state);
+        this.rpc = this.#createRpcFacade();
+        this.handle = { rpc: this.#createRpcHandleFacade() };
+        this.event = this.#createEventFacade();
+        this.feed = this.#createFeedFacade();
+        this.operation = this.#createOperationFacade();
+    }
+    get nats() {
+        return this.#nats;
+    }
+    get js() {
+        return this.#js;
+    }
+    get auth() {
+        return this.#auth;
+    }
+    #createStateFacade(state) {
+        const stores = (state ?? {});
+        const facade = {};
+        const stateRpc = (name) => {
+            const descriptor = Object.values(this.api.rpc).find((candidate) => candidate.permission.apiId === "trellis.state" &&
+                candidate.permission.apiVersion === "v1" &&
+                candidate.permission.surfaceName === name);
+            if (!descriptor) {
+                throw new Error(`Generated participant is missing State.${name}`);
+            }
+            return descriptor;
+        };
+        for (const [resourceName, descriptor] of Object.entries(stores)) {
+            Object.defineProperty(facade, resourceName, {
+                enumerable: true,
+                get: () => {
+                    const generation = this.#resourceGeneration();
+                    return new StateHandle({
+                        resourceName,
+                        definition: descriptor,
+                        migrations: this.#stateMigrations[resourceName],
+                        isCurrent: () => generation === this.#resourceGeneration(),
+                        isAvailable: () => this.#resourceAvailability(resourceName),
+                        calls: {
+                            get: (input) => this.#requestBuiltRpc("State.Get", input, {
+                                ...STATE_RUNTIME_RPC.Get,
+                                subject: stateRpc("Get").subject,
+                            }),
+                            set: (input) => this.#requestBuiltRpc("State.Put", {
+                                resourceName: input.resourceName,
+                                representationVersion: Number(input.representationVersion),
+                                value: input.value,
+                                mode: input.mode,
+                                ...(input.revision === undefined
+                                    ? {}
+                                    : { revision: input.revision }),
+                            }, {
+                                ...STATE_RUNTIME_RPC.Put,
+                                subject: stateRpc("Put").subject,
+                            }),
+                            delete: (input) => this.#requestBuiltRpc("State.Delete", {
+                                resourceName: input.resourceName,
+                                ...(input.revision === undefined
+                                    ? {}
+                                    : { revision: input.revision }),
+                            }, {
+                                ...STATE_RUNTIME_RPC.Delete,
+                                subject: stateRpc("Delete").subject,
+                            }),
+                        },
+                    });
+                },
+            });
+        }
+        return facade;
+    }
+    #createRpcFacade() {
+        const surface = {};
+        for (const method of Object.keys(this.api.rpc ?? {})) {
+            const leaf = (input, opts) => this.request(method, input, opts);
+            addSurfaceLeaf(surface, method, leaf);
+        }
+        return surface;
+    }
+    #createRpcHandleFacade() {
+        const surface = {};
+        for (const method of Object.keys(this.api.rpc ?? {})) {
+            addSurfaceLeaf(surface, method, (handler) => this.mount(method, handler));
+        }
+        return surface;
+    }
+    #createEventFacade() {
+        const surface = {};
+        for (const event of Object.keys(this.api.events ?? {})) {
+            addSurfaceLeaf(surface, event, {
+                prepare: (payload) => this.prepare(event, payload),
+                publish: (payload) => this.publish(event, payload),
+                listen: (handler, subjectData = {}, opts = {}) => this.listenEvent(event, subjectData, handler, opts),
+            });
+        }
+        return surface;
+    }
+    #createEventPublishFacade() {
+        const surface = {};
+        for (const event of Object.keys(this.api.events ?? {})) {
+            addSurfaceLeaf(surface, event, {
+                prepare: (payload) => this.prepare(event, payload),
+                publish: (payload) => this.publish(event, payload),
+            });
+        }
+        return surface;
+    }
+    #createFeedFacade() {
+        const surface = {};
+        for (const feed of Object.keys(this.api.feeds ?? {})) {
+            const leaf = (input, opts) => this.feedHandle(feed).input(input).subscribe(opts);
+            addSurfaceLeaf(surface, feed, leaf);
+        }
+        return surface;
+    }
+    #createHandlerTrellis() {
+        return {
+            rpc: this.rpc,
+            event: this.#createEventPublishFacade(),
+            feed: this.feed,
+            operation: this.operation,
+            request: this.request.bind(this),
+            prepare: (event, data) => this.prepare(event, data),
+            publish: (event, data) => this.publish(event, data),
+            publishPrepared: (event) => this.publishPrepared(event),
+            stopEventListeners: () => this.stopEventListeners(),
+        };
+    }
+    #createOperationFacade() {
+        const surface = {};
+        for (const operation of Object.keys(this.api.operations ?? {})) {
+            addSurfaceLeaf(surface, operation, this.operationHandle(operation));
+        }
+        return surface;
+    }
+    #unknownApiError(kind, name) {
+        const base = `Unknown ${kind} '${name}'.`;
+        if (this.#hasExplicitApi) {
+            return new Error(`${base} Did you forget to include its API module?`);
+        }
+        return new Error(`${base} No API surface was provided to the private transport session.`);
+    }
+    async operationStoreHandle() {
+        if (!this.#operationStore) {
+            if (!this.#operationDeploymentId) {
+                throw new Error("Service operation runtime requires a deployment operation store id");
+            }
+            const bucket = `trellis_operations_${this.#operationDeploymentId}`;
+            const operationStore = (async () => {
+                const result = await TypedKV.open(this.#nats, bucket, {
+                    version: 1,
+                    migrations: {},
+                    codec: {
+                        encode: (value) => value,
+                        decode: (value) => value,
+                    },
+                }, {
+                    bindOnly: true,
+                    ttl: 30 * 24 * 60 * 60 * 1_000,
+                    maxValueBytes: 1024 * 1024,
+                });
+                const value = result.take();
+                if (isErr(value)) {
+                    throw value.error;
+                }
+                return value;
+            })();
+            this.#operationStore = operationStore;
+        }
+        return this.#operationStore;
+    }
+    setOperationDeploymentId(id) {
+        this.#operationDeploymentId = id;
+    }
+    setFeedOwnerId(id) {
+        this.#feedOwnerId = id;
+    }
+    async loadOperationRecord(operationId) {
+        const store = await this.operationStoreHandle();
+        const entry = await store.getEntry(operationId);
+        const value = entry.take();
+        if (isErr(value)) {
+            throw value.error;
+        }
+        if (!value)
+            return null;
+        return value.value ?? null;
+    }
+    async listNonterminalOperationRecords() {
+        const store = await this.operationStoreHandle();
+        const keys = await store.keys();
+        const keyValue = keys.take();
+        if (isErr(keyValue))
+            throw keyValue.error;
+        const records = [];
+        for await (const key of keyValue) {
+            const record = await this.loadOperationRecord(key);
+            if (record && record.snapshot.state !== "completed" &&
+                record.snapshot.state !== "failed" &&
+                record.snapshot.state !== "cancelled")
+                records.push(record);
+        }
+        return records;
+    }
+    async saveOperationRecord(runtime) {
+        const store = await this.operationStoreHandle();
+        const loaded = await store.getEntry(runtime.id);
+        const loadedValue = loaded.take();
+        if (isErr(loadedValue))
+            throw loadedValue.error;
+        const existing = loadedValue?.value;
+        if (existing && existing.revision !== runtime.revision) {
+            throw new Error("operation revision conflict");
+        }
+        const revision = existing ? runtime.revision + 1 : runtime.revision;
+        const record = {
+            invocationId: runtime.id,
+            callerSessionKey: runtime.callerSessionKey,
+            invocationDigest: runtime.invocationDigest,
+            caller: runtime.caller,
+            creatorPrincipalId: runtime.creatorPrincipalId,
+            creatorParticipantId: runtime.creatorParticipantId,
+            apiId: runtime.apiId,
+            operation: runtime.operation,
+            input: runtime.input,
+            revision,
+            ownerInstanceId: runtime.ownerInstanceId,
+            ownerConnectionId: runtime.ownerConnectionId,
+            ownerEpoch: runtime.ownerEpoch,
+            leaseExpiresAt: runtime.leaseExpiresAt,
+            ...(runtime.cancelRequestedAt
+                ? { cancelRequestedAt: runtime.cancelRequestedAt }
+                : {}),
+            ...(runtime.transferGrant
+                ? { transferGrant: runtime.transferGrant }
+                : {}),
+            sequence: runtime.sequence,
+            signalSequence: runtime.signalSequence,
+            signals: runtime.signals,
+            snapshot: runtime.snapshot,
+        };
+        const byteLength = (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength;
+        if (byteLength(record.input) > MAX_OPERATION_INPUT_BYTES) {
+            throw new Error("operation input exceeds 256 KiB");
+        }
+        if (record.snapshot.progress !== undefined &&
+            byteLength(record.snapshot.progress) > MAX_OPERATION_PROGRESS_BYTES)
+            throw new Error("operation progress exceeds 64 KiB");
+        if (record.snapshot.output !== undefined &&
+            byteLength(record.snapshot.output) > MAX_OPERATION_OUTPUT_BYTES)
+            throw new Error("operation output exceeds 512 KiB");
+        if (record.snapshot.error !== undefined &&
+            byteLength(record.snapshot.error) > MAX_OPERATION_ERROR_BYTES)
+            throw new Error("operation error exceeds 32 KiB");
+        if ((record.signals?.length ?? 0) > MAX_OPERATION_SIGNALS) {
+            throw new Error("operation signal limit exceeded");
+        }
+        for (const signal of record.signals) {
+            if (byteLength(signal.input ?? null) > MAX_OPERATION_SIGNAL_BYTES) {
+                throw new Error("operation signal payload exceeds 64 KiB");
+            }
+        }
+        if (byteLength(record) > MAX_OPERATION_RECORD_BYTES) {
+            throw new Error("operation record exceeds 1 MiB");
+        }
+        const saved = loadedValue === undefined
+            ? await store.create(runtime.id, record)
+            : await store.replace(runtime.id, loadedValue.revision, record);
+        const value = saved.take();
+        if (isErr(value))
+            throw value.error;
+        runtime.revision = revision;
+    }
+    request(method, input, opts) {
+        const rpcApi = this.api["rpc"];
+        const ctx = rpcApi[method];
+        if (!ctx) {
+            return AsyncResult.from(Promise.resolve(err(new UnexpectedError({
+                cause: this.#unknownApiError("RPC method", method.toString()),
+                context: { method: method.toString() },
+            }))));
+        }
+        return this.#requestBuiltRpcUnknown(method, input, ctx, opts);
+    }
+    #requestBuiltRpcUnknown(method, input, ctx, opts) {
+        return this.#requestBuiltRpc(method, input, ctx, opts);
+    }
+    #requestBuiltRpc(method, input, ctx, opts) {
+        return AsyncResult.from((async () => {
+            this.#log.trace({ method: String(method) }, `Calling ${method.toString()}.`);
+            const msg = encodeRuntimeSchema(ctx.input, input).take();
+            if (isErr(msg)) {
+                recordRuntimeError(msg.error, {
+                    surface: "rpc",
+                    direction: "client",
+                    operation: method,
+                    phase: "request_encoding",
+                });
+                return msg;
+            }
+            const subject = this.template(ctx.subject, input).take();
+            if (isErr(subject)) {
+                recordRuntimeError(subject.error, {
+                    surface: "rpc",
+                    direction: "client",
+                    operation: method,
+                    phase: "request_encoding",
+                });
+                return subject;
+            }
+            const span = startClientSpan(method, subject);
+            const attempt = async () => {
+                const msgResult = await this.#requestMessageWithRetry({
+                    method,
+                    subject,
+                    payload: msg,
+                    timeout: opts?.timeout ?? this.timeout,
+                    signal: opts?.signal,
+                    callerCapabilities: ctx.callerCapabilities,
+                    span,
+                });
+                const response = msgResult.take();
+                if (isErr(response)) {
+                    recordRuntimeError(response.error, {
+                        surface: "rpc",
+                        direction: "client",
+                        operation: method,
+                        phase: "request_send",
+                    });
+                    return response;
+                }
+                if (response.headers?.get("status") === "error") {
+                    const json = safeJson(response).take();
+                    if (isErr(json)) {
+                        const error = requestFailedTransportError({
+                            code: "trellis.request.invalid_response",
+                            message: "Trellis returned an invalid response.",
+                            hint: "Retry the request. If it keeps happening, check the Trellis capability handling this request.",
+                            method,
+                            subject,
+                            cause: json.error.cause,
+                        });
+                        recordRuntimeError(error, {
+                            surface: "rpc",
+                            direction: "client",
+                            operation: method,
+                            phase: "response_decoding",
+                        });
+                        return err(error);
+                    }
+                    const errorData = parse(TrellisErrorDataSchema, json).take();
+                    if (isErr(errorData)) {
+                        const error = requestFailedTransportError({
+                            code: "trellis.request.invalid_response",
+                            message: "Trellis returned an invalid response.",
+                            hint: "Retry the request. If it keeps happening, check the Trellis capability handling this request.",
+                            method,
+                            subject,
+                            cause: errorData.error,
+                        });
+                        recordRuntimeError(error, {
+                            surface: "rpc",
+                            direction: "client",
+                            operation: method,
+                            phase: "response_decoding",
+                        });
+                        return err(error);
+                    }
+                    const declaredErrorTypes = Array.isArray(ctx.declaredErrorTypes)
+                        ? ctx.declaredErrorTypes.filter((value) => typeof value === "string")
+                        : ctx.errors;
+                    const runtimeErrors = Array.isArray(ctx.runtimeErrors)
+                        ? ctx.runtimeErrors.filter(isRuntimeRpcErrorDesc)
+                        : undefined;
+                    const reconstructed = reconstructDeclaredRpcError(declaredErrorTypes, runtimeErrors, errorData, json);
+                    if (reconstructed) {
+                        await this.#handleBrowserAuthRequired(reconstructed);
+                        recordRuntimeError(new RemoteError({ error: errorData }), {
+                            surface: "rpc",
+                            direction: "client",
+                            operation: method,
+                            phase: "remote_error",
+                        });
+                        return err(reconstructed);
+                    }
+                    const remoteError = new RemoteError({ error: errorData });
+                    await this.#handleBrowserAuthRequired(remoteError);
+                    recordRuntimeError(remoteError, {
+                        surface: "rpc",
+                        direction: "client",
+                        operation: method,
+                        phase: "remote_error",
+                    });
+                    return err(remoteError);
+                }
+                const json = safeJson(response).take();
+                if (isErr(json)) {
+                    const error = requestFailedTransportError({
+                        code: "trellis.request.invalid_response",
+                        message: "Trellis returned an invalid response.",
+                        hint: "Retry the request. If it keeps happening, check the Trellis capability handling this request.",
+                        method,
+                        subject,
+                        cause: json.error.cause,
+                    });
+                    recordRuntimeError(error, {
+                        surface: "rpc",
+                        direction: "client",
+                        operation: method,
+                        phase: "response_decoding",
+                    });
+                    return err(error);
+                }
+                const outputResult = parseRuntimeSchema(ctx.output, json).take();
+                if (isErr(outputResult)) {
+                    recordRuntimeError(outputResult.error, {
+                        surface: "rpc",
+                        direction: "client",
+                        operation: method,
+                        phase: "response_decoding",
+                    });
+                    return err(outputResult.error);
+                }
+                return ok(outputResult);
+            };
+            return await withSpanAsync(span, async () => {
+                try {
+                    const result = await attempt();
+                    const value = result.take();
+                    if (isErr(value)) {
+                        span.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: value.error.message,
+                        });
+                    }
+                    else {
+                        span.setStatus({ code: SpanStatusCode.OK });
+                    }
+                    return result;
+                }
+                catch (cause) {
+                    const unexpected = cause instanceof TransportError
+                        ? cause
+                        : new UnexpectedError({ cause });
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: unexpected.message,
+                    });
+                    span.recordException(unexpected);
+                    recordRuntimeError(unexpected, {
+                        surface: "rpc",
+                        direction: "client",
+                        operation: method,
+                        phase: "unexpected",
+                    });
+                    return err(unexpected);
+                }
+                finally {
+                    span.end();
+                }
+            });
+        })());
+    }
+    async #handleBrowserAuthRequired(error) {
+        if (!this.#onSessionNotFound || !isBrowserAuthRequiredError(error)) {
+            return;
+        }
+        await this.#onSessionNotFound();
+    }
+    async #authenticateFeedRequest(args) {
+        return await verifyLocalAuthorization({
+            kind: "request",
+            cache: this.#auth.authorizationProviderCache,
+            message: args.msg,
+            permission: args.permission,
+            requiredCapabilities: args.requiredCapabilities,
+        });
+    }
+    feedHandle(feed) {
+        const descriptor = this.api.feeds?.[feed];
+        if (!descriptor) {
+            throw this.#unknownApiError("feed", feed.toString());
+        }
+        return {
+            input: (input) => ({
+                subscribe: (opts) => this.#subscribeFeed(feed.toString(), descriptor, input, opts),
+            }),
+            handle: (handler) => this.#handleFeed(feed.toString(), descriptor, handler),
+        };
+    }
+    #subscribeFeed(feed, descriptor, input, opts) {
+        return AsyncResult.from((async () => {
+            const payload = encodeRuntimeSchema(descriptor.input, input).take();
+            if (isErr(payload)) {
+                recordRuntimeError(payload.error, {
+                    surface: "feed",
+                    direction: "client",
+                    operation: feed,
+                    phase: "request_encoding",
+                });
+                return payload;
+            }
+            const subject = this.template(descriptor.subject, input).take();
+            if (isErr(subject)) {
+                recordRuntimeError(subject.error, {
+                    surface: "feed",
+                    direction: "client",
+                    operation: feed,
+                    phase: "request_template",
+                });
+                return subject;
+            }
+            const inbox = createInbox(this.#inboxPrefix);
+            const authHeaders = await this.createRequestProof(subject, payload, inbox);
+            if (opts?.signal?.aborted) {
+                const error = createTransportError({
+                    code: "trellis.feed.subscribe_aborted",
+                    message: "The feed subscription was aborted before Trellis acknowledged it.",
+                    hint: "Retry the subscription if the feed is still needed.",
+                    context: { feed, subject },
+                });
+                recordRuntimeError(error, {
+                    surface: "feed",
+                    direction: "client",
+                    operation: feed,
+                    phase: "handshake",
+                });
+                return err(error);
+            }
+            const headers = natsHeaders();
+            headers.set("proof", authHeaders.proof);
+            headers.set("iat", String(authHeaders.iat));
+            headers.set("request-id", authHeaders.requestId);
+            headers.set("authorization-context", authHeaders.contextDigest);
+            headers.set("session-key", this.#auth.sessionKey);
+            injectTraceContext(createNatsHeaderCarrier(headers));
+            const sub = this.#nats.subscribe(inbox);
+            const iterator = sub[Symbol.asyncIterator]();
+            let feedId;
+            let cancelRequested = false;
+            let cancelSent = false;
+            let controlSubject;
+            const cancel = async () => {
+                cancelRequested = true;
+                if (cancelSent || controlSubject === undefined || feedId === undefined)
+                    return;
+                cancelSent = true;
+                try {
+                    const cancelPayload = JSON.stringify({
+                        _trellisFeedCancel: inbox,
+                        feedId,
+                    });
+                    const auth = await this.createRequestProof(controlSubject, cancelPayload, inbox);
+                    const cancelHeaders = natsHeaders();
+                    cancelHeaders.set("proof", auth.proof);
+                    cancelHeaders.set("iat", String(auth.iat));
+                    cancelHeaders.set("request-id", auth.requestId);
+                    cancelHeaders.set("authorization-context", auth.contextDigest);
+                    cancelHeaders.set("session-key", this.#auth.sessionKey);
+                    injectTraceContext(createNatsHeaderCarrier(cancelHeaders));
+                    this.#nats.publish(controlSubject, cancelPayload, {
+                        headers: cancelHeaders,
+                        reply: inbox,
+                    });
+                }
+                catch {
+                    // Best effort: the transport may already be closing with the feed.
+                }
+            };
+            const abort = () => {
+                sub.unsubscribe();
+                void cancel();
+            };
+            opts?.signal?.addEventListener("abort", abort, { once: true });
+            try {
+                this.#nats.publish(subject, payload, { headers, reply: inbox });
+            }
+            catch (cause) {
+                opts?.signal?.removeEventListener("abort", abort);
+                sub.unsubscribe();
+                await cancel();
+                const error = createTransportError({
+                    code: "trellis.feed.subscribe_failed",
+                    message: "Trellis could not subscribe to the feed.",
+                    hint: "Retry the subscription. If it keeps failing, check Trellis runtime health.",
+                    cause,
+                    context: { feed, subject },
+                });
+                recordRuntimeError(error, {
+                    surface: "feed",
+                    direction: "client",
+                    operation: feed,
+                    phase: "request_send",
+                });
+                return err(error);
+            }
+            let timeoutId;
+            let abortHandler;
+            const handshakePromises = [
+                iterator.next(),
+                new Promise((resolve) => {
+                    timeoutId = setTimeout(() => resolve("timeout"), this.timeout);
+                }),
+            ];
+            const signal = opts?.signal;
+            if (signal) {
+                handshakePromises.push(new Promise((resolve) => {
+                    abortHandler = () => resolve("aborted");
+                    signal.addEventListener("abort", abortHandler, { once: true });
+                }));
+            }
+            const firstFrame = await Promise.race(handshakePromises);
+            if (timeoutId !== undefined)
+                clearTimeout(timeoutId);
+            if (signal && abortHandler) {
+                signal.removeEventListener("abort", abortHandler);
+            }
+            if (firstFrame === "timeout" || firstFrame === "aborted") {
+                opts?.signal?.removeEventListener("abort", abort);
+                sub.unsubscribe();
+                await cancel();
+                const error = createTransportError({
+                    code: firstFrame === "timeout"
+                        ? "trellis.feed.subscribe_timeout"
+                        : "trellis.feed.subscribe_aborted",
+                    message: firstFrame === "timeout"
+                        ? "Trellis did not receive a feed acknowledgement."
+                        : "The feed subscription was aborted before Trellis acknowledged it.",
+                    hint: firstFrame === "timeout"
+                        ? "Check that the target service is running and has the current deployment digest, then retry."
+                        : "Retry the subscription if the feed is still needed.",
+                    context: { feed, subject },
+                });
+                recordRuntimeError(error, {
+                    surface: "feed",
+                    direction: "client",
+                    operation: feed,
+                    phase: "handshake",
+                });
+                return err(error);
+            }
+            if (firstFrame.done) {
+                opts?.signal?.removeEventListener("abort", abort);
+                sub.unsubscribe();
+                await cancel();
+                const error = createTransportError({
+                    code: "trellis.feed.subscribe_closed",
+                    message: "Trellis closed the feed before acknowledging it.",
+                    hint: "Retry the subscription. If it keeps failing, check Trellis runtime health.",
+                    context: { feed, subject },
+                });
+                recordRuntimeError(error, {
+                    surface: "feed",
+                    direction: "client",
+                    operation: feed,
+                    phase: "handshake",
+                });
+                return err(error);
+            }
+            const firstMessage = firstFrame.value;
+            controlSubject = firstMessage.headers?.get("feed-control-subject");
+            feedId = firstMessage.headers?.get("feed-id");
+            if (cancelRequested)
+                await cancel();
+            if (firstMessage.headers?.get("status") === "error") {
+                opts?.signal?.removeEventListener("abort", abort);
+                sub.unsubscribe();
+                await cancel();
+                const error = createTransportError({
+                    code: "trellis.feed.failed",
+                    message: "Trellis rejected the feed subscription.",
+                    hint: "Retry the subscription. If it keeps failing, check Trellis runtime health and permissions.",
+                    context: { feed, subject, frame: firstMessage.string() },
+                });
+                recordRuntimeError(error, {
+                    surface: "feed",
+                    direction: "client",
+                    operation: feed,
+                    phase: "remote_error",
+                });
+                return err(error);
+            }
+            const firstEvent = firstMessage.headers?.get("feed-status") === "ready"
+                ? undefined
+                : firstMessage;
+            const eventSchema = descriptor.event;
+            return ok((async function* () {
+                try {
+                    const parseFeedFrame = (msg) => {
+                        if (msg.headers?.get("status") === "error") {
+                            const error = createTransportError({
+                                code: "trellis.feed.failed",
+                                message: "Trellis stopped the feed.",
+                                hint: "Retry the subscription. If it keeps failing, check Trellis runtime health.",
+                                context: { feed, subject, frame: msg.string() },
+                            });
+                            recordRuntimeError(error, {
+                                surface: "feed",
+                                direction: "client",
+                                operation: feed,
+                                phase: "remote_error",
+                            });
+                            throw error;
+                        }
+                        const json = safeJson(msg).take();
+                        if (isErr(json)) {
+                            recordRuntimeError(json.error, {
+                                surface: "feed",
+                                direction: "client",
+                                operation: feed,
+                                phase: "event_decoding",
+                            });
+                            throw json.error;
+                        }
+                        const parsed = parseRuntimeSchema(eventSchema, json).take();
+                        if (isErr(parsed)) {
+                            recordRuntimeError(parsed.error, {
+                                surface: "feed",
+                                direction: "client",
+                                operation: feed,
+                                phase: "event_validation",
+                            });
+                            throw parsed.error;
+                        }
+                        return parsed;
+                    };
+                    if (firstEvent)
+                        yield parseFeedFrame(firstEvent);
+                    while (true) {
+                        const next = await iterator.next();
+                        if (next.done)
+                            break;
+                        yield parseFeedFrame(next.value);
+                    }
+                }
+                finally {
+                    opts?.signal?.removeEventListener("abort", abort);
+                    sub.unsubscribe();
+                    await cancel();
+                }
+            })());
+        })());
+    }
+    async #handleFeed(feed, descriptor, handler) {
+        const subject = this.template(descriptor.subject, {}, true).take();
+        if (isErr(subject))
+            throw subject.error;
+        let sub;
+        let controlSub;
+        const controlSubject = feedControlSubject(subject, this.#feedOwnerId);
+        try {
+            sub = this.#nats.subscribe(subject, { queue: routeQueueGroup(subject) });
+            controlSub = this.#nats.subscribe(controlSubject);
+        }
+        catch (cause) {
+            const error = createTransportError({
+                code: "trellis.feed.listen_failed",
+                message: "Trellis could not listen for feed requests.",
+                hint: "Check the service deployment digest and runtime permissions, then restart the service.",
+                cause,
+                context: { feed, subject },
+            });
+            recordRuntimeError(error, {
+                surface: "feed",
+                direction: "server",
+                operation: feed,
+                phase: "listen",
+            });
+            throw error;
+        }
+        const task = AsyncResult.try(async () => {
+            for await (const msg of sub) {
+                void (async () => {
+                    try {
+                        const result = await this.#processFeedMessage(feed, descriptor, msg, handler);
+                        const value = result.take();
+                        if (isErr(value)) {
+                            this.#respondWithError(msg, value.error);
+                        }
+                    }
+                    catch (cause) {
+                        const error = annotateHandlerBoundaryError(cause, {
+                            feed,
+                            requestId: msg.headers?.get("request-id"),
+                            service: this.name,
+                            contractId: this.contractId,
+                            contractDigest: this.contractDigest,
+                            traceId: traceIdFromTraceparent(msg.headers?.get("traceparent")),
+                        });
+                        recordRuntimeError(error, {
+                            surface: "feed",
+                            direction: "server",
+                            operation: feed,
+                            phase: "handler_throw",
+                        });
+                        this.#respondWithError(msg, error);
+                    }
+                })();
+            }
+        });
+        this.#tasks.add(`feed:${feed}`, task);
+        this.#tasks.add(`feed:${feed}:control`, AsyncResult.try(async () => {
+            for await (const msg of controlSub) {
+                const result = await this.#processFeedMessage(feed, descriptor, msg, handler);
+                const value = result.take();
+                if (isErr(value))
+                    this.#respondWithError(msg, value.error);
+            }
+        }));
+    }
+    async #processFeedMessage(feed, descriptor, msg, handler) {
+        const json = safeJson(msg).take();
+        if (isErr(json)) {
+            recordRuntimeError(json.error, {
+                surface: "feed",
+                direction: "server",
+                operation: feed,
+                phase: "request_decoding",
+            });
+            return json;
+        }
+        const caller = await this.#authenticateFeedRequest({
+            msg,
+            permission: descriptor.permission,
+            requiredCapabilities: descriptor.subscribeCapabilities,
+        });
+        const callerValue = caller.take();
+        if (isErr(callerValue)) {
+            recordRuntimeError(callerValue.error, {
+                surface: "feed",
+                direction: "server",
+                operation: feed,
+                phase: "auth",
+            });
+            return callerValue;
+        }
+        const cancelReply = json && typeof json === "object" &&
+            !Array.isArray(json) && Object.keys(json).length === 2 &&
+            typeof json._trellisFeedCancel ===
+                "string" &&
+            typeof json.feedId === "string"
+            ? json._trellisFeedCancel
+            : undefined;
+        if (cancelReply !== undefined) {
+            if (cancelReply !== msg.reply) {
+                return err(new AuthError({
+                    reason: "reply_subject_mismatch",
+                    context: { expected: msg.reply, actual: cancelReply },
+                }));
+            }
+            const active = this.#activeFeeds.get(cancelReply);
+            const controlFeedId = json.feedId;
+            if (!active || active.feedId !== controlFeedId ||
+                msg.subject !==
+                    feedControlSubject(descriptor.subject, this.#feedOwnerId, controlFeedId) ||
+                callerValue.type !== "verified" ||
+                active.principalId !== callerValue.principalId ||
+                active.participantId !== callerValue.participantId) {
+                return err(new AuthError({
+                    reason: "feed_control_denied",
+                    context: { feed, feedId: controlFeedId },
+                }));
+            }
+            active.controller.abort();
+            if (this.#activeFeeds.delete(cancelReply))
+                return ok(undefined);
+            const previous = this.#pendingFeedCancels.get(cancelReply);
+            if (previous !== undefined)
+                clearTimeout(previous);
+            if (previous !== undefined ||
+                this.#pendingFeedCancels.size < MAX_FEED_CANCEL_TOMBSTONES) {
+                const timeout = setTimeout(() => {
+                    this.#pendingFeedCancels.delete(cancelReply);
+                }, FEED_CANCEL_TOMBSTONE_MS);
+                this.#pendingFeedCancels.set(cancelReply, timeout);
+            }
+            return ok(undefined);
+        }
+        const parsed = parseRuntimeSchema(descriptor.input, json).take();
+        if (isErr(parsed)) {
+            recordRuntimeError(parsed.error, {
+                surface: "feed",
+                direction: "server",
+                operation: feed,
+                phase: "input_validation",
+            });
+            return parsed;
+        }
+        if (!msg.reply) {
+            const error = new UnexpectedError({
+                context: { feed, reason: "missing_reply" },
+            });
+            recordRuntimeError(error, {
+                surface: "feed",
+                direction: "server",
+                operation: feed,
+                phase: "handshake",
+            });
+            return err(error);
+        }
+        const pendingCancel = this.#pendingFeedCancels.get(msg.reply);
+        if (pendingCancel !== undefined) {
+            clearTimeout(pendingCancel);
+            this.#pendingFeedCancels.delete(msg.reply);
+            return ok(undefined);
+        }
+        const controller = new AbortController();
+        if (callerValue.type !== "verified") {
+            return err(new AuthError({ reason: "feed_creator_identity_required" }));
+        }
+        const feedId = crypto.randomUUID();
+        this.#activeFeeds.get(msg.reply)?.controller.abort();
+        this.#activeFeeds.set(msg.reply, {
+            controller,
+            feedId,
+            principalId: callerValue.principalId,
+            participantId: callerValue.participantId,
+        });
+        try {
+            const readyHeaders = natsHeaders();
+            readyHeaders.set("feed-status", "ready");
+            readyHeaders.set("feed-id", feedId);
+            readyHeaders.set("feed-control-subject", feedControlSubject(descriptor.subject, this.#feedOwnerId, feedId));
+            this.#nats.publish(msg.reply, new Uint8Array(), {
+                headers: readyHeaders,
+            });
+            if (controller.signal.aborted)
+                return ok(undefined);
+            const handlerResult = await handler({
+                input: parsed,
+                caller: callerValue,
+                signal: controller.signal,
+                emit: (event) => AsyncResult.from((async () => {
+                    const payload = encodeRuntimeSchema(descriptor.event, event).take();
+                    if (isErr(payload)) {
+                        recordRuntimeError(payload.error, {
+                            surface: "feed",
+                            direction: "server",
+                            operation: feed,
+                            phase: "event_encoding",
+                        });
+                        return payload;
+                    }
+                    if (!msg.reply) {
+                        const error = new UnexpectedError({
+                            context: { feed, reason: "missing_reply" },
+                        });
+                        recordRuntimeError(error, {
+                            surface: "feed",
+                            direction: "server",
+                            operation: feed,
+                            phase: "event_publish",
+                        });
+                        return err(error);
+                    }
+                    try {
+                        this.#nats.publish(msg.reply, payload);
+                    }
+                    catch (cause) {
+                        const error = new UnexpectedError({
+                            cause,
+                            context: { feed },
+                        });
+                        recordRuntimeError(error, {
+                            surface: "feed",
+                            direction: "server",
+                            operation: feed,
+                            phase: "event_publish",
+                        });
+                        return err(error);
+                    }
+                    return ok(undefined);
+                })()),
+            });
+            const handlerOutcome = isResultLike(handlerResult)
+                ? handlerResult.take()
+                : handlerResult;
+            if (isErr(handlerOutcome)) {
+                const error = annotateHandlerBoundaryError(handlerOutcome.error, {
+                    feed,
+                    requestId: msg.headers?.get("request-id"),
+                    service: this.name,
+                    contractId: this.contractId,
+                    contractDigest: this.contractDigest,
+                    traceId: traceIdFromTraceparent(msg.headers?.get("traceparent")),
+                });
+                recordRuntimeError(error, {
+                    surface: "feed",
+                    direction: "server",
+                    operation: feed,
+                    phase: "handler_result",
+                });
+                return err(error);
+            }
+            return ok(undefined);
+        }
+        finally {
+            if (this.#activeFeeds.get(msg.reply)?.controller === controller) {
+                this.#activeFeeds.delete(msg.reply);
+            }
+            controller.abort();
+        }
+    }
+    operationHandle(operation, unavailable) {
+        const descriptor = this.api["operations"]?.[operation];
+        if (!descriptor) {
+            throw this.#unknownApiError("operation", operation.toString());
+        }
+        const transport = {
+            requestJson: (subject, body) => {
+                const error = unavailable?.();
+                return error
+                    ? AsyncResult.from(Promise.resolve(err(error)))
+                    : this.#requestJson(subject, body);
+            },
+            watchJson: (subject, body) => {
+                const error = unavailable?.();
+                return error
+                    ? AsyncResult.from(Promise.resolve(err(error)))
+                    : this.#watchJson(subject, body);
+            },
+            putTransfer: (grant, body) => AsyncResult.from((async () => {
+                const handle = createTransferHandle(this.#nats, this.#auth, this.timeout, grant, this.#inboxPrefix);
+                if (!(handle instanceof Object) || !("send" in handle)) {
+                    return err(new TransferError({
+                        operation: "transfer",
+                        context: { reason: "invalid_operation_transfer_grant" },
+                    }));
+                }
+                return await handle.send(body);
+            })()),
+        };
+        return new OperationInvoker(transport, descriptor);
+    }
+    transfer(grant) {
+        return createTransferHandle(this.#nats, this.#auth, this.timeout, grant, this.#inboxPrefix);
+    }
+    /*
+     * Mount a handler to process requests made to a specific Trellis API
+     */
+    async mount(method, fn) {
+        const methodName = method;
+        const ctx = this.api["rpc"][methodName];
+        if (!ctx) {
+            throw this.#unknownApiError("RPC method", method.toString());
+        }
+        const task = this.#handleRPC(methodName, fn);
+        this.#tasks.add(methodName, task);
+    }
+    #handleRPC(method, fn, subjectData = {}) {
+        // Get API details
+        const ctx = this.api["rpc"][method];
+        const subject = this.template(ctx.subject, subjectData, true).take();
+        if (isErr(subject)) {
+            return AsyncResult.lift(subject);
+        }
+        const handlerTrellis = this.#createHandlerTrellis();
+        this.#log.info({ method: String(method) }, `Mounting ${method.toString()} RPC handler`);
+        const sub = this.#nats.subscribe(subject, {
+            queue: routeQueueGroup(subject),
+        });
+        return AsyncResult.try(async () => {
+            for await (const msg of sub) {
+                const resultPromise = await this.#processRPCMessage(method, ctx, msg, fn, handlerTrellis);
+                const result = resultPromise.take();
+                if (isErr(result)) {
+                    this.#respondWithError(msg, result.error, { method: String(method) });
+                    continue;
+                }
+                const sent = this.#respondWithPayload(msg, result.payload, undefined, {
+                    method: String(method),
+                    responseKind: "success",
+                });
+                if (sent.isErr()) {
+                    const responseBytes = payloadByteLength(result.payload);
+                    const message = causeMessage(sent.error.cause);
+                    this.#respondWithError(msg, new TransportError({
+                        code: "trellis.rpc.response_send_failed",
+                        message: message.includes("max_payload")
+                            ? "Trellis RPC response exceeded NATS max_payload."
+                            : "Trellis could not send the RPC response.",
+                        hint: "Reduce the requested page size or use a narrower RPC that does not include large detail payloads.",
+                        cause: sent.error.cause,
+                        context: {
+                            method: String(method),
+                            subject: msg.subject,
+                            responseBytes,
+                            causeMessage: message,
+                        },
+                    }), { method: String(method), responseBytes });
+                    continue;
+                }
+                if (result.afterReply.length > 0) {
+                    for (const task of result.afterReply) {
+                        try {
+                            await task();
+                        }
+                        catch (error) {
+                            this.#log.error({ method: String(method), error }, "RPC after-reply task failed");
+                        }
+                    }
+                }
+            }
+        });
+    }
+    async #processRPCMessage(method, ctx, msg, fn, handlerTrellis) {
+        this.#log.debug({ method: String(method), subject: msg.subject }, "Processing RPC message");
+        // Extract trace context from incoming NATS headers
+        const parentContext = extractTraceContext(createNatsHeaderCarrier({
+            get: (k) => msg.headers?.get(k) ?? undefined,
+            set: () => { }, // Server doesn't need to set headers on incoming messages
+        }));
+        // Start a server span for this RPC handler
+        const span = startServerSpan(method, msg.subject, parentContext);
+        const incomingTraceId = traceIdFromTraceparent(msg.headers?.get("traceparent"));
+        // Execute the handler within the span's context
+        return withSpanAsync(span, async () => {
+            const afterReply = [];
+            const execute = async () => {
+                const jsonData = safeJson(msg).take();
+                if (isErr(jsonData)) {
+                    this.#log.warn({ method, error: jsonData.error.message }, "Failed to parse JSON");
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Failed to parse JSON",
+                    });
+                    recordRuntimeError(jsonData.error, {
+                        surface: "rpc",
+                        direction: "server",
+                        operation: String(method),
+                        phase: "parse",
+                    });
+                    return jsonData;
+                }
+                const parsedInput = parseRuntimeSchema(ctx.input, jsonData).take();
+                if (isErr(parsedInput)) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Input validation failed",
+                    });
+                    recordRuntimeError(parsedInput.error, {
+                        surface: "rpc",
+                        direction: "server",
+                        operation: String(method),
+                        phase: "input_validation",
+                    });
+                    return parsedInput;
+                }
+                let caller;
+                let callerInboxPrefix = "_INBOX";
+                const handlerRequestIdFromHeader = msg.headers?.get("request-id") ?? "";
+                const handlerTraceIdFromHeader = traceIdFromTraceparent(msg.headers?.get("traceparent"));
+                const authRequired = ctx.authRequired ?? true;
+                if (!authRequired) {
+                    caller = {
+                        type: "internal",
+                        capabilities: [],
+                    };
+                }
+                else {
+                    const auth = await verifyLocalAuthorization({
+                        kind: "request",
+                        cache: this.#auth.authorizationProviderCache,
+                        message: msg,
+                        permission: ctx.permission,
+                        requiredCapabilities: ctx.callerCapabilities,
+                    });
+                    const authValue = auth.take();
+                    if (isErr(authValue)) {
+                        span.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: authValue.error.message,
+                        });
+                        recordRuntimeError(authValue.error, {
+                            surface: "rpc",
+                            direction: "server",
+                            operation: String(method),
+                            phase: "auth",
+                        });
+                        return err(authValue.error);
+                    }
+                    caller = authValue;
+                    callerInboxPrefix = authValue.inboxPrefix;
+                }
+                span.setAttribute("auth.caller.type", caller.type);
+                if (caller.type === "verified") {
+                    span.setAttribute("auth.principal.kind", caller.principalKind);
+                    span.setAttribute("auth.principal.id", caller.principalId);
+                    span.setAttribute("auth.participant.id", caller.participantId);
+                    span.setAttribute("auth.connection.id", caller.connectionId);
+                    span.setAttribute("auth.grant.revision", caller.grantRevision);
+                    if (caller.loginSessionId) {
+                        span.setAttribute("auth.login_session.id", caller.loginSessionId);
+                    }
+                    if (caller.deploymentId) {
+                        span.setAttribute("auth.deployment.id", caller.deploymentId);
+                    }
+                    if (caller.instanceId) {
+                        span.setAttribute("auth.instance.id", caller.instanceId);
+                    }
+                }
+                const invokeHandler = fn;
+                const handlerResultWrapped = await AsyncResult.try(async () => await Promise.resolve(invokeHandler({
+                    input: parsedInput,
+                    context: {
+                        caller,
+                        sessionKey: caller.type === "verified" ? caller.sessionKey : "",
+                        inboxPrefix: callerInboxPrefix,
+                        permission: ctx.permission,
+                        requiredCapabilities: ctx.callerCapabilities,
+                        requestId: handlerRequestIdFromHeader || undefined,
+                        traceId: handlerTraceIdFromHeader || undefined,
+                        afterReply: (task) => afterReply.push(task),
+                    },
+                    client: handlerTrellis,
+                })));
+                if (handlerResultWrapped.isErr()) {
+                    const error = annotateHandlerBoundaryError(handlerResultWrapped.error, {
+                        method: String(method),
+                        requestId: msg.headers?.get("request-id"),
+                        service: this.name,
+                        contractId: this.contractId,
+                        contractDigest: this.contractDigest,
+                        traceId: activeTraceId(span) ?? incomingTraceId,
+                    });
+                    this.#log.error({
+                        method,
+                        error: error.message,
+                        cause: error.cause instanceof Error
+                            ? { message: error.cause.message, stack: error.cause.stack }
+                            : error.cause,
+                    }, "Handler threw unexpectedly.");
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                    span.recordException(error);
+                    recordRuntimeError(error, {
+                        surface: "rpc",
+                        direction: "server",
+                        operation: String(method),
+                        phase: "handler_throw",
+                    });
+                    return err(error);
+                }
+                const handlerResult = handlerResultWrapped.take();
+                const handlerOutcome = handlerResult.take();
+                if (isErr(handlerOutcome)) {
+                    const error = annotateHandlerBoundaryError(handlerOutcome.error, {
+                        method: String(method),
+                        requestId: msg.headers?.get("request-id"),
+                        service: this.name,
+                        contractId: this.contractId,
+                        contractDigest: this.contractDigest,
+                        traceId: activeTraceId(span) ?? incomingTraceId,
+                    });
+                    this.#log.error({
+                        method,
+                        error: error.message,
+                        errorType: error.name,
+                        cause: error.cause instanceof Error
+                            ? { message: error.cause.message, stack: error.cause.stack }
+                            : error.cause,
+                    }, "Handler returned error.");
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                    recordRuntimeError(error, {
+                        surface: "rpc",
+                        direction: "server",
+                        operation: String(method),
+                        phase: "handler_result",
+                    });
+                    return err(error);
+                }
+                const encoded = encodeSchema(ctx.output, handlerOutcome).take();
+                if (isErr(encoded)) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Output encoding failed",
+                    });
+                    recordRuntimeError(encoded.error, {
+                        surface: "rpc",
+                        direction: "server",
+                        operation: String(method),
+                        phase: "output_encoding",
+                    });
+                    return encoded;
+                }
+                span.setStatus({ code: SpanStatusCode.OK });
+                return ok({ payload: encoded, afterReply });
+            };
+            const result = await execute();
+            if (isErr(result)) {
+                result.error.withTraceId(activeTraceId(span) ?? incomingTraceId);
+            }
+            span.end();
+            return result;
+        });
+    }
+    #respondWithPayload(msg, payload, options, context) {
+        const responseBytes = payloadByteLength(payload);
+        try {
+            msg.respond(payload, options);
+            return ok(undefined);
+        }
+        catch (cause) {
+            const error = new UnexpectedError({
+                cause,
+                context: {
+                    method: context.method,
+                    responseKind: context.responseKind,
+                    subject: msg.subject,
+                    reply: msg.reply,
+                    responseBytes,
+                    causeMessage: causeMessage(cause),
+                },
+            });
+            this.#log.error({
+                method: context.method,
+                responseKind: context.responseKind,
+                subject: msg.subject,
+                reply: msg.reply,
+                responseBytes,
+                cause: causeLogData(cause),
+            }, "Failed to send RPC response");
+            return err(error);
+        }
+    }
+    #respondWithError(msg, error, context = {}) {
+        const trellisError = error instanceof BaseError &&
+            !(error instanceof RemoteError)
+            ? error
+            : new UnexpectedError({ cause: error });
+        this.#log.error({
+            method: context.method,
+            subject: msg.subject,
+            responseBytes: context.responseBytes,
+            error: trellisError.toSerializable(),
+        }, "RPC error");
+        const errorData = trellisError.toSerializable();
+        const hdrs = natsHeaders();
+        hdrs.set("status", "error");
+        const serialized = Result.try(() => JSON.stringify(errorData));
+        if (serialized.isErr()) {
+            this.#log.error({ error: serialized.error }, "Failed to serialize error response");
+            this.#respondWithPayload(msg, '{"type":"UnexpectedError","message":"Failed to serialize error"}', { headers: hdrs }, { method: context.method, responseKind: "error" });
+            return;
+        }
+        this.#respondWithPayload(msg, serialized.take(), { headers: hdrs }, { method: context.method, responseKind: "error" });
+    }
+    respondWithError(msg, error) {
+        this.#respondWithError(msg, error);
+    }
+    /**
+     * Builds a stable event subject, encoded payload, and publish headers.
+     *
+     * The prepared event intentionally carries no contract id or digest so callers
+     * can persist it in a service-owned outbox without coupling storage to the
+     * publisher's current deployment metadata.
+     */
+    prepare(event, data) {
+        try {
+            const eventName = event;
+            const ctx = this.api["events"][eventName];
+            if (!ctx) {
+                const error = new UnexpectedError({
+                    cause: this.#unknownApiError("event", event.toString()),
+                    context: { event: event.toString() },
+                });
+                recordRuntimeError(error, {
+                    surface: "event",
+                    direction: "publisher",
+                    operation: event,
+                    phase: "prepare",
+                });
+                return err(error);
+            }
+            const subject = this.template(ctx.subject, data).take();
+            if (isErr(subject)) {
+                logger.error({ err: subject.error }, "Failed to template event.");
+                recordRuntimeError(subject.error, {
+                    surface: "event",
+                    direction: "publisher",
+                    operation: event,
+                    phase: "request_encoding",
+                });
+                return subject;
+            }
+            const header = {
+                id: ulid(),
+                time: new Date().toISOString(),
+            };
+            const payload = Object.freeze({ ...data });
+            const msg = encodeSchema(ctx.event, payload).take();
+            if (isErr(msg)) {
+                logger.error({ err: msg.error }, "Failed to encode event.");
+                const error = new UnexpectedError({ cause: msg.error });
+                recordRuntimeError(error, {
+                    surface: "event",
+                    direction: "publisher",
+                    operation: event,
+                    phase: "request_encoding",
+                });
+                return err(error);
+            }
+            const headers = natsHeaders();
+            injectTraceContext(createNatsHeaderCarrier(headers));
+            const headerRecord = {};
+            for (const [key, value] of headers) {
+                headerRecord[key] = value.join(",");
+            }
+            headerRecord["Trellis-Event-Descriptor"] = ctx.descriptorIdentity;
+            return ok(Object.freeze({
+                event: event.toString(),
+                descriptorIdentity: ctx.descriptorIdentity,
+                subject,
+                header: Object.freeze(header),
+                payload,
+                encodedPayload: msg,
+                headers: Object.freeze(headerRecord),
+            }));
+        }
+        catch (cause) {
+            const error = new UnexpectedError({
+                cause,
+                context: { event: event.toString() },
+            });
+            recordRuntimeError(error, {
+                surface: "event",
+                direction: "publisher",
+                operation: event,
+                phase: "prepare",
+            });
+            return err(error);
+        }
+    }
+    /**
+     * Publishes a previously prepared event without regenerating its id, time,
+     * subject, payload, or headers.
+     */
+    publishPrepared(event) {
+        return AsyncResult.from((async () => {
+            try {
+                const headers = natsHeaders();
+                for (const [key, value] of Object.entries(event.headers)) {
+                    headers.set(key, value);
+                }
+                headers.set("Nats-Msg-Id", event.header.id);
+                headers.set("Trellis-Event-Time", event.header.time);
+                headers.set("Trellis-Event-Descriptor", event.descriptorIdentity);
+                const proof = await this.#createEventProof(event);
+                headers.set("proof", proof.proof);
+                headers.set("authorization-context", proof.contextDigest);
+                headers.set("session-key", this.#auth.sessionKey);
+                logger.trace({ subject: event.subject }, `Publishing ${event.event} event.`);
+                await this.#js.publish(event.subject, event.encodedPayload, {
+                    headers,
+                });
+                return ok(undefined);
+            }
+            catch (cause) {
+                const error = new UnexpectedError({
+                    cause,
+                    context: { event: event.event },
+                });
+                recordRuntimeError(error, {
+                    surface: "event",
+                    direction: "publisher",
+                    operation: event.event,
+                    phase: "publish",
+                });
+                return err(error);
+            }
+        })());
+    }
+    publish(event, data) {
+        return AsyncResult.from((async () => {
+            const prepared = this.prepare(event, data).take();
+            if (isErr(prepared))
+                return prepared;
+            return await this.publishPrepared(prepared);
+        })());
+    }
+    listenEvent(event, subjectData, fn, opts) {
+        return AsyncResult.from((async () => {
+            try {
+                const eventName = event;
+                const ctx = this.api["events"][eventName];
+                if (!ctx) {
+                    return err(new UnexpectedError({
+                        cause: this.#unknownApiError("event", event.toString()),
+                        context: { event: event.toString() },
+                    }));
+                }
+                const subject = this.template(ctx.subject, subjectData, true).take();
+                if (isErr(subject))
+                    return subject;
+                if (opts?.mode === "ephemeral") {
+                    return await this.#startEphemeralEvent(eventName, ctx, subject, fn, opts.signal);
+                }
+                const groupResult = this.#resolveEventConsumerGroup(eventName, opts);
+                const group = groupResult.take();
+                if (isErr(group))
+                    return group;
+                this.#registerDurableEventHandler({
+                    group,
+                    event: eventName,
+                    ctx,
+                    subject,
+                    fn,
+                    signal: opts?.signal,
+                });
+                return ok(undefined);
+            }
+            catch (cause) {
+                return err(new UnexpectedError({ cause, context: { event: event.toString() } }));
+            }
+        })());
+    }
+    async #startEphemeralEvent(event, ctx, subject, fn, signal) {
+        let sub;
+        try {
+            sub = this.#nats.subscribe(subject);
+            if (signal) {
+                if (signal.aborted) {
+                    sub.unsubscribe();
+                    return ok(undefined);
+                }
+                signal.addEventListener("abort", () => sub?.unsubscribe(), {
+                    once: true,
+                });
+            }
+        }
+        catch (cause) {
+            if (sub) {
+                sub.unsubscribe();
+            }
+            return err(new UnexpectedError({
+                cause,
+                context: { event: String(event), subject },
+            }));
+        }
+        const task = AsyncResult.try(async () => {
+            for await (const msg of sub) {
+                const proofResult = await this.#validateEventProof(event, ctx, msg);
+                const proofValue = proofResult.take();
+                if (isErr(proofValue)) {
+                    this.#log.warn({ error: proofValue.error, event, subject: msg.subject }, "Event auth validation failed");
+                    continue;
+                }
+                const parsedEvent = this.#parseEventMessage(event, ctx, msg);
+                const m = parsedEvent.take();
+                if (isErr(m)) {
+                    this.#log.error({ error: m.error }, "Event validation failed");
+                    recordRuntimeError(m.error, {
+                        surface: "event",
+                        direction: "consumer",
+                        operation: String(event),
+                        phase: "input_validation",
+                    });
+                    continue;
+                }
+                const handlerResult = await this.#invokeEventHandler({
+                    event,
+                    payload: m,
+                    mode: "ephemeral",
+                    message: msg,
+                    fn,
+                });
+                const handlerValue = handlerResult.take();
+                if (isErr(handlerValue)) {
+                    recordRuntimeError(handlerValue.error, {
+                        surface: "event",
+                        direction: "consumer",
+                        operation: String(event),
+                        phase: "handler_result",
+                    });
+                    this.#log.error({
+                        error: handlerValue.error.toSerializable(),
+                        event,
+                        subject: msg.subject,
+                    }, "Event handler failed");
+                }
+            }
+        });
+        this.#tasks.add(`event:${event}:${ulid()}`, task);
+        return ok(undefined);
+    }
+    async #invokeEventHandler(args) {
+        const annotation = {
+            event: String(args.event),
+            service: this.name,
+            contractId: this.contractId,
+            contractDigest: this.contractDigest,
+            traceId: traceIdFromTraceparent(args.message.headers?.get("traceparent")),
+        };
+        try {
+            const result = await Promise.resolve(args.fn(args.payload, createEventListenerContext({
+                subject: args.message.subject,
+                mode: args.mode,
+                ...(args.group ? { group: args.group } : {}),
+                message: args.message,
+            })));
+            const outcome = isResultLike(result) ? result.take() : result;
+            if (isErr(outcome)) {
+                return err(annotateHandlerBoundaryError(outcome.error, annotation));
+            }
+            return ok(undefined);
+        }
+        catch (cause) {
+            return err(annotateHandlerBoundaryError(cause, annotation));
+        }
+    }
+    #resolveEventConsumerGroup(event, opts) {
+        const metadata = this.#eventConsumers.metadata;
+        const bindings = this.#eventConsumers.bindings ?? {};
+        const groups = Object.entries(metadata ?? {})
+            .filter(([, group]) => eventConsumerGroupEvents(group).includes(String(event)))
+            .map(([group]) => group);
+        if (opts?.group) {
+            if (!groups.includes(opts.group)) {
+                return err(new UnexpectedError({
+                    cause: new Error(`Event '${String(event)}' is not declared in event consumer group '${opts.group}'.`),
+                    context: { event: String(event), group: opts.group },
+                }));
+            }
+            if (!bindings[opts.group]) {
+                return err(new UnexpectedError({
+                    cause: new Error(`Event consumer group '${opts.group}' has no Trellis-provisioned binding.`),
+                    context: { event: String(event), group: opts.group },
+                }));
+            }
+            return ok(opts.group);
+        }
+        if (groups.length === 0) {
+            return err(new UnexpectedError({
+                cause: new Error(`Event '${String(event)}' is not declared in any event consumer group.`),
+                context: { event: String(event) },
+            }));
+        }
+        if (groups.length > 1) {
+            return err(new UnexpectedError({
+                cause: new Error(`Event '${String(event)}' is declared in multiple event consumer groups; pass opts.group.`),
+                context: { event: String(event), groups },
+            }));
+        }
+        const group = groups[0];
+        if (!bindings[group]) {
+            return err(new UnexpectedError({
+                cause: new Error(`Event consumer group '${group}' has no Trellis-provisioned binding.`),
+                context: { event: String(event), group },
+            }));
+        }
+        return ok(group);
+    }
+    #registerDurableEventHandler(args) {
+        if (args.signal?.aborted || this.#durableEventListenersStopped)
+            return;
+        const binding = this.#eventConsumers.bindings?.[args.group];
+        if (!binding) {
+            throw new Error(`Event consumer group '${args.group}' has no Trellis-provisioned binding.`);
+        }
+        if (!Number.isInteger(binding.concurrency) || binding.concurrency < 1) {
+            throw new Error(`Event consumer group '${args.group}' has invalid concurrency ${binding.concurrency}; expected a positive integer`);
+        }
+        const loop = this.#durableEventLoops.get(args.group) ?? {
+            registrations: [],
+            concurrency: binding.concurrency,
+            startedWorkers: new Set(),
+            messages: new Set(),
+        };
+        if (loop.concurrency !== binding.concurrency) {
+            throw new Error(`Event consumer group '${args.group}' is already registered with concurrency ${loop.concurrency}; binding now requires ${binding.concurrency}`);
+        }
+        const registration = {
+            event: args.event,
+            ctx: args.ctx,
+            subject: args.subject,
+            fn: args.fn,
+        };
+        loop.registrations.push(registration);
+        this.#durableEventLoops.set(args.group, loop);
+        args.signal?.addEventListener("abort", () => {
+            const index = loop.registrations.indexOf(registration);
+            if (index >= 0)
+                loop.registrations.splice(index, 1);
+            if (!this.#durableEventConsumerGroupReady(args.group, loop)) {
+                for (const messages of loop.messages)
+                    messages.stop();
+            }
+        }, { once: true });
+        this.#startDurableEventConsumer(args.group, loop);
+    }
+    #startDurableEventConsumer(group, loop) {
+        if (this.#durableEventListenersStopped ||
+            !this.#durableEventConsumerGroupReady(group, loop)) {
+            return;
+        }
+        for (let workerIndex = 0; workerIndex < loop.concurrency; workerIndex += 1) {
+            if (loop.startedWorkers.has(workerIndex))
+                continue;
+            loop.startedWorkers.add(workerIndex);
+            this.#tasks.add(`event-consumer:${group}:${workerIndex}:${ulid()}`, this.#runDurableEventConsumer(group, loop, workerIndex));
+        }
+    }
+    #durableEventConsumerGroupReady(group, loop) {
+        const metadata = this.#eventConsumers.metadata?.[group];
+        if (!metadata)
+            return false;
+        return eventConsumerGroupEvents(metadata).every((event) => loop.registrations.some((registration) => String(registration.event) === event));
+    }
+    #runDurableEventConsumer(group, loop, workerIndex) {
+        return AsyncResult.from((async () => {
+            const binding = this.#eventConsumers.bindings?.[group];
+            if (!binding) {
+                return err(new UnexpectedError({
+                    cause: new Error(`Event consumer group '${group}' has no Trellis-provisioned binding.`),
+                    context: { group },
+                }));
+            }
+            let originalOpened = false;
+            let fetchingReplay = true;
+            try {
+                const infoResult = await AsyncResult.try(async () => {
+                    const jsm = await jetstreamManager(this.#nats);
+                    return await jsm.consumers.info(binding.stream, binding.consumerName);
+                });
+                const info = infoResult.take();
+                if (isErr(info)) {
+                    if (this.#durableEventListenersStopped ||
+                        !this.#durableEventConsumerGroupReady(group, loop)) {
+                        return ok(undefined);
+                    }
+                    if (isConsumerNotFoundError(info.error.cause)) {
+                        this.#log.debug({ group, stream: binding.stream, consumer: binding.consumerName }, "Durable event consumer is not available yet; retrying");
+                        await sleep(25);
+                        return ok(undefined);
+                    }
+                    return info;
+                }
+                originalOpened = true;
+                const replayInfo = await (await jetstreamManager(this.#nats)).consumers
+                    .info(binding.replayBinding.stream, binding.replayBinding.consumerName);
+                const consumers = [
+                    this.#js.consumers.getConsumerFromInfo(info),
+                    this.#js.consumers.getConsumerFromInfo(replayInfo),
+                ];
+                let replay = false;
+                while (!this.#durableEventListenersStopped &&
+                    this.#durableEventConsumerGroupReady(group, loop)) {
+                    fetchingReplay = replay;
+                    const messages = await consumers[replay ? 1 : 0].fetch({
+                        max_messages: 1,
+                        expires: 1_000,
+                    });
+                    const isReplay = replay;
+                    replay = !replay;
+                    loop.messages.add(messages);
+                    if (!this.#durableEventConsumerGroupReady(group, loop)) {
+                        messages.stop();
+                        loop.messages.delete(messages);
+                        break;
+                    }
+                    try {
+                        await this.#handleDurableEventConsumer(group, loop, messages, isReplay)
+                            .orThrow();
+                    }
+                    finally {
+                        loop.messages.delete(messages);
+                    }
+                }
+            }
+            catch (cause) {
+                if (this.#durableEventListenersStopped ||
+                    !this.#durableEventConsumerGroupReady(group, loop)) {
+                    return ok(undefined);
+                }
+                if (isConsumerNotFoundError(cause) &&
+                    (fetchingReplay || !originalOpened)) {
+                    this.#log.debug({ group, stream: binding.stream, consumer: binding.consumerName }, "Durable event consumer is not available yet; retrying");
+                    await sleep(25);
+                    return ok(undefined);
+                }
+                await sleep(25);
+                return err(new UnexpectedError({ cause, context: { group } }));
+            }
+            finally {
+                loop.startedWorkers.delete(workerIndex);
+                if (!this.#durableEventListenersStopped) {
+                    this.#startDurableEventConsumer(group, loop);
+                }
+            }
+            return ok(undefined);
+        })());
+    }
+    #handleDurableEventConsumer(group, loop, messages, isReplay = false) {
+        return AsyncResult.try(async () => {
+            const binding = this.#eventConsumers.bindings?.[group];
+            if (!binding) {
+                throw new Error(`Event consumer group '${group}' is unavailable`);
+            }
+            for await (const msg of messages) {
+                let replayEnvelope;
+                let deliveredMessage = msg;
+                if (isReplay) {
+                    const parsedReplayEnvelope = JSON.parse(new TextDecoder().decode(msg.data));
+                    replayEnvelope = parsedReplayEnvelope;
+                    if (parsedReplayEnvelope.resourceId !== binding.resourceId ||
+                        parsedReplayEnvelope.originalRecordSequence <= 0) {
+                        msg.ack();
+                        continue;
+                    }
+                    let inspected;
+                    try {
+                        inspected = await this.#requestConsumerManagement("DeadLetters.Inspect", {
+                            resourceId: binding.resourceId,
+                            deadLetterId: parsedReplayEnvelope.deadLetterId,
+                        });
+                    }
+                    catch (error) {
+                        this.#log.warn({ error, group }, "Replay state inspection unavailable");
+                        const delivery = msg.info.deliveryCount;
+                        msg.nak(binding.backoffMs[Math.min(Math.max(0, delivery - 1), binding.backoffMs.length - 1)] ?? binding.ackWaitMs);
+                        continue;
+                    }
+                    const detail = Reflect.get(inspected, "deadLetter");
+                    const deadLetter = detail && typeof detail === "object"
+                        ? Reflect.get(detail, "deadLetter")
+                        : undefined;
+                    const projectedGeneration = deadLetter && typeof deadLetter === "object"
+                        ? Reflect.get(deadLetter, "generation")
+                        : undefined;
+                    if (typeof projectedGeneration !== "number" ||
+                        projectedGeneration < parsedReplayEnvelope.generation) {
+                        msg.nak(25);
+                        continue;
+                    }
+                    if (projectedGeneration !== parsedReplayEnvelope.generation ||
+                        !["replayPending", "replaying"].includes(Reflect.get(deadLetter, "state"))) {
+                        msg.ack();
+                        continue;
+                    }
+                    const originalHeaders = natsHeaders();
+                    for (const [name, values] of Object.entries(parsedReplayEnvelope.originalHeaders)) {
+                        for (const value of values)
+                            originalHeaders.append(name, value);
+                    }
+                    const data = new Uint8Array(parsedReplayEnvelope.originalPayloadBytes);
+                    deliveredMessage = {
+                        data,
+                        headers: originalHeaders,
+                        subject: parsedReplayEnvelope.originalSubject,
+                        json: () => JSON.parse(new TextDecoder().decode(data)),
+                    };
+                }
+                if (!this.#durableEventConsumerGroupReady(group, loop)) {
+                    messages.stop();
+                    break;
+                }
+                const matching = loop.registrations.filter((registration) => natsSubjectMatches(registration.subject, deliveredMessage.subject));
+                if (matching.length === 0) {
+                    this.#log.warn({ group, subject: msg.subject }, "Durable event consumer received message without registered handler");
+                    msg.nak();
+                    continue;
+                }
+                let failed = false;
+                for (const registration of matching) {
+                    const proofResult = await this.#validateEventProof(registration.event, registration.ctx, deliveredMessage);
+                    const proofValue = proofResult.take();
+                    if (isErr(proofValue)) {
+                        recordRuntimeError(proofValue.error, {
+                            surface: "event",
+                            direction: "consumer",
+                            operation: String(registration.event),
+                            phase: "auth",
+                        });
+                        this.#log.warn({
+                            error: proofValue.error,
+                            event: registration.event,
+                            subject: msg.subject,
+                        }, "Event auth validation failed");
+                        if (proofValue.error instanceof EventVerificationAuthError &&
+                            proofValue.error.retryable) {
+                            const delivery = msg.info.deliveryCount;
+                            msg.nak(binding.backoffMs[Math.min(Math.max(0, delivery - 1), binding.backoffMs.length - 1)] ?? binding.ackWaitMs);
+                        }
+                        else {
+                            if (replayEnvelope) {
+                                try {
+                                    msg.working();
+                                    await this.#reportConsumerDelivery({
+                                        resourceId: binding.resourceId,
+                                        sourceStream: binding.replayBinding.stream,
+                                        sourceSequence: BigInt(msg.info.streamSequence),
+                                        deliveryCount: msg.info.deliveryCount,
+                                        deliveryProof: jetStreamDeliveryProof(msg),
+                                        replayGeneration: replayEnvelope.generation,
+                                        outcome: "unreplayable",
+                                        error: proofValue.error.message,
+                                    });
+                                }
+                                catch (error) {
+                                    this.#log.warn({ error, group }, "Replay delivery report unavailable");
+                                    failed = true;
+                                    break;
+                                }
+                            }
+                            msg.term();
+                        }
+                        failed = true;
+                        break;
+                    }
+                    const parsedEvent = this.#parseEventMessage(registration.event, registration.ctx, deliveredMessage);
+                    const eventPayload = parsedEvent.take();
+                    if (isErr(eventPayload)) {
+                        this.#log.error({ error: eventPayload.error }, "Event validation failed");
+                        recordRuntimeError(eventPayload.error, {
+                            surface: "event",
+                            direction: "consumer",
+                            operation: String(registration.event),
+                            phase: "input_validation",
+                        });
+                        msg.term();
+                        failed = true;
+                        break;
+                    }
+                    const delivery = msg.info.deliveryCount;
+                    const wait = binding.backoffMs[Math.min(Math.max(0, delivery - 1), binding.backoffMs.length - 1)] ?? binding.ackWaitMs;
+                    const progress = setInterval(() => msg.working(), Math.max(1, Math.min(wait - 1, Math.floor(wait / 3))));
+                    const handlerResult = await this.#invokeEventHandler({
+                        event: registration.event,
+                        payload: eventPayload,
+                        mode: "durable",
+                        group,
+                        message: deliveredMessage,
+                        fn: registration.fn,
+                    }).finally(() => clearInterval(progress));
+                    const handlerValue = handlerResult.take();
+                    if (isErr(handlerValue)) {
+                        recordRuntimeError(handlerValue.error, {
+                            surface: "event",
+                            direction: "consumer",
+                            operation: String(registration.event),
+                            phase: "handler_result",
+                        });
+                        this.#log.error({
+                            error: handlerValue.error.toSerializable(),
+                            event: registration.event,
+                            subject: msg.subject,
+                        }, "Event handler failed");
+                        if (delivery >= binding.maxDeliver) {
+                            try {
+                                msg.working();
+                                await this.#reportConsumerDelivery({
+                                    resourceId: binding.resourceId,
+                                    sourceStream: isReplay
+                                        ? binding.replayBinding.stream
+                                        : binding.stream,
+                                    sourceSequence: BigInt(msg.info.streamSequence),
+                                    deliveryCount: delivery,
+                                    deliveryProof: jetStreamDeliveryProof(msg),
+                                    ...(replayEnvelope
+                                        ? { replayGeneration: replayEnvelope.generation }
+                                        : {}),
+                                    outcome: "exhausted",
+                                    error: JSON.stringify(handlerValue.error.toSerializable()),
+                                });
+                                msg.ack();
+                            }
+                            catch (error) {
+                                this.#log.warn({ error, group }, "Delivery report unavailable");
+                            }
+                            failed = true;
+                            break;
+                        }
+                        const delay = binding.backoffMs[Math.min(Math.max(0, delivery - 1), binding.backoffMs.length - 1)] ?? 0;
+                        msg.nak(delay);
+                        failed = true;
+                        break;
+                    }
+                }
+                if (!failed) {
+                    if (replayEnvelope) {
+                        try {
+                            msg.working();
+                            await this.#reportConsumerDelivery({
+                                resourceId: binding.resourceId,
+                                sourceStream: binding.replayBinding.stream,
+                                sourceSequence: BigInt(msg.info.streamSequence),
+                                deliveryCount: msg.info.deliveryCount,
+                                deliveryProof: jetStreamDeliveryProof(msg),
+                                replayGeneration: replayEnvelope.generation,
+                                outcome: "succeeded",
+                            });
+                        }
+                        catch (error) {
+                            this.#log.warn({ error, group }, "Delivery report unavailable");
+                            continue;
+                        }
+                    }
+                    msg.ack();
+                }
+            }
+        });
+    }
+    async #reportConsumerDelivery(input) {
+        await this.#requestConsumerManagement("Consumers.ReportDelivery", input);
+    }
+    async #requestConsumerManagement(method, input) {
+        const binding = this.#apiBindings[EVENTS_API.identity];
+        const providerDeploymentId = binding && typeof binding === "object"
+            ? Reflect.get(binding, "providerDeploymentId")
+            : undefined;
+        const action = method === "Consumers.ReportDelivery"
+            ? EVENTS_API.actions["rpc:Consumers.ReportDelivery"]
+            : method === "DeadLetters.Inspect"
+                ? EVENTS_API.actions["rpc:DeadLetters.Inspect"]
+                : undefined;
+        if (typeof providerDeploymentId !== "string" || !action) {
+            throw new Error(`Consumer management '${method}' is unavailable`);
+        }
+        return await this.#requestBuiltRpc(method, input, {
+            subject: boundApiSubject("rpc", EVENTS_API.identity, providerDeploymentId, method),
+            input: action.input,
+            output: action.output,
+            callerCapabilities: [],
+            errors: action.errors.map((error) => error.type),
+            declaredErrorTypes: action.errors.map((error) => error.type),
+            runtimeErrors: action.errors,
+        }).orThrow();
+    }
+    #parseEventMessage(event, ctx, msg) {
+        const jsonData = Result.try(() => msg.json());
+        const json = jsonData.take();
+        if (isErr(json)) {
+            this.#log.error({ error: json.error, event, subject: msg.subject }, "Event parse failed");
+            return json;
+        }
+        return parseRuntimeSchema(ctx.event, json);
+    }
+    async #validateEventProof(event, descriptor, msg) {
+        return await verifyLocalAuthorization({
+            kind: "event",
+            cache: this.#auth.authorizationProviderCache,
+            message: msg,
+            permission: descriptor.publishPermission,
+            descriptorIdentity: descriptor.descriptorIdentity,
+            requiredCapabilities: descriptor.publishCapabilities,
+        });
+    }
+    wait() {
+        return this.#tasks.wait();
+    }
+    /** Stops durable event listener loops without closing the underlying transport. */
+    stopEventListeners() {
+        this.#durableEventListenersStopped = true;
+        for (const loop of this.#durableEventLoops.values()) {
+            loop.registrations.splice(0, loop.registrations.length);
+            for (const messages of loop.messages)
+                messages.stop();
+        }
+    }
+    // FIXME: If are validating things twice in most cases...
+    template(subject, data, allowWildcards = false) {
+        // Find all template placeholders and check if values exist
+        const placeholders = subject.match(/\{([^}]+)\}/g) || [];
+        for (const placeholder of placeholders) {
+            const key = placeholder.slice(1, -1); // Remove { and }
+            const value = Pointer.Get(data, key);
+            if ((value === undefined || value === null) && !allowWildcards) {
+                return err(new ValidationError({
+                    errors: [
+                        {
+                            path: key,
+                            message: "Missing required data for subject template",
+                        },
+                    ],
+                    context: { key },
+                }));
+            }
+            if (value !== undefined && value !== null && value !== "*" &&
+                (typeof value !== "string" && typeof value !== "number" ||
+                    typeof value === "number" &&
+                        (!Number.isFinite(value) ||
+                            Number.isInteger(value) && !Number.isSafeInteger(value)))) {
+                return err(new ValidationError({
+                    errors: [{
+                            path: key,
+                            message: "Subject template values must be strings or numbers",
+                        }],
+                    context: { key },
+                }));
+            }
+        }
+        const result = subject.replace(/\{([^}]+)\}/g, (_, key) => {
+            const value = Pointer.Get(data, key);
+            if (allowWildcards && value === "*") {
+                return "*";
+            }
+            if (allowWildcards && (value === undefined || value === null)) {
+                return "*";
+            }
+            return this.#encodeSubjectToken(`${Object.is(value, -0) ? 0 : value}`);
+        });
+        return ok(result);
+    }
+    #encodeSubjectToken(token) {
+        return encodeEventSubjectParameterToken(token);
+    }
+    #currentIat() {
+        return this.#auth.currentIat?.() ?? Math.floor(Date.now() / 1000);
+    }
+    #contextDigest() {
+        const digest = typeof this.#auth.contextDigest === "function"
+            ? this.#auth.contextDigest()
+            : this.#auth.contextDigest;
+        if (digest === undefined) {
+            throw new Error("contextDigest is required to sign v1 request and event proofs");
+        }
+        return digest;
+    }
+    /** Creates a context-bound request proof for an exact subject, payload, and reply. */
+    async createRequestProof(subject, payload, reply) {
+        const contextDigest = this.#contextDigest();
+        const payloadBytes = new TextEncoder().encode(payload);
+        const payloadHash = await sha256(payloadBytes);
+        const iat = this.#currentIat();
+        const requestId = ulid();
+        const input = buildProofInput(contextDigest, subject, reply, payloadHash, iat, requestId);
+        const digest = await sha256(input);
+        const sigBytes = await this.#auth.sign(digest);
+        return {
+            proof: base64urlEncode(sigBytes),
+            iat,
+            requestId,
+            contextDigest,
+        };
+    }
+    async #createEventProof(event) {
+        const contextDigest = this.#contextDigest();
+        const payloadHash = await sha256(new TextEncoder().encode(event.encodedPayload));
+        const input = buildEventProofInput(contextDigest, event.descriptorIdentity, event.subject, payloadHash, event.header.id, event.header.time);
+        const digest = await sha256(input);
+        return {
+            proof: base64urlEncode(await this.#auth.sign(digest)),
+            contextDigest,
+        };
+    }
+    async #requestMessageWithRetry(args) {
+        for (let retry = 0; retry <= this.#noResponderMaxRetries; retry++) {
+            if (args.signal?.aborted) {
+                return err(classifyRequestTransportFailure({
+                    method: args.method,
+                    subject: args.subject,
+                    callerCapabilities: args.callerCapabilities,
+                    cause: args.signal.reason ??
+                        new DOMException("Request aborted", "AbortError"),
+                }));
+            }
+            if (this.#nats.isClosed()) {
+                return err(requestFailedTransportError({
+                    code: "trellis.request.closed",
+                    message: "The Trellis connection is closed.",
+                    hint: "Connect to Trellis again before making another request.",
+                    method: args.method,
+                    subject: args.subject,
+                }));
+            }
+            // Create the exact reply inbox before signing so the proof binds the
+            // reply subject the response arrives on.
+            const reply = createInbox(this.#inboxPrefix);
+            const authHeaders = await this.createRequestProof(args.subject, args.payload, reply);
+            const headers = natsHeaders();
+            headers.set("authorization-context", authHeaders.contextDigest);
+            headers.set("session-key", this.#auth.sessionKey);
+            headers.set("proof", authHeaders.proof);
+            headers.set("iat", String(authHeaders.iat));
+            headers.set("request-id", authHeaders.requestId);
+            injectTraceContext(createNatsHeaderCarrier(headers), args.span);
+            const result = await AsyncResult.try(async () => {
+                const response = Promise.withResolvers();
+                const abort = () => response.reject(args.signal?.reason ??
+                    new DOMException("Request aborted", "AbortError"));
+                args.signal?.addEventListener("abort", abort, { once: true });
+                const subscription = this.#nats.subscribe(reply, {
+                    max: 1,
+                    timeout: args.timeout,
+                    callback: (error, message) => {
+                        if (error)
+                            response.reject(error);
+                        else if (message.data.length === 0 && message.headers?.code === 503) {
+                            response.reject(new Error("no responders"));
+                        }
+                        else
+                            response.resolve(message);
+                    },
+                });
+                // NATS noMux requests abandon their promise when connection closure
+                // cancels the subscription timer. Bind settlement to this subscription.
+                subscription.closed.then((error) => {
+                    response.reject(error ?? new Error("connection closed before RPC response"));
+                });
+                const initialStatus = this.connection.status;
+                const stopObserving = this.connection.subscribe((status) => {
+                    // Publish denials arrive on the connection, not the reply inbox.
+                    if (status === initialStatus)
+                        return;
+                    const error = status.transport?.error;
+                    if (error instanceof Error &&
+                        ((error.name === "PermissionViolationError" &&
+                            Reflect.get(error, "operation") === "publish" &&
+                            Reflect.get(error, "subject") === args.subject) ||
+                            error.name === "AuthorizationError" ||
+                            error.name === "UserAuthenticationExpiredError"))
+                        response.reject(error);
+                });
+                try {
+                    if (args.signal?.aborted) {
+                        abort();
+                    }
+                    else {
+                        this.#nats.publish(args.subject, args.payload, {
+                            headers,
+                            reply,
+                        });
+                    }
+                    return await response.promise;
+                }
+                finally {
+                    args.signal?.removeEventListener("abort", abort);
+                    stopObserving();
+                    subscription.unsubscribe();
+                }
+            });
+            if (result.isOk()) {
+                return ok(result.take());
+            }
+            const cause = result.error.cause;
+            const message = cause instanceof Error ? cause.message : String(cause);
+            const isNoResponders = message.includes("no responders");
+            if (isNoResponders && retry < this.#noResponderMaxRetries) {
+                this.#log.debug({ method: args.method, subject: args.subject, retry }, "No responders, retrying...");
+                await new Promise((resolve) => {
+                    const done = () => {
+                        clearTimeout(timeout);
+                        args.signal?.removeEventListener("abort", done);
+                        resolve();
+                    };
+                    const timeout = setTimeout(done, this.#noResponderRetryMs * (retry + 1));
+                    args.signal?.addEventListener("abort", done, { once: true });
+                });
+                continue;
+            }
+            this.#log.warn({ method: args.method, subject: args.subject, error: message }, "NATS request failed");
+            return err(classifyRequestTransportFailure({
+                method: args.method,
+                subject: args.subject,
+                callerCapabilities: args.callerCapabilities,
+                cause,
+            }));
+        }
+        return err(requestFailedTransportError({
+            code: "trellis.request.retry_exhausted",
+            message: "Trellis could not complete the request after retrying.",
+            hint: "Retry the request. If it keeps failing, check that the target service is available.",
+            method: args.method,
+            subject: args.subject,
+            context: { retries: this.#noResponderMaxRetries + 1 },
+        }));
+    }
+    #requestJson(subject, body) {
+        return AsyncResult.from((async () => {
+            const span = startClientSpan(subject, subject);
+            return await withSpanAsync(span, async () => {
+                try {
+                    const payload = JSON.stringify(body);
+                    const response = (await this.#requestMessageWithRetry({
+                        subject,
+                        payload,
+                        timeout: this.timeout,
+                        span,
+                    })).take();
+                    if (isErr(response)) {
+                        span.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: response.error.message,
+                        });
+                        recordRuntimeError(response.error, {
+                            surface: "operation",
+                            direction: "client",
+                            operation: "requestJson",
+                            phase: "request_send",
+                        });
+                        return response;
+                    }
+                    const json = safeJson(response).take();
+                    if (isErr(json)) {
+                        const error = createTransportError({
+                            code: "trellis.request.invalid_response",
+                            message: "Trellis returned an invalid response.",
+                            hint: "Retry the request. If it keeps happening, reconnect to Trellis and try again.",
+                            cause: json.error.cause,
+                            context: { subject },
+                        });
+                        span.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: error.message,
+                        });
+                        recordRuntimeError(error, {
+                            surface: "operation",
+                            direction: "client",
+                            operation: "requestJson",
+                            phase: "response_decoding",
+                        });
+                        return err(error);
+                    }
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    return ok(json);
+                }
+                catch (cause) {
+                    const error = new UnexpectedError({ cause });
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                    span.recordException(error);
+                    recordRuntimeError(error, {
+                        surface: "operation",
+                        direction: "client",
+                        operation: "requestJson",
+                        phase: "unexpected",
+                    });
+                    return err(error);
+                }
+                finally {
+                    span.end();
+                }
+            });
+        })());
+    }
+    #watchJson(subject, body) {
+        return AsyncResult.from((async () => {
+            const payload = JSON.stringify(body);
+            const inbox = createInbox(this.#inboxPrefix);
+            const authHeaders = await this.createRequestProof(subject, payload, inbox);
+            const headers = natsHeaders();
+            headers.set("proof", authHeaders.proof);
+            headers.set("iat", String(authHeaders.iat));
+            headers.set("request-id", authHeaders.requestId);
+            headers.set("authorization-context", authHeaders.contextDigest);
+            headers.set("session-key", this.#auth.sessionKey);
+            const sub = this.#nats.subscribe(inbox);
+            try {
+                this.#nats.publish(subject, payload, {
+                    headers,
+                    reply: inbox,
+                });
+            }
+            catch (cause) {
+                sub.unsubscribe();
+                const error = createTransportError({
+                    code: "trellis.watch.failed",
+                    message: "Trellis could not start the operation watch.",
+                    hint: "Retry watching the operation. If it keeps failing, reconnect to Trellis and try again.",
+                    cause,
+                    context: { subject },
+                });
+                recordRuntimeError(error, {
+                    surface: "operation",
+                    direction: "client",
+                    operation: "watchJson",
+                    phase: "request_send",
+                });
+                return err(error);
+            }
+            const iterator = sub[Symbol.asyncIterator]();
+            let timer;
+            let first;
+            try {
+                first = await Promise.race([
+                    iterator.next(),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error("operation watch setup timed out")), this.timeout);
+                    }),
+                ]);
+            }
+            catch (cause) {
+                sub.unsubscribe();
+                const error = createTransportError({
+                    code: "trellis.watch.failed",
+                    message: "Trellis could not start the operation watch.",
+                    hint: "Retry watching the operation. If it keeps failing, reconnect to Trellis and try again.",
+                    cause,
+                    context: { subject },
+                });
+                recordRuntimeError(error, {
+                    surface: "operation",
+                    direction: "client",
+                    operation: "watchJson",
+                    phase: "response_wait",
+                });
+                return err(error);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+            return ok((async function* () {
+                try {
+                    let next = first;
+                    while (!next.done) {
+                        const msg = next.value;
+                        if (msg.headers?.get("status") === "error") {
+                            const error = createTransportError({
+                                code: "trellis.watch.failed",
+                                message: "Trellis stopped the operation watch.",
+                                hint: "Retry watching the operation. If it keeps happening, reconnect to Trellis and try again.",
+                                context: { subject, frame: msg.string() },
+                            });
+                            recordRuntimeError(error, {
+                                surface: "operation",
+                                direction: "client",
+                                operation: "watchJson",
+                                phase: "remote_error",
+                            });
+                            yield err(error);
+                            next = await iterator.next();
+                            continue;
+                        }
+                        const json = safeJson(msg).take();
+                        if (isErr(json)) {
+                            const error = createTransportError({
+                                code: "trellis.watch.invalid_response",
+                                message: "Trellis returned an invalid watch update.",
+                                hint: "Retry watching the operation. If it keeps happening, reconnect to Trellis and try again.",
+                                cause: json.error.cause,
+                                context: { subject },
+                            });
+                            recordRuntimeError(error, {
+                                surface: "operation",
+                                direction: "client",
+                                operation: "watchJson",
+                                phase: "response_decoding",
+                            });
+                            yield err(error);
+                            next = await iterator.next();
+                            continue;
+                        }
+                        yield ok(json);
+                        next = await iterator.next();
+                    }
+                }
+                finally {
+                    await iterator.return?.();
+                    sub.unsubscribe();
+                }
+            })());
+        })());
+    }
+}