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

package/esm/contract_support/mod.js

@@ -3,10 +3,13 @@ import { TrellisError } from "../errors/TrellisError.js";
 import { canonicalizeJson, digestJson, isJsonValue, sha256Base64urlSync, } from "./canonical.js";
 import { schema, unwrapSchema, } from "./runtime.js";
 import { assertDataPointersExistAndAreTokenable, getSubschemaAtDataPointer, } from "./schema_pointers.js";
-export { ContractJobQueueResourceSchema, ContractJobsResourceSchema, ContractKvResourceSchema, ContractResourceBindingsSchema, ContractResourcesSchema, ContractSchemaRefSchema, ContractStoreResourceSchema, ContractStreamResourceSchema, EventHeaderSchema, InstalledServiceContractSchema, IsoDateSchema, JobsQueueBindingSchema, JobsResourceBindingSchema, KvResourceBindingSchema, PaginatedSchema, StoreResourceBindingSchema, StreamResourceBindingSchema, } from "./protocol.js";
+export { ContractJobQueueSchema, ContractJobsSchema, ContractKvResourceSchema, ContractResourceBindingsSchema, ContractResourcesSchema, ContractSchemaRefSchema, ContractStateSchema, ContractStateStoreSchema, ContractStoreResourceSchema, EventHeaderSchema, InstalledServiceContractSchema, IsoDateSchema, JobsQueueBindingSchema, JobsResourceBindingSchema, KvResourceBindingSchema, PaginatedSchema, StoreResourceBindingSchema, } from "./protocol.js";
 export const CONTRACT_FORMAT_V1 = "trellis.contract.v1";
 export const CATALOG_FORMAT_V1 = "trellis.catalog.v1";
 const CONTRACT_MODULE_METADATA = Symbol.for("@qlever-llc/trellis/contracts/contract-module");
