@qlever-llc/trellis 0.8.4 → 0.9.0-rc.10

package/esm/npm/src/contract_support/mod.js

@@ -1,11 +1,157 @@
 import Type from "typebox";
+import { Value } from "typebox/value";
 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 { ContractJobQueueSchema, ContractJobsSchema, ContractKvResourceSchema, ContractResourceBindingsSchema, ContractResourcesSchema, ContractSchemaRefSchema, ContractStateSchema, ContractStateStoreSchema, ContractStoreResourceSchema, EventHeaderSchema, InstalledServiceContractSchema, IsoDateSchema, JobsQueueBindingSchema, JobsResourceBindingSchema, KvResourceBindingSchema, PaginatedSchema, StoreResourceBindingSchema, } from "./protocol.js";
+import { ContractJobQueueSchema, ContractResourcesSchema, ContractSchemaRefSchema, ContractStateSchema, } from "./protocol.js";
+export { ContractJobQueueSchema, ContractJobsSchema, ContractKvResourceSchema, ContractResourceBindingsSchema, ContractResourcesSchema, ContractSchemaRefSchema, ContractStateSchema, ContractStateStoreSchema, ContractStoreResourceSchema, EventHeaderSchema, InstalledServiceContractSchema, IsoDateSchema, JobsQueueBindingSchema, JobsResourceBindingSchema, KvResourceBindingSchema, PageRequestSchema, PageResponseSchema, StoreResourceBindingSchema, } from "./protocol.js";
 export const CONTRACT_FORMAT_V1 = "trellis.contract.v1";
 export const CATALOG_FORMAT_V1 = "trellis.catalog.v1";
