@qlever-llc/trellis 0.7.0-rc.5 → 0.7.0

package/esm/trellis.js

@@ -0,0 +1,1049 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Trellis_instances, _Trellis_log, _Trellis_tasks, _Trellis_hasExplicitApi, _Trellis_noResponderMaxRetries, _Trellis_noResponderRetryMs, _Trellis_authBypassMethods, _Trellis_operationStore, _Trellis_unknownApiError, _Trellis_handleRPC, _Trellis_processRPCMessage, _Trellis_respondWithError, _Trellis_startEphemeralEvent, _Trellis_handleDurableEvent, _Trellis_parseEventMessage, _Trellis_escapeSubjectToken, _Trellis_createProof, _Trellis_requestJson, _Trellis_watchJson;
+import { jetstream, jetstreamManager, } from "@nats-io/jetstream";
+import { createInbox, headers as natsHeaders, } from "@nats-io/nats-core";
+import { AsyncResult, BaseError, err, isErr, ok, Result, } from "@qlever-llc/result";
+import { createNatsHeaderCarrier, extractTraceContext, injectTraceContext, SpanStatusCode, startClientSpan, startServerSpan, withSpanAsync, } from "./tracing.js";
+import { Type } from "typebox";
+import { Pointer } from "typebox/value";
+import { ulid } from "ulid";
+import { encodeSchema, parse, parseUnknownSchema, } from "./codec.js";
+import { TransferError, AuthError, getBuiltinRpcError, 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 "./models/trellis/TrellisError.js";
+import { OperationInvoker, } from "./operations.js";
+import { createTransferHandle, } from "./transfer.js";
+import { TrellisTasks } from "./tasks.js";
+/**
+ * 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 encodeRuntimeSchema(schema, data) {
+    return encodeSchema(schema, data);
+}
+function parseRuntimeSchema(schema, data) {
+    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(sessionKey, subject, payloadHash) {
+    const enc = new TextEncoder();
+    const sessionKeyBytes = enc.encode(sessionKey);
+    const subjectBytes = enc.encode(subject);
+    const buf = new Uint8Array(4 +
+        sessionKeyBytes.length +
+        4 +
+        subjectBytes.length +
+        4 +
+        payloadHash.length);
+    const view = new DataView(buf.buffer);
+    let offset = 0;
+    view.setUint32(offset, sessionKeyBytes.length);
+    offset += 4;
+    buf.set(sessionKeyBytes, offset);
+    offset += sessionKeyBytes.length;
+    view.setUint32(offset, subjectBytes.length);
+    offset += 4;
+    buf.set(subjectBytes, offset);
+    offset += subjectBytes.length;
+    view.setUint32(offset, payloadHash.length);
+    offset += 4;
+    buf.set(payloadHash, offset);
+    return buf;
+}
+export function isResultLike(value) {
+    return value instanceof Result;
+}
+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({
+        type: Type.String(),
+        message: Type.String(),
+    })),
+});
+export const DurableOperationRecordSchema = Type.Object({
+    ownerSessionKey: Type.String(),
+    sequence: Type.Number(),
+    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 NATS_SUBJECT_TOKEN_FORBIDDEN = /[\u0000\s.*>~]/gu;
+const DEFAULT_NO_RESPONDER_MAX_RETRIES = 2;
+const DEFAULT_NO_RESPONDER_RETRY_MS = 200;
+const DEFAULT_AUTH_VALIDATE_SESSION_RETRY_ATTEMPTS = 3;
+const DEFAULT_AUTH_VALIDATE_SESSION_RETRY_MS = 25;
+const EMPTY_TRELLIS_API = {
+    rpc: {},
+    operations: {},
+    events: {},
+    subjects: {},
+};
+function isTransientAuthValidateSessionError(error) {
+    if (error instanceof AuthError) {
+        return error.reason === "session_not_found";
+    }
+    if (error instanceof RemoteError &&
+        error.remoteError.type === "AuthError") {
+        const reason = Reflect.get(error.remoteError, "reason");
+        return typeof reason === "string" && reason === "session_not_found";
+    }
+    return false;
+}
+function isDeclaredRpcError(errorNames, type) {
+    return !!errorNames?.includes(type);
+}
+function isRuntimeRpcErrorDesc(value) {
+    return !!value && typeof value === "object" &&
+        typeof Reflect.get(value, "type") === "string" &&
+        typeof Reflect.get(value, "fromSerializable") === "function";
+}
+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 {
+    constructor(name, // Must be unique for a service
+    nats, auth, opts) {
+        _Trellis_instances.add(this);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "timeout", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "stream", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "nats", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "js", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "auth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "api", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        _Trellis_log.set(this, void 0);
+        _Trellis_tasks.set(this, void 0);
+        _Trellis_hasExplicitApi.set(this, void 0);
+        _Trellis_noResponderMaxRetries.set(this, void 0);
+        _Trellis_noResponderRetryMs.set(this, void 0);
+        _Trellis_authBypassMethods.set(this, void 0);
+        _Trellis_operationStore.set(this, void 0);
+        const api = opts?.api;
+        this.name = name;
+        this.nats = nats;
+        this.js = jetstream(this.nats);
+        this.auth = auth;
+        this.api = (api ?? EMPTY_TRELLIS_API);
+        __classPrivateFieldSet(this, _Trellis_log, (opts?.log ?? logger).child({ lib: "trellis" }), "f");
+        this.timeout = opts?.timeout ?? 3000;
+        this.stream = opts?.stream ?? "trellis";
+        __classPrivateFieldSet(this, _Trellis_hasExplicitApi, api !== undefined, "f");
+        __classPrivateFieldSet(this, _Trellis_noResponderMaxRetries, opts?.noResponderRetry?.maxAttempts ??
+            DEFAULT_NO_RESPONDER_MAX_RETRIES, "f");
+        __classPrivateFieldSet(this, _Trellis_noResponderRetryMs, opts?.noResponderRetry?.baseDelayMs ??
+            DEFAULT_NO_RESPONDER_RETRY_MS, "f");
+        __classPrivateFieldSet(this, _Trellis_authBypassMethods, new Set(opts?.authBypassMethods ?? []), "f");
+        __classPrivateFieldSet(this, _Trellis_tasks, new TrellisTasks({ log: __classPrivateFieldGet(this, _Trellis_log, "f") }), "f");
+    }
+    /**
+     * Returns the underlying NATS connection.
+     */
+    get natsConnection() {
+        return this.nats;
+    }
+    async operationStoreHandle() {
+        if (!__classPrivateFieldGet(this, _Trellis_operationStore, "f")) {
+            const bucket = `trellis_operations_${this.auth.sessionKey.slice(0, 16)}`;
+            __classPrivateFieldSet(this, _Trellis_operationStore, (async () => {
+                const result = await TypedKV.open(this.nats, bucket, DurableOperationRecordSchema, {
+                    history: 5,
+                    ttl: 0,
+                });
+                const value = result.take();
+                if (isErr(value)) {
+                    throw value.error;
+                }
+                return value;
+            })(), "f");
+        }
+        return __classPrivateFieldGet(this, _Trellis_operationStore, "f");
+    }
+    async loadOperationRecord(operationId) {
+        const store = await this.operationStoreHandle();
+        const entry = await store.get(operationId);
+        const value = entry.take();
+        if (isErr(value)) {
+            return null;
+        }
+        return value.value;
+    }
+    async saveOperationRecord(runtime) {
+        const store = await this.operationStoreHandle();
+        const record = {
+            ownerSessionKey: runtime.ownerSessionKey,
+            sequence: runtime.sequence,
+            snapshot: runtime.snapshot,
+        };
+        await store.put(runtime.id, record);
+    }
+    /**
+     * Makes an authenticated request to a Trellis RPC method.
+     *
+     * @template M The specific RPC method being called.
+     * @param method The name of the RPC method to call.
+     * @param input The input data for the method, conforming to its schema.
+     * @param opts Optional request-specific options.
+     * @returns A promise that resolves with a `Result` containing either the method's
+     * output or an error.
+     * @returns A `Result` object:
+     *              ok: A validated reponse of method M
+     *              err: declared RPC errors | RemoteError | ValidationError | UnexpectedError
+     */
+    async request(method, input, opts) {
+        __classPrivateFieldGet(this, _Trellis_log, "f").trace({ method: String(method) }, `Calling ${method.toString()}.`);
+        const methodName = method;
+        const ctx = this.api["rpc"][methodName];
+        if (!ctx) {
+            return err(new UnexpectedError({
+                cause: __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_unknownApiError).call(this, "RPC method", method.toString()),
+                context: { method: method.toString() },
+            }));
+        }
+        const msg = encodeRuntimeSchema(ctx.input, input).take();
+        if (isErr(msg)) {
+            return msg;
+        }
+        const subject = this.template(ctx.subject, input).take();
+        if (isErr(subject)) {
+            return subject;
+        }
+        // Start a client span for this RPC request
+        const span = startClientSpan(method, subject);
+        const attempt = async () => {
+            const proof = await __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_createProof).call(this, subject, msg);
+            const headers = natsHeaders();
+            headers.set("session-key", this.auth.sessionKey);
+            headers.set("proof", proof);
+            // Inject trace context into NATS headers for propagation
+            injectTraceContext(createNatsHeaderCarrier(headers), span);
+            // Attempt request with retry for transient "no responders" errors
+            const requestWithRetry = async () => {
+                for (let retry = 0; retry <= __classPrivateFieldGet(this, _Trellis_noResponderMaxRetries, "f"); retry++) {
+                    const result = await AsyncResult.try(() => this.nats.request(subject, msg, {
+                        headers,
+                        timeout: opts?.timeout ?? this.timeout,
+                    }));
+                    if (result.isOk()) {
+                        return ok((await result).take());
+                    }
+                    const cause = result.error.cause;
+                    const message = cause instanceof Error
+                        ? cause.message
+                        : String(cause);
+                    const isNoResponders = message.includes("no responders");
+                    // If it's a no-responders error and we have retries left, retry
+                    if (isNoResponders && retry < __classPrivateFieldGet(this, _Trellis_noResponderMaxRetries, "f")) {
+                        __classPrivateFieldGet(this, _Trellis_log, "f").debug({ method, subject, retry }, "No responders, retrying...");
+                        await new Promise((r) => setTimeout(r, __classPrivateFieldGet(this, _Trellis_noResponderRetryMs, "f") * (retry + 1)));
+                        continue;
+                    }
+                    // Final attempt failed or non-retryable error
+                    __classPrivateFieldGet(this, _Trellis_log, "f").warn({ method, subject, error: message }, "NATS request failed");
+                    const isNatsPermission = message.includes("Permissions Violation");
+                    const reason = isNatsPermission
+                        ? `Permission denied. You need one of these capabilities: ${ctx.callerCapabilities.join(", ")}`
+                        : message;
+                    return err(new UnexpectedError({
+                        cause,
+                        context: {
+                            method,
+                            subject,
+                            reason,
+                            requiredCapabilities: ctx.callerCapabilities,
+                            noResponders: isNoResponders,
+                        },
+                    }));
+                }
+                // Should be unreachable, but TypeScript needs explicit return
+                return err(new UnexpectedError({
+                    context: { method, subject, reason: "retry loop exhausted" },
+                }));
+            };
+            const msgResult = await requestWithRetry();
+            const m = msgResult.take();
+            if (isErr(m)) {
+                return m;
+            }
+            if (m.headers?.get("status") === "error") {
+                const json = safeJson(m).take();
+                if (isErr(json)) {
+                    return json;
+                }
+                const errorData = parse(TrellisErrorDataSchema, json).take();
+                if (isErr(errorData)) {
+                    return errorData;
+                }
+                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) {
+                    return err(reconstructed);
+                }
+                return err(new RemoteError({ error: errorData }));
+            }
+            const json = safeJson(m).take();
+            if (isErr(json)) {
+                return json;
+            }
+            const outputResult = parseRuntimeSchema(ctx.output, json).take();
+            if (isErr(outputResult)) {
+                return err(outputResult.error);
+            }
+            return ok(outputResult);
+        };
+        return 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 = new UnexpectedError({ cause });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: unexpected.message,
+                });
+                span.recordException(unexpected);
+                return err(unexpected);
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    async requestOrThrow(method, input, opts) {
+        const result = await this.request(method, input, opts);
+        const value = result.take();
+        if (isErr(value)) {
+            throw value.error;
+        }
+        return value;
+    }
+    operation(operation) {
+        const descriptor = this.api["operations"]?.[operation];
+        if (!descriptor) {
+            throw __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_unknownApiError).call(this, "operation", operation.toString());
+        }
+        const transport = {
+            requestJson: (subject, body) => __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_requestJson).call(this, subject, body),
+            watchJson: (subject, body) => __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_watchJson).call(this, subject, body),
+            putTransfer: async (grant, body) => {
+                const handle = createTransferHandle(this.nats, this.auth, this.timeout, grant);
+                if (!(handle instanceof Object) || !("put" in handle)) {
+                    return err(new TransferError({
+                        operation: "transfer",
+                        context: { reason: "invalid_operation_transfer_grant" },
+                    }));
+                }
+                return await handle.put(body);
+            },
+        };
+        return new OperationInvoker(transport, descriptor);
+    }
+    /*
+     * 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 __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_unknownApiError).call(this, "RPC method", method.toString());
+        }
+        const task = __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_handleRPC).call(this, methodName, fn);
+        __classPrivateFieldGet(this, _Trellis_tasks, "f").add(methodName, task);
+    }
+    respondWithError(msg, error) {
+        __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_respondWithError).call(this, msg, error);
+    }
+    async publish(event, data) {
+        const eventName = event;
+        const ctx = this.api["events"][eventName];
+        if (!ctx) {
+            return err(new UnexpectedError({
+                cause: __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_unknownApiError).call(this, "event", event.toString()),
+                context: { event: event.toString() },
+            }));
+        }
+        const subject = this.template(ctx.subject, data).take();
+        if (isErr(subject)) {
+            logger.error({ err: subject.error }, "Failed to template event.");
+            return subject;
+        }
+        const payload = {
+            ...data,
+            header: {
+                id: ulid(),
+                time: new Date().toISOString(),
+            },
+        };
+        const msg = encodeSchema(ctx.event, payload).take();
+        if (isErr(msg)) {
+            logger.error({ err: msg.error }, "Failed to encode event.");
+            return err(new UnexpectedError({ cause: msg.error }));
+        }
+        logger.trace({ subject }, `Publishing ${event.toString()} event.`);
+        await this.js.publish(subject, msg);
+        return ok(undefined);
+    }
+    async event(event, subjectData, fn, opts) {
+        const eventName = event;
+        const ctx = this.api["events"][eventName];
+        if (!ctx) {
+            return err(new UnexpectedError({
+                cause: __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_unknownApiError).call(this, "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 __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_startEphemeralEvent).call(this, eventName, ctx, subject, fn, opts.signal);
+        }
+        const jsm = await jetstreamManager(this.nats);
+        const consumerName = opts?.durableName ??
+            `${this.name}-${event.replaceAll(".", "_")}`;
+        const addResult = await AsyncResult.try(() => jsm.consumers.add(this.stream, {
+            durable_name: consumerName,
+            ack_policy: "explicit",
+            deliver_policy: opts?.replay === "new" ? "new" : "all",
+            filter_subjects: [subject],
+        }));
+        // If add failed (consumer already exists), try to get existing consumer info
+        const consumerInfoResult = addResult.isOk()
+            ? addResult
+            : await AsyncResult.try(() => jsm.consumers.info(this.stream, consumerName));
+        const info = consumerInfoResult.take();
+        if (isErr(info))
+            return info;
+        const consumer = this.js.consumers.getConsumerFromInfo(info);
+        const messages = await consumer.consume();
+        if (opts?.signal) {
+            if (opts.signal.aborted) {
+                messages.stop();
+            }
+            else {
+                opts.signal.addEventListener("abort", () => messages.stop(), {
+                    once: true,
+                });
+            }
+        }
+        __classPrivateFieldGet(this, _Trellis_tasks, "f").add(`event:${eventName}:${ulid()}`, __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_handleDurableEvent).call(this, eventName, ctx, messages, fn));
+        return ok(undefined);
+    }
+    wait() {
+        return __classPrivateFieldGet(this, _Trellis_tasks, "f").wait();
+    }
+    // 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 },
+                }));
+            }
+        }
+        const result = subject.replace(/\{([^}]+)\}/g, (_, key) => {
+            const value = Pointer.Get(data, key);
+            if (allowWildcards && value === "*") {
+                return "*";
+            }
+            if (allowWildcards && (value === undefined || value === null)) {
+                return "*";
+            }
+            return __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_escapeSubjectToken).call(this, `${value}`);
+        });
+        return ok(result);
+    }
+    async requestAuthValidate(input) {
+        const request = this.request.bind(this);
+        const result = await request("Auth.ValidateRequest", input);
+        return result;
+    }
+}
+_Trellis_log = new WeakMap(), _Trellis_tasks = new WeakMap(), _Trellis_hasExplicitApi = new WeakMap(), _Trellis_noResponderMaxRetries = new WeakMap(), _Trellis_noResponderRetryMs = new WeakMap(), _Trellis_authBypassMethods = new WeakMap(), _Trellis_operationStore = new WeakMap(), _Trellis_instances = new WeakSet(), _Trellis_unknownApiError = function _Trellis_unknownApiError(kind, name) {
+    const base = `Unknown ${kind} '${name}'.`;
+    if (__classPrivateFieldGet(this, _Trellis_hasExplicitApi, "f")) {
+        return new Error(`${base} Did you forget to include its API module?`);
+    }
+    return new Error(`${base} No API surface was provided. Pass opts.api, use createClient(contract, ...), or await createCoreClient(...) instead.`);
+}, _Trellis_handleRPC = function _Trellis_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;
+    __classPrivateFieldGet(this, _Trellis_log, "f").info({ method: String(method) }, `Mounting ${method.toString()} RPC handler`);
+    const sub = this.nats.subscribe(subject);
+    return AsyncResult.try(async () => {
+        for await (const msg of sub) {
+            const resultPromise = await __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_processRPCMessage).call(this, method, ctx, msg, fn, handlerTrellis);
+            const result = resultPromise.take();
+            if (isErr(result)) {
+                __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_respondWithError).call(this, msg, result.error);
+                continue;
+            }
+            msg.respond(result);
+        }
+    });
+}, _Trellis_processRPCMessage = async function _Trellis_processRPCMessage(method, ctx, msg, fn, handlerTrellis) {
+    __classPrivateFieldGet(this, _Trellis_log, "f").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);
+    // Execute the handler within the span's context
+    return withSpanAsync(span, async () => {
+        const execute = async () => {
+            const jsonData = safeJson(msg).take();
+            if (isErr(jsonData)) {
+                __classPrivateFieldGet(this, _Trellis_log, "f").warn({ method, error: jsonData.error.message }, "Failed to parse JSON");
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: "Failed to parse JSON",
+                });
+                return jsonData;
+            }
+            const parsedInput = parseRuntimeSchema(ctx.input, jsonData).take();
+            if (isErr(parsedInput)) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: "Input validation failed",
+                });
+                return parsedInput;
+            }
+            let caller;
+            const callerSessionKey = msg.headers?.get("session-key") ?? "";
+            const authRequired = ctx.authRequired ?? true;
+            if (!authRequired || __classPrivateFieldGet(this, _Trellis_authBypassMethods, "f").has(method)) {
+                caller = {
+                    type: "service",
+                    id: "system",
+                    active: true,
+                    name: "System",
+                    capabilities: ["service"],
+                };
+            }
+            else {
+                const sessionKey = msg.headers?.get("session-key");
+                const proof = msg.headers?.get("proof");
+                if (!sessionKey) {
+                    __classPrivateFieldGet(this, _Trellis_log, "f").warn({ method }, "Missing session-key header");
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Missing session-key",
+                    });
+                    return err(new AuthError({ reason: "missing_session_key" }));
+                }
+                if (!proof) {
+                    __classPrivateFieldGet(this, _Trellis_log, "f").warn({ method }, "Missing proof in request");
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Missing proof",
+                    });
+                    return err(new AuthError({ reason: "missing_proof" }));
+                }
+                // Verify proof signature locally using the raw request bytes we received.
+                const payloadBytes = msg.data ?? new Uint8Array();
+                const payloadHash = await sha256(payloadBytes);
+                const proofInput = buildProofInput(sessionKey, msg.subject, payloadHash);
+                const digest = await sha256(proofInput);
+                const verifyResult = await AsyncResult.try(async () => {
+                    const publicKeyRaw = base64urlDecode(sessionKey);
+                    const pub = await crypto.subtle.importKey("raw", toArrayBuffer(publicKeyRaw), { name: "Ed25519" }, true, ["verify"]);
+                    return crypto.subtle.verify({ name: "Ed25519" }, pub, toArrayBuffer(base64urlDecode(proof)), toArrayBuffer(digest));
+                });
+                const signatureOk = verifyResult.isOk() &&
+                    (await verifyResult).take() === true;
+                if (!signatureOk) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Invalid signature",
+                    });
+                    return err(new AuthError({
+                        reason: "invalid_signature",
+                        context: { sessionKey },
+                    }));
+                }
+                let auth;
+                for (let attempt = 0; attempt < DEFAULT_AUTH_VALIDATE_SESSION_RETRY_ATTEMPTS; attempt++) {
+                    const authResult = await this.requestAuthValidate({
+                        sessionKey,
+                        proof,
+                        subject: msg.subject,
+                        payloadHash: base64urlEncode(payloadHash),
+                        capabilities: [...ctx.callerCapabilities],
+                    });
+                    const authValue = authResult.take();
+                    if (!isErr(authValue)) {
+                        auth = authValue;
+                        break;
+                    }
+                    const authError = authValue.error;
+                    if (!isTransientAuthValidateSessionError(authError) ||
+                        attempt === DEFAULT_AUTH_VALIDATE_SESSION_RETRY_ATTEMPTS - 1) {
+                        auth = authError;
+                        break;
+                    }
+                    await sleep(DEFAULT_AUTH_VALIDATE_SESSION_RETRY_MS * (attempt + 1));
+                }
+                if (!auth) {
+                    return err(new UnexpectedError({
+                        context: { reason: "missing_auth_validate_result" },
+                    }));
+                }
+                if (auth instanceof Error) {
+                    __classPrivateFieldGet(this, _Trellis_log, "f").warn({
+                        method,
+                        error: auth.message,
+                        errorType: auth.name,
+                        remoteError: auth instanceof RemoteError
+                            ? auth.toSerializable()
+                            : undefined,
+                    }, "Auth.ValidateRequest failed");
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Auth.ValidateRequest failed",
+                    });
+                    if (auth instanceof BaseError) {
+                        return err(auth);
+                    }
+                    return err(new UnexpectedError({ cause: auth }));
+                }
+                if (!auth.allowed) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Insufficient permissions",
+                    });
+                    return err(new AuthError({
+                        reason: "insufficient_permissions",
+                        context: {
+                            requiredCapabilities: ctx.callerCapabilities,
+                            userCapabilities: auth.caller.capabilities,
+                        },
+                    }));
+                }
+                if (typeof msg.reply !== "string" ||
+                    !msg.reply.startsWith(`${auth.inboxPrefix}.`)) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Reply subject mismatch",
+                    });
+                    return err(new AuthError({
+                        reason: "reply_subject_mismatch",
+                        context: { expected: auth.inboxPrefix, actual: msg.reply },
+                    }));
+                }
+                caller = auth.caller;
+            }
+            span.setAttribute("auth.caller.type", caller.type);
+            if (caller.type === "user") {
+                span.setAttribute("user.id", caller.id);
+                span.setAttribute("user.origin", caller.origin);
+            }
+            if (caller.type === "service") {
+                span.setAttribute("service.id", caller.id);
+            }
+            if (caller.type === "device") {
+                span.setAttribute("device.id", caller.deviceId);
+                span.setAttribute("device.profile_id", caller.profileId);
+            }
+            const invokeHandler = fn;
+            const handlerResultWrapped = await AsyncResult.try(async () => await Promise.resolve(invokeHandler(parsedInput, {
+                caller,
+                sessionKey: callerSessionKey,
+            }, handlerTrellis)));
+            if (handlerResultWrapped.isErr()) {
+                const error = handlerResultWrapped.error.withContext({ method });
+                __classPrivateFieldGet(this, _Trellis_log, "f").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);
+                return err(error);
+            }
+            const handlerResult = (await handlerResultWrapped).take();
+            const handlerOutcome = handlerResult.take();
+            if (isErr(handlerOutcome)) {
+                const handlerError = handlerOutcome.error;
+                const error = handlerError instanceof BaseError &&
+                    !(handlerError instanceof RemoteError)
+                    ? handlerError
+                    : new UnexpectedError({ cause: handlerError });
+                __classPrivateFieldGet(this, _Trellis_log, "f").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,
+                });
+                return err(error);
+            }
+            const encoded = encodeSchema(ctx.output, handlerOutcome).take();
+            if (isErr(encoded)) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: "Output encoding failed",
+                });
+                return encoded;
+            }
+            span.setStatus({ code: SpanStatusCode.OK });
+            return ok(encoded);
+        };
+        const result = await execute();
+        span.end();
+        return result;
+    });
+}, _Trellis_respondWithError = function _Trellis_respondWithError(msg, error) {
+    const trellisError = error instanceof BaseError &&
+        !(error instanceof RemoteError)
+        ? error
+        : new UnexpectedError({ cause: error });
+    __classPrivateFieldGet(this, _Trellis_log, "f").error({ 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()) {
+        __classPrivateFieldGet(this, _Trellis_log, "f").error({ error: serialized.error }, "Failed to serialize error response");
+        msg.respond('{"type":"UnexpectedError","message":"Failed to serialize error"}', { headers: hdrs });
+        return;
+    }
+    msg.respond(serialized.take(), { headers: hdrs });
+}, _Trellis_startEphemeralEvent = function _Trellis_startEphemeralEvent(event, ctx, subject, fn, signal) {
+    const sub = this.nats.subscribe(subject);
+    if (signal) {
+        if (signal.aborted) {
+            sub.unsubscribe();
+            return ok(undefined);
+        }
+        signal.addEventListener("abort", () => sub.unsubscribe(), { once: true });
+    }
+    const task = AsyncResult.try(async () => {
+        for await (const msg of sub) {
+            const parsedEvent = __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_parseEventMessage).call(this, event, ctx, msg);
+            const m = parsedEvent.take();
+            if (isErr(m)) {
+                __classPrivateFieldGet(this, _Trellis_log, "f").error({ error: m.error }, "Event validation failed");
+                continue;
+            }
+            const handlerResult = await AsyncResult.lift(fn(m));
+            if (handlerResult.isErr()) {
+                __classPrivateFieldGet(this, _Trellis_log, "f").error({
+                    error: handlerResult.error.toSerializable(),
+                    event,
+                    subject: msg.subject,
+                }, "Event handler failed");
+            }
+        }
+    });
+    __classPrivateFieldGet(this, _Trellis_tasks, "f").add(`event:${event}:${ulid()}`, task);
+    return ok(undefined);
+}, _Trellis_handleDurableEvent = function _Trellis_handleDurableEvent(event, ctx, messages, fn) {
+    return AsyncResult.try(async () => {
+        for await (const msg of messages) {
+            const parsedEvent = __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_parseEventMessage).call(this, event, ctx, msg);
+            const m = parsedEvent.take();
+            if (isErr(m)) {
+                __classPrivateFieldGet(this, _Trellis_log, "f").error({ error: m.error }, "Event validation failed");
+                msg.term();
+                continue;
+            }
+            const handlerResult = await AsyncResult.lift(fn(m));
+            if (handlerResult.isErr()) {
+                __classPrivateFieldGet(this, _Trellis_log, "f").error({
+                    error: handlerResult.error.toSerializable(),
+                    event,
+                    subject: msg.subject,
+                }, "Event handler failed");
+                msg.nak();
+                continue;
+            }
+            msg.ack();
+        }
+    });
+}, _Trellis_parseEventMessage = function _Trellis_parseEventMessage(event, ctx, msg) {
+    const jsonData = Result.try(() => msg.json());
+    const json = jsonData.take();
+    if (isErr(json)) {
+        __classPrivateFieldGet(this, _Trellis_log, "f").error({ error: json.error, event, subject: msg.subject }, "Event parse failed");
+        return json;
+    }
+    return parseRuntimeSchema(ctx.event, json);
+}, _Trellis_escapeSubjectToken = function _Trellis_escapeSubjectToken(token) {
+    const out = token.replace(NATS_SUBJECT_TOKEN_FORBIDDEN, (ch) => `~${ch.codePointAt(0).toString(16).toUpperCase()}~`);
+    // Protect stapRet with $ due to NATS internal use of it
+    if (out.length === 0 || out.startsWith("$")) {
+        return `_${out}`;
+    }
+    return out;
+}, _Trellis_createProof = async function _Trellis_createProof(subject, payload) {
+    const payloadBytes = new TextEncoder().encode(payload);
+    const payloadHash = await sha256(payloadBytes);
+    const input = buildProofInput(this.auth.sessionKey, subject, payloadHash);
+    const digest = await sha256(input);
+    const sigBytes = await this.auth.sign(digest);
+    return base64urlEncode(sigBytes);
+}, _Trellis_requestJson = async function _Trellis_requestJson(subject, body) {
+    const payload = JSON.stringify(body);
+    const proof = await __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_createProof).call(this, subject, payload);
+    const headers = natsHeaders();
+    headers.set("session-key", this.auth.sessionKey);
+    headers.set("proof", proof);
+    const response = await AsyncResult.try(() => this.nats.request(subject, payload, {
+        timeout: this.timeout,
+        headers,
+    })).take();
+    if (isErr(response)) {
+        return response;
+    }
+    return safeJson(response);
+}, _Trellis_watchJson = async function _Trellis_watchJson(subject, body) {
+    const payload = JSON.stringify(body);
+    const proof = await __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_createProof).call(this, subject, payload);
+    const headers = natsHeaders();
+    headers.set("session-key", this.auth.sessionKey);
+    headers.set("proof", proof);
+    const inbox = createInbox(`_INBOX.${this.auth.sessionKey.slice(0, 16)}`);
+    const sub = this.nats.subscribe(inbox);
+    try {
+        this.nats.publish(subject, payload, {
+            headers,
+            reply: inbox,
+        });
+        await this.nats.flush();
+    }
+    catch (cause) {
+        sub.unsubscribe();
+        return err(new UnexpectedError({ cause }));
+    }
+    return ok((async function* () {
+        try {
+            for await (const msg of sub) {
+                if (msg.headers?.get("status") === "error") {
+                    yield err(new UnexpectedError({ cause: new Error(msg.string()) }));
+                    continue;
+                }
+                yield safeJson(msg);
+            }
+        }
+        finally {
+            sub.unsubscribe();
+        }
+    })());
+};