@oatscenter/trellis 0.100.0-rc.1

package/service/runtime/service.js

@@ -0,0 +1,1896 @@
+import { jetstream } from "@nats-io/jetstream";
+import { headers as natsHeaders, } from "@nats-io/nats-core";
+import { installConnectionAvailability, } from "../../connection.js";
+import { TypedKV } from "../../kv.js";
+import { TypedStore, } from "../../store.js";
+import { TrellisServiceRuntime, } from "./core.js";
+import { base64urlEncode, createAuth, } from "../../auth.js";
+import { AuthorizationContextCache, AuthorizationContextRefreshError, AuthorizationProviderCache, startAuthorizationContextRefresh, } from "../../auth/authorization_context.js";
+import { TrellisHttpError } from "../../auth/http_error.js";
+import { bindApiRoutes, getParticipantRuntime, participantAvailability, participantEvidence, refreshApiRoutes, } from "../../participant_runtime/participant.js";
+import { lowerCamelSurfaceName, } from "../../participant_runtime/surface_names.js";
+import { AsyncResult, isErr, Result, } from "@oatscenter/result";
+import { Value } from "typebox/value";
+import { ServiceHealthRuntime, } from "./health.js";
+import { publishHealthHeartbeatSample } from "../../health_transport.js";
+import { annotateHandlerBoundaryError, createTrellisInternal, } from "../../session.js";
+import { ServiceTransfer } from "./transfer.js";
+import { logger as noopLogger } from "../../globals.js";
+import { createProviderRuntime, PROVIDER_CALLER, } from "../../provider.js";
+import { DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS, DEFAULT_SERVICE_RUNTIME_WAIT_ON_FIRST_CONNECT, selectRuntimeTransportServers, } from "../../runtime_transport.js";
+import { serviceRuntimeLogger } from "./logger.js";
+import { TransportError, UnexpectedError, ValidationError, } from "../../errors/index.js";
+import { ActiveJob as PublicActiveJob, decodeJobUpdateEnvelope, JobNotEnqueuedError, JobRef, JobWorkerHostAdapter, RetryJobError, } from "../../jobs.js";
+import { parseSchema } from "../../codec.js";
+import { isJsonValue } from "../../participant_runtime/json.js";
+import { ulid } from "ulid";
+import { JobManager as InternalJobManager, JobProcessError as InternalJobProcessError, prepareJobSubmission, } from "./internal_jobs/job-manager.js";
+import { startNatsWorkerHostFromBinding } from "./internal_jobs/runtime-worker.js";
+import { createNatsJobKeyCoordinator, normalizeJobKeyPolicy, } from "./internal_jobs/key-coordinator.js";
+import { JobEventSchema, PreparedJobSubmissionSchema, } from "./internal_jobs/types.js";
+import { observeNatsTrellisConnection, } from "../../connection.js";
+import { recordTrellisDuration } from "../../telemetry/mod.js";
+import { defaultSqlOutboxTables, OutboxDispatcher, preparedTrellisEventToOutboxRecord, SqlOutboxRepository, } from "../outbox_inbox.js";
+import { closeFailedServiceBootstrapConnection, fetchServiceBootstrapInfo, loadDefaultServiceRuntimeDeps, } from "./bootstrap.js";
+function normalizeResourceJobsBinding(binding) {
+    const queues = {};
+    for (const [name, queue] of Object.entries(binding.queues)) {
+        const baseQueue = baseJobsQueueBinding(queue);
+        if (!queue.keyConcurrency) {
+            queues[name] = {
+                ...baseQueue,
+                ...(queue.queue ? { queue: normalizeQueuePolicy(queue.queue) } : {}),
+            };
+            continue;
+        }
+        const policy = normalizeJobKeyPolicy({
+            keyConcurrency: queue.keyConcurrency,
+            queue: queue.queue,
+        });
+        queues[name] = {
+            ...baseQueue,
+            keyConcurrency: {
+                key: policy.key,
+                maxActive: policy.maxActive,
+                heartbeatIntervalMs: policy.heartbeatIntervalMs,
+                heartbeatTtlMs: policy.heartbeatTtlMs,
+                stalePolicy: policy.stalePolicy,
+            },
+            queue: policy.queue,
+        };
+    }
+    return {
+        serviceName: binding.serviceName,
+        namespace: binding.namespace,
+        queues,
+    };
+}
+function baseJobsQueueBinding(queue) {
+    return {
+        queueType: queue.queueType,
+        publishPrefix: queue.publishPrefix,
+        workSubject: queue.workSubject,
+        consumerName: queue.consumerName,
+        payload: queue.payload,
+        ...(queue.update ? { update: queue.update } : {}),
+        ...(queue.updatesPrefix ? { updatesPrefix: queue.updatesPrefix } : {}),
+        ...(queue.result ? { result: queue.result } : {}),
+        maxDeliver: queue.maxDeliver ?? 5,
+        backoffMs: queue.backoffMs ?? [5_000, 30_000, 120_000, 600_000],
+        ackWaitMs: queue.ackWaitMs ?? 5_000,
+        ...(queue.defaultDeadlineMs !== undefined
+            ? { defaultDeadlineMs: queue.defaultDeadlineMs }
+            : {}),
+    };
+}
+function normalizeQueuePolicy(queue) {
+    return {
+        maxQueuedPerKey: queue.maxQueuedPerKey ?? 0,
+        whenFull: queue.whenFull ?? "reject",
+    };
+}
+function resolveServiceLogger(log) {
+    return log === false ? noopLogger : log ?? serviceRuntimeLogger;
+}
+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) {
+    return lowerCamelSurfaceName(value) || "_";
+}
+function addSurfaceLeaf(surface, key, leaf) {
+    const group = surfaceGroupName(key);
+    surface[group] ??= {};
+    surface[group][surfaceLeafName(key)] = leaf;
+}
+const storeHandleConstructorToken = Symbol("StoreHandle.constructorToken");
+const trellisServiceConstructorToken = Symbol("TrellisService.constructorToken");
+export class StoreHandle {
+}
+class InternalStoreHandle extends StoreHandle {
+    binding;
+    #nc;
+    constructor(nc, binding, token) {
+        super();
+        if (token !== storeHandleConstructorToken) {
+            throw new TypeError("StoreHandle instances are created by TrellisService");
+        }
+        this.#nc = nc;
+        this.binding = binding;
+    }
+    open() {
+        return TypedStore.open(this.#nc, this.binding.name, {
+            ttlMs: this.binding.ttlMs,
+            maxObjectBytes: this.binding.maxObjectBytes,
+            maxTotalBytes: this.binding.maxTotalBytes,
+            bindOnly: true,
+        });
+    }
+    /**
+     * Waits for a staged object to appear in the bound store and returns its entry.
+     */
+    waitFor(key, options = {}) {
+        return this.open().andThen((store) => store.waitFor(key, options));
+    }
+}
+async function openServiceKvBindings(args) {
+    for (const alias of Object.keys(args.bindings)) {
+        if (!args.contractKv[alias]) {
+            throw new Error(`KV binding '${alias}' is missing contract schema metadata`);
+        }
+    }
+    const entries = await Promise.all(Object.entries(args.contractKv).map(async ([alias, metadata]) => {
+        const binding = args.bindings[alias];
+        if (!binding) {
+            if (!metadata.required) {
+                return [alias, undefined];
+            }
+            throw new Error(`Required KV binding '${alias}' is unavailable`);
+        }
+        const store = await TypedKV.open(args.nc, binding.bucket, metadata.schema, {
+            history: binding.history,
+            ttl: binding.ttlMs,
+            maxValueBytes: binding.maxValueBytes,
+            bindOnly: true,
+        }).orThrow();
+        return [alias, store];
+    }));
+    return Object.fromEntries(entries);
+}
+const MANAGED_JOB_WORKERS = Symbol("trellis.managedJobWorkers");
+function createServiceEventPublishFacade(outbound) {
+    const surface = {};
+    for (const event of Object.keys(outbound.api.events ?? {})) {
+        addSurfaceLeaf(surface, event, {
+            prepare: (payload) => outbound.prepare(event, payload),
+            publish: (payload) => outbound.publish(event, payload),
+        });
+    }
+    return surface;
+}
+/**
+ * @internal Shared by Trellis-owned service bootstrap paths.
+ */
+export async function createConnectedService(args) {
+    const resolvedLog = resolveServiceLogger(args.runtime.log);
+    const connection = observeNatsTrellisConnection({
+        kind: "service",
+        nc: args.nc,
+        availability: args.availability,
+        onTransportEvent: (event) => args.authorizationProviderCache?.observeTransportEvent(event),
+        log: false,
+        lifecycleLog: {
+            log: resolvedLog,
+            context: { service: args.name },
+        },
+    });
+    if (args.authorizationProviderCache) {
+        connection.subscribe((status) => args.authorizationProviderCache?.observeConnectionPhase(status.phase));
+    }
+    const currentApi = (args.runtime.trellisApi ?? args.runtime.api);
+    const storeNames = Object.keys(args.bindings.store);
+    const runtimeApi = {
+        ...currentApi,
+        rpc: currentApi.rpc,
+        operations: storeNames.length === 1
+            ? Object.fromEntries(Object.entries(currentApi.operations).map(([name, operation]) => [
+                name,
+                operation.transfer?.store === undefined
+                    ? {
+                        ...operation,
+                        ...(operation.transfer
+                            ? {
+                                transfer: { ...operation.transfer, store: storeNames[0] },
+                            }
+                            : {}),
+                    }
+                    : operation,
+            ]))
+            : currentApi.operations,
+    };
+    const runtime = TrellisServiceRuntime.create(args.name, args.nc, {
+        sessionKey: args.auth.sessionKey,
+        sign: args.auth.sign,
+        contextDigest: args.contextDigest,
+        authorizationProviderCache: args.auth.authorizationProviderCache,
+    }, {
+        log: resolvedLog,
+        timeout: args.runtime.timeout,
+        stream: args.runtime.stream,
+        noResponderRetry: args.runtime.noResponderRetry,
+        api: runtimeApi,
+        contractId: args.contractId,
+        contractDigest: args.contractDigest,
+        connection,
+        transferSupport: {
+            openOperationTransfer: (transferArgs) => getTransfer().createOperationUpload(transferArgs),
+        },
+        operationDeploymentId: args.healthIdentity?.deploymentId,
+        operationConnectionId: args.operationConnectionId,
+        feedOwnerId: args.healthIdentity?.instanceId ?? ulid(),
+    });
+    const outbound = createTrellisInternal(args.name, args.nc, {
+        sessionKey: args.auth.sessionKey,
+        sign: args.auth.sign,
+        contextDigest: args.contextDigest,
+        authorizationProviderCache: args.auth.authorizationProviderCache,
+    }, {
+        log: resolvedLog,
+        timeout: args.runtime.timeout,
+        stream: args.runtime.stream,
+        noResponderRetry: args.runtime.noResponderRetry,
+        api: runtimeApi,
+        contractId: args.contractId,
+        contractDigest: args.contractDigest,
+        inboxPrefix: args.inboxPrefix,
+        eventConsumers: {
+            metadata: args.contractEventConsumers,
+            bindings: args.bindings.eventConsumers,
+        },
+        apiBindings: args.apiBindings,
+        connection,
+    });
+    const resources = {};
+    const getTransfer = () => {
+        if (!resources.transfer) {
+            throw new Error("service transfer helper accessed before initialization");
+        }
+        return resources.transfer;
+    };
+    const getHandlerResources = () => {
+        if (!resources.handlerResources) {
+            throw new Error("service resource handles accessed before initialization");
+        }
+        return resources.handlerResources;
+    };
+    const handlerTrellis = {
+        rpc: outbound.rpc,
+        event: createServiceEventPublishFacade(outbound),
+        feed: outbound.feed,
+        operation: outbound.operation,
+        request: outbound.request.bind(outbound),
+        prepare: (event, data) => outbound.prepare(event, data),
+        publish: (event, data) => outbound.publish(event, data),
+        publishPrepared: (event) => outbound.publishPrepared(event),
+        stopEventListeners: () => outbound.stopEventListeners(),
+        get kv() {
+            return getHandlerResources().kv;
+        },
+        get store() {
+            return getHandlerResources().store;
+        },
+        get jobs() {
+            return getHandlerResources().jobs;
+        },
+    };
+    const health = new ServiceHealthRuntime({
+        serviceName: args.name,
+        instanceId: args.healthIdentity?.instanceId,
+        contractId: args.contractId ?? "unknown",
+        contractDigest: args.participantDigest ?? "unknown",
+        publishIntervalMs: args.runtime.health?.publishIntervalMs ?? 30_000,
+    });
+    health.add("nats", () => ({
+        status: args.nc.isClosed() ? "failed" : "ok",
+        ...(args.nc.isClosed() ? { summary: "NATS connection closed" } : {}),
+    }));
+    const heartbeatEnabled = args.healthIdentity !== undefined;
+    let healthPublishTimer;
+    let publishingHeartbeat = false;
+    const publishHealthHeartbeat = async () => {
+        if (!args.healthIdentity || publishingHeartbeat) {
+            return;
+        }
+        publishingHeartbeat = true;
+        try {
+            await publishHealthHeartbeatSample({
+                nc: args.nc,
+                identity: {
+                    sessionKey: args.auth.sessionKey,
+                    participantKind: "service",
+                    contractId: health.contractId,
+                    contractDigest: health.contractDigest,
+                    deploymentId: args.healthIdentity.deploymentId,
+                    instanceId: health.instanceId,
+                },
+                sample: await health.sample(),
+            });
+        }
+        catch (error) {
+            resolvedLog.warn({ error }, "Failed to build or publish health heartbeat");
+        }
+        finally {
+            publishingHeartbeat = false;
+        }
+    };
+    const stopHealthPublishing = () => {
+        if (healthPublishTimer !== undefined) {
+            clearInterval(healthPublishTimer);
+            healthPublishTimer = undefined;
+        }
+        return Promise.resolve();
+    };
+    const kv = await openServiceKvBindings({
+        nc: args.nc,
+        bindings: args.bindings.kv ?? {},
+        contractKv: args.contractKv,
+    });
+    const operationTransfer = new ServiceTransfer({
+        name: args.name,
+        nc: args.nc,
+        auth: args.auth,
+        stores: Object.fromEntries(Object.entries(args.bindings.store ?? {}).map(([alias, binding]) => [
+            alias,
+            new InternalStoreHandle(args.nc, binding, storeHandleConstructorToken),
+        ])),
+    });
+    const service = Reflect.construct(TrellisServiceSession, [
+        args.name,
+        args.auth,
+        args.nc,
+        runtime,
+        outbound.event,
+        outbound,
+        handlerTrellis,
+        kv,
+        args.contractJobs,
+        args.bindings,
+        operationTransfer,
+        health,
+        stopHealthPublishing,
+        connection,
+        trellisServiceConstructorToken,
+    ]);
+    resources.handlerResources = {
+        kv: service.kv,
+        store: service.store,
+        jobs: service.jobs,
+    };
+    resources.transfer = operationTransfer;
+    if (heartbeatEnabled) {
+        await publishHealthHeartbeat();
+        healthPublishTimer = setInterval(() => {
+            void publishHealthHeartbeat();
+        }, health.publishIntervalMs);
+        void args.nc.closed().then(stopHealthPublishing, stopHealthPublishing);
+    }
+    return service;
+}
+function toUnexpectedError(cause) {
+    return cause instanceof UnexpectedError
+        ? cause
+        : new UnexpectedError({ cause });
+}
+function resolveSqlOutboxTables(tables) {
+    return {
+        outbox: tables?.outbox ?? defaultSqlOutboxTables.outbox,
+        inbox: tables?.inbox ?? defaultSqlOutboxTables.inbox,
+    };
+}
+function createSqlOutboxBaseExecutor(options) {
+    return options.executor;
+}
+function createSqlOutboxTransactionRunner(options) {
+    return options.transaction;
+}
+function createSqlOutboxEventEnqueueFacade(args) {
+    const facade = {};
+    const source = args.event;
+    for (const [groupName, leaves] of Object.entries(source)) {
+        const group = {};
+        for (const [leafName, leaf] of Object.entries(leaves)) {
+            group[leafName] = {
+                enqueue: (payload) => AsyncResult.from((async () => {
+                    const prepared = leaf.prepare(payload).take();
+                    if (isErr(prepared))
+                        return Result.err(prepared.error);
+                    const record = preparedTrellisEventToOutboxRecord(prepared);
+                    try {
+                        const message = await args.repository.enqueue(record);
+                        args.onEnqueued();
+                        return Result.ok(message);
+                    }
+                    catch (cause) {
+                        return Result.err(toUnexpectedError(cause));
+                    }
+                })()),
+            };
+        }
+        Object.defineProperty(facade, groupName, {
+            value: group,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return facade;
+}
+function createSqlOutboxJobEnqueueFacade(args) {
+    const facade = {};
+    for (const queueType of Object.keys(args.contractJobs)) {
+        const jobsBinding = args.jobsBinding;
+        const queueBinding = jobsBinding?.queues[queueType];
+        const queue = queueType;
+        facade[queue] = {
+            create: (payload) => {
+                if (!queueBinding) {
+                    return AsyncResult.err(new ValidationError({
+                        errors: [{
+                                path: "/",
+                                message: `Jobs binding unavailable for queue '${queue}'`,
+                            }],
+                    }));
+                }
+                const submissionId = ulid();
+                const jobId = ulid();
+                const submission = prepareJobSubmission({
+                    submissionId,
+                    mode: "create",
+                    service: jobsBinding.serviceName,
+                    queue,
+                    jobId,
+                    payload,
+                    createdAt: new Date().toISOString(),
+                });
+                const record = {
+                    id: submissionId,
+                    kind: "job.create",
+                    name: queue,
+                    subject: `${queueBinding.publishPrefix}.${jobId}.created`,
+                    payload: JSON.stringify(submission),
+                    headers: {
+                        "request-id": submission.context.requestId,
+                        "traceparent": submission.context.traceparent,
+                        ...(submission.context.tracestate
+                            ? { "tracestate": submission.context.tracestate }
+                            : {}),
+                    },
+                };
+                return AsyncResult.from((async () => {
+                    try {
+                        await args.repository.enqueue(record);
+                        args.onEnqueued();
+                        return Result.ok({
+                            submissionId,
+                            jobId,
+                            queue,
+                            mode: "create",
+                        });
+                    }
+                    catch (cause) {
+                        return Result.err(toUnexpectedError(cause));
+                    }
+                })());
+            },
+            submit: (payload) => {
+                if (!queueBinding) {
+                    return AsyncResult.err(new ValidationError({
+                        errors: [{
+                                path: "/",
+                                message: `Jobs binding unavailable for queue '${queue}'`,
+                            }],
+                    }));
+                }
+                const submissionId = ulid();
+                const jobId = ulid();
+                const submission = prepareJobSubmission({
+                    submissionId,
+                    mode: "submit",
+                    service: jobsBinding.serviceName,
+                    queue,
+                    jobId,
+                    payload,
+                    createdAt: new Date().toISOString(),
+                });
+                const record = {
+                    id: submissionId,
+                    kind: "job.submit",
+                    name: queue,
+                    subject: `${queueBinding.publishPrefix}.${jobId}.created`,
+                    payload: JSON.stringify(submission),
+                    headers: {
+                        "request-id": submission.context.requestId,
+                        "traceparent": submission.context.traceparent,
+                        ...(submission.context.tracestate
+                            ? { "tracestate": submission.context.tracestate }
+                            : {}),
+                    },
+                };
+                return AsyncResult.from((async () => {
+                    try {
+                        await args.repository.enqueue(record);
+                        args.onEnqueued();
+                        return Result.ok({
+                            submissionId,
+                            jobId,
+                            queue,
+                            mode: "submit",
+                        });
+                    }
+                    catch (cause) {
+                        return Result.err(toUnexpectedError(cause));
+                    }
+                })());
+            },
+        };
+    }
+    return facade;
+}
+function serializeJobHandlerError(error) {
+    try {
+        return JSON.stringify(error.toSerializable());
+    }
+    catch {
+        return error.message;
+    }
+}
+function okVoid() {
+    return Result.ok(undefined);
+}
+function wrapVoidTask(task) {
+    return AsyncResult.from((async () => {
+        try {
+            await task();
+            return okVoid();
+        }
+        catch (cause) {
+            return Result.err(toUnexpectedError(cause));
+        }
+    })());
+}
+function isTerminalJobState(state) {
+    return state === "completed" || state === "failed" || state === "cancelled" ||
+        state === "expired" || state === "skipped" || state === "stale" ||
+        state === "dead" || state === "dismissed";
+}
+function isTerminalJobSnapshot(snapshot) {
+    return isTerminalJobState(snapshot.state);
+}
+function operationOutputsEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (typeof left !== typeof right || left === null || right === null) {
+        return false;
+    }
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((value, index) => operationOutputsEqual(value, right[index]));
+    }
+    if (typeof left === "object") {
+        if (Object.getPrototypeOf(left) !== Object.prototype)
+            return false;
+        if (Object.getPrototypeOf(right) !== Object.prototype)
+            return false;
+        const leftRecord = left;
+        const rightRecord = right;
+        const leftKeys = Object.keys(leftRecord);
+        const rightKeys = Object.keys(rightRecord);
+        return leftKeys.length === rightKeys.length &&
+            leftKeys.every((key) => Object.hasOwn(rightRecord, key) &&
+                operationOutputsEqual(leftRecord[key], rightRecord[key]));
+    }
+    return false;
+}
+function parseJobLifecycleEvent(data) {
+    try {
+        const decoded = JSON.parse(new TextDecoder().decode(data));
+        if (!Value.Check(JobEventSchema, decoded)) {
+            return undefined;
+        }
+        return decoded;
+    }
+    catch {
+        return undefined;
+    }
+}
+function jobLifecycleKey(service, jobType, jobId) {
+    return `${service}.${jobType}.${jobId}`;
+}
+function subjectMatchesLifecycleEvent(subject, queueBinding, event) {
+    const prefix = `${queueBinding.publishPrefix}.`;
+    if (!subject.startsWith(prefix))
+        return false;
+    const suffix = subject.slice(prefix.length).split(".");
+    return suffix.length === 2 && suffix[0] === event.jobId &&
+        suffix[1] === event.eventType;
+}
+function snapshotFromLifecycleEvent(current, event) {
+    if (event.service !== current.service || event.jobType !== current.type ||
+        event.jobId !== current.id) {
+        return current;
+    }
+    if (isTerminalJobState(current.state)) {
+        return current;
+    }
+    const base = {
+        ...current,
+        state: event.state,
+        updatedAt: event.timestamp,
+        tries: event.tries,
+        ...(event.maxTries !== undefined ? { maxTries: event.maxTries } : {}),
+        ...(event.deadline !== undefined ? { deadline: event.deadline } : {}),
+        ...(event.trigger !== undefined ? { trigger: event.trigger } : {}),
+        ...(event.lineage !== undefined ? { lineage: event.lineage } : {}),
+    };
+    switch (event.eventType) {
+        case "created":
+        case "retried":
+            return event.payload === undefined ? base : {
+                ...base,
+                payload: event.payload,
+            };
+        case "started":
+            return { ...base, startedAt: event.timestamp };
+        case "progress":
+            return event.progress === undefined ? base : {
+                ...base,
+                progress: event.progress,
+            };
+        case "logged":
+            return event.logs === undefined ? base : {
+                ...base,
+                logs: [...(current.logs ?? []), ...event.logs],
+            };
+        case "waiting": {
+            if (event.waitEdge === undefined)
+                return base;
+            const waitingOn = (current.waitingOn ?? []).filter((edge) => edge.id !== event.waitEdge?.id);
+            return { ...base, waitingOn: [...waitingOn, event.waitEdge] };
+        }
+        case "resumed":
+            return event.waitEdge === undefined ? base : {
+                ...base,
+                waitingOn: (current.waitingOn ?? []).filter((edge) => edge.id !== event.waitEdge?.id),
+            };
+        case "completed":
+            return {
+                ...base,
+                completedAt: event.timestamp,
+                ...(event.result !== undefined ? { result: event.result } : {}),
+            };
+        case "failed":
+        case "cancelled":
+        case "expired":
+        case "skipped":
+        case "stale":
+        case "staleCompletionIgnored":
+        case "dead":
+        case "dismissed":
+            return event.error === undefined ? base : {
+                ...base,
+                lastError: event.error,
+            };
+    }
+    return base;
+}
+function headersFromJobContext(context) {
+    const headers = natsHeaders();
+    headers.set("request-id", context.requestId);
+    headers.set("traceparent", context.traceparent);
+    if (context.tracestate) {
+        headers.set("tracestate", context.tracestate);
+    }
+    return headers;
+}
+function createJobLifecycleTracker(nc) {
+    const snapshots = new Map();
+    const attempts = new Map();
+    const waiters = new Map();
+    const subscriptions = new Map();
+    let stopped = false;
+    const notify = (key, snapshot) => {
+        if (!isTerminalJobSnapshot(snapshot))
+            return;
+        const pending = waiters.get(key) ?? [];
+        waiters.delete(key);
+        for (const waiter of pending)
+            waiter.resolve(snapshot);
+    };
+    const apply = (event) => {
+        const key = jobLifecycleKey(event.service, event.jobType, event.jobId);
+        attempts.set(key, Math.max(attempts.get(key) ?? 0, event.tries));
+        const current = snapshots.get(key);
+        if (!current)
+            return undefined;
+        const next = snapshotFromLifecycleEvent(current, event);
+        snapshots.set(key, next);
+        notify(key, next);
+        return next;
+    };
+    return {
+        watch(queueBinding) {
+            if (subscriptions.has(queueBinding.publishPrefix))
+                return;
+            const subscription = nc.subscribe(`${queueBinding.publishPrefix}.*.*`);
+            subscriptions.set(queueBinding.publishPrefix, subscription);
+            void (async () => {
+                for await (const msg of subscription) {
+                    const event = parseJobLifecycleEvent(msg.data);
+                    if (!event || !subjectMatchesLifecycleEvent(msg.subject, queueBinding, event)) {
+                        continue;
+                    }
+                    apply(event);
+                }
+            })();
+        },
+        seed(snapshot) {
+            const key = jobLifecycleKey(snapshot.service, snapshot.type, snapshot.id);
+            attempts.set(key, Math.max(attempts.get(key) ?? 0, snapshot.tries));
+            const current = snapshots.get(key);
+            if (current && isTerminalJobState(current.state))
+                return;
+            snapshots.set(key, snapshot);
+            notify(key, snapshot);
+        },
+        get(args) {
+            const current = snapshots.get(jobLifecycleKey(args.service, args.jobType, args.id));
+            return current;
+        },
+        attempt(args) {
+            return attempts.get(jobLifecycleKey(args.service, args.jobType, args.id));
+        },
+        apply,
+        wait(snapshot) {
+            this.seed(snapshot);
+            const key = jobLifecycleKey(snapshot.service, snapshot.type, snapshot.id);
+            const current = snapshots.get(key);
+            if (current && isTerminalJobSnapshot(current)) {
+                return Promise.resolve(current);
+            }
+            if (stopped) {
+                return Promise.reject(toUnexpectedError(new Error("job lifecycle tracker stopped")));
+            }
+            return new Promise((resolve, reject) => {
+                const pending = waiters.get(key) ?? [];
+                pending.push({
+                    resolve: resolve,
+                    reject,
+                });
+                waiters.set(key, pending);
+            });
+        },
+        stop() {
+            stopped = true;
+            for (const subscription of subscriptions.values()) {
+                subscription.unsubscribe();
+            }
+            subscriptions.clear();
+            const error = toUnexpectedError(new Error("job lifecycle tracker stopped"));
+            for (const pending of waiters.values()) {
+                for (const waiter of pending)
+                    waiter.reject(error);
+            }
+            waiters.clear();
+            attempts.clear();
+        },
+    };
+}
+function createJobRef(args) {
+    args.lifecycle.seed(args.seed);
+    return new JobRef({
+        id: args.seed.id,
+        service: args.seed.service,
+        jobType: args.queueType,
+    }, {
+        get: () => AsyncResult.ok(args.lifecycle.get({
+            service: args.seed.service,
+            jobType: args.queueType,
+            id: args.seed.id,
+        }) ?? args.seed),
+        wait: () => AsyncResult.from((async () => {
+            try {
+                return Result.ok(await args.lifecycle.wait(args.seed));
+            }
+            catch (cause) {
+                return Result.err(toUnexpectedError(cause));
+            }
+        })()),
+        cancel: () => AsyncResult.from(Promise.resolve().then(() => {
+            const current = args.lifecycle.get({
+                service: args.seed.service,
+                jobType: args.queueType,
+                id: args.seed.id,
+            }) ?? args.seed;
+            if (isTerminalJobState(current.state)) {
+                return Result.ok(current);
+            }
+            const event = {
+                jobId: args.seed.id,
+                service: current.service,
+                jobType: args.queueType,
+                eventType: "cancelled",
+                state: "cancelled",
+                previousState: current.state,
+                context: current.context,
+                tries: current.tries,
+                error: "cancelled",
+                timestamp: new Date().toISOString(),
+            };
+            try {
+                args.nc.publish(`${args.queueBinding.publishPrefix}.${args.seed.id}.cancelled`, new TextEncoder().encode(JSON.stringify(event)), { headers: headersFromJobContext(event.context) });
+            }
+            catch (cause) {
+                return Result.err(toUnexpectedError(cause));
+            }
+            return Result.ok(args.lifecycle.apply(event) ?? current);
+        })),
+        updates: args.updates,
+    });
+}
+function subscribeToJobUpdates(args) {
+    return AsyncResult.from(Promise.resolve().then(() => {
+        if (!args.queue.update || !args.queue.updatesPrefix) {
+            return Result.err(toUnexpectedError(new Error("Job updates are not configured for this queue")));
+        }
+        if (!/^[^.>*\s]+$/u.test(args.jobId)) {
+            return Result.err(new ValidationError({
+                errors: [{
+                        path: "/jobId",
+                        message: "Job id must be one NATS token",
+                    }],
+            }));
+        }
+        const subscription = args.nc.subscribe(`${args.queue.updatesPrefix}.${args.jobId}`);
+        args.active.add(subscription);
+        const close = () => {
+            subscription.unsubscribe();
+            args.active.delete(subscription);
+        };
+        const abort = () => close();
+        args.options?.signal?.addEventListener("abort", abort, { once: true });
+        if (args.options?.signal?.aborted)
+            close();
+        const updates = {
+            unsubscribe: close,
+            async *[Symbol.asyncIterator]() {
+                let attempt = 0;
+                let sequence = 0;
+                try {
+                    for await (const message of subscription) {
+                        const envelope = decodeJobUpdateEnvelope(message.data);
+                        if (!envelope || envelope.jobId !== args.jobId)
+                            continue;
+                        if (!isJsonValue(envelope.update))
+                            continue;
+                        const parsed = parseSchema(args.updateSchema, envelope.update)
+                            .take();
+                        if (isErr(parsed))
+                            continue;
+                        const lifecycleAttempt = args.lifecycle.attempt({
+                            service: args.service,
+                            jobType: args.queue.queueType,
+                            id: args.jobId,
+                        }) ?? 0;
+                        if (lifecycleAttempt > attempt) {
+                            attempt = lifecycleAttempt;
+                            sequence = 0;
+                        }
+                        if (envelope.attempt < attempt)
+                            continue;
+                        if (envelope.attempt > attempt) {
+                            attempt = envelope.attempt;
+                            sequence = 0;
+                        }
+                        if (envelope.sequence <= sequence)
+                            continue;
+                        sequence = envelope.sequence;
+                        yield parsed;
+                    }
+                }
+                finally {
+                    close();
+                    args.options?.signal?.removeEventListener("abort", abort);
+                }
+            },
+        };
+        return Result.ok(updates);
+    }));
+}
+function createNoopJobWorkerHost() {
+    return new JobWorkerHostAdapter({
+        stop: () => AsyncResult.ok(undefined),
+        join: () => AsyncResult.ok(undefined),
+    });
+}
+function createJobsFacade(args) {
+    const handlers = new Map();
+    const jobsFacade = {};
+    const lifecycle = createJobLifecycleTracker(args.nc);
+    const updateSubscriptions = new Set();
+    const keyCoordinator = createNatsJobKeyCoordinator(args.nc);
+    const jobsBinding = args.jobsBinding
+        ? normalizeResourceJobsBinding(args.jobsBinding)
+        : undefined;
+    const manager = new InternalJobManager({
+        nc: jetstream(args.nc),
+        jobs: jobsBinding,
+        keyCoordinator,
+    });
+    let activeHost;
+    let startupPromise;
+    let stopPromise;
+    for (const queueType of Object.keys(args.contractJobs ?? {})) {
+        const queueBinding = jobsBinding?.queues[queueType];
+        const updateSchema = args.contractJobs[queueType]?.updateSchema;
+        if (queueBinding)
+            lifecycle.watch(queueBinding);
+        const updates = (jobId, options) => {
+            if (!queueBinding || !updateSchema) {
+                return AsyncResult.err(toUnexpectedError(new Error(`Job updates are unavailable for queue '${queueType}'`)));
+            }
+            return subscribeToJobUpdates({
+                nc: args.nc,
+                active: updateSubscriptions,
+                lifecycle,
+                service: args.serviceName,
+                queue: queueBinding,
+                updateSchema,
+                jobId,
+                options,
+            });
+        };
+        jobsFacade[queueType] = {
+            updates,
+            create: (payload) => AsyncResult.from((async () => {
+                try {
+                    if (!jobsBinding) {
+                        return Result.err(toUnexpectedError(new Error("Jobs bindings are unavailable")));
+                    }
+                    const queueBinding = jobsBinding.queues[queueType];
+                    if (!queueBinding) {
+                        return Result.err(toUnexpectedError(new Error(`Jobs binding for queue '${queueType}' is unavailable`)));
+                    }
+                    const created = await manager.create(queueType, payload);
+                    return Result.ok(createJobRef({
+                        nc: args.nc,
+                        queueType,
+                        jobsBinding,
+                        queueBinding,
+                        seed: created,
+                        lifecycle,
+                        updates: (options) => updates(created.id, options),
+                    }));
+                }
+                catch (cause) {
+                    if (cause instanceof JobNotEnqueuedError) {
+                        return Result.err(cause);
+                    }
+                    return Result.err(toUnexpectedError(cause));
+                }
+            })()),
+            submit: (payload) => AsyncResult.from((async () => {
+                try {
+                    if (!jobsBinding) {
+                        return Result.err(toUnexpectedError(new Error("Jobs bindings are unavailable")));
+                    }
+                    const queueBinding = jobsBinding.queues[queueType];
+                    if (!queueBinding) {
+                        return Result.err(toUnexpectedError(new Error(`Jobs binding for queue '${queueType}' is unavailable`)));
+                    }
+                    const outcome = await manager.submit(queueType, payload);
+                    if (outcome.kind === "accepted") {
+                        return Result.ok({
+                            kind: "accepted",
+                            key: outcome.key,
+                            ref: createJobRef({
+                                nc: args.nc,
+                                queueType,
+                                jobsBinding,
+                                queueBinding,
+                                seed: outcome.job,
+                                lifecycle,
+                                updates: (options) => updates(outcome.job.id, options),
+                            }),
+                        });
+                    }
+                    if (outcome.kind === "replaced") {
+                        return Result.ok({
+                            kind: "replaced",
+                            key: outcome.key,
+                            replaced: outcome.replaced,
+                            ref: createJobRef({
+                                nc: args.nc,
+                                queueType,
+                                jobsBinding,
+                                queueBinding,
+                                seed: outcome.job,
+                                lifecycle,
+                                updates: (options) => updates(outcome.job.id, options),
+                            }),
+                        });
+                    }
+                    return Result.ok(outcome);
+                }
+                catch (cause) {
+                    return Result.err(toUnexpectedError(cause));
+                }
+            })()),
+            handle: (handler, options) => {
+                if (handlers.has(queueType)) {
+                    throw new Error(`Job handler for queue '${queueType}' is already registered`);
+                }
+                if (activeHost || startupPromise) {
+                    throw new Error(`Job handler for queue '${queueType}' cannot be registered after worker startup has begun`);
+                }
+                const concurrency = options?.concurrency ?? 1;
+                if (!Number.isInteger(concurrency) || concurrency < 1) {
+                    throw new Error(`Job handler for queue '${queueType}' has invalid concurrency ${concurrency}; expected a positive integer`);
+                }
+                handlers.set(queueType, {
+                    concurrency,
+                    handler: async (job) => await handler({
+                        job,
+                        client: args.client,
+                    }),
+                });
+            },
+        };
+    }
+    const managedWorkers = {
+        start: () => {
+            if (activeHost) {
+                return AsyncResult.ok(activeHost);
+            }
+            if (startupPromise) {
+                return AsyncResult.from(startupPromise);
+            }
+            startupPromise = (async () => {
+                const selectedQueues = [...handlers.keys()];
+                if (selectedQueues.length === 0) {
+                    const host = createNoopJobWorkerHost();
+                    activeHost = host;
+                    return Result.ok(host);
+                }
+                if (!jobsBinding || !args.workStream) {
+                    return Result.err(toUnexpectedError(new Error("Jobs infrastructure bindings are unavailable for this service")));
+                }
+                const workStream = args.workStream;
+                const hosts = [];
+                try {
+                    for (const queueType of selectedQueues) {
+                        const queueBinding = jobsBinding.queues[queueType];
+                        if (!queueBinding) {
+                            throw new Error(`Unknown jobs queue '${queueType}'`);
+                        }
+                        const updateSchema = args.contractJobs[queueType]?.updateSchema;
+                        const workerUpdates = (jobId, options) => {
+                            if (!updateSchema) {
+                                return AsyncResult.err(toUnexpectedError(new Error(`Job updates are unavailable for queue '${queueType}'`)));
+                            }
+                            return subscribeToJobUpdates({
+                                nc: args.nc,
+                                active: updateSubscriptions,
+                                lifecycle,
+                                service: args.serviceName,
+                                queue: queueBinding,
+                                updateSchema,
+                                jobId,
+                                options,
+                            });
+                        };
+                        const registration = handlers.get(queueType);
+                        if (!registration) {
+                            throw new Error(`No job handler registered for queue '${queueType}'`);
+                        }
+                        const host = await startNatsWorkerHostFromBinding({
+                            jobs: jobsBinding,
+                            workStream,
+                        }, {
+                            nats: args.nc,
+                            instanceId: `${args.serviceName}-worker`,
+                            queueTypes: [queueType],
+                            queueConcurrency: {
+                                [queueType]: registration.concurrency,
+                            },
+                            manager,
+                            heartbeatPublisher: args.nc,
+                            getProjectedJob: (job) => Promise.resolve(lifecycle.get({
+                                service: job.service,
+                                jobType: job.type,
+                                id: job.id,
+                            })),
+                            handler: async (job) => {
+                                let updateSequence = 0;
+                                let attemptActive = true;
+                                const publicJob = new PublicActiveJob(createJobRef({
+                                    nc: args.nc,
+                                    queueType,
+                                    jobsBinding,
+                                    queueBinding,
+                                    seed: job.job(),
+                                    lifecycle,
+                                    updates: (options) => workerUpdates(job.job().id, options),
+                                }), job.job().payload, job.context(), () => job.isCancelled(), {
+                                    heartbeat: () => wrapVoidTask(() => job.heartbeat()),
+                                    progress: (value) => wrapVoidTask(() => job.updateProgress(value)),
+                                    log: (entry) => wrapVoidTask(() => job.log(entry.level, entry.message)),
+                                    emitUpdate: (value) => AsyncResult.from(Promise.resolve().then(() => {
+                                        if (!attemptActive) {
+                                            return Result.err(toUnexpectedError(new Error("Job attempt is no longer active")));
+                                        }
+                                        if (!queueBinding.update ||
+                                            !queueBinding.updatesPrefix ||
+                                            !updateSchema) {
+                                            return Result.err(toUnexpectedError(new Error(`Job updates are unavailable for queue '${queueType}'`)));
+                                        }
+                                        if (!isJsonValue(value)) {
+                                            return Result.err(new ValidationError({
+                                                errors: [{
+                                                        path: "/",
+                                                        message: "Job update must be JSON-serializable",
+                                                    }],
+                                            }));
+                                        }
+                                        const parsed = parseSchema(updateSchema, value)
+                                            .take();
+                                        if (isErr(parsed))
+                                            return parsed;
+                                        updateSequence += 1;
+                                        try {
+                                            args.nc.publish(`${queueBinding.updatesPrefix}.${job.job().id}`, new TextEncoder().encode(JSON.stringify({
+                                                jobId: job.job().id,
+                                                attempt: job.job().tries + 1,
+                                                sequence: updateSequence,
+                                                timestamp: new Date().toISOString(),
+                                                update: parsed,
+                                            })));
+                                            return Result.ok(undefined);
+                                        }
+                                        catch (cause) {
+                                            return Result.err(toUnexpectedError(cause));
+                                        }
+                                    })),
+                                    waitFor: (target, fn) => job.waitFor(target, fn),
+                                    redeliveryCount: job.redeliveryCount(),
+                                    signal: job.signal,
+                                });
+                                const jobErrorContext = {
+                                    jobType: queueType,
+                                    requestId: job.context().requestId,
+                                    service: args.serviceName,
+                                    contractId: args.contractId,
+                                    contractDigest: args.contractDigest,
+                                    traceId: job.context().traceId,
+                                };
+                                let handled;
+                                try {
+                                    handled = (await registration.handler(publicJob)).take();
+                                }
+                                catch (cause) {
+                                    const annotatedError = annotateHandlerBoundaryError(cause, jobErrorContext);
+                                    const signal = annotatedError instanceof RetryJobError
+                                        ? InternalJobProcessError.retryable
+                                        : InternalJobProcessError.failed;
+                                    throw signal(serializeJobHandlerError(annotatedError));
+                                }
+                                finally {
+                                    attemptActive = false;
+                                }
+                                if (isErr(handled)) {
+                                    const annotatedError = annotateHandlerBoundaryError(handled.error, jobErrorContext);
+                                    const signal = annotatedError instanceof RetryJobError
+                                        ? InternalJobProcessError.retryable
+                                        : InternalJobProcessError.failed;
+                                    throw signal(serializeJobHandlerError(annotatedError));
+                                }
+                                return handled;
+                            },
+                        });
+                        hosts.push(host);
+                    }
+                }
+                catch (cause) {
+                    const stopResults = await Promise.allSettled(hosts.map((host) => host.stop()));
+                    const stopErrors = stopResults
+                        .filter((result) => result.status === "rejected")
+                        .map((result) => result.reason);
+                    if (stopErrors.length > 0) {
+                        return Result.err(toUnexpectedError(new AggregateError([cause, ...stopErrors])));
+                    }
+                    return Result.err(toUnexpectedError(cause));
+                }
+                activeHost = new JobWorkerHostAdapter({
+                    stop: () => wrapVoidTask(async () => {
+                        for (const host of hosts) {
+                            await host.stop();
+                        }
+                    }),
+                    join: () => AsyncResult.ok(undefined),
+                });
+                return Result.ok(activeHost);
+            })().finally(() => {
+                startupPromise = undefined;
+            });
+            return AsyncResult.from(startupPromise);
+        },
+        stop: () => {
+            if (stopPromise) {
+                return AsyncResult.from(stopPromise);
+            }
+            stopPromise = (async () => {
+                const startup = startupPromise;
+                if (startup) {
+                    const started = await startup;
+                    if (isErr(started)) {
+                        return Result.ok(undefined);
+                    }
+                }
+                if (!activeHost) {
+                    for (const subscription of updateSubscriptions) {
+                        subscription.unsubscribe();
+                    }
+                    updateSubscriptions.clear();
+                    lifecycle.stop();
+                    return Result.ok(undefined);
+                }
+                const host = activeHost;
+                try {
+                    return await host.stop();
+                }
+                finally {
+                    for (const subscription of updateSubscriptions) {
+                        subscription.unsubscribe();
+                    }
+                    updateSubscriptions.clear();
+                    lifecycle.stop();
+                    if (activeHost === host) {
+                        activeHost = undefined;
+                    }
+                    stopPromise = undefined;
+                }
+            })();
+            return AsyncResult.from(stopPromise);
+        },
+    };
+    Object.defineProperty(jobsFacade, MANAGED_JOB_WORKERS, {
+        value: managedWorkers,
+        enumerable: false,
+    });
+    return jobsFacade;
+}
+/**
+ * Connects a service with caller-supplied runtime dependencies for tests and
+ * Trellis-owned internals. This helper is intentionally not re-exported from
+ * public package subpaths.
+ *
+ * @internal
+ */
+export function connectTrellisServiceWithRuntimeDeps(args, deps) {
+    return AsyncResult.from((async () => {
+        const totalStartedAt = performance.now();
+        try {
+            const runtimeDeps = {
+                ...(await loadDefaultServiceRuntimeDeps()),
+                ...deps,
+            };
+            const serviceName = args.name ?? args.participant.identity;
+            if (args.telemetry !== false && args.telemetry?.enabled !== false) {
+                runtimeDeps.initTelemetry?.(serviceName);
+            }
+            const identityAuth = await createAuth({
+                sessionKeySeed: args.seed,
+            });
+            const sessionAuth = await createAuth({
+                sessionKeySeed: base64urlEncode(crypto.getRandomValues(new Uint8Array(32))),
+            });
+            const bootstrapLog = resolveServiceLogger(args.runtime?.log);
+            const bootstrapStartedAt = performance.now();
+            const bootstrap = await fetchServiceBootstrapInfo({
+                trellisUrl: args.trellisUrl,
+                serviceName,
+                name: args.name,
+                contractId: args.participant.identity,
+                contractDigest: participantEvidence(args.participant).packageDigest,
+                contract: args.participant,
+                identityAuth,
+                sessionAuth,
+                log: bootstrapLog,
+            });
+            recordTrellisDuration("trellis.connect.duration", performance.now() - bootstrapStartedAt, {
+                phase: "bootstrap",
+                participantKind: "service",
+                outcome: "ok",
+            });
+            const authorizationContexts = new AuthorizationContextCache(args.trellisUrl);
+            authorizationContexts.setServerClockOffsetMs(bootstrap.serverClockOffsetMs);
+            await authorizationContexts.install(bootstrap.connectInfo.authorizationContext, {
+                bootstrapJwt: bootstrap.connectInfo.jwt,
+                bootstrapJwtExpiresAt: bootstrap.connectInfo.jwtExpiresAt,
+            });
+            const verifiedContext = authorizationContexts.current();
+            if (verifiedContext.context.participantId !== args.participant.identity) {
+                throw new Error("service authorization context belongs to another participant");
+            }
+            if (!verifiedContext.context.deploymentId ||
+                !verifiedContext.context.instanceId) {
+                throw new Error("service authorization context is missing its deployment assignment");
+            }
+            const { authenticator, inboxPrefix } = await sessionAuth
+                .natsConnectOptions({
+                sessionId: bootstrap.connectInfo.connectionId,
+                contextDigest: () => authorizationContexts.transportCurrent().contextDigest,
+                jwt: () => authorizationContexts.transportRoutingJwt(),
+                authorizationUsable: () => authorizationProviderCache?.transportUsable() ?? true,
+            });
+            let nc;
+            let authorizationProviderCache;
+            let stopContextRefresh;
+            try {
+                const natsStartedAt = performance.now();
+                nc = await runtimeDeps.connect({
+                    servers: selectRuntimeTransportServers(bootstrap.connectInfo.transports),
+                    maxReconnectAttempts: DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS,
+                    ignoreAuthErrorAbort: true,
+                    waitOnFirstConnect: DEFAULT_SERVICE_RUNTIME_WAIT_ON_FIRST_CONNECT,
+                    inboxPrefix,
+                    authenticator,
+                });
+                const connectedNats = nc;
+                authorizationProviderCache = await AuthorizationProviderCache.attach(connectedNats, authorizationContexts.bundle().authorizationRegistry, inboxPrefix, authorizationContexts);
+                authorizationProviderCache.start();
+                await authorizationProviderCache.waitReady();
+                await authorizationProviderCache.retainOwnContext();
+                void connectedNats.closed().then(() => {
+                    stopContextRefresh?.();
+                    authorizationProviderCache?.stop();
+                }, () => {
+                    stopContextRefresh?.();
+                    authorizationProviderCache?.stop();
+                });
+                recordTrellisDuration("trellis.connect.duration", performance.now() - natsStartedAt, {
+                    phase: "nats_connect",
+                    participantKind: "service",
+                    outcome: "ok",
+                });
+            }
+            catch (cause) {
+                authorizationProviderCache?.stop();
+                stopContextRefresh?.();
+                if (nc && !nc.isClosed())
+                    await nc.close();
+                throw new TransportError({
+                    code: "trellis.runtime.connect_failed",
+                    message: "Trellis could not open the service runtime connection.",
+                    hint: "Retry the connection. If it keeps failing, check Trellis transport availability.",
+                    cause,
+                    context: {
+                        trellisUrl: args.trellisUrl,
+                        contractId: args.participant.identity,
+                        contractDigest: bootstrap.connectInfo.participantDigest,
+                    },
+                });
+            }
+            if (!nc || !authorizationProviderCache) {
+                throw new Error("Trellis service runtime connection was not established");
+            }
+            const serviceAuth = {
+                ...sessionAuth,
+                authorizationProviderCache,
+            };
+            try {
+                const contractRuntime = getParticipantRuntime(args.participant);
+                const runtime = {
+                    ...(args.runtime ?? {}),
+                    api: bindApiRoutes(contractRuntime.ownedApi, bootstrap.binding.apiBindings),
+                    trellisApi: bindApiRoutes(contractRuntime.api, bootstrap.binding.apiBindings),
+                    operationDeploymentId: verifiedContext.context.deploymentId,
+                    operationConnectionId: verifiedContext.context.connectionId,
+                };
+                const service = await createConnectedService({
+                    name: serviceName,
+                    auth: serviceAuth,
+                    nc,
+                    inboxPrefix,
+                    contextDigest: () => authorizationContexts.current().contextDigest,
+                    operationConnectionId: verifiedContext.context.connectionId,
+                    contractId: args.participant.identity,
+                    contractDigest: bootstrap.connectInfo.participantDigest,
+                    participantDigest: bootstrap.connectInfo.participantDigest,
+                    contractJobs: contractRuntime.jobs,
+                    contractKv: contractRuntime.kv,
+                    contractEventConsumers: contractRuntime.eventConsumers,
+                    apiBindings: bootstrap.binding.apiBindings,
+                    runtime,
+                    bindings: bootstrap.binding.resources,
+                    availability: participantAvailability(args.participant, bootstrap.binding.apiBindings, bootstrap.binding.resources),
+                    healthIdentity: {
+                        instanceId: verifiedContext.context.instanceId,
+                        deploymentId: verifiedContext.context.deploymentId,
+                    },
+                    authorizationProviderCache,
+                });
+                let installedAvailability = participantAvailability(args.participant, bootstrap.binding.apiBindings, bootstrap.binding.resources);
+                authorizationProviderCache.onOwnInvalidated(() => installConnectionAvailability(service.connection, participantAvailability(args.participant, {}, {}, [])));
+                authorizationProviderCache.onOwnResumed(() => {
+                    installConnectionAvailability(service.connection, installedAvailability);
+                });
+                stopContextRefresh = startAuthorizationContextRefresh({
+                    trellisUrl: args.trellisUrl,
+                    sessionId: bootstrap.connectInfo.connectionId,
+                    auth: sessionAuth,
+                    cache: authorizationContexts,
+                    refresh: async (shouldInstall) => {
+                        try {
+                            const next = await fetchServiceBootstrapInfo({
+                                trellisUrl: args.trellisUrl,
+                                serviceName,
+                                name: args.name,
+                                contractId: args.participant.identity,
+                                contractDigest: bootstrap.connectInfo.participantDigest,
+                                contract: args.participant,
+                                identityAuth,
+                                sessionAuth,
+                                log: bootstrapLog,
+                                connectionId: bootstrap.connectInfo.connectionId,
+                            });
+                            authorizationContexts.setServerClockOffsetMs(next.serverClockOffsetMs);
+                            const context = await authorizationContexts.prepare(next.connectInfo.authorizationContext, {
+                                bootstrapJwt: next.connectInfo.jwt,
+                                bootstrapJwtExpiresAt: next.connectInfo.jwtExpiresAt,
+                            }, next.serverNow, shouldInstall, {
+                                connectionId: next.connectInfo.connectionId,
+                                loginSessionId: null,
+                                participantId: next.connectInfo.participantId,
+                                inboxPrefix,
+                                transports: next.connectInfo.transports,
+                            }, () => () => {
+                                installedAvailability = participantAvailability(args.participant, next.binding.apiBindings, next.binding.resources);
+                                installConnectionAvailability(service.connection, installedAvailability);
+                                refreshApiRoutes(runtime.api, next.binding.apiBindings);
+                                refreshApiRoutes(runtime.trellisApi, next.binding.apiBindings);
+                            });
+                            return context;
+                        }
+                        catch (error) {
+                            if (error instanceof TrellisHttpError) {
+                                throw new AuthorizationContextRefreshError(error.status, error.code);
+                            }
+                            throw error;
+                        }
+                    },
+                    onRefresh: async (context) => {
+                        nc.setServers(selectRuntimeTransportServers(authorizationContexts.transportRuntimeBinding().transports));
+                        if (service.connection.status.phase === "connected") {
+                            await nc.reconnect();
+                        }
+                        await authorizationProviderCache.waitReady({ timeoutMs: 30_000 });
+                        const generation = authorizationProviderCache
+                            .connectionGeneration();
+                        await authorizationProviderCache.retainOwnCandidate(context.contextDigest, generation);
+                        authorizationProviderCache.promoteOwnCandidate(context.contextDigest, generation);
+                    },
+                    onTerminalFailure: async () => {
+                        if (!nc.isClosed())
+                            await nc.close();
+                    },
+                });
+                recordTrellisDuration("trellis.connect.duration", performance.now() - totalStartedAt, {
+                    phase: "total",
+                    participantKind: "service",
+                    outcome: "ok",
+                });
+                return Result.ok(service);
+            }
+            catch (cause) {
+                await closeFailedServiceBootstrapConnection(nc);
+                throw cause;
+            }
+        }
+        catch (cause) {
+            return Result.err(cause instanceof TransportError ? cause : toUnexpectedError(cause));
+        }
+    })());
+}
+/** Connected session implementation backing the public service type. */
+export class TrellisServiceSession {
+    name;
+    auth;
+    #runtime;
+    #nc;
+    #handlerTrellis;
+    /** Event lifecycle surface for service startup listeners and publishers. */
+    event;
+    kv;
+    store;
+    jobs;
+    health;
+    handle;
+    /** Framework-neutral lifecycle handle for the service runtime connection. */
+    connection;
+    #operationTransfer;
+    #stopHealthPublishing;
+    #managedJobWorkers;
+    #contractJobs;
+    #jobsBinding;
+    #ownedOutboxDispatchers = new Set();
+    #waitPromise;
+    #stopPromise;
+    constructor(name, auth, nc, runtime, event, providerCaller, handlerTrellis, kv, contractJobs, bindings, operationTransfer, health, stopHealthPublishing, connection, token) {
+        if (token !== trellisServiceConstructorToken) {
+            throw new TypeError("TrellisService instances are created by connect()");
+        }
+        const storeBindings = bindings.store ?? {};
+        this.name = name;
+        this.auth = auth;
+        this.#nc = nc;
+        this.#runtime = runtime;
+        this.#handlerTrellis = handlerTrellis;
+        Object.defineProperty(this, PROVIDER_CALLER, {
+            value: providerCaller,
+        });
+        this.event = event;
+        this.kv = kv;
+        this.store = Object.fromEntries(Object.entries(storeBindings).map(([alias, binding]) => [
+            alias,
+            new InternalStoreHandle(nc, binding, storeHandleConstructorToken),
+        ]));
+        this.#operationTransfer = operationTransfer;
+        const jobs = createJobsFacade({
+            serviceName: name,
+            contractId: health.contractId,
+            contractDigest: health.contractDigest,
+            nc,
+            contractJobs,
+            client: handlerTrellis,
+            jobsBinding: bindings.jobs,
+            workStream: bindings.jobs?.workStream,
+        });
+        this.jobs = jobs;
+        this.#managedJobWorkers = jobs[MANAGED_JOB_WORKERS];
+        this.#contractJobs = contractJobs;
+        this.#jobsBinding = bindings.jobs;
+        this.health = health;
+        this.handle = this.#createHandleFacade();
+        this.connection = connection;
+        this.#stopHealthPublishing = stopHealthPublishing;
+    }
+    /**
+     * Creates an explicit SQL outbox helper for service-owned transactions.
+     * Services should create this at startup and close over it in handlers.
+     */
+    createSqlOutbox(options) {
+        const binding = this.#createSqlOutboxBinding(options);
+        return this.#createSqlOutbox(binding);
+    }
+    /** Publishes a prepared event through the service runtime connection. */
+    publishPrepared(event) {
+        return this.#handlerTrellis.publishPrepared(event);
+    }
+    #createHandleFacade() {
+        const rpc = {};
+        for (const method of Object.keys(this.#runtime.api.rpc ?? {})) {
+            addSurfaceLeaf(rpc, method, (handler) => this.#runtime.mountRuntime(method, async ({ input, context }) => await Promise.resolve(handler({
+                input,
+                context,
+                client: this.#handlerTrellis,
+            }))));
+        }
+        const feed = {};
+        for (const feedName of Object.keys(this.#runtime.api.feeds ?? {})) {
+            addSurfaceLeaf(feed, feedName, (handler) => this.#runtime.feedHandle(feedName).handle((context) => handler({
+                ...context,
+                client: this.#handlerTrellis,
+            })));
+        }
+        const operation = {};
+        for (const operationName of Object.keys(this.#runtime.api.operations ?? {})) {
+            const registration = this.#operation(operationName);
+            const leaf = ((handler) => registration.handle((context) => handler({
+                ...context,
+                client: this.#handlerTrellis,
+            })));
+            addSurfaceLeaf(operation, operationName, leaf);
+        }
+        return { rpc, feed, operation };
+    }
+    #createSqlOutboxBinding(options) {
+        const tables = resolveSqlOutboxTables(options.tables);
+        const executor = createSqlOutboxBaseExecutor(options);
+        const repository = new SqlOutboxRepository(executor, options.dialect, tables);
+        const dispatchRuntime = {
+            publishPreparedEvent: (event) => this.#handlerTrellis.publishPrepared(event),
+            dispatchJobSubmission: (message) => AsyncResult.from((async () => {
+                try {
+                    if (!this.#jobsBinding) {
+                        return Result.ok({
+                            kind: "invalid",
+                            error: "Jobs bindings are unavailable",
+                        });
+                    }
+                    const jobsBinding = normalizeResourceJobsBinding(this.#jobsBinding);
+                    const queueBinding = jobsBinding.queues[message.name];
+                    if (!queueBinding) {
+                        return Result.ok({
+                            kind: "invalid",
+                            error: `Jobs binding for queue '${message.name}' is unavailable`,
+                        });
+                    }
+                    let submission;
+                    try {
+                        submission = Value.Parse(PreparedJobSubmissionSchema, JSON.parse(message.payload));
+                    }
+                    catch (cause) {
+                        return Result.ok({
+                            kind: "invalid",
+                            error: cause instanceof Error ? cause.message : String(cause),
+                        });
+                    }
+                    const expectedMode = message.kind === "job.create"
+                        ? "create"
+                        : "submit";
+                    const expectedSubject = `${queueBinding.publishPrefix}.${submission.jobId}.created`;
+                    if (submission.submissionId !== message.id ||
+                        submission.mode !== expectedMode ||
+                        submission.service !== jobsBinding.serviceName ||
+                        submission.queue !== message.name ||
+                        message.subject !== expectedSubject ||
+                        message.headers["request-id"] !==
+                            submission.context.requestId ||
+                        message.headers.traceparent !== submission.context.traceparent ||
+                        message.headers.tracestate !== submission.context.tracestate) {
+                        return Result.ok({
+                            kind: "invalid",
+                            error: "Outbox job submission metadata is inconsistent",
+                        });
+                    }
+                    const manager = new InternalJobManager({
+                        nc: jetstream(this.#nc),
+                        jobs: jobsBinding,
+                        keyCoordinator: createNatsJobKeyCoordinator(this.#nc),
+                    });
+                    if (submission.mode === "create") {
+                        const job = await manager.createPrepared(submission);
+                        return Result.ok({ kind: "accepted", jobId: job.id });
+                    }
+                    const outcome = await manager.submitPrepared(submission);
+                    if (outcome.kind === "accepted") {
+                        return Result.ok({
+                            kind: outcome.kind,
+                            jobId: outcome.job.id,
+                            ...(outcome.key ? { key: outcome.key } : {}),
+                        });
+                    }
+                    if (outcome.kind === "replaced") {
+                        return Result.ok({
+                            kind: outcome.kind,
+                            jobId: outcome.job.id,
+                            key: outcome.key,
+                            replaced: outcome.replaced,
+                        });
+                    }
+                    return Result.ok(outcome);
+                }
+                catch (cause) {
+                    if (cause instanceof JobNotEnqueuedError) {
+                        return Result.ok({
+                            kind: "rejected",
+                            reason: cause.reason,
+                            key: cause.key,
+                            active: cause.active,
+                            queued: cause.queued,
+                            limit: cause.limit,
+                            ...(cause.existingJobId
+                                ? { existingJobId: cause.existingJobId }
+                                : {}),
+                        });
+                    }
+                    if (cause instanceof ValidationError) {
+                        return Result.ok({ kind: "invalid", error: cause.message });
+                    }
+                    if (cause instanceof UnexpectedError) {
+                        return Result.err(cause);
+                    }
+                    return Result.err(toUnexpectedError(cause));
+                }
+            })()),
+        };
+        const dispatcher = new OutboxDispatcher(repository, dispatchRuntime, options.dispatcher);
+        this.#ownedOutboxDispatchers.add(dispatcher);
+        return {
+            dialect: options.dialect,
+            tables,
+            transaction: createSqlOutboxTransactionRunner(options),
+            dispatcher,
+            repository,
+        };
+    }
+    #createSqlOutbox(binding) {
+        return {
+            jobSubmissionOutcome: (submissionId) => AsyncResult.from((async () => {
+                try {
+                    const message = await binding.repository.get(submissionId);
+                    if (message?.state !== "dispatched") {
+                        return Result.ok(undefined);
+                    }
+                    const outcome = message.outcome;
+                    if (!outcome || typeof outcome !== "object" ||
+                        !("kind" in outcome) || typeof outcome.kind !== "string") {
+                        return Result.err(toUnexpectedError(new Error(`Outbox job submission '${submissionId}' has no valid outcome`)));
+                    }
+                    return Result.ok({ ...outcome, kind: outcome.kind });
+                }
+                catch (cause) {
+                    return Result.err(toUnexpectedError(cause));
+                }
+            })()),
+            transaction: (work) => AsyncResult.from((() => {
+                let enqueued = 0;
+                const toResultError = (cause) => {
+                    if (cause instanceof ValidationError ||
+                        cause instanceof UnexpectedError) {
+                        return Result.err(cause);
+                    }
+                    return Result.err(toUnexpectedError(cause));
+                };
+                let transaction;
+                try {
+                    transaction = binding.transaction(({ tx, executor }) => {
+                        const repository = new SqlOutboxRepository(executor, binding.dialect, binding.tables);
+                        const event = createSqlOutboxEventEnqueueFacade({
+                            event: this.event,
+                            repository,
+                            onEnqueued: () => {
+                                enqueued += 1;
+                            },
+                        });
+                        const job = createSqlOutboxJobEnqueueFacade({
+                            contractJobs: this.#contractJobs,
+                            jobsBinding: this.#jobsBinding,
+                            repository,
+                            onEnqueued: () => {
+                                enqueued += 1;
+                            },
+                        });
+                        return work({ tx, event, job });
+                    });
+                }
+                catch (cause) {
+                    return Promise.resolve(toResultError(cause));
+                }
+                return transaction.then((result) => {
+                    if (enqueued > 0)
+                        binding.dispatcher.notify();
+                    return Result.ok(result);
+                }, toResultError);
+            })()),
+        };
+    }
+    /**
+     * Creates a short-lived receive transfer grant for a caller session.
+     */
+    createTransfer(args) {
+        return AsyncResult.from(this.#operationTransfer.initiateDownload({
+            store: args.store,
+            key: args.key,
+            sessionKey: args.sessionKey,
+            permission: args.permission,
+            requiredCapabilities: args.requiredCapabilities,
+            inboxPrefix: args.inboxPrefix,
+            expiresInMs: args.expiresInMs ?? 60_000,
+        }));
+    }
+    /**
+     * Completes an operation from Trellis-owned runtime code that resolves
+     * an operation from a separate RPC handler.
+     *
+     * @internal
+     */
+    completeOperation(operationId, output) {
+        return AsyncResult.from((async () => {
+            const completed = await this.#runtime.operations.complete(operationId, output).take();
+            if (!isErr(completed))
+                return Result.ok(completed);
+            const current = await this.#runtime.operations.get(operationId).take();
+            if (!isErr(current) && current.state === "completed") {
+                if (!operationOutputsEqual(current.output, output)) {
+                    return Result.err(new UnexpectedError({
+                        cause: new Error("operation already completed with different output"),
+                    }));
+                }
+                return Result.ok(current);
+            }
+            return Result.err(completed.error);
+        })());
+    }
+    static connect(args) {
+        return AsyncResult.from((async () => {
+            const connected = await connectTrellisServiceWithRuntimeDeps(args, {});
+            if (isErr(connected)) {
+                return connected;
+            }
+            const service = connected.unwrapOrElse(() => {
+                throw new Error("Connected service result narrowed incorrectly");
+            });
+            return Result.ok(createProviderRuntime(service, args.participant));
+        })());
+    }
+    async wait() {
+        this.#waitPromise ??= (async () => {
+            try {
+                await this.#managedJobWorkers.start().orThrow();
+                const closed = await this.#nc.closed();
+                if (closed instanceof Error) {
+                    throw closed;
+                }
+            }
+            finally {
+                await this.stop();
+            }
+        })();
+        await this.#waitPromise;
+    }
+    async stop() {
+        this.#stopPromise ??= (async () => {
+            this.connection.stopObserving();
+            this.#handlerTrellis.stopEventListeners();
+            for (const dispatcher of this.#ownedOutboxDispatchers) {
+                dispatcher.stop();
+            }
+            this.#ownedOutboxDispatchers.clear();
+            try {
+                await this.#stopHealthPublishing();
+            }
+            finally {
+                try {
+                    await this.#managedJobWorkers.stop().orThrow();
+                }
+                finally {
+                    try {
+                        await this.#operationTransfer.stop();
+                    }
+                    finally {
+                        try {
+                            await this.#runtime.stop();
+                        }
+                        finally {
+                            await this.connection.close();
+                        }
+                    }
+                }
+            }
+        })();
+        await this.#stopPromise;
+    }
+    #operation(operation) {
+        const registration = this.#runtime.operationHandle(operation);
+        return {
+            handle: (handler) => registration.handle((context) => handler({
+                ...context,
+                client: this.#handlerTrellis,
+            })),
+        };
+    }
+}
+/** Public factory for connecting a descriptor-defined Trellis service. */
+export class TrellisService {
+    constructor() { }
+    /** Connects a service and returns its provider-only runtime facade. */
+    static connect(args) {
+        return TrellisServiceSession.connect(args);
+    }
+}