@qlever-llc/trellis 0.7.0 → 0.8.0-rc.3

package/esm/npm/src/server/service.js

@@ -0,0 +1,1131 @@
+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 _StoreHandle_nc, _TrellisService_server, _TrellisService_handlerTrellis, _TrellisService_operationTransfer, _TrellisService_stopHealthPublishing, _TrellisService_managedJobWorkers, _TrellisService_waitPromise, _TrellisService_stopPromise;
+import { jwtAuthenticator, } from "@nats-io/nats-core";
+import { Trellis as RootTrellis, TypedKV, TypedStore, } from "@qlever-llc/trellis";
+import { auth as trellisAuth } from "../sdk/auth.js";
+import { TrellisServiceRuntime, } from "../server.js";
+import { createAuth, estimateMidpointClockOffsetMs, SentinelCredsSchema, } from "@qlever-llc/trellis/auth";
+import { ContractResourceBindingsSchema, } from "@qlever-llc/trellis/contracts";
+import { CONTRACT_JOBS_METADATA, CONTRACT_KV_METADATA, } from "../contract_support/mod.js";
+import { AsyncResult, isErr, Result } from "@qlever-llc/result";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { ServiceHealth } from "./health.js";
+import { mountStandardHealthRpc } from "./health_rpc.js";
+import { ServiceTransfer } from "./transfer.js";
+import { logger as noopLogger } from "../globals.js";
+import { DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS, loadDefaultRuntimeTransport, selectRuntimeTransportServers, } from "../runtime_transport.js";
+import { serverLogger } from "../server_logger.js";
+import { TransportError, UnexpectedError, } from "../errors/index.js";
+import { ActiveJob as PublicActiveJob, JobRef, JobWorkerHostAdapter, } from "../jobs.js";
+import { JobManager as InternalJobManager, JobProcessError as InternalJobProcessError, } from "./internal_jobs/job-manager.js";
+import { startNatsWorkerHostFromBinding } from "./internal_jobs/runtime-worker.js";
+import { JobEventSchema, } from "./internal_jobs/types.js";
+import { observeNatsTrellisConnection, } from "../connection.js";
+const ClientTransportEndpointsSchema = Type.Object({
+    natsServers: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+});
+const ClientTransportsSchema = Type.Object({
+    native: Type.Optional(ClientTransportEndpointsSchema),
+    websocket: Type.Optional(ClientTransportEndpointsSchema),
+});
+function resolveServiceLogger(log) {
+    if (log === false) {
+        return noopLogger;
+    }
+    return log ?? serverLogger;
+}
+function getErrorCauseMessage(error) {
+    if (error && typeof error === "object") {
+        const context = error.context;
+        if (typeof context?.causeMessage === "string" &&
+            context.causeMessage.length > 0) {
+            return context.causeMessage;
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function bootstrapContractStateError(args) {
+    const base = `Service '${args.serviceName}' could not bootstrap contract '${args.contractId}' (${args.contractDigest}) during ${args.step}. ` +
+        "This usually means Trellis has stale or incomplete state for this service session. " +
+        "Re-run the service deployment apply or instance provisioning flow so Trellis records the allowed digest, permissions, and resource bindings for this instance key.";
+    const cause = args.cause
+        ? ` Underlying error: ${getErrorCauseMessage(args.cause)}`
+        : "";
+    return new Error(base + cause);
+}
+function runtimeImport(specifier) {
+    const load = new Function("specifier", "return import(specifier);");
+    return load(specifier);
+}
+async function loadDefaultServiceRuntimeDeps() {
+    const transport = await loadDefaultRuntimeTransport();
+    return {
+        connect: ({ servers, token, authenticator, inboxPrefix, ...extraOptions }) => transport.connect({
+            servers,
+            ...extraOptions,
+            ...(token ? { token } : {}),
+            ...(authenticator ? { authenticator: authenticator } : {}),
+            ...(inboxPrefix ? { inboxPrefix } : {}),
+        }),
+    };
+}
+const ServiceBootstrapReadySchema = Type.Object({
+    status: Type.Literal("ready"),
+    serverNow: Type.Integer(),
+    connectInfo: Type.Object({
+        sessionKey: Type.String({ minLength: 1 }),
+        contractId: Type.String({ minLength: 1 }),
+        contractDigest: Type.String({ minLength: 1 }),
+        transports: ClientTransportsSchema,
+        transport: Type.Object({
+            sentinel: SentinelCredsSchema,
+        }),
+        auth: Type.Object({
+            mode: Type.Literal("service_identity"),
+            iatSkewSeconds: Type.Integer({ minimum: 1 }),
+        }),
+    }),
+    binding: Type.Object({
+        contractId: Type.String({ minLength: 1 }),
+        digest: Type.String({ minLength: 1 }),
+        resources: ContractResourceBindingsSchema,
+    }),
+}, { additionalProperties: true });
+const ServiceBootstrapFailureSchema = Type.Object({
+    reason: Type.String({ minLength: 1 }),
+    message: Type.Optional(Type.String({ minLength: 1 })),
+    serverNow: Type.Optional(Type.Integer()),
+}, { additionalProperties: true });
+async function fetchServiceBootstrapInfoOnce(args) {
+    const requestStartedAtMs = Date.now();
+    const iat = args.auth.currentIat();
+    const response = await fetch(new URL("/bootstrap/service", args.trellisUrl), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            sessionKey: args.auth.sessionKey,
+            contractId: args.contractId,
+            contractDigest: args.contractDigest,
+            iat,
+            sig: await args.auth.natsConnectSigForIat(iat, args.contractDigest),
+        }),
+    });
+    const responseReceivedAtMs = Date.now();
+    const responseText = await response.text();
+    let payload;
+    try {
+        payload = JSON.parse(responseText);
+    }
+    catch {
+        payload = undefined;
+    }
+    return {
+        response,
+        responseText,
+        payload,
+        requestStartedAtMs,
+        responseReceivedAtMs,
+    };
+}
+async function fetchServiceBootstrapInfo(args) {
+    let settled = await fetchServiceBootstrapInfoOnce(args);
+    if (!settled.response.ok &&
+        settled.payload !== undefined &&
+        Value.Check(ServiceBootstrapFailureSchema, settled.payload)) {
+        const failure = settled.payload;
+        if (failure.reason === "iat_out_of_range" &&
+            typeof failure.serverNow === "number") {
+            args.auth.setServerClockOffsetMs(estimateMidpointClockOffsetMs({
+                requestStartedAtMs: settled.requestStartedAtMs,
+                responseReceivedAtMs: settled.responseReceivedAtMs,
+                serverNowSeconds: failure.serverNow,
+            }));
+            settled = await fetchServiceBootstrapInfoOnce(args);
+        }
+    }
+    if (!settled.response.ok) {
+        if (settled.payload !== undefined &&
+            Value.Check(ServiceBootstrapFailureSchema, settled.payload)) {
+            const failure = settled.payload;
+            throw new TransportError({
+                code: "trellis.bootstrap.failed",
+                message: `Service bootstrap failed: ${failure.message ?? failure.reason}`,
+                hint: "Retry the connection. If it keeps failing, check Trellis bootstrap availability and contract activation.",
+                context: {
+                    trellisUrl: args.trellisUrl,
+                    contractId: args.contractId,
+                    contractDigest: args.contractDigest,
+                    status: settled.response.status,
+                    reason: failure.reason,
+                },
+            });
+        }
+        const detail = settled.responseText.trim();
+        throw new TransportError({
+            code: "trellis.bootstrap.failed",
+            message: detail.length > 0
+                ? `Service bootstrap failed with HTTP ${settled.response.status}: ${detail}`
+                : `Service bootstrap failed with HTTP ${settled.response.status}`,
+            hint: "Retry the connection. If it keeps failing, check Trellis bootstrap availability.",
+            context: {
+                trellisUrl: args.trellisUrl,
+                contractId: args.contractId,
+                contractDigest: args.contractDigest,
+                status: settled.response.status,
+            },
+        });
+    }
+    if (settled.payload === undefined) {
+        throw new TransportError({
+            code: "trellis.bootstrap.invalid_response",
+            message: `Service bootstrap returned invalid JSON: ${settled.responseText.trim() || "<empty body>"}`,
+            hint: "Retry the connection. If it keeps happening, check the Trellis deployment.",
+            context: {
+                trellisUrl: args.trellisUrl,
+                contractId: args.contractId,
+                contractDigest: args.contractDigest,
+            },
+        });
+    }
+    const ready = Value.Parse(ServiceBootstrapReadySchema, settled.payload);
+    args.auth.setServerClockOffsetMs(estimateMidpointClockOffsetMs({
+        requestStartedAtMs: settled.requestStartedAtMs,
+        responseReceivedAtMs: settled.responseReceivedAtMs,
+        serverNowSeconds: ready.serverNow,
+    }));
+    return ready;
+}
+export class StoreHandle {
+    constructor(nc, binding) {
+        Object.defineProperty(this, "binding", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        _StoreHandle_nc.set(this, void 0);
+        __classPrivateFieldSet(this, _StoreHandle_nc, nc, "f");
+        this.binding = binding;
+    }
+    open() {
+        return TypedStore.open(__classPrivateFieldGet(this, _StoreHandle_nc, "f"), 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));
+    }
+}
+_StoreHandle_nc = new WeakMap();
+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");
+export async function createConnectedService(args) {
+    const resolvedLog = resolveServiceLogger(args.server.log);
+    const connection = observeNatsTrellisConnection({
+        kind: "service",
+        nc: args.nc,
+        log: false,
+        lifecycleLog: {
+            log: resolvedLog,
+            context: { service: args.name },
+        },
+    });
+    const currentApi = (args.server.trellisApi ?? args.server.api);
+    const runtimeApi = {
+        ...currentApi,
+        rpc: {
+            ...trellisAuth.API.owned.rpc,
+            ...currentApi.rpc,
+        },
+    };
+    const server = TrellisServiceRuntime.create(args.name, args.nc, { sessionKey: args.auth.sessionKey, sign: args.auth.sign }, {
+        log: resolvedLog,
+        timeout: args.server.timeout,
+        stream: args.server.stream,
+        noResponderRetry: args.server.noResponderRetry,
+        api: runtimeApi,
+        connection,
+        transferSupport: {
+            openOperationTransfer: (transferArgs) => getTransfer().createOperationUpload(transferArgs),
+        },
+        version: args.server.version,
+    });
+    const outbound = new RootTrellis(args.name, args.nc, { sessionKey: args.auth.sessionKey, sign: args.auth.sign }, {
+        log: resolvedLog,
+        timeout: args.server.timeout,
+        stream: args.server.stream,
+        noResponderRetry: args.server.noResponderRetry,
+        api: runtimeApi,
+        connection,
+    });
+    let transfer;
+    const getTransfer = () => {
+        if (!transfer) {
+            throw new Error("service transfer helper accessed before initialization");
+        }
+        return transfer;
+    };
+    let handlerResources;
+    const getHandlerResources = () => {
+        if (!handlerResources) {
+            throw new Error("service resource handles accessed before initialization");
+        }
+        return handlerResources;
+    };
+    const handlerTrellis = {
+        request: outbound.request.bind(outbound),
+        publish: (event, data) => outbound.publish(event, data),
+        event: (event, subjectData, fn, opts) => outbound.event(event, subjectData, fn, opts),
+        operation: (operation) => outbound.operation(operation),
+        get kv() {
+            return getHandlerResources().kv;
+        },
+        get store() {
+            return getHandlerResources().store;
+        },
+        get jobs() {
+            return getHandlerResources().jobs;
+        },
+    };
+    const trellis = Object.assign(outbound, {
+        mount: (method, fn) => server.mountRuntime(method, async ({ input, context }) => await Promise.resolve(fn({
+            input: input,
+            context,
+            trellis: handlerTrellis,
+        }))),
+    });
+    const health = new ServiceHealth({
+        serviceName: args.name,
+        contractId: args.contractId ?? "unknown",
+        contractDigest: args.contractDigest ?? "unknown",
+        publishIntervalMs: args.server.health?.publishIntervalMs ?? 30_000,
+        checks: args.server.healthChecks,
+    });
+    health.add("nats", () => ({
+        status: args.nc.isClosed() ? "failed" : "ok",
+        ...(args.nc.isClosed() ? { summary: "NATS connection closed" } : {}),
+    }));
+    await mountStandardHealthRpc(server, {
+        response: () => health.response(),
+    });
+    const heartbeatEventEnabled = Boolean(currentApi.events?.["Health.Heartbeat"]);
+    let healthPublishTimer;
+    let publishingHeartbeat = false;
+    const publishHealthHeartbeat = async () => {
+        if (!heartbeatEventEnabled || publishingHeartbeat) {
+            return;
+        }
+        publishingHeartbeat = true;
+        try {
+            const heartbeat = await health.heartbeat();
+            const published = await outbound.publish("Health.Heartbeat", heartbeat);
+            const value = published.take();
+            if (isErr(value)) {
+                resolvedLog.warn({ error: value.error }, "Failed to publish health heartbeat");
+            }
+        }
+        catch (error) {
+            resolvedLog.warn({ error }, "Failed to build or publish health heartbeat");
+        }
+        finally {
+            publishingHeartbeat = false;
+        }
+    };
+    const stopHealthPublishing = async () => {
+        if (healthPublishTimer !== undefined) {
+            clearInterval(healthPublishTimer);
+            healthPublishTimer = undefined;
+        }
+    };
+    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 StoreHandle(args.nc, binding),
+        ])),
+    });
+    const service = new TrellisService(args.name, args.auth, args.nc, server, trellis, handlerTrellis, kv, args.contractJobs, args.bindings, operationTransfer, health, stopHealthPublishing, connection);
+    handlerResources = {
+        kv: service.kv,
+        store: service.store,
+        jobs: service.jobs,
+    };
+    transfer = operationTransfer;
+    if (heartbeatEventEnabled) {
+        await publishHealthHeartbeat();
+        healthPublishTimer = setInterval(() => {
+            void publishHealthHeartbeat();
+        }, health.publishIntervalMs);
+        void args.nc.closed().finally(stopHealthPublishing);
+    }
+    return service;
+}
+function toUnexpectedError(cause) {
+    return cause instanceof UnexpectedError
+        ? cause
+        : new UnexpectedError({ cause });
+}
+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 === "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 } : {}),
+    };
+    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 "completed":
+            return {
+                ...base,
+                completedAt: event.timestamp,
+                ...(event.result !== undefined ? { result: event.result } : {}),
+            };
+        case "failed":
+        case "cancelled":
+        case "expired":
+        case "dead":
+        case "dismissed":
+            return event.error === undefined ? base : {
+                ...base,
+                lastError: event.error,
+            };
+    }
+    return base;
+}
+function createJobLifecycleTracker(nc) {
+    const snapshots = 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);
+        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);
+            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;
+        },
+        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();
+        },
+    };
+}
+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((async () => {
+            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,
+                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)));
+            }
+            catch (cause) {
+                return Result.err(toUnexpectedError(cause));
+            }
+            return Result.ok(args.lifecycle.apply(event) ?? current);
+        })()),
+    });
+}
+function createNoopJobWorkerHost() {
+    return new JobWorkerHostAdapter({
+        stop: () => AsyncResult.ok(undefined),
+        join: () => AsyncResult.ok(undefined),
+    });
+}
+async function closeFailedServiceBootstrapConnection(nc) {
+    if (nc.isClosed()) {
+        return;
+    }
+    try {
+        await nc.drain();
+    }
+    catch {
+        await nc.closed().catch(() => undefined);
+    }
+}
+function createJobsFacade(args) {
+    const handlers = new Map();
+    const jobsFacade = {};
+    const lifecycle = createJobLifecycleTracker(args.nc);
+    let activeHost;
+    let startupPromise;
+    let stopPromise;
+    for (const queueType of Object.keys(args.contractJobs ?? {})) {
+        const queueBinding = args.jobsBinding?.queues[queueType];
+        if (queueBinding)
+            lifecycle.watch(queueBinding);
+        jobsFacade[queueType] = {
+            create: (payload) => AsyncResult.from((async () => {
+                try {
+                    const jobsBinding = args.jobsBinding;
+                    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 manager = new InternalJobManager({
+                        nc: args.nc,
+                        jobs: jobsBinding,
+                    });
+                    await args.nc.flush();
+                    const created = await manager.create(queueType, payload);
+                    return Result.ok(createJobRef({
+                        nc: args.nc,
+                        queueType,
+                        jobsBinding,
+                        queueBinding,
+                        seed: created,
+                        lifecycle,
+                    }));
+                }
+                catch (cause) {
+                    return Result.err(toUnexpectedError(cause));
+                }
+            })()),
+            handle: (handler) => {
+                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`);
+                }
+                handlers.set(queueType, async (job) => await handler({
+                    job,
+                    trellis: args.trellis,
+                }));
+            },
+        };
+    }
+    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 (!args.jobsBinding || !args.workStream) {
+                    return Result.err(toUnexpectedError(new Error("Jobs infrastructure bindings are unavailable for this service")));
+                }
+                const jobsBinding = args.jobsBinding;
+                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 handler = handlers.get(queueType);
+                        if (!handler) {
+                            throw new Error(`No job handler registered for queue '${queueType}'`);
+                        }
+                        const manager = new InternalJobManager({
+                            nc: args.nc,
+                            jobs: jobsBinding,
+                        });
+                        const host = await startNatsWorkerHostFromBinding({
+                            jobs: jobsBinding,
+                            workStream,
+                        }, {
+                            nats: args.nc,
+                            instanceId: `${args.serviceName}-worker`,
+                            queueTypes: [queueType],
+                            manager,
+                            getProjectedJob: async (job) => {
+                                return lifecycle.get({
+                                    service: job.service,
+                                    jobType: job.type,
+                                    id: job.id,
+                                });
+                            },
+                            handler: async (job) => {
+                                const publicJob = new PublicActiveJob(createJobRef({
+                                    nc: args.nc,
+                                    queueType,
+                                    jobsBinding,
+                                    queueBinding,
+                                    seed: job.job(),
+                                    lifecycle,
+                                }), job.job().payload, () => job.isCancelled(), {
+                                    heartbeat: () => wrapVoidTask(() => job.heartbeat()),
+                                    progress: (value) => wrapVoidTask(() => job.updateProgress(value)),
+                                    log: (entry) => wrapVoidTask(() => job.log(entry.level, entry.message)),
+                                    redeliveryCount: job.redeliveryCount(),
+                                });
+                                const handled = (await handler(publicJob)).take();
+                                if (isErr(handled)) {
+                                    throw InternalJobProcessError.failed(handled.error.message);
+                                }
+                                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) {
+                    lifecycle.stop();
+                    return Result.ok(undefined);
+                }
+                const host = activeHost;
+                try {
+                    return await host.stop();
+                }
+                finally {
+                    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;
+}
+export class TrellisService {
+    constructor(name, auth, nc, server, trellis, handlerTrellis, kv, contractJobs, bindings, operationTransfer, health, stopHealthPublishing, connection) {
+        Object.defineProperty(this, "name", {
+            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, "nc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        _TrellisService_server.set(this, void 0);
+        Object.defineProperty(this, "trellis", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        _TrellisService_handlerTrellis.set(this, void 0);
+        Object.defineProperty(this, "kv", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "jobs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "health", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Framework-neutral lifecycle handle for the service runtime connection. */
+        Object.defineProperty(this, "connection", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        _TrellisService_operationTransfer.set(this, void 0);
+        _TrellisService_stopHealthPublishing.set(this, void 0);
+        _TrellisService_managedJobWorkers.set(this, void 0);
+        _TrellisService_waitPromise.set(this, void 0);
+        _TrellisService_stopPromise.set(this, void 0);
+        const storeBindings = bindings.store ?? {};
+        this.name = name;
+        this.auth = auth;
+        this.nc = nc;
+        __classPrivateFieldSet(this, _TrellisService_server, server, "f");
+        Object.defineProperty(this, "server", {
+            value: server,
+            enumerable: false,
+        });
+        this.trellis = trellis;
+        __classPrivateFieldSet(this, _TrellisService_handlerTrellis, handlerTrellis, "f");
+        this.kv = kv;
+        this.store = Object.fromEntries(Object.entries(storeBindings).map(([alias, binding]) => [alias, new StoreHandle(nc, binding)]));
+        __classPrivateFieldSet(this, _TrellisService_operationTransfer, operationTransfer, "f");
+        const jobs = createJobsFacade({
+            serviceName: name,
+            nc,
+            contractJobs,
+            trellis: handlerTrellis,
+            jobsBinding: bindings.jobs,
+            workStream: bindings.jobs?.workStream,
+        });
+        this.jobs = jobs;
+        __classPrivateFieldSet(this, _TrellisService_managedJobWorkers, jobs[MANAGED_JOB_WORKERS], "f");
+        this.health = health;
+        this.connection = connection;
+        __classPrivateFieldSet(this, _TrellisService_stopHealthPublishing, stopHealthPublishing, "f");
+    }
+    /**
+     * Creates a short-lived receive transfer grant for a caller session.
+     */
+    createTransfer(args) {
+        return AsyncResult.from(__classPrivateFieldGet(this, _TrellisService_operationTransfer, "f").initiateDownload({
+            store: args.store,
+            key: args.key,
+            sessionKey: args.sessionKey,
+            expiresInMs: args.expiresInMs ?? 60_000,
+        }));
+    }
+    /**
+     * Completes an operation from Trellis-owned control-plane code that resolves
+     * an operation from a separate RPC handler.
+     *
+     * @internal
+     */
+    completeOperation(operationId, output) {
+        return AsyncResult.from((async () => {
+            const completed = await __classPrivateFieldGet(this, _TrellisService_server, "f").operations.complete(operationId, output).take();
+            if (!isErr(completed))
+                return Result.ok(completed);
+            const current = await __classPrivateFieldGet(this, _TrellisService_server, "f").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, deps) {
+        return AsyncResult.from((async () => {
+            try {
+                const runtimeDeps = {
+                    ...(await loadDefaultServiceRuntimeDeps()),
+                    ...deps,
+                };
+                const auth = await createAuth({ sessionKeySeed: args.sessionKeySeed });
+                const bootstrap = await fetchServiceBootstrapInfo({
+                    trellisUrl: args.trellisUrl,
+                    contractId: args.contract.CONTRACT_ID,
+                    contractDigest: args.contract.CONTRACT_DIGEST,
+                    auth,
+                });
+                const { authenticator: authTokenAuthenticator, inboxPrefix } = await auth
+                    .natsConnectOptions({
+                    contractDigest: args.contract.CONTRACT_DIGEST,
+                });
+                let nc;
+                try {
+                    nc = await runtimeDeps.connect({
+                        servers: selectRuntimeTransportServers(bootstrap.connectInfo.transports),
+                        maxReconnectAttempts: DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS,
+                        inboxPrefix,
+                        authenticator: [
+                            authTokenAuthenticator,
+                            jwtAuthenticator(bootstrap.connectInfo.transport.sentinel.jwt, new TextEncoder().encode(bootstrap.connectInfo.transport.sentinel.seed)),
+                        ],
+                    });
+                }
+                catch (cause) {
+                    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.contract.CONTRACT_ID,
+                            contractDigest: args.contract.CONTRACT_DIGEST,
+                        },
+                    });
+                }
+                try {
+                    return Result.ok(await createConnectedService({
+                        name: args.name,
+                        auth,
+                        nc,
+                        contractId: args.contract.CONTRACT_ID,
+                        contractDigest: args.contract.CONTRACT_DIGEST,
+                        contractJobs: (args.contract[CONTRACT_JOBS_METADATA] ?? {}),
+                        contractKv: (args.contract[CONTRACT_KV_METADATA] ?? {}),
+                        server: {
+                            ...(args.server ?? {}),
+                            api: args.contract.API.owned,
+                            trellisApi: args.contract.API.trellis,
+                        },
+                        bindings: bootstrap.binding.resources,
+                    }));
+                }
+                catch (cause) {
+                    await closeFailedServiceBootstrapConnection(nc);
+                    throw cause;
+                }
+            }
+            catch (cause) {
+                return Result.err(cause instanceof TransportError ? cause : toUnexpectedError(cause));
+            }
+        })());
+    }
+    /**
+     * Starts managed job workers for registered handlers and waits for shutdown.
+     */
+    async wait() {
+        __classPrivateFieldSet(this, _TrellisService_waitPromise, __classPrivateFieldGet(this, _TrellisService_waitPromise, "f") ?? (async () => {
+            try {
+                await __classPrivateFieldGet(this, _TrellisService_managedJobWorkers, "f").start().orThrow();
+                const closed = await this.nc.closed();
+                if (closed instanceof Error) {
+                    throw closed;
+                }
+            }
+            finally {
+                await this.stop();
+            }
+        })(), "f");
+        await __classPrivateFieldGet(this, _TrellisService_waitPromise, "f");
+    }
+    async stop() {
+        __classPrivateFieldSet(this, _TrellisService_stopPromise, __classPrivateFieldGet(this, _TrellisService_stopPromise, "f") ?? (async () => {
+            this.connection.stopObserving();
+            try {
+                await __classPrivateFieldGet(this, _TrellisService_stopHealthPublishing, "f").call(this);
+            }
+            finally {
+                try {
+                    await __classPrivateFieldGet(this, _TrellisService_managedJobWorkers, "f").stop().orThrow();
+                }
+                finally {
+                    try {
+                        await __classPrivateFieldGet(this, _TrellisService_operationTransfer, "f").stop();
+                    }
+                    finally {
+                        await __classPrivateFieldGet(this, _TrellisService_server, "f").stop();
+                    }
+                }
+            }
+        })(), "f");
+        await __classPrivateFieldGet(this, _TrellisService_stopPromise, "f");
+    }
+    request(method, input, opts) {
+        return this.trellis.request(method, input, opts);
+    }
+    operation(operation) {
+        const registration = __classPrivateFieldGet(this, _TrellisService_server, "f").operation(operation);
+        return {
+            accept: (args) => registration.accept(args),
+            handle: (handler) => registration.handle((context) => handler({
+                ...context,
+                trellis: __classPrivateFieldGet(this, _TrellisService_handlerTrellis, "f"),
+            })),
+        };
+    }
+}
+_TrellisService_server = new WeakMap(), _TrellisService_handlerTrellis = new WeakMap(), _TrellisService_operationTransfer = new WeakMap(), _TrellisService_stopHealthPublishing = new WeakMap(), _TrellisService_managedJobWorkers = new WeakMap(), _TrellisService_waitPromise = new WeakMap(), _TrellisService_stopPromise = new WeakMap();