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

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

@@ -0,0 +1,1137 @@
+"use strict";
+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;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrellisService = exports.StoreHandle = void 0;
+exports.createConnectedService = createConnectedService;
+const nats_core_1 = require("@nats-io/nats-core");
+const trellis_1 = require("@qlever-llc/trellis");
+const auth_js_1 = require("../sdk/auth.js");
+const server_js_1 = require("../server.js");
+const auth_1 = require("@qlever-llc/trellis/auth");
+const contracts_1 = require("@qlever-llc/trellis/contracts");
+const mod_js_1 = require("../contract_support/mod.js");
+const result_1 = require("@qlever-llc/result");
+const typebox_1 = require("typebox");
+const value_1 = require("typebox/value");
+const health_js_1 = require("./health.js");
+const health_rpc_js_1 = require("./health_rpc.js");
+const transfer_js_1 = require("./transfer.js");
+const globals_js_1 = require("../globals.js");
+const runtime_transport_js_1 = require("../runtime_transport.js");
+const server_logger_js_1 = require("../server_logger.js");
+const index_js_1 = require("../errors/index.js");
+const jobs_js_1 = require("../jobs.js");
+const job_manager_js_1 = require("./internal_jobs/job-manager.js");
+const runtime_worker_js_1 = require("./internal_jobs/runtime-worker.js");
+const types_js_1 = require("./internal_jobs/types.js");
+const connection_js_1 = require("../connection.js");
+const ClientTransportEndpointsSchema = typebox_1.Type.Object({
+    natsServers: typebox_1.Type.Array(typebox_1.Type.String({ minLength: 1 }), { minItems: 1 }),
+});
+const ClientTransportsSchema = typebox_1.Type.Object({
+    native: typebox_1.Type.Optional(ClientTransportEndpointsSchema),
+    websocket: typebox_1.Type.Optional(ClientTransportEndpointsSchema),
+});
+function resolveServiceLogger(log) {
+    if (log === false) {
+        return globals_js_1.logger;
+    }
+    return log ?? server_logger_js_1.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 (0, runtime_transport_js_1.loadDefaultRuntimeTransport)();
+    return {
+        connect: ({ servers, token, authenticator, inboxPrefix, ...extraOptions }) => transport.connect({
+            servers,
+            ...extraOptions,
+            ...(token ? { token } : {}),
+            ...(authenticator ? { authenticator: authenticator } : {}),
+            ...(inboxPrefix ? { inboxPrefix } : {}),
+        }),
+    };
+}
+const ServiceBootstrapReadySchema = typebox_1.Type.Object({
+    status: typebox_1.Type.Literal("ready"),
+    serverNow: typebox_1.Type.Integer(),
+    connectInfo: typebox_1.Type.Object({
+        sessionKey: typebox_1.Type.String({ minLength: 1 }),
+        contractId: typebox_1.Type.String({ minLength: 1 }),
+        contractDigest: typebox_1.Type.String({ minLength: 1 }),
+        transports: ClientTransportsSchema,
+        transport: typebox_1.Type.Object({
+            sentinel: auth_1.SentinelCredsSchema,
+        }),
+        auth: typebox_1.Type.Object({
+            mode: typebox_1.Type.Literal("service_identity"),
+            iatSkewSeconds: typebox_1.Type.Integer({ minimum: 1 }),
+        }),
+    }),
+    binding: typebox_1.Type.Object({
+        contractId: typebox_1.Type.String({ minLength: 1 }),
+        digest: typebox_1.Type.String({ minLength: 1 }),
+        resources: contracts_1.ContractResourceBindingsSchema,
+    }),
+}, { additionalProperties: true });
+const ServiceBootstrapFailureSchema = typebox_1.Type.Object({
+    reason: typebox_1.Type.String({ minLength: 1 }),
+    message: typebox_1.Type.Optional(typebox_1.Type.String({ minLength: 1 })),
+    serverNow: typebox_1.Type.Optional(typebox_1.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_1.Value.Check(ServiceBootstrapFailureSchema, settled.payload)) {
+        const failure = settled.payload;
+        if (failure.reason === "iat_out_of_range" &&
+            typeof failure.serverNow === "number") {
+            args.auth.setServerClockOffsetMs((0, auth_1.estimateMidpointClockOffsetMs)({
+                requestStartedAtMs: settled.requestStartedAtMs,
+                responseReceivedAtMs: settled.responseReceivedAtMs,
+                serverNowSeconds: failure.serverNow,
+            }));
+            settled = await fetchServiceBootstrapInfoOnce(args);
+        }
+    }
+    if (!settled.response.ok) {
+        if (settled.payload !== undefined &&
+            value_1.Value.Check(ServiceBootstrapFailureSchema, settled.payload)) {
+            const failure = settled.payload;
+            throw new index_js_1.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 index_js_1.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 index_js_1.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_1.Value.Parse(ServiceBootstrapReadySchema, settled.payload);
+    args.auth.setServerClockOffsetMs((0, auth_1.estimateMidpointClockOffsetMs)({
+        requestStartedAtMs: settled.requestStartedAtMs,
+        responseReceivedAtMs: settled.responseReceivedAtMs,
+        serverNowSeconds: ready.serverNow,
+    }));
+    return ready;
+}
+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 trellis_1.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));
+    }
+}
+exports.StoreHandle = StoreHandle;
+_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 trellis_1.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");
+async function createConnectedService(args) {
+    const resolvedLog = resolveServiceLogger(args.server.log);
+    const connection = (0, connection_js_1.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: {
+            ...auth_js_1.auth.API.owned.rpc,
+            ...currentApi.rpc,
+        },
+    };
+    const server = server_js_1.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 trellis_1.Trellis(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 health_js_1.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 (0, health_rpc_js_1.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 ((0, result_1.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 transfer_js_1.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 index_js_1.UnexpectedError
+        ? cause
+        : new index_js_1.UnexpectedError({ cause });
+}
+function okVoid() {
+    return result_1.Result.ok(undefined);
+}
+function wrapVoidTask(task) {
+    return result_1.AsyncResult.from((async () => {
+        try {
+            await task();
+            return okVoid();
+        }
+        catch (cause) {
+            return result_1.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_1.Value.Check(types_js_1.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 jobs_js_1.JobRef({
+        id: args.seed.id,
+        service: args.seed.service,
+        jobType: args.queueType,
+    }, {
+        get: () => result_1.AsyncResult.ok(args.lifecycle.get({
+            service: args.seed.service,
+            jobType: args.queueType,
+            id: args.seed.id,
+        }) ?? args.seed),
+        wait: () => result_1.AsyncResult.from((async () => {
+            try {
+                return result_1.Result.ok(await args.lifecycle.wait(args.seed));
+            }
+            catch (cause) {
+                return result_1.Result.err(toUnexpectedError(cause));
+            }
+        })()),
+        cancel: () => result_1.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_1.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_1.Result.err(toUnexpectedError(cause));
+            }
+            return result_1.Result.ok(args.lifecycle.apply(event) ?? current);
+        })()),
+    });
+}
+function createNoopJobWorkerHost() {
+    return new jobs_js_1.JobWorkerHostAdapter({
+        stop: () => result_1.AsyncResult.ok(undefined),
+        join: () => result_1.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) => result_1.AsyncResult.from((async () => {
+                try {
+                    const jobsBinding = args.jobsBinding;
+                    if (!jobsBinding) {
+                        return result_1.Result.err(toUnexpectedError(new Error("Jobs bindings are unavailable")));
+                    }
+                    const queueBinding = jobsBinding.queues[queueType];
+                    if (!queueBinding) {
+                        return result_1.Result.err(toUnexpectedError(new Error(`Jobs binding for queue '${queueType}' is unavailable`)));
+                    }
+                    const manager = new job_manager_js_1.JobManager({
+                        nc: args.nc,
+                        jobs: jobsBinding,
+                    });
+                    await args.nc.flush();
+                    const created = await manager.create(queueType, payload);
+                    return result_1.Result.ok(createJobRef({
+                        nc: args.nc,
+                        queueType,
+                        jobsBinding,
+                        queueBinding,
+                        seed: created,
+                        lifecycle,
+                    }));
+                }
+                catch (cause) {
+                    return result_1.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 result_1.AsyncResult.ok(activeHost);
+            }
+            if (startupPromise) {
+                return result_1.AsyncResult.from(startupPromise);
+            }
+            startupPromise = (async () => {
+                const selectedQueues = [...handlers.keys()];
+                if (selectedQueues.length === 0) {
+                    const host = createNoopJobWorkerHost();
+                    activeHost = host;
+                    return result_1.Result.ok(host);
+                }
+                if (!args.jobsBinding || !args.workStream) {
+                    return result_1.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 job_manager_js_1.JobManager({
+                            nc: args.nc,
+                            jobs: jobsBinding,
+                        });
+                        const host = await (0, runtime_worker_js_1.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 jobs_js_1.ActiveJob(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 ((0, result_1.isErr)(handled)) {
+                                    throw job_manager_js_1.JobProcessError.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_1.Result.err(toUnexpectedError(new AggregateError([cause, ...stopErrors])));
+                    }
+                    return result_1.Result.err(toUnexpectedError(cause));
+                }
+                activeHost = new jobs_js_1.JobWorkerHostAdapter({
+                    stop: () => wrapVoidTask(async () => {
+                        for (const host of hosts) {
+                            await host.stop();
+                        }
+                    }),
+                    join: () => result_1.AsyncResult.ok(undefined),
+                });
+                return result_1.Result.ok(activeHost);
+            })().finally(() => {
+                startupPromise = undefined;
+            });
+            return result_1.AsyncResult.from(startupPromise);
+        },
+        stop: () => {
+            if (stopPromise) {
+                return result_1.AsyncResult.from(stopPromise);
+            }
+            stopPromise = (async () => {
+                const startup = startupPromise;
+                if (startup) {
+                    const started = await startup;
+                    if ((0, result_1.isErr)(started)) {
+                        return result_1.Result.ok(undefined);
+                    }
+                }
+                if (!activeHost) {
+                    lifecycle.stop();
+                    return result_1.Result.ok(undefined);
+                }
+                const host = activeHost;
+                try {
+                    return await host.stop();
+                }
+                finally {
+                    lifecycle.stop();
+                    if (activeHost === host) {
+                        activeHost = undefined;
+                    }
+                    stopPromise = undefined;
+                }
+            })();
+            return result_1.AsyncResult.from(stopPromise);
+        },
+    };
+    Object.defineProperty(jobsFacade, MANAGED_JOB_WORKERS, {
+        value: managedWorkers,
+        enumerable: false,
+    });
+    return jobsFacade;
+}
+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 result_1.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 result_1.AsyncResult.from((async () => {
+            const completed = await __classPrivateFieldGet(this, _TrellisService_server, "f").operations.complete(operationId, output).take();
+            if (!(0, result_1.isErr)(completed))
+                return result_1.Result.ok(completed);
+            const current = await __classPrivateFieldGet(this, _TrellisService_server, "f").operations.get(operationId).take();
+            if (!(0, result_1.isErr)(current) && current.state === "completed") {
+                if (!operationOutputsEqual(current.output, output)) {
+                    return result_1.Result.err(new index_js_1.UnexpectedError({
+                        cause: new Error("operation already completed with different output"),
+                    }));
+                }
+                return result_1.Result.ok(current);
+            }
+            return result_1.Result.err(completed.error);
+        })());
+    }
+    static connect(args, deps) {
+        return result_1.AsyncResult.from((async () => {
+            try {
+                const runtimeDeps = {
+                    ...(await loadDefaultServiceRuntimeDeps()),
+                    ...deps,
+                };
+                const auth = await (0, auth_1.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: (0, runtime_transport_js_1.selectRuntimeTransportServers)(bootstrap.connectInfo.transports),
+                        maxReconnectAttempts: runtime_transport_js_1.DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS,
+                        inboxPrefix,
+                        authenticator: [
+                            authTokenAuthenticator,
+                            (0, nats_core_1.jwtAuthenticator)(bootstrap.connectInfo.transport.sentinel.jwt, new TextEncoder().encode(bootstrap.connectInfo.transport.sentinel.seed)),
+                        ],
+                    });
+                }
+                catch (cause) {
+                    throw new index_js_1.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_1.Result.ok(await createConnectedService({
+                        name: args.name,
+                        auth,
+                        nc,
+                        contractId: args.contract.CONTRACT_ID,
+                        contractDigest: args.contract.CONTRACT_DIGEST,
+                        contractJobs: (args.contract[mod_js_1.CONTRACT_JOBS_METADATA] ?? {}),
+                        contractKv: (args.contract[mod_js_1.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_1.Result.err(cause instanceof index_js_1.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"),
+            })),
+        };
+    }
+}
+exports.TrellisService = TrellisService;
+_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();