+export const CONTRACT_JOBS_METADATA = Symbol.for("@qlever-llc/trellis/contracts/jobs");
+export const CONTRACT_KV_METADATA = Symbol.for("@qlever-llc/trellis/contracts/kv");
+export const CONTRACT_STATE_METADATA = Symbol.for("@qlever-llc/trellis/contracts/state");
 const CONTRACT_ERROR_RUNTIME_METADATA = Symbol.for("@qlever-llc/trellis/contracts/error-runtime");
 const RESERVED_DEFINED_ERROR_FIELD_NAMES = new Set([
     "id",
@@ -25,7 +28,7 @@ function getContractErrorType(errorClass) {
     const explicitType = Reflect.get(errorClass, "type");
     return typeof explicitType === "string" ? explicitType : errorClass.name;
 }
-function isTransportErrorData(value) {
+function isSerializableErrorData(value) {
     return !!value && typeof value === "object" &&
         typeof value.id === "string" &&
         typeof value.type === "string" &&
@@ -80,6 +83,47 @@ function attachDefinedErrorPayload(error, payload) {
     error[DEFINED_ERROR_PAYLOAD] = payload;
     return Object.assign(error, payload);
 }
+const TRELLIS_AUTH_CONTRACT_ID = "trellis.auth@v1";
+const TRELLIS_STATE_CONTRACT_ID = "trellis.state@v1";
+const BASELINE_AUTH_RPC_CALL = ["Auth.Me", "Auth.Logout"];
+const BASELINE_STATE_RPC_CALL = [
+    "State.Get",
+    "State.Put",
+    "State.Delete",
+    "State.List",
+];
+const UnknownRuntimeSchema = schema(Type.Unknown());
+function typedUnknownRuntimeSchema() {
+    return UnknownRuntimeSchema;
+}
+function trellisRpcDesc(name) {
+    return {
+        subject: rpcSubject(name, "v1"),
+        input: typedUnknownRuntimeSchema(),
+        output: typedUnknownRuntimeSchema(),
+        callerCapabilities: [],
+    };
+}
+const BASELINE_AUTH_API = {
+    rpc: {
+        "Auth.Me": trellisRpcDesc("Auth.Me"),
+        "Auth.Logout": trellisRpcDesc("Auth.Logout"),
+    },
+    operations: {},
+    events: {},
+    subjects: {},
+};
+const BASELINE_STATE_API = {
+    rpc: {
+        "State.Get": trellisRpcDesc("State.Get"),
+        "State.Put": trellisRpcDesc("State.Put"),
+        "State.Delete": trellisRpcDesc("State.Delete"),
+        "State.List": trellisRpcDesc("State.List"),
+    },
+    operations: {},
+    events: {},
+    subjects: {},
+};
 function createContractRefBuilder(registry) {
     const schemaRef = registry.schemas
         ? createSchemaRef(registry.schemas)
@@ -109,6 +153,16 @@ function cloneSchemas(schemas) {
     }
     return Object.fromEntries(Object.entries(schemas).map(([name, schemaValue]) => [name, cloneSchema(schemaValue)]));
 }
+function cloneContractExports(contractExports) {
+    if (!contractExports) {
+        return undefined;
+    }
+    return {
+        ...(contractExports.schemas
+            ? { schemas: [...contractExports.schemas] }
+            : {}),
+    };
+}
 function getErrorRuntimeSchema(errorDecl) {
     const errorClass = getContractErrorRuntimeClass(errorDecl);
     const runtimeSchema = errorClass
@@ -203,6 +257,18 @@ function assertSchemaRefExists(schemas, ref, context) {
         throw new Error(`${context} references unknown schema '${ref.schema}'`);
     }
 }
+function assertExportedSchemasExist(schemas, contractExports) {
+    for (const schemaName of contractExports?.schemas ?? []) {
+        if (!schemas || !Object.hasOwn(schemas, schemaName)) {
+            throw new Error(`contract exports reference unknown schema '${schemaName}'`);
+        }
+    }
+}
+function assertRegistryDoesNotDeclareExports(registry) {
+    if (Object.hasOwn(registry, "exports")) {
+        throw new Error("contract exports must be declared in the callback body, not the registry argument");
+    }
+}
 function resolveSchemaRef(schemas, ref, context) {
     assertSchemaRefExists(schemas, ref, context);
     return cloneSchema(schemas[ref.schema]);
@@ -210,6 +276,203 @@ function resolveSchemaRef(schemas, ref, context) {
 function digestCanonicalJson(value) {
     return sha256Base64urlSync(canonicalizeJson(value));
 }
+function sortedUnique(values) {
+    return [...new Set(values)].sort();
+}
+function collectSchemaRef(reachableSchemas, ref) {
+    if (ref) {
+        reachableSchemas.add(ref.schema);
+    }
+}
+function collectReachableSchemaNames(contract) {
+    const reachableSchemas = new Set();
+    for (const store of Object.values(contract.state ?? {})) {
+        collectSchemaRef(reachableSchemas, store.schema);
+        for (const accepted of Object.values(store.acceptedVersions ?? {})) {
+            collectSchemaRef(reachableSchemas, accepted);
+        }
+    }
+    for (const method of Object.values(contract.rpc ?? {})) {
+        collectSchemaRef(reachableSchemas, method.input);
+        collectSchemaRef(reachableSchemas, method.output);
+        for (const error of method.errors ?? []) {
+            const declaration = Object.values(contract.errors ?? {}).find((decl) => decl.type === error.type);
+            collectSchemaRef(reachableSchemas, declaration?.schema);
+        }
+    }
+    for (const operation of Object.values(contract.operations ?? {})) {
+        collectSchemaRef(reachableSchemas, operation.input);
+        collectSchemaRef(reachableSchemas, operation.progress);
+        collectSchemaRef(reachableSchemas, operation.output);
+    }
+    for (const event of Object.values(contract.events ?? {})) {
+        collectSchemaRef(reachableSchemas, event.event);
+    }
+    for (const job of Object.values(contract.jobs ?? {})) {
+        collectSchemaRef(reachableSchemas, job.payload);
+        collectSchemaRef(reachableSchemas, job.result);
+    }
+    for (const resource of Object.values(contract.resources?.kv ?? {})) {
+        collectSchemaRef(reachableSchemas, resource.schema);
+    }
+    return reachableSchemas;
+}
+function projectReachableSchemas(contract) {
+    const reachableNames = collectReachableSchemaNames(contract);
+    if (!contract.schemas || reachableNames.size === 0) {
+        return undefined;
+    }
+    const entries = Object.entries(contract.schemas).filter(([name]) => reachableNames.has(name));
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function projectRpcDeclaredErrors(contract) {
+    if (!contract.errors) {
+        return undefined;
+    }
+    const declaredErrorTypes = new Set();
+    for (const method of Object.values(contract.rpc ?? {})) {
+        for (const error of method.errors ?? []) {
+            declaredErrorTypes.add(error.type);
+        }
+    }
+    const entries = Object.entries(contract.errors).filter(([, error]) => declaredErrorTypes.has(error.type));
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function projectDigestResources(resources) {
+    if (!resources?.kv && !resources?.store) {
+        return undefined;
+    }
+    return {
+        ...(resources.kv ? { kv: resources.kv } : {}),
+        ...(resources.store ? { store: resources.store } : {}),
+    };
+}
+function projectDigestUses(uses) {
+    if (!uses) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(uses).map(([alias, use]) => [
+        alias,
+        {
+            contract: use.contract,
+            ...(use.rpc?.call ? { rpc: { call: sortedUnique(use.rpc.call) } } : {}),
+            ...(use.operations?.call
+                ? { operations: { call: sortedUnique(use.operations.call) } }
+                : {}),
+            ...((use.events?.publish || use.events?.subscribe)
+                ? {
+                    events: {
+                        ...(use.events.publish
+                            ? { publish: sortedUnique(use.events.publish) }
+                            : {}),
+                        ...(use.events.subscribe
+                            ? { subscribe: sortedUnique(use.events.subscribe) }
+                            : {}),
+                    },
+                }
+                : {}),
+        },
+    ]));
+}
+function projectDigestRpc(rpc) {
+    if (!rpc) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(rpc).map(([name, method]) => [
+        name,
+        {
+            ...method,
+            ...(method.capabilities?.call
+                ? { capabilities: { call: sortedUnique(method.capabilities.call) } }
+                : {}),
+            ...(method.errors
+                ? {
+                    errors: sortedUnique(method.errors.map((error) => error.type)).map((type) => ({ type })),
+                }
+                : {}),
+        },
+    ]));
+}
+function projectDigestOperations(operations) {
+    if (!operations) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(operations).map(([name, operation]) => [
+        name,
+        {
+            ...operation,
+            ...((operation.capabilities?.call || operation.capabilities?.read ||
+                operation.capabilities?.cancel)
+                ? {
+                    capabilities: {
+                        ...(operation.capabilities.call
+                            ? { call: sortedUnique(operation.capabilities.call) }
+                            : {}),
+                        ...(operation.capabilities.read
+                            ? { read: sortedUnique(operation.capabilities.read) }
+                            : {}),
+                        ...(operation.capabilities.cancel
+                            ? { cancel: sortedUnique(operation.capabilities.cancel) }
+                            : {}),
+                    },
+                }
+                : {}),
+        },
+    ]));
+}
+function projectDigestEvents(events) {
+    if (!events) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(events).map(([name, event]) => [
+        name,
+        {
+            ...event,
+            ...((event.capabilities?.publish || event.capabilities?.subscribe)
+                ? {
+                    capabilities: {
+                        ...(event.capabilities.publish
+                            ? { publish: sortedUnique(event.capabilities.publish) }
+                            : {}),
+                        ...(event.capabilities.subscribe
+                            ? { subscribe: sortedUnique(event.capabilities.subscribe) }
+                            : {}),
+                    },
+                }
+                : {}),
+        },
+    ]));
+}
+/**
+ * Build the normalized runtime/interface projection used for contract identity.
+ */
+export function projectContractDigestManifest(contract) {
+    const schemas = projectReachableSchemas(contract);
+    const errors = projectRpcDeclaredErrors(contract);
+    const resources = projectDigestResources(contract.resources);
+    const uses = projectDigestUses(contract.uses);
+    const rpc = projectDigestRpc(contract.rpc);
+    const operations = projectDigestOperations(contract.operations);
+    const events = projectDigestEvents(contract.events);
+    return {
+        format: contract.format,
+        id: contract.id,
+        kind: contract.kind,
+        ...(schemas ? { schemas } : {}),
+        ...(contract.state ? { state: contract.state } : {}),
+        ...(uses ? { uses } : {}),
+        ...(rpc ? { rpc } : {}),
+        ...(operations ? { operations } : {}),
+        ...(events ? { events } : {}),
+        ...(errors ? { errors } : {}),
+        ...(contract.jobs ? { jobs: contract.jobs } : {}),
+        ...(resources ? { resources } : {}),
+    };
+}
+/** Compute the v1 contract digest from the normalized digest projection. */
+export function digestContractManifest(contract) {
+    return digestCanonicalJson(projectContractDigestManifest(contract));
+}
 function rpcSubject(name, version) {
     return `rpc.${version}.${name}`;
 }
@@ -223,8 +486,7 @@ function eventSubject(name, version, params) {
     return `events.${version}.${name}${suffix}`;
 }
 function emitResources(resources) {
-    if (!resources?.kv && !resources?.store && !resources?.streams &&
-        !resources?.jobs) {
+    if (!resources?.kv && !resources?.store) {
         return undefined;
     }
     return {
@@ -234,6 +496,7 @@ function emitResources(resources) {
                     alias,
                     {
                         purpose: resource.purpose,
+                        schema: { ...resource.schema },
                         required: resource.required ?? true,
                         history: resource.history ?? 1,
                         ttlMs: resource.ttlMs ?? 0,
@@ -262,79 +525,94 @@ function emitResources(resources) {
                 ])),
             }
             : {}),
-        ...(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 emitJobs(jobs) {
+    if (!jobs) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(jobs).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 buildContractJobsMetadata(jobs) {
+    if (!jobs) {
+        return {};
+    }
+    return Object.fromEntries(Object.keys(jobs).map((queueType) => [queueType, {
+            payload: undefined,
+            result: undefined,
+        }]));
+}
+function buildContractKvMetadata(resources, schemas) {
+    const kv = resources?.kv;
+    if (!kv) {
+        return {};
+    }
+    const metadata = {};
+    for (const [alias, resource] of Object.entries(kv)) {
+        assertSchemaRefExists(schemas, resource.schema, `kv resource '${alias}'`);
+        metadata[alias] = {
+            required: resource.required ?? true,
+            value: undefined,
+            schema: schemas[resource.schema.schema],
+        };
+    }
+    return metadata;
+}
+function buildContractStateMetadata(state, schemas) {
+    if (!state) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(state).map(([storeName, store]) => [storeName, {
+            kind: store.kind,
+            value: undefined,
+            schema: resolveSchemaRef(schemas, store.schema, `state store '${storeName}'`),
+            stateVersion: store.stateVersion ?? "v1",
+            acceptedVersions: Object.fromEntries(Object.entries(store.acceptedVersions ?? {}).map(([version, schema]) => [
+                version,
+                resolveSchemaRef(schemas, schema, `state store '${storeName}' accepted version '${version}'`),
+            ])),
+        }]));
+}
+function emitState(state) {
+    if (!state) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(state).map(([storeName, store]) => [
+        storeName,
+        {
+            kind: store.kind,
+            schema: { ...store.schema },
+            ...(store.stateVersion === undefined
+                ? {}
+                : { stateVersion: store.stateVersion }),
+            ...(store.acceptedVersions === undefined
+                ? {}
+                : { acceptedVersions: store.acceptedVersions }),
+        },
+    ]));
+}
 function emitUses(uses) {
     if (!uses) {
         return undefined;
@@ -343,30 +621,18 @@ function emitUses(uses) {
         alias,
         {
             contract: use.contract,
-            ...(use.rpc?.call ? { rpc: { call: [...use.rpc.call] } } : {}),
+            ...(use.rpc?.call ? { rpc: { call: sortedUnique(use.rpc.call) } } : {}),
             ...(use.operations?.call
-                ? { operations: { call: [...use.operations.call] } }
+                ? { operations: { call: sortedUnique(use.operations.call) } }
                 : {}),
             ...((use.events?.publish || use.events?.subscribe)
                 ? {
                     events: {
                         ...(use.events.publish
-                            ? { publish: [...use.events.publish] }
+                            ? { publish: sortedUnique(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] }
+                            ? { subscribe: sortedUnique(use.events.subscribe) }
                             : {}),
                     },
                 }
@@ -384,12 +650,15 @@ function emitContract(source) {
                 output: { ...method.output },
             };
             if (method.capabilities?.call) {
-                emitted.capabilities = { call: [...method.capabilities.call] };
+                emitted.capabilities = {
+                    call: sortedUnique(method.capabilities.call),
+                };
+            }
+            if (method.transfer) {
+                emitted.transfer = { ...method.transfer };
             }
             if (method.errors && method.errors.length > 0) {
-                emitted.errors = method.errors.map((errorName) => ({
-                    type: source.errors?.[errorName]?.type ?? errorName,
-                }));
+                emitted.errors = sortedUnique(method.errors.map((errorName) => source.errors?.[errorName]?.type ?? errorName)).map((type) => ({ type }));
             }
             return [name, emitted];
         }))
@@ -420,27 +689,25 @@ function emitContract(source) {
                 subject: operation.subject ??
                     operationSubject(name, operation.version),
                 input: { ...operation.input },
+                output: { ...operation.output },
             };
             if (operation.progress) {
                 emitted.progress = { ...operation.progress };
             }
-            if (operation.output) {
-                emitted.output = { ...operation.output };
-            }
             if (operation.transfer) {
-                emitted.transfer = { ...operation.transfer };
+                emitted.transfer = { ...operation.transfer, direction: "send" };
             }
             if (operation.capabilities?.call || operation.capabilities?.read ||
                 operation.capabilities?.cancel) {
                 emitted.capabilities = {
                     ...(operation.capabilities.call
-                        ? { call: [...operation.capabilities.call] }
+                        ? { call: sortedUnique(operation.capabilities.call) }
                         : {}),
                     ...(operation.capabilities.read
-                        ? { read: [...operation.capabilities.read] }
+                        ? { read: sortedUnique(operation.capabilities.read) }
                         : {}),
                     ...(operation.capabilities.cancel
-                        ? { cancel: [...operation.capabilities.cancel] }
+                        ? { cancel: sortedUnique(operation.capabilities.cancel) }
                         : {}),
                 };
             }
@@ -467,31 +734,10 @@ function emitContract(source) {
             if (event.capabilities?.publish || event.capabilities?.subscribe) {
                 emitted.capabilities = {
                     ...(event.capabilities.publish
-                        ? { publish: [...event.capabilities.publish] }
+                        ? { publish: sortedUnique(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] }
+                        ? { subscribe: sortedUnique(event.capabilities.subscribe) }
                         : {}),
                 };
             }
@@ -508,6 +754,8 @@ function emitContract(source) {
             return [name, emitted];
         }))
         : undefined;
+    const jobs = emitJobs(source.jobs);
+    const state = emitState(source.state);
     const resources = emitResources(source.resources);
     const uses = emitUses(source.uses);
     return {
@@ -517,12 +765,16 @@ function emitContract(source) {
         description: source.description,
         kind: source.kind,
         ...(source.schemas ? { schemas: cloneSchemas(source.schemas) } : {}),
+        ...(source.exports
+            ? { exports: cloneContractExports(source.exports) }
+            : {}),
+        ...(state ? { state } : {}),
         ...(uses ? { uses } : {}),
         ...(rpc ? { rpc } : {}),
         ...(operations ? { operations } : {}),
         ...(events ? { events } : {}),
-        ...(subjects ? { subjects } : {}),
         ...(errors ? { errors } : {}),
+        ...(jobs ? { jobs } : {}),
         ...(resources ? { resources } : {}),
     };
 }
@@ -542,7 +794,7 @@ function buildOwnedApi(source) {
                 }
                 : {}),
             fromSerializable(data) {
-                if (!isTransportErrorData(data)) {
+                if (!isSerializableErrorData(data)) {
                     throw new Error(`Transport error '${errorDecl.type}' is missing base error fields`);
                 }
                 return errorClass.fromSerializable(data);
@@ -556,6 +808,7 @@ function buildOwnedApi(source) {
             input: schema(resolveSchemaRef(source.schemas, method.input, `rpc '${name}' input`)),
             output: schema(resolveSchemaRef(source.schemas, method.output, `rpc '${name}' output`)),
             callerCapabilities: method.capabilities?.call ?? [],
+            transfer: method.transfer ? { ...method.transfer } : undefined,
             authRequired: method.authRequired ?? true,
             errors: method.errors,
             declaredErrorTypes: method.errors?.map((errorName) => source.errors?.[errorName]?.type ?? errorName),
@@ -577,7 +830,7 @@ function buildOwnedApi(source) {
                 ? schema(resolveSchemaRef(source.schemas, operation.output, `operation '${name}' output`))
                 : undefined,
             transfer: operation.transfer
-                ? { ...operation.transfer }
+                ? { ...operation.transfer, direction: "send" }
                 : undefined,
             callerCapabilities: operation.capabilities?.call ?? [],
             readCapabilities: operation.capabilities?.read ?? [],
@@ -601,18 +854,7 @@ function buildOwnedApi(source) {
             },
         ];
     }));
-    const subjects = Object.fromEntries(Object.entries(source.subjects ?? {}).map(([name, subject]) => [
-        name,
-        {
-            subject: subject.subject,
-            schema: subject.message
-                ? schema(resolveSchemaRef(source.schemas, subject.message, `subject '${name}'`))
-                : undefined,
-            publishCapabilities: subject.capabilities?.publish ?? [],
-            subscribeCapabilities: subject.capabilities?.subscribe ?? [],
-        },
-    ]));
-    return { rpc, operations, events, subjects };
+    return { rpc, operations, events, subjects: {} };
 }
 function mergeRecord(kind, out, next) {
     for (const [key, value] of Object.entries(next)) {
@@ -637,8 +879,6 @@ function assertValidUseSpec(contractId, spec, api) {
     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, {
@@ -767,18 +1007,6 @@ function createUseHelper(getContractModule) {
                     },
                 }
                 : {}),
-            ...((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);
     });
@@ -810,8 +1038,6 @@ function normalizeUses(uses) {
         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}'`);
         }
@@ -826,14 +1052,6 @@ function normalizeUses(uses) {
                     },
                 }
                 : {}),
-            ...((subjectsPublish || subjectsSubscribe)
-                ? {
-                    subjects: {
-                        ...(subjectsPublish ? { publish: subjectsPublish } : {}),
-                        ...(subjectsSubscribe ? { subscribe: subjectsSubscribe } : {}),
-                    },
-                }
-                : {}),
         }, contractModule.API.owned);
         manifestUses[alias] = {
             contract: contractModule.CONTRACT_ID,
@@ -847,14 +1065,6 @@ function normalizeUses(uses) {
                     },
                 }
                 : {}),
