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

package/script/js/packages/trellis/contract_support/mod.js

@@ -0,0 +1,1001 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapSchema = exports.schema = exports.isJsonValue = exports.digestJson = exports.canonicalizeJson = exports.CATALOG_FORMAT_V1 = exports.CONTRACT_FORMAT_V1 = exports.StreamResourceBindingSchema = exports.StoreResourceBindingSchema = exports.PaginatedSchema = exports.KvResourceBindingSchema = exports.JobsResourceBindingSchema = exports.JobsQueueBindingSchema = exports.IsoDateSchema = exports.InstalledServiceContractSchema = exports.EventHeaderSchema = exports.ContractStreamResourceSchema = exports.ContractStoreResourceSchema = exports.ContractSchemaRefSchema = exports.ContractResourcesSchema = exports.ContractResourceBindingsSchema = exports.ContractKvResourceSchema = exports.ContractJobsResourceSchema = exports.ContractJobQueueResourceSchema = void 0;
+exports.defineError = defineError;
+exports.defineServiceContract = defineServiceContract;
+exports.defineAppContract = defineAppContract;
+exports.definePortalContract = definePortalContract;
+exports.defineCliContract = defineCliContract;
+exports.defineDeviceContract = defineDeviceContract;
+const typebox_1 = __importDefault(require("typebox"));
+const TrellisError_ts_1 = require("../errors/TrellisError.js");
+const canonical_ts_1 = require("./canonical.js");
+Object.defineProperty(exports, "canonicalizeJson", { enumerable: true, get: function () { return canonical_ts_1.canonicalizeJson; } });
+Object.defineProperty(exports, "digestJson", { enumerable: true, get: function () { return canonical_ts_1.digestJson; } });
+Object.defineProperty(exports, "isJsonValue", { enumerable: true, get: function () { return canonical_ts_1.isJsonValue; } });
+const runtime_ts_1 = require("./runtime.js");
+Object.defineProperty(exports, "schema", { enumerable: true, get: function () { return runtime_ts_1.schema; } });
+Object.defineProperty(exports, "unwrapSchema", { enumerable: true, get: function () { return runtime_ts_1.unwrapSchema; } });
+const schema_pointers_ts_1 = require("./schema_pointers.js");
+var protocol_ts_1 = require("./protocol.js");
+Object.defineProperty(exports, "ContractJobQueueResourceSchema", { enumerable: true, get: function () { return protocol_ts_1.ContractJobQueueResourceSchema; } });
+Object.defineProperty(exports, "ContractJobsResourceSchema", { enumerable: true, get: function () { return protocol_ts_1.ContractJobsResourceSchema; } });
+Object.defineProperty(exports, "ContractKvResourceSchema", { enumerable: true, get: function () { return protocol_ts_1.ContractKvResourceSchema; } });
+Object.defineProperty(exports, "ContractResourceBindingsSchema", { enumerable: true, get: function () { return protocol_ts_1.ContractResourceBindingsSchema; } });
+Object.defineProperty(exports, "ContractResourcesSchema", { enumerable: true, get: function () { return protocol_ts_1.ContractResourcesSchema; } });
+Object.defineProperty(exports, "ContractSchemaRefSchema", { enumerable: true, get: function () { return protocol_ts_1.ContractSchemaRefSchema; } });
+Object.defineProperty(exports, "ContractStoreResourceSchema", { enumerable: true, get: function () { return protocol_ts_1.ContractStoreResourceSchema; } });
+Object.defineProperty(exports, "ContractStreamResourceSchema", { enumerable: true, get: function () { return protocol_ts_1.ContractStreamResourceSchema; } });
+Object.defineProperty(exports, "EventHeaderSchema", { enumerable: true, get: function () { return protocol_ts_1.EventHeaderSchema; } });
+Object.defineProperty(exports, "InstalledServiceContractSchema", { enumerable: true, get: function () { return protocol_ts_1.InstalledServiceContractSchema; } });
+Object.defineProperty(exports, "IsoDateSchema", { enumerable: true, get: function () { return protocol_ts_1.IsoDateSchema; } });
+Object.defineProperty(exports, "JobsQueueBindingSchema", { enumerable: true, get: function () { return protocol_ts_1.JobsQueueBindingSchema; } });
+Object.defineProperty(exports, "JobsResourceBindingSchema", { enumerable: true, get: function () { return protocol_ts_1.JobsResourceBindingSchema; } });
+Object.defineProperty(exports, "KvResourceBindingSchema", { enumerable: true, get: function () { return protocol_ts_1.KvResourceBindingSchema; } });
+Object.defineProperty(exports, "PaginatedSchema", { enumerable: true, get: function () { return protocol_ts_1.PaginatedSchema; } });
+Object.defineProperty(exports, "StoreResourceBindingSchema", { enumerable: true, get: function () { return protocol_ts_1.StoreResourceBindingSchema; } });
+Object.defineProperty(exports, "StreamResourceBindingSchema", { enumerable: true, get: function () { return protocol_ts_1.StreamResourceBindingSchema; } });
+exports.CONTRACT_FORMAT_V1 = "trellis.contract.v1";
+exports.CATALOG_FORMAT_V1 = "trellis.catalog.v1";
+const CONTRACT_MODULE_METADATA = Symbol.for("@qlever-llc/trellis/contracts/contract-module");
+const CONTRACT_ERROR_RUNTIME_METADATA = Symbol.for("@qlever-llc/trellis/contracts/error-runtime");
+const RESERVED_DEFINED_ERROR_FIELD_NAMES = new Set([
+    "id",
+    "type",
+    "message",
+    "context",
+    "traceId",
+    "cause",
+]);
+const DEFINED_ERROR_PAYLOAD = Symbol.for("@qlever-llc/trellis/contracts/defined-error-payload");
+function createSchemaRef(_schemas) {
+    void _schemas;
+    return (schemaName) => ({ schema: schemaName });
+}
+function getContractErrorType(errorClass) {
+    const explicitType = Reflect.get(errorClass, "type");
+    return typeof explicitType === "string" ? explicitType : errorClass.name;
+}
+function isTransportErrorData(value) {
+    return !!value && typeof value === "object" &&
+        typeof value.id === "string" &&
+        typeof value.type === "string" &&
+        typeof value.message === "string";
+}
+function isErrorClass(value) {
+    return typeof value === "function" &&
+        typeof Reflect.get(value, "name") === "string" &&
+        typeof Reflect.get(value, "fromSerializable") === "function" &&
+        typeof Reflect.get(value, "schema") === "object";
+}
+function assertNoReservedDefinedErrorFieldNames(fields) {
+    for (const fieldName of Object.keys(fields)) {
+        if (RESERVED_DEFINED_ERROR_FIELD_NAMES.has(fieldName)) {
+            throw new Error(`Defined error field '${fieldName}' is reserved`);
+        }
+    }
+}
+function createDefinedErrorSchema(type, fields) {
+    return typebox_1.default.Object({
+        id: typebox_1.default.String(),
+        type: typebox_1.default.Literal(type),
+        message: typebox_1.default.String(),
+        ...fields,
+        context: typebox_1.default.Optional(typebox_1.default.Record(typebox_1.default.String(), typebox_1.default.Unknown())),
+        traceId: typebox_1.default.Optional(typebox_1.default.String()),
+    });
+}
+function definedErrorPayloadFieldNames(fields) {
+    return Object.keys(fields);
+}
+function pickDefinedErrorPayload(fieldNames, source) {
+    return Object.fromEntries(fieldNames.map((fieldName) => [fieldName, source[fieldName]]));
+}
+function definedErrorBaseOptions(options) {
+    const baseOptions = {};
+    if (options.cause !== undefined) {
+        baseOptions.cause = options.cause;
+    }
+    if (options.context !== undefined) {
+        baseOptions.context = options.context;
+    }
+    if (options.id !== undefined) {
+        baseOptions.id = options.id;
+    }
+    if (options.traceId !== undefined) {
+        baseOptions.traceId = options.traceId;
+    }
+    return baseOptions;
+}
+function attachDefinedErrorPayload(error, payload) {
+    error[DEFINED_ERROR_PAYLOAD] = payload;
+    return Object.assign(error, payload);
+}
+function createContractRefBuilder(registry) {
+    const schemaRef = registry.schemas
+        ? createSchemaRef(registry.schemas)
+        : undefined;
+    return {
+        schema(schemaName) {
+            if (!schemaRef) {
+                throw new Error(`Contract builder ref.schema('${schemaName}') requires a schemas registry`);
+            }
+            return schemaRef(schemaName);
+        },
+        error(errorName) {
+            return errorName;
+        },
+    };
+}
+function cloneSchema(schemaValue) {
+    const cloned = JSON.parse(JSON.stringify(schemaValue));
+    if (!(0, canonical_ts_1.isJsonValue)(cloned)) {
+        throw new Error("Contract schema is not JSON-serializable");
+    }
+    return cloned;
+}
+function cloneSchemas(schemas) {
+    if (!schemas) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(schemas).map(([name, schemaValue]) => [name, cloneSchema(schemaValue)]));
+}
+function getErrorRuntimeSchema(errorDecl) {
+    const errorClass = getContractErrorRuntimeClass(errorDecl);
+    const runtimeSchema = errorClass
+        ? Reflect.get(errorClass, "schema")
+        : undefined;
+    if (!runtimeSchema || typeof runtimeSchema !== "object") {
+        return undefined;
+    }
+    return runtimeSchema;
+}
+function createContractErrorDecl(errorClass) {
+    const errorDecl = {
+        type: getContractErrorType(errorClass),
+    };
+    return attachContractErrorRuntimeMetadata(errorDecl, errorClass);
+}
+function normalizeErrorRegistry(errors) {
+    if (!errors) {
+        return undefined;
+    }
+    const normalizedEntries = Object.entries(errors).flatMap(([key, value]) => isErrorClass(value) ? [[key, createContractErrorDecl(value)]] : []);
+    if (normalizedEntries.length === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(normalizedEntries);
+}
+function getErrorClassRegistry(errors) {
+    if (!errors) {
+        return undefined;
+    }
+    const classEntries = Object.entries(errors).flatMap(([key, value]) => isErrorClass(value) ? [[key, value]] : []);
+    if (classEntries.length === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(classEntries);
+}
+function findMatchingSchemaName(schemas, targetSchema) {
+    if (!schemas) {
+        return undefined;
+    }
+    const targetDigest = digestCanonicalJson(cloneSchema(targetSchema));
+    for (const [schemaName, schemaValue] of Object.entries(schemas)) {
+        if (schemaValue === targetSchema) {
+            return schemaName;
+        }
+        if (digestCanonicalJson(cloneSchema(schemaValue)) === targetDigest) {
+            return schemaName;
+        }
+    }
+    return undefined;
+}
+function chooseDerivedErrorSchemaName(schemas, errorName, errorType) {
+    const baseNames = [`${errorType}Data`, `${errorName}Data`];
+    for (const baseName of baseNames) {
+        if (!Object.hasOwn(schemas, baseName)) {
+            return baseName;
+        }
+    }
+    let suffix = 2;
+    while (true) {
+        const candidate = `${errorType}Data${suffix}`;
+        if (!Object.hasOwn(schemas, candidate)) {
+            return candidate;
+        }
+        suffix += 1;
+    }
+}
+function materializeErrorSchemas(schemas, errors) {
+    if (!errors) {
+        return schemas;
+    }
+    let mergedSchemas = schemas;
+    for (const [errorName, errorDecl] of Object.entries(errors)) {
+        if (errorDecl.schema) {
+            continue;
+        }
+        const runtimeSchema = getErrorRuntimeSchema(errorDecl);
+        if (!runtimeSchema) {
+            continue;
+        }
+        if (findMatchingSchemaName(mergedSchemas, runtimeSchema)) {
+            continue;
+        }
+        mergedSchemas = { ...(mergedSchemas ?? {}) };
+        const derivedSchemaName = chooseDerivedErrorSchemaName(mergedSchemas, errorName, errorDecl.type);
+        mergedSchemas[derivedSchemaName] = runtimeSchema;
+    }
+    return mergedSchemas;
+}
+function assertSchemaRefExists(schemas, ref, context) {
+    if (!schemas || !Object.hasOwn(schemas, ref.schema)) {
+        throw new Error(`${context} references unknown schema '${ref.schema}'`);
+    }
+}
+function resolveSchemaRef(schemas, ref, context) {
+    assertSchemaRefExists(schemas, ref, context);
+    return cloneSchema(schemas[ref.schema]);
+}
+function digestCanonicalJson(value) {
+    return (0, canonical_ts_1.sha256Base64urlSync)((0, canonical_ts_1.canonicalizeJson)(value));
+}
+function rpcSubject(name, version) {
+    return `rpc.${version}.${name}`;
+}
+function operationSubject(name, version) {
+    return `operations.${version}.${name}`;
+}
+function eventSubject(name, version, params) {
+    const suffix = params && params.length > 0
+        ? `.${params.map((pointer) => `{${pointer}}`).join(".")}`
+        : "";
+    return `events.${version}.${name}${suffix}`;
+}
+function emitResources(resources) {
+    if (!resources?.kv && !resources?.store && !resources?.streams &&
+        !resources?.jobs) {
+        return undefined;
+    }
+    return {
+        ...(resources.kv
+            ? {
+                kv: Object.fromEntries(Object.entries(resources.kv).map(([alias, resource]) => [
+                    alias,
+                    {
+                        purpose: resource.purpose,
+                        required: resource.required ?? true,
+                        history: resource.history ?? 1,
+                        ttlMs: resource.ttlMs ?? 0,
+                        ...(resource.maxValueBytes
+                            ? { maxValueBytes: resource.maxValueBytes }
+                            : {}),
+                    },
+                ])),
+            }
+            : {}),
+        ...(resources.store
+            ? {
+                store: Object.fromEntries(Object.entries(resources.store).map(([alias, resource]) => [
+                    alias,
+                    {
+                        purpose: resource.purpose,
+                        required: resource.required ?? true,
+                        ttlMs: resource.ttlMs ?? 0,
+                        ...(resource.maxObjectBytes !== undefined
+                            ? { maxObjectBytes: resource.maxObjectBytes }
+                            : {}),
+                        ...(resource.maxTotalBytes !== undefined
+                            ? { maxTotalBytes: resource.maxTotalBytes }
+                            : {}),
+                    },
+                ])),
+            }
+            : {}),
+        ...(resources.streams
+            ? {
+                streams: Object.fromEntries(Object.entries(resources.streams).map(([alias, resource]) => [
+                    alias,
+                    {
+                        purpose: resource.purpose,
+                        required: resource.required ?? true,
+                        ...(resource.retention ? { retention: resource.retention } : {}),
+                        ...(resource.storage ? { storage: resource.storage } : {}),
+                        ...(resource.numReplicas !== undefined
+                            ? { numReplicas: resource.numReplicas }
+                            : {}),
+                        ...(resource.maxAgeMs !== undefined
+                            ? { maxAgeMs: resource.maxAgeMs }
+                            : {}),
+                        ...(resource.maxBytes !== undefined
+                            ? { maxBytes: resource.maxBytes }
+                            : {}),
+                        ...(resource.maxMsgs !== undefined
+                            ? { maxMsgs: resource.maxMsgs }
+                            : {}),
+                        ...(resource.discard ? { discard: resource.discard } : {}),
+                        subjects: [...resource.subjects],
+                        ...(resource.sources
+                            ? {
+                                sources: resource.sources.map((source) => ({
+                                    fromAlias: source.fromAlias,
+                                    ...(source.filterSubject
+                                        ? { filterSubject: source.filterSubject }
+                                        : {}),
+                                    ...(source.subjectTransformDest
+                                        ? { subjectTransformDest: source.subjectTransformDest }
+                                        : {}),
+                                })),
+                            }
+                            : {}),
+                    },
+                ])),
+            }
+            : {}),
+        ...(resources.jobs
+            ? {
+                jobs: {
+                    queues: Object.fromEntries(Object.entries(resources.jobs.queues).map(([queueType, queue]) => [
+                        queueType,
+                        {
+                            payload: { ...queue.payload },
+                            ...(queue.result ? { result: { ...queue.result } } : {}),
+                            ...(queue.maxDeliver !== undefined
+                                ? { maxDeliver: queue.maxDeliver }
+                                : {}),
+                            ...(queue.backoffMs ? { backoffMs: [...queue.backoffMs] } : {}),
+                            ...(queue.ackWaitMs !== undefined
+                                ? { ackWaitMs: queue.ackWaitMs }
+                                : {}),
+                            ...(queue.defaultDeadlineMs !== undefined
+                                ? { defaultDeadlineMs: queue.defaultDeadlineMs }
+                                : {}),
+                            ...(queue.progress !== undefined
+                                ? { progress: queue.progress }
+                                : {}),
+                            ...(queue.logs !== undefined ? { logs: queue.logs } : {}),
+                            ...(queue.dlq !== undefined ? { dlq: queue.dlq } : {}),
+                            ...(queue.concurrency !== undefined
+                                ? { concurrency: queue.concurrency }
+                                : {}),
+                        },
+                    ])),
+                },
+            }
+            : {}),
+    };
+}
+function emitUses(uses) {
+    if (!uses) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(uses).map(([alias, use]) => [
+        alias,
+        {
+            contract: use.contract,
+            ...(use.rpc?.call ? { rpc: { call: [...use.rpc.call] } } : {}),
+            ...(use.operations?.call
+                ? { operations: { call: [...use.operations.call] } }
+                : {}),
+            ...((use.events?.publish || use.events?.subscribe)
+                ? {
+                    events: {
+                        ...(use.events.publish
+                            ? { publish: [...use.events.publish] }
+                            : {}),
+                        ...(use.events.subscribe
+                            ? { subscribe: [...use.events.subscribe] }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...((use.subjects?.publish || use.subjects?.subscribe)
+                ? {
+                    subjects: {
+                        ...(use.subjects.publish
+                            ? { publish: [...use.subjects.publish] }
+                            : {}),
+                        ...(use.subjects.subscribe
+                            ? { subscribe: [...use.subjects.subscribe] }
+                            : {}),
+                    },
+                }
+                : {}),
+        },
+    ]));
+}
+function emitContract(source) {
+    const rpc = source.rpc
+        ? Object.fromEntries(Object.entries(source.rpc).map(([name, method]) => {
+            const emitted = {
+                version: method.version,
+                subject: method.subject ?? rpcSubject(name, method.version),
+                input: { ...method.input },
+                output: { ...method.output },
+            };
+            if (method.capabilities?.call) {
+                emitted.capabilities = { call: [...method.capabilities.call] };
+            }
+            if (method.errors && method.errors.length > 0) {
+                emitted.errors = method.errors.map((errorName) => ({
+                    type: source.errors?.[errorName]?.type ?? errorName,
+                }));
+            }
+            return [name, emitted];
+        }))
+        : undefined;
+    const operations = source.operations
+        ? Object.fromEntries(Object.entries(source.operations).map(([name, operation]) => {
+            if (operation.transfer) {
+                const store = source.resources?.store?.[operation.transfer.store];
+                if (!store) {
+                    throw new Error(`Operation '${name}' references unknown store resource '${operation.transfer.store}'`);
+                }
+                const inputSchema = resolveSchemaRef(source.schemas, operation.input, `operation '${name}' input`);
+                for (const pointer of [
+                    operation.transfer.key,
+                    operation.transfer.contentType,
+                    operation.transfer.metadata,
+                ]) {
+                    if (!pointer) {
+                        continue;
+                    }
+                    if ((0, schema_pointers_ts_1.getSubschemaAtDataPointer)(inputSchema, pointer) === undefined) {
+                        throw new Error(`Invalid transfer pointer '${pointer}' for operation '${name}' (path not found in input schema)`);
+                    }
+                }
+            }
+            const emitted = {
+                version: operation.version,
+                subject: operation.subject ??
+                    operationSubject(name, operation.version),
+                input: { ...operation.input },
+            };
+            if (operation.progress) {
+                emitted.progress = { ...operation.progress };
+            }
+            if (operation.output) {
+                emitted.output = { ...operation.output };
+            }
+            if (operation.transfer) {
+                emitted.transfer = { ...operation.transfer };
+            }
+            if (operation.capabilities?.call || operation.capabilities?.read ||
+                operation.capabilities?.cancel) {
+                emitted.capabilities = {
+                    ...(operation.capabilities.call
+                        ? { call: [...operation.capabilities.call] }
+                        : {}),
+                    ...(operation.capabilities.read
+                        ? { read: [...operation.capabilities.read] }
+                        : {}),
+                    ...(operation.capabilities.cancel
+                        ? { cancel: [...operation.capabilities.cancel] }
+                        : {}),
+                };
+            }
+            if (operation.cancel !== undefined) {
+                emitted.cancel = operation.cancel;
+            }
+            return [name, emitted];
+        }))
+        : undefined;
+    const events = source.events
+        ? Object.fromEntries(Object.entries(source.events).map(([name, event]) => {
+            if (event.params && event.params.length > 0) {
+                (0, schema_pointers_ts_1.assertDataPointersExistAndAreTokenable)(name, resolveSchemaRef(source.schemas, event.event, `event '${name}'`), event.params);
+            }
+            const emitted = {
+                version: event.version,
+                subject: event.subject ??
+                    eventSubject(name, event.version, event.params),
+                event: { ...event.event },
+            };
+            if (event.params && event.params.length > 0) {
+                emitted.params = [...event.params];
+            }
+            if (event.capabilities?.publish || event.capabilities?.subscribe) {
+                emitted.capabilities = {
+                    ...(event.capabilities.publish
+                        ? { publish: [...event.capabilities.publish] }
+                        : {}),
+                    ...(event.capabilities.subscribe
+                        ? { subscribe: [...event.capabilities.subscribe] }
+                        : {}),
+                };
+            }
+            return [name, emitted];
+        }))
+        : undefined;
+    const subjects = source.subjects
+        ? Object.fromEntries(Object.entries(source.subjects).map(([name, subject]) => {
+            const emitted = {
+                subject: subject.subject,
+            };
+            if (subject.message) {
+                emitted.message = { ...subject.message };
+            }
+            if (subject.capabilities?.publish || subject.capabilities?.subscribe) {
+                emitted.capabilities = {
+                    ...(subject.capabilities.publish
+                        ? { publish: [...subject.capabilities.publish] }
+                        : {}),
+                    ...(subject.capabilities.subscribe
+                        ? { subscribe: [...subject.capabilities.subscribe] }
+                        : {}),
+                };
+            }
+            return [name, emitted];
+        }))
+        : undefined;
+    const errors = source.errors
+        ? Object.fromEntries(Object.entries(source.errors).map(([name, error]) => {
+            const emitted = { type: error.type };
+            const schemaRef = resolveErrorSchemaRef(source.schemas, name, error);
+            if (schemaRef) {
+                emitted.schema = { ...schemaRef };
+            }
+            return [name, emitted];
+        }))
+        : undefined;
+    const resources = emitResources(source.resources);
+    const uses = emitUses(source.uses);
+    return {
+        format: exports.CONTRACT_FORMAT_V1,
+        id: source.id,
+        displayName: source.displayName,
+        description: source.description,
+        kind: source.kind,
+        ...(source.schemas ? { schemas: cloneSchemas(source.schemas) } : {}),
+        ...(uses ? { uses } : {}),
+        ...(rpc ? { rpc } : {}),
+        ...(operations ? { operations } : {}),
+        ...(events ? { events } : {}),
+        ...(subjects ? { subjects } : {}),
+        ...(errors ? { errors } : {}),
+        ...(resources ? { resources } : {}),
+    };
+}
+function buildOwnedApi(source) {
+    const localRuntimeErrors = {};
+    for (const [name, errorDecl] of Object.entries(source.errors ?? {})) {
+        const errorClass = getContractErrorRuntimeClass(errorDecl);
+        if (!errorClass) {
+            continue;
+        }
+        const errorSchemaRef = resolveErrorSchemaRef(source.schemas, name, errorDecl);
+        localRuntimeErrors[name] = {
+            type: errorDecl.type,
+            ...(errorSchemaRef
+                ? {
+                    schema: (0, runtime_ts_1.schema)(resolveSchemaRef(source.schemas, errorSchemaRef, `error '${name}' schema`)),
+                }
+                : {}),
+            fromSerializable(data) {
+                if (!isTransportErrorData(data)) {
+                    throw new Error(`Transport error '${errorDecl.type}' is missing base error fields`);
+                }
+                return errorClass.fromSerializable(data);
+            },
+        };
+    }
+    const rpc = {};
+    for (const [name, method] of Object.entries(source.rpc ?? {})) {
+        rpc[name] = {
+            subject: method.subject ?? rpcSubject(name, method.version),
+            input: (0, runtime_ts_1.schema)(resolveSchemaRef(source.schemas, method.input, `rpc '${name}' input`)),
+            output: (0, runtime_ts_1.schema)(resolveSchemaRef(source.schemas, method.output, `rpc '${name}' output`)),
+            callerCapabilities: method.capabilities?.call ?? [],
+            authRequired: method.authRequired ?? true,
+            errors: method.errors,
+            declaredErrorTypes: method.errors?.map((errorName) => source.errors?.[errorName]?.type ?? errorName),
+            runtimeErrors: method.errors?.flatMap((errorName) => {
+                const runtimeError = localRuntimeErrors[errorName];
+                return runtimeError ? [runtimeError] : [];
+            }),
+        };
+    }
+    const operations = Object.fromEntries(Object.entries(source.operations ?? {}).map(([name, operation]) => [
+        name,
+        {
+            subject: operation.subject ?? operationSubject(name, operation.version),
+            input: (0, runtime_ts_1.schema)(resolveSchemaRef(source.schemas, operation.input, `operation '${name}' input`)),
+            progress: operation.progress
+                ? (0, runtime_ts_1.schema)(resolveSchemaRef(source.schemas, operation.progress, `operation '${name}' progress`))
+                : undefined,
+            output: operation.output
+                ? (0, runtime_ts_1.schema)(resolveSchemaRef(source.schemas, operation.output, `operation '${name}' output`))
+                : undefined,
+            transfer: operation.transfer
+                ? { ...operation.transfer }
+                : undefined,
+            callerCapabilities: operation.capabilities?.call ?? [],
+            readCapabilities: operation.capabilities?.read ?? [],
+            cancelCapabilities: operation.capabilities?.cancel ?? [],
+            cancel: operation.cancel,
+        },
+    ]));
+    const events = Object.fromEntries(Object.entries(source.events ?? {}).map(([name, event]) => {
+        if (event.params && event.params.length > 0) {
+            (0, schema_pointers_ts_1.assertDataPointersExistAndAreTokenable)(name, resolveSchemaRef(source.schemas, event.event, `event '${name}'`), event.params);
+        }
+        return [
+            name,
+            {
+                subject: event.subject ??
+                    eventSubject(name, event.version, event.params),
+                params: event.params,
+                event: (0, runtime_ts_1.schema)(resolveSchemaRef(source.schemas, event.event, `event '${name}'`)),
+                publishCapabilities: event.capabilities?.publish ?? [],
+                subscribeCapabilities: event.capabilities?.subscribe ?? [],
+            },
+        ];
+    }));
+    const subjects = Object.fromEntries(Object.entries(source.subjects ?? {}).map(([name, subject]) => [
+        name,
+        {
+            subject: subject.subject,
+            schema: subject.message
+                ? (0, runtime_ts_1.schema)(resolveSchemaRef(source.schemas, subject.message, `subject '${name}'`))
+                : undefined,
+            publishCapabilities: subject.capabilities?.publish ?? [],
+            subscribeCapabilities: subject.capabilities?.subscribe ?? [],
+        },
+    ]));
+    return { rpc, operations, events, subjects };
+}
+function mergeRecord(kind, out, next) {
+    for (const [key, value] of Object.entries(next)) {
+        if (Object.hasOwn(out, key)) {
+            throw new Error(`Duplicate ${kind} key '${key}' while deriving contract API`);
+        }
+        out[key] = value;
+    }
+}
+function assertSelectedKeysExist(contractId, kind, keys, api) {
+    if (!keys) {
+        return;
+    }
+    for (const key of keys) {
+        if (!Object.hasOwn(api, key)) {
+            throw new Error(`Contract '${contractId}' does not expose ${kind} key '${key}'`);
+        }
+    }
+}
+function assertValidUseSpec(contractId, spec, api) {
+    assertSelectedKeysExist(contractId, "rpc", spec.rpc?.call, api.rpc);
+    assertSelectedKeysExist(contractId, "operations", spec.operations?.call, api.operations);
+    assertSelectedKeysExist(contractId, "events", spec.events?.publish, api.events);
+    assertSelectedKeysExist(contractId, "events", spec.events?.subscribe, api.events);
+    assertSelectedKeysExist(contractId, "subjects", spec.subjects?.publish, api.subjects);
+    assertSelectedKeysExist(contractId, "subjects", spec.subjects?.subscribe, api.subjects);
+}
+function attachContractModuleMetadata(value, contractModule) {
+    Object.defineProperty(value, CONTRACT_MODULE_METADATA, {
+        value: contractModule,
+        enumerable: false,
+    });
+    return value;
+}
+function attachContractErrorRuntimeMetadata(value, errorClass) {
+    Object.defineProperty(value, CONTRACT_ERROR_RUNTIME_METADATA, {
+        value: errorClass,
+        enumerable: false,
+    });
+    return value;
+}
+function getContractErrorRuntimeClass(errorDecl) {
+    const value = Object.getOwnPropertyDescriptor(errorDecl, CONTRACT_ERROR_RUNTIME_METADATA)?.value;
+    if (isErrorClass(value)) {
+        return value;
+    }
+    return undefined;
+}
+function resolveErrorSchemaRef(schemas, errorName, errorDecl) {
+    if (errorDecl.schema) {
+        return errorDecl.schema;
+    }
+    const runtimeSchema = getErrorRuntimeSchema(errorDecl);
+    if (!runtimeSchema) {
+        return undefined;
+    }
+    const schemaName = findMatchingSchemaName(schemas, runtimeSchema);
+    if (schemaName) {
+        return { schema: schemaName };
+    }
+    throw new Error(`error '${errorName}' schema must be declared in contract.schemas`);
+}
+/**
+ * Define a transportable Trellis error class from a payload-object schema.
+ *
+ * The returned value is a real runtime error class that carries the wire schema
+ * and reconstruction logic needed by `defineServiceContract(...)`.
+ */
+function defineError(options) {
+    var _a;
+    assertNoReservedDefinedErrorFieldNames(options.fields);
+    const errorSchema = createDefinedErrorSchema(options.type, options.fields);
+    const fieldNames = definedErrorPayloadFieldNames(options.fields);
+    class DefinedErrorImpl extends TrellisError_ts_1.TrellisError {
+        constructor(payload) {
+            const customPayload = pickDefinedErrorPayload(fieldNames, payload);
+            const message = typeof options.message === "function"
+                ? options.message(customPayload)
+                : options.message;
+            super(message, definedErrorBaseOptions(payload));
+            Object.defineProperty(this, "name", {
+                enumerable: true,
+                configurable: true,
+                writable: true,
+                value: options.type
+            });
+            Object.defineProperty(this, _a, {
+                enumerable: true,
+                configurable: true,
+                writable: true,
+                value: void 0
+            });
+            this[DEFINED_ERROR_PAYLOAD] = customPayload;
+            Object.assign(this, customPayload);
+        }
+        static fromSerializable(data) {
+            const customPayload = pickDefinedErrorPayload(fieldNames, data);
+            const ErrorCtor = DefinedErrorImpl;
+            const error = new ErrorCtor({
+                ...customPayload,
+                id: data.id,
+                context: data.context,
+                traceId: data.traceId,
+            });
+            error[DEFINED_ERROR_PAYLOAD] = customPayload;
+            return Object.assign(error, customPayload);
+        }
+        toSerializable() {
+            return {
+                ...this.baseSerializable(),
+                type: this.name,
+                ...this[DEFINED_ERROR_PAYLOAD],
+            };
+        }
+    }
+    _a = DEFINED_ERROR_PAYLOAD;
+    Object.defineProperty(DefinedErrorImpl, "type", {
+        enumerable: true,
+        configurable: true,
+        writable: true,
+        value: options.type
+    });
+    Object.defineProperty(DefinedErrorImpl, "schema", {
+        enumerable: true,
+        configurable: true,
+        writable: true,
+        value: errorSchema
+    });
+    // @ts-expect-error TypeScript cannot model the dynamically assigned payload
+    // fields on the generated class instance constructor return type.
+    return DefinedErrorImpl;
+}
+function createUseHelper(getContractModule) {
+    return ((spec) => {
+        const contractModule = getContractModule();
+        assertValidUseSpec(contractModule.CONTRACT_ID, spec, contractModule.API.owned);
+        const dependencyUse = {
+            contract: contractModule.CONTRACT_ID,
+            ...(spec.rpc?.call ? { rpc: { call: [...spec.rpc.call] } } : {}),
+            ...(spec.operations?.call
+                ? { operations: { call: [...spec.operations.call] } }
+                : {}),
+            ...((spec.events?.publish || spec.events?.subscribe)
+                ? {
+                    events: {
+                        ...(spec.events.publish
+                            ? { publish: [...spec.events.publish] }
+                            : {}),
+                        ...(spec.events.subscribe
+                            ? { subscribe: [...spec.events.subscribe] }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...((spec.subjects?.publish || spec.subjects?.subscribe)
+                ? {
+                    subjects: {
+                        ...(spec.subjects.publish
+                            ? { publish: [...spec.subjects.publish] }
+                            : {}),
+                        ...(spec.subjects.subscribe
+                            ? { subscribe: [...spec.subjects.subscribe] }
+                            : {}),
+                    },
+                }
+                : {}),
+        };
+        return attachContractModuleMetadata(dependencyUse, contractModule);
+    });
+}
+function getContractModuleFromUse(alias, useValue) {
+    const contractModule = Object.getOwnPropertyDescriptor(useValue, CONTRACT_MODULE_METADATA)?.value;
+    if (!contractModule) {
+        throw new Error(`Contract use '${alias}' must be created with contractModule.use(...) from @qlever-llc/trellis/contracts`);
+    }
+    return contractModule;
+}
+function normalizeUses(uses) {
+    if (!uses) {
+        return {
+            manifestUses: undefined,
+            usedApi: { rpc: {}, operations: {}, events: {}, subjects: {} },
+        };
+    }
+    const manifestUses = {};
+    const usedApi = {
+        rpc: {},
+        operations: {},
+        events: {},
+        subjects: {},
+    };
+    for (const [alias, useValue] of Object.entries(uses)) {
+        const contractModule = getContractModuleFromUse(alias, useValue);
+        const rpcCall = useValue.rpc?.call;
+        const operationsCall = useValue.operations?.call;
+        const eventsPublish = useValue.events?.publish;
+        const eventsSubscribe = useValue.events?.subscribe;
+        const subjectsPublish = useValue.subjects?.publish;
+        const subjectsSubscribe = useValue.subjects?.subscribe;
+        if (useValue.contract !== contractModule.CONTRACT_ID) {
+            throw new Error(`Contract use '${alias}' references '${useValue.contract}' but module id is '${contractModule.CONTRACT_ID}'`);
+        }
+        assertValidUseSpec(contractModule.CONTRACT_ID, {
+            ...(rpcCall ? { rpc: { call: rpcCall } } : {}),
+            ...(operationsCall ? { operations: { call: operationsCall } } : {}),
+            ...((eventsPublish || eventsSubscribe)
+                ? {
+                    events: {
+                        ...(eventsPublish ? { publish: eventsPublish } : {}),
+                        ...(eventsSubscribe ? { subscribe: eventsSubscribe } : {}),
+                    },
+                }
+                : {}),
+            ...((subjectsPublish || subjectsSubscribe)
+                ? {
+                    subjects: {
+                        ...(subjectsPublish ? { publish: subjectsPublish } : {}),
+                        ...(subjectsSubscribe ? { subscribe: subjectsSubscribe } : {}),
+                    },
+                }
+                : {}),
+        }, contractModule.API.owned);
+        manifestUses[alias] = {
+            contract: contractModule.CONTRACT_ID,
+            ...(rpcCall ? { rpc: { call: [...rpcCall] } } : {}),
+            ...(operationsCall ? { operations: { call: [...operationsCall] } } : {}),
+            ...((eventsPublish || eventsSubscribe)
+                ? {
+                    events: {
+                        ...(eventsPublish ? { publish: [...eventsPublish] } : {}),
+                        ...(eventsSubscribe ? { subscribe: [...eventsSubscribe] } : {}),
+                    },
+                }
+                : {}),
+            ...((subjectsPublish || subjectsSubscribe)
+                ? {
+                    subjects: {
+                        ...(subjectsPublish ? { publish: [...subjectsPublish] } : {}),
+                        ...(subjectsSubscribe ? { subscribe: [...subjectsSubscribe] } : {}),
+                    },
+                }
+                : {}),
+        };
+        const rpcKeys = selectedKeys(rpcCall);
+        if (rpcKeys.length > 0) {
+            mergeRecord("rpc", usedApi.rpc, Object.fromEntries(rpcKeys.map((key) => [key, contractModule.API.owned.rpc[key]])));
+        }
+        const operationKeys = selectedKeys(operationsCall);
+        if (operationKeys.length > 0) {
+            mergeRecord("operations", usedApi.operations, Object.fromEntries(operationKeys.map((key) => [key, contractModule.API.owned.operations[key]])));
+        }
+        const eventKeys = new Set([
+            ...selectedKeys(eventsPublish),
+            ...selectedKeys(eventsSubscribe),
+        ]);
+        if (eventKeys.size > 0) {
+            mergeRecord("events", usedApi.events, Object.fromEntries([...eventKeys].map((key) => [key, contractModule.API.owned.events[key]])));
+        }
+        const subjectKeys = new Set([
+            ...selectedKeys(subjectsPublish),
+            ...selectedKeys(subjectsSubscribe),
+        ]);
+        if (subjectKeys.size > 0) {
+            mergeRecord("subjects", usedApi.subjects, Object.fromEntries([...subjectKeys].map((key) => [key, contractModule.API.owned.subjects[key]])));
+        }
+    }
+    return { manifestUses, usedApi };
+}
+function selectedKeys(keys) {
+    return keys ?? [];
+}
+function mergeApiSection(kind, usedEntries, ownedEntries) {
+    const merged = {};
+    mergeRecord(kind, merged, usedEntries);
+    mergeRecord(kind, merged, ownedEntries);
+    return merged;
+}
+function mergeDerivedApis(ownedApi, usedApi) {
+    return {
+        rpc: mergeApiSection("rpc", usedApi.rpc, ownedApi.rpc),
+        operations: mergeApiSection("operations", usedApi.operations, ownedApi.operations),
+        events: mergeApiSection("events", usedApi.events, ownedApi.events),
+        subjects: mergeApiSection("subjects", usedApi.subjects, ownedApi.subjects),
+    };
+}
+function defineContract(registry, build) {
+    const errorClasses = getErrorClassRegistry(registry.errors);
+    const normalizedErrors = normalizeErrorRegistry(registry.errors);
+    const body = build(createContractRefBuilder({
+        ...(registry.schemas ? { schemas: registry.schemas } : {}),
+        ...(errorClasses ? { errors: errorClasses } : {}),
+    }));
+    const materializedSchemas = materializeErrorSchemas(registry.schemas, normalizedErrors);
+    const source = {
+        ...body,
+        ...(materializedSchemas ? { schemas: materializedSchemas } : {}),
+        ...(normalizedErrors ? { errors: normalizedErrors } : {}),
+    };
+    const { manifestUses, usedApi } = normalizeUses(source.uses);
+    const emittedSource = {
+        id: source.id,
+        displayName: source.displayName,
+        description: source.description,
+        kind: source.kind,
+        ...(source.schemas ? { schemas: source.schemas } : {}),
+        ...(manifestUses ? { uses: manifestUses } : {}),
+        ...(source.rpc ? { rpc: source.rpc } : {}),
+        ...(source.operations ? { operations: source.operations } : {}),
+        ...(source.events ? { events: source.events } : {}),
+        ...(source.subjects ? { subjects: source.subjects } : {}),
+        ...(source.errors ? { errors: source.errors } : {}),
+        ...(source.resources ? { resources: source.resources } : {}),
+    };
+    const ownedApi = buildOwnedApi(emittedSource);
+    const trellisApi = mergeDerivedApis(ownedApi, usedApi);
+    const CONTRACT = emitContract(emittedSource);
+    const CONTRACT_DIGEST = digestCanonicalJson(CONTRACT);
+    let contract;
+    contract = {
+        CONTRACT_ID: source.id,
+        CONTRACT,
+        CONTRACT_DIGEST,
+        API: {
+            owned: ownedApi,
+            used: usedApi,
+            trellis: trellisApi,
+        },
+        use: createUseHelper(() => contract),
+    };
+    return contract;
+}
+function defineServiceContract(registry, build) {
+    return defineContract(registry, (ref) => ({
+        ...build(ref),
+        kind: "service",
+    }));
+}
+function defineClientContract(kind, build) {
+    return defineContract({}, () => ({ ...build(), kind }));
+}
+function defineAppContract(build) {
+    return defineClientContract("app", build);
+}
+function definePortalContract(build) {
+    return defineClientContract("portal", build);
+}
+function defineCliContract(build) {
+    return defineClientContract("cli", build);
+}
+function defineDeviceContract(build) {
+    return defineClientContract("device", build);
+}