+const NonEmptyStringSchema = Type.String({ minLength: 1 });
+const VersionSchema = Type.String({ pattern: "^v[0-9]+$" });
+const PointerStringSchema = Type.String({ pattern: "^/.*" });
+const CapabilityListSchema = Type.Array(NonEmptyStringSchema);
+const JsonSchemaValueSchema = Type.Union([
+    Type.Object({}, { additionalProperties: true }),
+    Type.Boolean(),
+]);
+export const ContractCapabilityMetadataSchema = Type.Object({
+    displayName: NonEmptyStringSchema,
+    description: NonEmptyStringSchema,
+    consequence: Type.Optional(NonEmptyStringSchema),
+});
+export const ContractCapabilitiesSchema = Type.Record(NonEmptyStringSchema, ContractCapabilityMetadataSchema);
+export const ContractExportsSchema = Type.Object({
+    schemas: Type.Optional(Type.Array(NonEmptyStringSchema, { uniqueItems: true })),
+});
+const ContractUseRpcSchema = Type.Object({
+    call: Type.Optional(CapabilityListSchema),
+});
+const ContractUsePubSubSchema = Type.Object({
+    publish: Type.Optional(CapabilityListSchema),
+    subscribe: Type.Optional(CapabilityListSchema),
+});
+const ContractUseFeedSchema = Type.Object({
+    subscribe: Type.Optional(CapabilityListSchema),
+});
+const ContractUseSchema = Type.Object({
+    contract: NonEmptyStringSchema,
+    rpc: Type.Optional(ContractUseRpcSchema),
+    operations: Type.Optional(ContractUseRpcSchema),
+    events: Type.Optional(ContractUsePubSubSchema),
+    feeds: Type.Optional(ContractUseFeedSchema),
+});
+const ContractUsesFlatSchema = Type.Record(NonEmptyStringSchema, ContractUseSchema);
+export const ContractUsesSchema = Type.Object({
+    required: Type.Optional(ContractUsesFlatSchema),
+    optional: Type.Optional(ContractUsesFlatSchema),
+});
+const ContractErrorDeclSchema = Type.Object({
+    type: NonEmptyStringSchema,
+    schema: Type.Optional(ContractSchemaRefSchema),
+});
+const ContractErrorRefSchema = Type.Object({
+    type: NonEmptyStringSchema,
+});
+const RpcCapabilitiesSchema = Type.Object({
+    call: Type.Optional(CapabilityListSchema),
+});
+const OperationCapabilitiesSchema = Type.Object({
+    call: Type.Optional(CapabilityListSchema),
+    read: Type.Optional(CapabilityListSchema),
+    cancel: Type.Optional(CapabilityListSchema),
+    control: Type.Optional(CapabilityListSchema),
+});
+const PubSubCapabilitiesSchema = Type.Object({
+    publish: Type.Optional(CapabilityListSchema),
+    subscribe: Type.Optional(CapabilityListSchema),
+});
+const FeedCapabilitiesSchema = Type.Object({
+    subscribe: Type.Optional(CapabilityListSchema),
+});
+const RpcTransferSchema = Type.Object({
+    direction: Type.Literal("receive"),
+});
+const OperationTransferSchema = Type.Object({
+    direction: Type.Literal("send"),
+    store: NonEmptyStringSchema,
+    key: PointerStringSchema,
+    contentType: Type.Optional(PointerStringSchema),
+    metadata: Type.Optional(PointerStringSchema),
+    expiresInMs: Type.Optional(Type.Integer({ minimum: 1 })),
+    maxBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+const ContractRpcMethodSchema = Type.Object({
+    version: VersionSchema,
+    subject: NonEmptyStringSchema,
+    input: ContractSchemaRefSchema,
+    output: ContractSchemaRefSchema,
+    capabilities: Type.Optional(RpcCapabilitiesSchema),
+    errors: Type.Optional(Type.Array(ContractErrorRefSchema)),
+    transfer: Type.Optional(RpcTransferSchema),
+});
+const ContractOperationSignalSchema = Type.Object({
+    input: ContractSchemaRefSchema,
+});
+const ContractOperationSchema = Type.Object({
+    version: VersionSchema,
+    subject: NonEmptyStringSchema,
+    input: ContractSchemaRefSchema,
+    progress: Type.Optional(ContractSchemaRefSchema),
+    output: ContractSchemaRefSchema,
+    transfer: Type.Optional(OperationTransferSchema),
+    capabilities: Type.Optional(OperationCapabilitiesSchema),
+    signals: Type.Optional(Type.Record(NonEmptyStringSchema, ContractOperationSignalSchema)),
+    cancel: Type.Optional(Type.Boolean()),
+});
+const ContractEventSchema = Type.Object({
+    version: VersionSchema,
+    subject: NonEmptyStringSchema,
+    params: Type.Optional(Type.Array(PointerStringSchema)),
+    event: ContractSchemaRefSchema,
+    capabilities: Type.Optional(PubSubCapabilitiesSchema),
+});
+const ContractFeedSchema = Type.Object({
+    version: VersionSchema,
+    subject: NonEmptyStringSchema,
+    input: ContractSchemaRefSchema,
+    event: ContractSchemaRefSchema,
+    capabilities: Type.Optional(FeedCapabilitiesSchema),
+});
+export const TrellisContractV1Schema = Type.Object({
+    format: Type.Literal(CONTRACT_FORMAT_V1),
+    id: NonEmptyStringSchema,
+    displayName: NonEmptyStringSchema,
+    description: NonEmptyStringSchema,
+    kind: Type.Union([
+        Type.Literal("service"),
+        Type.Literal("app"),
+        Type.Literal("device"),
+        Type.Literal("agent"),
+    ]),
+    capabilities: Type.Optional(ContractCapabilitiesSchema),
+    schemas: Type.Optional(Type.Record(NonEmptyStringSchema, JsonSchemaValueSchema)),
+    exports: Type.Optional(ContractExportsSchema),
+    uses: Type.Optional(ContractUsesSchema),
+    state: Type.Optional(ContractStateSchema),
+    rpc: Type.Optional(Type.Record(NonEmptyStringSchema, ContractRpcMethodSchema)),
+    operations: Type.Optional(Type.Record(NonEmptyStringSchema, ContractOperationSchema)),
+    events: Type.Optional(Type.Record(NonEmptyStringSchema, ContractEventSchema)),
+    feeds: Type.Optional(Type.Record(NonEmptyStringSchema, ContractFeedSchema)),
+    errors: Type.Optional(Type.Record(NonEmptyStringSchema, ContractErrorDeclSchema)),
+    jobs: Type.Optional(Type.Record(NonEmptyStringSchema, ContractJobQueueSchema)),
+    resources: Type.Optional(ContractResourcesSchema),
+});
+export const TrellisCatalogV1Schema = Type.Object({
+    format: Type.Literal(CATALOG_FORMAT_V1),
+    contracts: Type.Array(Type.Object({
+        id: NonEmptyStringSchema,
+        digest: Type.String({ pattern: "^[A-Za-z0-9_-]+$" }),
+        displayName: NonEmptyStringSchema,
+        description: NonEmptyStringSchema,
+    })),
+});
 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");
@@ -85,13 +231,18 @@ function attachDefinedErrorPayload(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 TRELLIS_HEALTH_CONTRACT_ID = "trellis.health@v1";
+const BASELINE_AUTH_RPC_CALL = [
+    "Auth.Sessions.Me",
+    "Auth.Sessions.Logout",
+];
 const BASELINE_STATE_RPC_CALL = [
     "State.Get",
     "State.Put",
     "State.Delete",
     "State.List",
 ];
+const BASELINE_HEALTH_EVENTS_PUBLISH = ["Health.Heartbeat"];
 const UnknownRuntimeSchema = schema(Type.Unknown());
 function typedUnknownRuntimeSchema() {
     return UnknownRuntimeSchema;
@@ -104,13 +255,22 @@ function trellisRpcDesc(name) {
         callerCapabilities: [],
     };
 }
+function trellisEventDesc(name) {
+    return {
+        subject: eventSubject(name, "v1", undefined),
+        event: typedUnknownRuntimeSchema(),
+        publishCapabilities: [],
+        subscribeCapabilities: [],
+    };
+}
 const BASELINE_AUTH_API = {
     rpc: {
-        "Auth.Me": trellisRpcDesc("Auth.Me"),
-        "Auth.Logout": trellisRpcDesc("Auth.Logout"),
+        "Auth.Sessions.Me": trellisRpcDesc("Auth.Sessions.Me"),
+        "Auth.Sessions.Logout": trellisRpcDesc("Auth.Sessions.Logout"),
     },
     operations: {},
     events: {},
+    feeds: {},
     subjects: {},
 };
 const BASELINE_STATE_API = {
@@ -122,6 +282,16 @@ const BASELINE_STATE_API = {
     },
     operations: {},
     events: {},
+    feeds: {},
+    subjects: {},
+};
+const BASELINE_HEALTH_API = {
+    rpc: {},
+    operations: {},
+    events: {
+        "Health.Heartbeat": trellisEventDesc("Health.Heartbeat"),
+    },
+    feeds: {},
     subjects: {},
 };
 function createContractRefBuilder(registry) {
@@ -138,6 +308,9 @@ function createContractRefBuilder(registry) {
         error(errorName) {
             return errorName;
         },
+        capability(capabilityName) {
+            return capabilityName;
+        },
     };
 }
 function cloneSchema(schemaValue) {
@@ -269,9 +442,18 @@ function assertRegistryDoesNotDeclareExports(registry) {
         throw new Error("contract exports must be declared in the callback body, not the registry argument");
     }
 }
+function assertRegistryDoesNotDeclareCapabilities(registry) {
+    if (Object.hasOwn(registry, "capabilities")) {
+        throw new Error("contract capabilities 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]);
+    const schema = schemas?.[ref.schema];
+    if (!schema) {
+        throw new Error(`${context} references missing schema '${ref.schema}'`);
+    }
+    return cloneSchema(schema);
 }
 function digestCanonicalJson(value) {
     return sha256Base64urlSync(canonicalizeJson(value));
@@ -279,6 +461,41 @@ function digestCanonicalJson(value) {
 function sortedUnique(values) {
     return [...new Set(values)].sort();
 }
+/** Return the global capability namespace for a contract id. */
+export function contractCapabilityNamespace(contractId) {
+    return contractId.replace(/@v\d+$/, "");
+}
+/** Return the globally qualified name for a contract-local capability. */
+export function globalCapabilityName(contractId, localCapability) {
+    return `${contractCapabilityNamespace(contractId)}::${localCapability}`;
+}
+function projectCapabilities(capabilities, contractId, declaredCapabilities, context) {
+    if (!capabilities) {
+        return undefined;
+    }
+    return sortedUnique(capabilities.map((capability) => {
+        if (declaredCapabilities && Object.hasOwn(declaredCapabilities, capability)) {
+            return globalCapabilityName(contractId, capability);
+        }
+        if (capability === "admin" || capability === "service" ||
+            capability.includes("::")) {
+            return capability;
+        }
+        throw new Error(`${context} references undeclared local capability '${capability}'`);
+    }));
+}
+function emitCapabilities(contractId, capabilities) {
+    if (!capabilities) {
+        return undefined;
+    }
+    const entries = Object.entries(capabilities)
+        .map(([localCapability, metadata]) => [
+        globalCapabilityName(contractId, localCapability),
+        { ...metadata },
+    ]);
+    entries.sort(([left], [right]) => left.localeCompare(right));
+    return Object.fromEntries(entries);
+}
 function collectSchemaRef(reachableSchemas, ref) {
     if (ref) {
         reachableSchemas.add(ref.schema);
@@ -304,10 +521,17 @@ function collectReachableSchemaNames(contract) {
         collectSchemaRef(reachableSchemas, operation.input);
         collectSchemaRef(reachableSchemas, operation.progress);
         collectSchemaRef(reachableSchemas, operation.output);
+        for (const signal of Object.values(operation.signals ?? {})) {
+            collectSchemaRef(reachableSchemas, signal.input);
+        }
     }
     for (const event of Object.values(contract.events ?? {})) {
         collectSchemaRef(reachableSchemas, event.event);
     }
+    for (const feed of Object.values(contract.feeds ?? {})) {
+        collectSchemaRef(reachableSchemas, feed.input);
+        collectSchemaRef(reachableSchemas, feed.event);
+    }
     for (const job of Object.values(contract.jobs ?? {})) {
         collectSchemaRef(reachableSchemas, job.payload);
         collectSchemaRef(reachableSchemas, job.result);
@@ -347,7 +571,7 @@ function projectDigestResources(resources) {
         ...(resources.store ? { store: resources.store } : {}),
     };
 }
-function projectDigestUses(uses) {
+function projectDigestUsesFlat(uses) {
     if (!uses) {
         return undefined;
     }
@@ -371,9 +595,37 @@ function projectDigestUses(uses) {
                     },
                 }
                 : {}),
+            ...(use.feeds?.subscribe
+                ? { feeds: { subscribe: sortedUnique(use.feeds.subscribe) } }
+                : {}),
         },
     ]));
 }
+function omitRequiredUseAliases(optional, required) {
+    if (!optional) {
+        return undefined;
+    }
+    if (!required) {
+        return optional;
+    }
+    const requiredAliases = new Set(Object.keys(required));
+    const entries = Object.entries(optional).filter(([alias]) => !requiredAliases.has(alias));
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function projectDigestUses(uses) {
+    if (!uses) {
+        return undefined;
+    }
+    const required = projectDigestUsesFlat(uses.required);
+    const optional = omitRequiredUseAliases(projectDigestUsesFlat(uses.optional), required);
+    if (!required && !optional) {
+        return undefined;
+    }
+    return {
+        ...(required ? { required } : {}),
+        ...(optional ? { optional } : {}),
+    };
+}
 function projectDigestRpc(rpc) {
     if (!rpc) {
         return undefined;
@@ -402,7 +654,7 @@ function projectDigestOperations(operations) {
         {
             ...operation,
             ...((operation.capabilities?.call || operation.capabilities?.read ||
-                operation.capabilities?.cancel)
+                operation.capabilities?.cancel || operation.capabilities?.control)
                 ? {
                     capabilities: {
                         ...(operation.capabilities.call
@@ -414,6 +666,9 @@ function projectDigestOperations(operations) {
                         ...(operation.capabilities.cancel
                             ? { cancel: sortedUnique(operation.capabilities.cancel) }
                             : {}),
+                        ...(operation.capabilities.control
+                            ? { control: sortedUnique(operation.capabilities.control) }
+                            : {}),
                     },
                 }
                 : {}),
@@ -443,6 +698,314 @@ function projectDigestEvents(events) {
         },
     ]));
 }
+function projectDigestFeeds(feeds) {
+    if (!feeds) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(feeds).map(([name, feed]) => [
+        name,
+        {
+            ...feed,
+            ...(feed.capabilities?.subscribe
+                ? {
+                    capabilities: {
+                        subscribe: sortedUnique(feed.capabilities.subscribe),
+                    },
+                }
+                : {}),
+        },
+    ]));
+}
+function mapValues(values, map) {
+    if (!values)
+        return undefined;
+    return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, map(value)]));
+}
+function schemaRef(ref) {
+    return { schema: ref.schema };
+}
+function capabilityMetadata(metadata) {
+    return {
+        displayName: metadata.displayName,
+        description: metadata.description,
+        ...(metadata.consequence ? { consequence: metadata.consequence } : {}),
+    };
+}
+function useRpc(use) {
+    if (!use)
+        return undefined;
+    return {
+        ...(use.call ? { call: [...use.call] } : {}),
+    };
+}
+function usePubSub(use) {
+    if (!use)
+        return undefined;
+    return {
+        ...(use.publish ? { publish: [...use.publish] } : {}),
+        ...(use.subscribe ? { subscribe: [...use.subscribe] } : {}),
+    };
+}
+function contractUse(use) {
+    return {
+        contract: use.contract,
+        ...(use.rpc ? { rpc: useRpc(use.rpc) } : {}),
+        ...(use.operations ? { operations: useRpc(use.operations) } : {}),
+        ...(use.events ? { events: usePubSub(use.events) } : {}),
+        ...(use.feeds
+            ? {
+                feeds: {
+                    ...(use.feeds.subscribe
+                        ? { subscribe: [...use.feeds.subscribe] }
+                        : {}),
+                },
+            }
+            : {}),
+    };
+}
+function contractUses(uses) {
+    if (!uses)
+        return undefined;
+    return {
+        ...(uses.required
+            ? { required: mapValues(uses.required, contractUse) }
+            : {}),
+        ...(uses.optional
+            ? { optional: mapValues(uses.optional, contractUse) }
+            : {}),
+    };
+}
+function stateStore(store) {
+    return {
+        kind: store.kind,
+        schema: schemaRef(store.schema),
+        ...(store.stateVersion ? { stateVersion: store.stateVersion } : {}),
+        ...(store.acceptedVersions
+            ? { acceptedVersions: mapValues(store.acceptedVersions, schemaRef) }
+            : {}),
+    };
+}
+function rpcMethod(method) {
+    return {
+        version: method.version,
+        subject: method.subject,
+        input: schemaRef(method.input),
+        output: schemaRef(method.output),
+        ...(method.transfer
+            ? { transfer: { direction: method.transfer.direction } }
+            : {}),
+        ...(method.capabilities?.call
+            ? { capabilities: { call: [...method.capabilities.call] } }
+            : {}),
+        ...(method.errors
+            ? { errors: method.errors.map((error) => ({ type: error.type })) }
+            : {}),
+    };
+}
+function operation(operation) {
+    return {
+        version: operation.version,
+        subject: operation.subject,
+        input: schemaRef(operation.input),
+        ...(operation.progress ? { progress: schemaRef(operation.progress) } : {}),
+        output: schemaRef(operation.output),
+        ...(operation.transfer
+            ? {
+                transfer: {
+                    direction: operation.transfer.direction,
+                    store: operation.transfer.store,
+                    key: operation.transfer.key,
+                    ...(operation.transfer.contentType
+                        ? { contentType: operation.transfer.contentType }
+                        : {}),
+                    ...(operation.transfer.metadata
+                        ? { metadata: operation.transfer.metadata }
+                        : {}),
+                    ...(operation.transfer.expiresInMs !== undefined
+                        ? { expiresInMs: operation.transfer.expiresInMs }
+                        : {}),
+                    ...(operation.transfer.maxBytes !== undefined
+                        ? { maxBytes: operation.transfer.maxBytes }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(operation.capabilities
+            ? {
+                capabilities: {
+                    ...(operation.capabilities.call
+                        ? { call: [...operation.capabilities.call] }
+                        : {}),
+                    ...(operation.capabilities.read
+                        ? { read: [...operation.capabilities.read] }
+                        : {}),
+                    ...(operation.capabilities.cancel
+                        ? { cancel: [...operation.capabilities.cancel] }
+                        : {}),
+                    ...(operation.capabilities.control
+                        ? { control: [...operation.capabilities.control] }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(operation.signals
+            ? {
+                signals: mapValues(operation.signals, (signal) => ({ input: schemaRef(signal.input) })),
+            }
+            : {}),
+        ...(operation.cancel !== undefined ? { cancel: operation.cancel } : {}),
+    };
+}
+function event(event) {
+    return {
+        version: event.version,
+        subject: event.subject,
+        ...(event.params ? { params: [...event.params] } : {}),
+        event: schemaRef(event.event),
+        ...(event.capabilities
+            ? {
+                capabilities: {
+                    ...(event.capabilities.publish
+                        ? { publish: [...event.capabilities.publish] }
+                        : {}),
+                    ...(event.capabilities.subscribe
+                        ? { subscribe: [...event.capabilities.subscribe] }
+                        : {}),
+                },
+            }
+            : {}),
+    };
+}
+function feed(feed) {
+    return {
+        version: feed.version,
+        subject: feed.subject,
+        input: schemaRef(feed.input),
+        event: schemaRef(feed.event),
+        ...(feed.capabilities?.subscribe
+            ? { capabilities: { subscribe: [...feed.capabilities.subscribe] } }
+            : {}),
+    };
+}
+function errorDecl(error) {
+    return {
+        type: error.type,
+        ...(error.schema ? { schema: schemaRef(error.schema) } : {}),
+    };
+}
+function jobQueue(queue) {
+    return {
+        payload: schemaRef(queue.payload),
+        ...(queue.result ? { result: schemaRef(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 kvResource(resource) {
+    return {
+        purpose: resource.purpose,
+        schema: schemaRef(resource.schema),
+        ...(resource.required !== undefined ? { required: resource.required } : {}),
+        ...(resource.history !== undefined ? { history: resource.history } : {}),
+        ...(resource.ttlMs !== undefined ? { ttlMs: resource.ttlMs } : {}),
+        ...(resource.maxValueBytes !== undefined
+            ? { maxValueBytes: resource.maxValueBytes }
+            : {}),
+    };
+}
+function storeResource(resource) {
+    return {
+        purpose: resource.purpose,
+        ...(resource.required !== undefined ? { required: resource.required } : {}),
+        ...(resource.ttlMs !== undefined ? { ttlMs: resource.ttlMs } : {}),
+        ...(resource.maxObjectBytes !== undefined
+            ? { maxObjectBytes: resource.maxObjectBytes }
+            : {}),
+        ...(resource.maxTotalBytes !== undefined
+            ? { maxTotalBytes: resource.maxTotalBytes }
+            : {}),
+    };
+}
+/**
+ * Return the canonical manifest shape used by Trellis runtimes before
+ * validation, persistence, and digesting.
+ *
+ * This is not the digest projection: human-facing fields such as
+ * `displayName` and `description` are preserved here even though they are not
+ * part of contract identity. Unknown extension fields are intentionally omitted
+ * until the runtime explicitly supports them.
+ */
+export function normalizeContractManifest(contract) {
+    return {
+        format: contract.format,
+        id: contract.id,
+        displayName: contract.displayName,
+        description: contract.description,
+        kind: contract.kind,
+        ...(contract.capabilities
+            ? { capabilities: mapValues(contract.capabilities, capabilityMetadata) }
+            : {}),
+        ...(contract.schemas ? { schemas: contract.schemas } : {}),
+        ...(contract.exports
+            ? {
+                exports: {
+                    ...(contract.exports.schemas
+                        ? { schemas: [...contract.exports.schemas] }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(contract.uses ? { uses: contractUses(contract.uses) } : {}),
+        ...(contract.state ? { state: mapValues(contract.state, stateStore) } : {}),
+        ...(contract.rpc ? { rpc: mapValues(contract.rpc, rpcMethod) } : {}),
+        ...(contract.operations
+            ? { operations: mapValues(contract.operations, operation) }
+            : {}),
+        ...(contract.events ? { events: mapValues(contract.events, event) } : {}),
+        ...(contract.feeds ? { feeds: mapValues(contract.feeds, feed) } : {}),
+        ...(contract.jobs ? { jobs: mapValues(contract.jobs, jobQueue) } : {}),
+        ...(contract.resources
+            ? {
+                resources: {
+                    ...(contract.resources.kv
+                        ? { kv: mapValues(contract.resources.kv, kvResource) }
+                        : {}),
+                    ...(contract.resources.store
+                        ? { store: mapValues(contract.resources.store, storeResource) }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(contract.errors
+            ? { errors: mapValues(contract.errors, errorDecl) }
+            : {}),
+    };
+}
+/**
+ * Parse untrusted contract JSON into the current Trellis v1 manifest shape.
+ *
+ * Unknown extension fields are accepted for forward compatibility but are not
+ * returned. Callers must use the returned value for persistence and digesting.
+ */
+export function parseContractManifest(value) {
+    try {
+        return normalizeContractManifest(Value.Parse(TrellisContractV1Schema, value));
+    }
+    catch (error) {
+        const details = [...Value.Errors(TrellisContractV1Schema, value)].map((entry) => `${entry.instancePath || "#"}: ${entry.message}`);
+        throw new TypeError(`Invalid contract${details.length > 0 ? `:\n${details.join("\n")}` : ""}`, { cause: error });
+    }
+}
 /**
  * Build the normalized runtime/interface projection used for contract identity.
  */
@@ -454,16 +1017,19 @@ export function projectContractDigestManifest(contract) {
     const rpc = projectDigestRpc(contract.rpc);
     const operations = projectDigestOperations(contract.operations);
     const events = projectDigestEvents(contract.events);
+    const feeds = projectDigestFeeds(contract.feeds);
     return {
         format: contract.format,
         id: contract.id,
         kind: contract.kind,
+        ...(contract.capabilities ? { capabilities: contract.capabilities } : {}),
         ...(schemas ? { schemas } : {}),
         ...(contract.state ? { state: contract.state } : {}),
         ...(uses ? { uses } : {}),
         ...(rpc ? { rpc } : {}),
         ...(operations ? { operations } : {}),
         ...(events ? { events } : {}),
+        ...(feeds ? { feeds } : {}),
         ...(errors ? { errors } : {}),
         ...(contract.jobs ? { jobs: contract.jobs } : {}),
         ...(resources ? { resources } : {}),
@@ -471,7 +1037,7 @@ export function projectContractDigestManifest(contract) {
 }
 /** Compute the v1 contract digest from the normalized digest projection. */
 export function digestContractManifest(contract) {
-    return digestCanonicalJson(projectContractDigestManifest(contract));
+    return digestCanonicalJson(projectContractDigestManifest(normalizeContractManifest(contract)));
 }
 function rpcSubject(name, version) {
     return `rpc.${version}.${name}`;
@@ -479,6 +1045,9 @@ function rpcSubject(name, version) {
 function operationSubject(name, version) {
     return `operations.${version}.${name}`;
 }
+function feedSubject(name, version) {
+    return `feeds.${version}.${name}`;
+}
 function eventSubject(name, version, params) {
     const suffix = params && params.length > 0
         ? `.${params.map((pointer) => `{${pointer}}`).join(".")}`
@@ -572,10 +1141,14 @@ function buildContractKvMetadata(resources, schemas) {
     const metadata = {};
     for (const [alias, resource] of Object.entries(kv)) {
         assertSchemaRefExists(schemas, resource.schema, `kv resource '${alias}'`);
+        const schema = schemas?.[resource.schema.schema];
+        if (!schema) {
+            throw new Error(`kv resource '${alias}' references missing schema '${resource.schema.schema}'`);
+        }
         metadata[alias] = {
             required: resource.required ?? true,
             value: undefined,
-            schema: schemas[resource.schema.schema],
+            schema,
         };
     }
     return metadata;
@@ -613,7 +1186,7 @@ function emitState(state) {
         },
     ]));
 }
-function emitUses(uses) {
+function emitUsesFlat(uses) {
     if (!uses) {
         return undefined;
     }
@@ -637,10 +1210,28 @@ function emitUses(uses) {
                     },
                 }
                 : {}),
+            ...(use.feeds?.subscribe
+                ? { feeds: { subscribe: sortedUnique(use.feeds.subscribe) } }
+                : {}),
         },
     ]));
 }
+function emitUses(uses) {
+    if (!uses) {
+        return undefined;
+    }
+    const required = emitUsesFlat(uses.required);
+    const optional = omitRequiredUseAliases(emitUsesFlat(uses.optional), required);
+    if (!required && !optional) {
+        return undefined;
+    }
+    return {
+        ...(required ? { required } : {}),
+        ...(optional ? { optional } : {}),
+    };
+}
 function emitContract(source) {
+    const capabilities = emitCapabilities(source.id, source.capabilities);
     const rpc = source.rpc
         ? Object.fromEntries(Object.entries(source.rpc).map(([name, method]) => {
             const emitted = {
@@ -651,7 +1242,7 @@ function emitContract(source) {
             };
             if (method.capabilities?.call) {
                 emitted.capabilities = {
-                    call: sortedUnique(method.capabilities.call),
+                    call: projectCapabilities(method.capabilities.call, source.id, source.capabilities, `rpc '${name}' call capabilities`) ?? [],
                 };
             }
             if (method.transfer) {
@@ -698,19 +1289,36 @@ function emitContract(source) {
                 emitted.transfer = { ...operation.transfer, direction: "send" };
             }
             if (operation.capabilities?.call || operation.capabilities?.read ||
-                operation.capabilities?.cancel) {
+                operation.capabilities?.cancel || operation.capabilities?.control) {
                 emitted.capabilities = {
                     ...(operation.capabilities.call
-                        ? { call: sortedUnique(operation.capabilities.call) }
+                        ? {
+                            call: projectCapabilities(operation.capabilities.call, source.id, source.capabilities, `operation '${name}' call capabilities`) ?? [],
+                        }
                         : {}),
                     ...(operation.capabilities.read
-                        ? { read: sortedUnique(operation.capabilities.read) }
+                        ? {
+                            read: projectCapabilities(operation.capabilities.read, source.id, source.capabilities, `operation '${name}' read capabilities`) ?? [],
+                        }
                         : {}),
                     ...(operation.capabilities.cancel
-                        ? { cancel: sortedUnique(operation.capabilities.cancel) }
+                        ? {
+                            cancel: projectCapabilities(operation.capabilities.cancel, source.id, source.capabilities, `operation '${name}' cancel capabilities`) ?? [],
+                        }
+                        : {}),
+                    ...(operation.capabilities.control
+                        ? {
+                            control: projectCapabilities(operation.capabilities.control, source.id, source.capabilities, `operation '${name}' control capabilities`) ?? [],
+                        }
                         : {}),
                 };
             }
+            if (operation.signals) {
+                emitted.signals = Object.fromEntries(Object.entries(operation.signals).map(([signalName, signal]) => [
+                    signalName,
+                    { input: { ...signal.input } },
+                ]));
+            }
             if (operation.cancel !== undefined) {
                 emitted.cancel = operation.cancel;
             }
@@ -734,16 +1342,36 @@ function emitContract(source) {
             if (event.capabilities?.publish || event.capabilities?.subscribe) {
                 emitted.capabilities = {
                     ...(event.capabilities.publish
-                        ? { publish: sortedUnique(event.capabilities.publish) }
+                        ? {
+                            publish: projectCapabilities(event.capabilities.publish, source.id, source.capabilities, `event '${name}' publish capabilities`) ?? [],
+                        }
                         : {}),
                     ...(event.capabilities.subscribe
-                        ? { subscribe: sortedUnique(event.capabilities.subscribe) }
+                        ? {
+                            subscribe: projectCapabilities(event.capabilities.subscribe, source.id, source.capabilities, `event '${name}' subscribe capabilities`) ?? [],
+                        }
                         : {}),
                 };
             }
             return [name, emitted];
         }))
         : undefined;
+    const feeds = source.feeds
+        ? Object.fromEntries(Object.entries(source.feeds).map(([name, feed]) => {
+            const emitted = {
+                version: feed.version,
+                subject: feed.subject ?? feedSubject(name, feed.version),
+                input: { ...feed.input },
+                event: { ...feed.event },
+            };
+            if (feed.capabilities?.subscribe) {
+                emitted.capabilities = {
+                    subscribe: projectCapabilities(feed.capabilities.subscribe, source.id, source.capabilities, `feed '${name}' subscribe capabilities`) ?? [],
+                };
+            }
+            return [name, emitted];
+        }))
+        : undefined;
     const errors = source.errors
         ? Object.fromEntries(Object.entries(source.errors).map(([name, error]) => {
             const emitted = { type: error.type };
@@ -764,6 +1392,7 @@ function emitContract(source) {
         displayName: source.displayName,
         description: source.description,
         kind: source.kind,
+        ...(capabilities ? { capabilities } : {}),
         ...(source.schemas ? { schemas: cloneSchemas(source.schemas) } : {}),
         ...(source.exports
             ? { exports: cloneContractExports(source.exports) }
@@ -773,6 +1402,7 @@ function emitContract(source) {
         ...(rpc ? { rpc } : {}),
         ...(operations ? { operations } : {}),
         ...(events ? { events } : {}),
+        ...(feeds ? { feeds } : {}),
         ...(errors ? { errors } : {}),
         ...(jobs ? { jobs } : {}),
         ...(resources ? { resources } : {}),
@@ -807,7 +1437,7 @@ function buildOwnedApi(source) {
             subject: method.subject ?? rpcSubject(name, method.version),
             input: schema(resolveSchemaRef(source.schemas, method.input, `rpc '${name}' input`)),
             output: schema(resolveSchemaRef(source.schemas, method.output, `rpc '${name}' output`)),
-            callerCapabilities: method.capabilities?.call ?? [],
+            callerCapabilities: projectCapabilities(method.capabilities?.call, source.id, source.capabilities, `rpc '${name}' call capabilities`) ?? [],
             transfer: method.transfer ? { ...method.transfer } : undefined,
             authRequired: method.authRequired ?? true,
             errors: method.errors,
@@ -832,9 +1462,18 @@ function buildOwnedApi(source) {
             transfer: operation.transfer
                 ? { ...operation.transfer, direction: "send" }
                 : undefined,
-            callerCapabilities: operation.capabilities?.call ?? [],
-            readCapabilities: operation.capabilities?.read ?? [],
-            cancelCapabilities: operation.capabilities?.cancel ?? [],
+            signals: operation.signals
+                ? Object.fromEntries(Object.entries(operation.signals).map(([signalName, signal]) => [
+                    signalName,
+                    {
+                        input: schema(resolveSchemaRef(source.schemas, signal.input, `operation '${name}' signal '${signalName}' input`)),
+                    },
+                ]))
+                : undefined,
+            callerCapabilities: projectCapabilities(operation.capabilities?.call, source.id, source.capabilities, `operation '${name}' call capabilities`) ?? [],
+            readCapabilities: projectCapabilities(operation.capabilities?.read, source.id, source.capabilities, `operation '${name}' read capabilities`) ?? [],
+            cancelCapabilities: projectCapabilities(operation.capabilities?.cancel, source.id, source.capabilities, `operation '${name}' cancel capabilities`) ?? [],
+            controlCapabilities: projectCapabilities(operation.capabilities?.control, source.id, source.capabilities, `operation '${name}' control capabilities`) ?? [],
             cancel: operation.cancel,
         },
     ]));
@@ -849,12 +1488,21 @@ function buildOwnedApi(source) {
                     eventSubject(name, event.version, event.params),
                 params: event.params,
                 event: schema(resolveSchemaRef(source.schemas, event.event, `event '${name}'`)),
-                publishCapabilities: event.capabilities?.publish ?? [],
-                subscribeCapabilities: event.capabilities?.subscribe ?? [],
+                publishCapabilities: projectCapabilities(event.capabilities?.publish, source.id, source.capabilities, `event '${name}' publish capabilities`) ?? [],
+                subscribeCapabilities: projectCapabilities(event.capabilities?.subscribe, source.id, source.capabilities, `event '${name}' subscribe capabilities`) ?? [],
             },
         ];
     }));
-    return { rpc, operations, events, subjects: {} };
+    const feeds = Object.fromEntries(Object.entries(source.feeds ?? {}).map(([name, feed]) => [
+        name,
+        {
+            subject: feed.subject ?? feedSubject(name, feed.version),
+            input: schema(resolveSchemaRef(source.schemas, feed.input, `feed '${name}' input`)),
+            event: schema(resolveSchemaRef(source.schemas, feed.event, `feed '${name}' event`)),
+            subscribeCapabilities: projectCapabilities(feed.capabilities?.subscribe, source.id, source.capabilities, `feed '${name}' subscribe capabilities`) ?? [],
+        },
+    ]));
+    return { rpc, operations, events, feeds, subjects: {} };
 }
 function mergeRecord(kind, out, next) {
     for (const [key, value] of Object.entries(next)) {
@@ -879,6 +1527,7 @@ 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, "feeds", spec.feeds?.subscribe, api.feeds ?? {});
 }
 function attachContractModuleMetadata(value, contractModule) {
     Object.defineProperty(value, CONTRACT_MODULE_METADATA, {
@@ -1007,6 +1656,9 @@ function createUseHelper(getContractModule) {
                     },
                 }
                 : {}),
+            ...(spec.feeds?.subscribe
+                ? { feeds: { subscribe: [...spec.feeds.subscribe] } }
+                : {}),
         };
         return attachContractModuleMetadata(dependencyUse, contractModule);
     });
@@ -1018,11 +1670,11 @@ function getContractModuleFromUse(alias, useValue) {
     }
     return contractModule;
 }
-function normalizeUses(uses) {
+function normalizeUseEntries(uses) {
     if (!uses) {
         return {
             manifestUses: undefined,
-            usedApi: { rpc: {}, operations: {}, events: {}, subjects: {} },
+            usedApi: { rpc: {}, operations: {}, events: {}, feeds: {}, subjects: {} },
         };
     }
     const manifestUses = {};
@@ -1030,6 +1682,7 @@ function normalizeUses(uses) {
         rpc: {},
         operations: {},
         events: {},
+        feeds: {},
         subjects: {},
     };
     for (const [alias, useValue] of Object.entries(uses)) {
@@ -1038,6 +1691,7 @@ function normalizeUses(uses) {
         const operationsCall = useValue.operations?.call;
         const eventsPublish = useValue.events?.publish;
         const eventsSubscribe = useValue.events?.subscribe;
+        const feedsSubscribe = useValue.feeds?.subscribe;
         if (useValue.contract !== contractModule.CONTRACT_ID) {
             throw new Error(`Contract use '${alias}' references '${useValue.contract}' but module id is '${contractModule.CONTRACT_ID}'`);
         }
@@ -1052,6 +1706,7 @@ function normalizeUses(uses) {
                     },
                 }
                 : {}),
+            ...(feedsSubscribe ? { feeds: { subscribe: feedsSubscribe } } : {}),
         }, contractModule.API.owned);
         manifestUses[alias] = {
             contract: contractModule.CONTRACT_ID,
@@ -1065,6 +1720,7 @@ function normalizeUses(uses) {
                     },
                 }
                 : {}),
+            ...(feedsSubscribe ? { feeds: { subscribe: [...feedsSubscribe] } } : {}),
         };
         const rpcKeys = selectedKeys(rpcCall);
         if (rpcKeys.length > 0) {
@@ -1081,11 +1737,35 @@ function normalizeUses(uses) {
         if (eventKeys.size > 0) {
             mergeRecord("events", usedApi.events, Object.fromEntries([...eventKeys].map((key) => [key, contractModule.API.owned.events[key]])));
         }
+        const feedKeys = selectedKeys(feedsSubscribe);
+        if (feedKeys.length > 0) {
+            mergeRecord("feeds", usedApi.feeds ?? {}, Object.fromEntries(feedKeys.map((key) => [key, contractModule.API.owned.feeds?.[key]])));
+        }
     }
     return { manifestUses, usedApi };
 }
+function normalizeUses(uses) {
+    if (!uses) {
+        return {
+            manifestUses: undefined,
+            usedApi: emptyApi(),
+        };
+    }
+    const required = normalizeUseEntries(uses.required);
+    const optional = normalizeUseEntries(omitRequiredUseAliases(uses.optional, uses.required));
+    const usedApi = emptyApi();
+    mergeUseIntoApi(usedApi, required.usedApi);
+    mergeUseIntoApi(usedApi, optional.usedApi);
+    return {
+        manifestUses: {
+            ...(required.manifestUses ? { required: required.manifestUses } : {}),
+            ...(optional.manifestUses ? { optional: optional.manifestUses } : {}),
+        },
+        usedApi,
+    };
+}
 function emptyApi() {
-    return { rpc: {}, operations: {}, events: {}, subjects: {} };
+    return { rpc: {}, operations: {}, events: {}, feeds: {}, subjects: {} };
 }
 function addUniqueStrings(target, values) {
     for (const value of values) {
@@ -1111,6 +1791,8 @@ function mergeUseIntoManifest(manifestUses, alias, use) {
     addUniqueStrings(eventsPublish, use.events?.publish ?? []);
     const eventsSubscribe = [...(existing.events?.subscribe ?? [])];
     addUniqueStrings(eventsSubscribe, use.events?.subscribe ?? []);
+    const feedsSubscribe = [...(existing.feeds?.subscribe ?? [])];
+    addUniqueStrings(feedsSubscribe, use.feeds?.subscribe ?? []);
     manifestUses[alias] = {
         contract: existing.contract,
         ...(rpcCall.length > 0 ? { rpc: { call: rpcCall } } : {}),
@@ -1125,6 +1807,9 @@ function mergeUseIntoManifest(manifestUses, alias, use) {
                 },
             }
             : {}),
+        ...(feedsSubscribe.length > 0
+            ? { feeds: { subscribe: feedsSubscribe } }
+            : {}),
     };
 }
 function mergeApiAllowDuplicateSubject(kind, out, next) {
@@ -1149,6 +1834,7 @@ function mergeUseIntoApi(target, api) {
     mergeApiAllowDuplicateSubject("rpc", target.rpc, api.rpc);
     mergeApiAllowDuplicateSubject("operations", target.operations, api.operations);
     mergeApiAllowDuplicateSubject("events", target.events, api.events);
+    mergeApiAllowDuplicateSubject("feeds", target.feeds ?? {}, api.feeds ?? {});
     mergeApiAllowDuplicateSubject("subjects", target.subjects, api.subjects);
 }
 function baselineUse(contract, use, api) {
@@ -1162,22 +1848,33 @@ function deriveImplicitTrellisUses(source) {
     if (source.state) {
         uses.state = baselineUse(TRELLIS_STATE_CONTRACT_ID, { rpc: { call: [...BASELINE_STATE_RPC_CALL] } }, BASELINE_STATE_API);
     }
+    if ((source.kind === "service" || source.kind === "device") &&
+        source.id !== TRELLIS_HEALTH_CONTRACT_ID) {
+        uses.health = baselineUse(TRELLIS_HEALTH_CONTRACT_ID, { events: { publish: [...BASELINE_HEALTH_EVENTS_PUBLISH] } }, BASELINE_HEALTH_API);
+    }
     return uses;
 }
 function normalizeContractUses(source) {
     const explicit = normalizeUses(source.uses);
-    const manifestUses = {
-        ...(explicit.manifestUses ?? {}),
-    };
     const usedApi = emptyApi();
     mergeUseIntoApi(usedApi, explicit.usedApi);
+    const required = {
+        ...(explicit.manifestUses?.required ?? {}),
+    };
+    const optional = explicit.manifestUses?.optional
+        ? { ...explicit.manifestUses.optional }
+        : undefined;
     for (const [alias, use] of Object.entries(deriveImplicitTrellisUses(source))) {
-        mergeUseIntoManifest(manifestUses, alias, use.manifestUse);
+        mergeUseIntoManifest(required, alias, use.manifestUse);
         mergeUseIntoApi(usedApi, use.api);
     }
     return {
-        manifestUses: Object.keys(manifestUses).length > 0
-            ? manifestUses
+        manifestUses: Object.keys(required).length > 0 ||
+            (optional && Object.keys(optional).length > 0)
+            ? {
+                ...(Object.keys(required).length > 0 ? { required } : {}),
+                ...(optional && Object.keys(optional).length > 0 ? { optional } : {}),
+            }
             : undefined,
         usedApi,
     };
@@ -1196,11 +1893,13 @@ function mergeDerivedApis(ownedApi, usedApi) {
         rpc: mergeApiSection("rpc", usedApi.rpc, ownedApi.rpc),
         operations: mergeApiSection("operations", usedApi.operations, ownedApi.operations),
         events: mergeApiSection("events", usedApi.events, ownedApi.events),
+        feeds: mergeApiSection("feeds", usedApi.feeds ?? {}, ownedApi.feeds ?? {}),
         subjects: mergeApiSection("subjects", usedApi.subjects, ownedApi.subjects),
     };
 }
 function defineContract(registry, build) {
     assertRegistryDoesNotDeclareExports(registry);
+    assertRegistryDoesNotDeclareCapabilities(registry);
     const errorClasses = getErrorClassRegistry(registry.errors);
     const normalizedErrors = normalizeErrorRegistry(registry.errors);
     const body = build(createContractRefBuilder({
@@ -1220,6 +1919,7 @@ function defineContract(registry, build) {
         displayName: source.displayName,
         description: source.description,
         kind: source.kind,
+        ...(source.capabilities ? { capabilities: source.capabilities } : {}),
         ...(source.schemas ? { schemas: source.schemas } : {}),
         ...(source.exports ? { exports: source.exports } : {}),
         ...(source.state ? { state: source.state } : {}),
@@ -1227,6 +1927,7 @@ function defineContract(registry, build) {
         ...(source.rpc ? { rpc: source.rpc } : {}),
         ...(source.operations ? { operations: source.operations } : {}),
         ...(source.events ? { events: source.events } : {}),
+        ...(source.feeds ? { feeds: source.feeds } : {}),
         ...(source.errors ? { errors: source.errors } : {}),
         ...(source.jobs ? { jobs: source.jobs } : {}),
         ...(source.resources ? { resources: source.resources } : {}),