-            ...((subjectsPublish || subjectsSubscribe)
-                ? {
-                    subjects: {
-                        ...(subjectsPublish ? { publish: [...subjectsPublish] } : {}),
-                        ...(subjectsSubscribe ? { subscribe: [...subjectsSubscribe] } : {}),
-                    },
-                }
-                : {}),
         };
         const rpcKeys = selectedKeys(rpcCall);
         if (rpcKeys.length > 0) {
@@ -871,16 +1081,107 @@ function normalizeUses(uses) {
         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 emptyApi() {
+    return { rpc: {}, operations: {}, events: {}, subjects: {} };
+}
+function addUniqueStrings(target, values) {
+    for (const value of values) {
+        if (!target.includes(value)) {
+            target.push(value);
+        }
+    }
+}
+function mergeUseIntoManifest(manifestUses, alias, use) {
+    const existing = manifestUses[alias];
+    if (!existing) {
+        manifestUses[alias] = use;
+        return;
+    }
+    if (existing.contract !== use.contract) {
+        throw new Error(`Contract use '${alias}' references both '${existing.contract}' and '${use.contract}'`);
+    }
+    const rpcCall = [...(existing.rpc?.call ?? [])];
+    addUniqueStrings(rpcCall, use.rpc?.call ?? []);
+    const operationsCall = [...(existing.operations?.call ?? [])];
+    addUniqueStrings(operationsCall, use.operations?.call ?? []);
+    const eventsPublish = [...(existing.events?.publish ?? [])];
+    addUniqueStrings(eventsPublish, use.events?.publish ?? []);
+    const eventsSubscribe = [...(existing.events?.subscribe ?? [])];
+    addUniqueStrings(eventsSubscribe, use.events?.subscribe ?? []);
+    manifestUses[alias] = {
+        contract: existing.contract,
+        ...(rpcCall.length > 0 ? { rpc: { call: rpcCall } } : {}),
+        ...(operationsCall.length > 0
+            ? { operations: { call: operationsCall } }
+            : {}),
+        ...((eventsPublish.length > 0 || eventsSubscribe.length > 0)
+            ? {
+                events: {
+                    ...(eventsPublish.length > 0 ? { publish: eventsPublish } : {}),
+                    ...(eventsSubscribe.length > 0 ? { subscribe: eventsSubscribe } : {}),
+                },
+            }
+            : {}),
+    };
+}
+function mergeApiAllowDuplicateSubject(kind, out, next) {
+    for (const [key, value] of Object.entries(next)) {
+        const existing = out[key];
+        if (existing !== undefined) {
+            const existingSubject = typeof existing === "object" && existing !== null
+                ? existing.subject
+                : undefined;
+            const nextSubject = typeof value === "object" && value !== null
+                ? value.subject
+                : undefined;
+            if (typeof existingSubject === "string" && existingSubject === nextSubject) {
+                continue;
+            }
+            throw new Error(`Duplicate ${kind} key '${key}' while deriving contract API`);
+        }
+        out[key] = value;
+    }
+}
+function mergeUseIntoApi(target, api) {
+    mergeApiAllowDuplicateSubject("rpc", target.rpc, api.rpc);
+    mergeApiAllowDuplicateSubject("operations", target.operations, api.operations);
+    mergeApiAllowDuplicateSubject("events", target.events, api.events);
+    mergeApiAllowDuplicateSubject("subjects", target.subjects, api.subjects);
+}
+function baselineUse(contract, use, api) {
+    return { manifestUse: { contract, ...use }, api };
+}
+function deriveImplicitTrellisUses(source) {
+    const uses = {};
+    if (source.kind === "app" || source.kind === "agent" || source.kind === "device") {
+        uses.auth = baselineUse(TRELLIS_AUTH_CONTRACT_ID, { rpc: { call: [...BASELINE_AUTH_RPC_CALL] } }, BASELINE_AUTH_API);
+    }
+    if (source.state) {
+        uses.state = baselineUse(TRELLIS_STATE_CONTRACT_ID, { rpc: { call: [...BASELINE_STATE_RPC_CALL] } }, BASELINE_STATE_API);
+    }
+    return uses;
+}
+function normalizeContractUses(source) {
+    const explicit = normalizeUses(source.uses);
+    const manifestUses = {
+        ...(explicit.manifestUses ?? {}),
+    };
+    const usedApi = emptyApi();
+    mergeUseIntoApi(usedApi, explicit.usedApi);
+    for (const [alias, use] of Object.entries(deriveImplicitTrellisUses(source))) {
+        mergeUseIntoManifest(manifestUses, alias, use.manifestUse);
+        mergeUseIntoApi(usedApi, use.api);
+    }
+    return {
+        manifestUses: Object.keys(manifestUses).length > 0
+            ? manifestUses
+            : undefined,
+        usedApi,
+    };
+}
 function selectedKeys(keys) {
     return keys ?? [];
 }
@@ -899,6 +1200,7 @@ function mergeDerivedApis(ownedApi, usedApi) {
     };
 }
 function defineContract(registry, build) {
+    assertRegistryDoesNotDeclareExports(registry);
     const errorClasses = getErrorClassRegistry(registry.errors);
     const normalizedErrors = normalizeErrorRegistry(registry.errors);
     const body = build(createContractRefBuilder({
@@ -911,25 +1213,28 @@ function defineContract(registry, build) {
         ...(materializedSchemas ? { schemas: materializedSchemas } : {}),
         ...(normalizedErrors ? { errors: normalizedErrors } : {}),
     };
-    const { manifestUses, usedApi } = normalizeUses(source.uses);
+    assertExportedSchemasExist(source.schemas, source.exports);
+    const { manifestUses, usedApi } = normalizeContractUses(source);
     const emittedSource = {
         id: source.id,
         displayName: source.displayName,
         description: source.description,
         kind: source.kind,
         ...(source.schemas ? { schemas: source.schemas } : {}),
+        ...(source.exports ? { exports: source.exports } : {}),
+        ...(source.state ? { state: source.state } : {}),
         ...(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.jobs ? { jobs: source.jobs } : {}),
         ...(source.resources ? { resources: source.resources } : {}),
     };
     const ownedApi = buildOwnedApi(emittedSource);
     const trellisApi = mergeDerivedApis(ownedApi, usedApi);
     const CONTRACT = emitContract(emittedSource);
-    const CONTRACT_DIGEST = digestCanonicalJson(CONTRACT);
+    const CONTRACT_DIGEST = digestContractManifest(CONTRACT);
     let contract;
     contract = {
         CONTRACT_ID: source.id,
@@ -941,6 +1246,9 @@ function defineContract(registry, build) {
             trellis: trellisApi,
         },
         use: createUseHelper(() => contract),
+        [CONTRACT_JOBS_METADATA]: buildContractJobsMetadata(source.jobs),
+        [CONTRACT_KV_METADATA]: buildContractKvMetadata(source.resources, source.schemas),
+        [CONTRACT_STATE_METADATA]: buildContractStateMetadata(source.state, source.schemas),
     };
     return contract;
 }
@@ -950,19 +1258,28 @@ export function defineServiceContract(registry, build) {
         kind: "service",
     }));
 }
-function defineClientContract(kind, build) {
-    return defineContract({}, () => ({ ...build(), kind }));
-}
-export function defineAppContract(build) {
-    return defineClientContract("app", build);
+function defineClientContract(kind, registry, build) {
+    return defineContract(registry, (ref) => ({ ...build(ref), kind }));
 }
-export function definePortalContract(build) {
-    return defineClientContract("portal", build);
+export function defineAppContract(...args) {
+    const [registryOrBuild, maybeBuild] = args;
+    if (typeof registryOrBuild === "function") {
+        return defineClientContract("app", {}, () => registryOrBuild());
+    }
+    return defineClientContract("app", registryOrBuild, maybeBuild);
 }
-export function defineCliContract(build) {
-    return defineClientContract("cli", build);
+export function defineAgentContract(...args) {
+    const [registryOrBuild, maybeBuild] = args;
+    if (typeof registryOrBuild === "function") {
+        return defineClientContract("agent", {}, () => registryOrBuild());
+    }
+    return defineClientContract("agent", registryOrBuild, maybeBuild);
 }
-export function defineDeviceContract(build) {
-    return defineClientContract("device", build);
+export function defineDeviceContract(...args) {
+    const [registryOrBuild, maybeBuild] = args;
+    if (typeof registryOrBuild === "function") {
+        return defineClientContract("device", {}, () => registryOrBuild());
+    }
+    return defineClientContract("device", registryOrBuild, maybeBuild);
 }
 export { canonicalizeJson, digestJson, isJsonValue, schema, unwrapSchema };