@qlever-llc/trellis 0.10.22 → 0.11.0-rc.1

package/script/codec.js

@@ -9,6 +9,124 @@ const contracts_js_1 = require("./contracts.js");
 const result_1 = require("@qlever-llc/result");
 const value_1 = require("typebox/value");
 const index_js_1 = require("./errors/index.js");
+const X_TRELLIS_VALIDATION = "x-trellis-validation";
+function readTrellisValidationExtension(schema) {
+    if (schema === null || schema === undefined || typeof schema !== "object") {
+        return undefined;
+    }
+    const ext = schema[X_TRELLIS_VALIDATION];
+    if (ext === null || ext === undefined || typeof ext !== "object") {
+        return undefined;
+    }
+    return ext;
+}
+function resolveSchemaNode(root, schemaPath) {
+    if (!schemaPath.startsWith("#/")) {
+        if (schemaPath === "#")
+            return root;
+        return undefined;
+    }
+    const parts = schemaPath.slice(2).split("/").map(decodeURIComponent);
+    let current = root;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== "object") {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+function resolveRequiredErrorNode(root, error) {
+    const params = error.params;
+    const missingProperty = (params?.missingProperty ??
+        params?.requiredProperties?.[0]);
+    if (!missingProperty)
+        return undefined;
+    const objNode = resolveSchemaNode(root, error.schemaPath);
+    if (!objNode || typeof objNode !== "object")
+        return undefined;
+    const properties = objNode.properties;
+    if (!properties || typeof properties !== "object")
+        return undefined;
+    return properties[missingProperty];
+}
+const ALLOWED_HINT_KEYWORDS = new Set([
+    "required",
+    "minItems",
+    "maxItems",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "pattern",
+    "format",
+    "enum",
+    "const",
+]);
+function keywordAllowsHint(keyword) {
+    return ALLOWED_HINT_KEYWORDS.has(keyword);
+}
+function typeboxIssueToPath(error) {
+    if (error.keyword === "required") {
+        const params = error.params;
+        const missingProperty = (params?.missingProperty ??
+            params?.requiredProperties?.[0]);
+        if (missingProperty) {
+            return error.instancePath
+                ? `${error.instancePath}/${missingProperty}`
+                : `/${missingProperty}`;
+        }
+    }
+    return error.instancePath || error.schemaPath;
+}
+function collectValidationIssues(root, errors) {
+    const annotated = [];
+    const unannotated = [];
+    for (const error of [...errors]) {
+        const schemaNode = error.keyword === "required"
+            ? resolveRequiredErrorNode(root, error)
+            : resolveSchemaNode(root, error.schemaPath);
+        const extension = schemaNode !== undefined
+            ? readTrellisValidationExtension(schemaNode)
+            : undefined;
+        if (extension !== undefined &&
+            keywordAllowsHint(error.keyword) &&
+            extension.issues?.[error.keyword] !== undefined) {
+            const hint = extension.issues[error.keyword];
+            if (hint.code !== undefined) {
+                annotated.push({
+                    path: typeboxIssueToPath(error),
+                    schemaPath: error.schemaPath,
+                    keyword: error.keyword,
+                    code: hint.code,
+                    message: hint.message || error.message,
+                    label: hint.label ?? extension.label,
+                    note: hint.note ?? extension.note,
+                    i18nKey: hint.i18nKey,
+                    severity: hint.severity ?? "error",
+                    params: error.params,
+                });
+                continue;
+            }
+        }
+        unannotated.push(error);
+    }
+    return { annotated, unannotated };
+}
+function buildValidationError(schema, data, errors, cause) {
+    const { annotated, unannotated } = collectValidationIssues(schema, errors);
+    if (annotated.length > 0 && unannotated.length === 0) {
+        return new index_js_1.SchemaValidationError({ issues: annotated, cause });
+    }
+    return new index_js_1.ValidationError({
+        errors: unannotated.length > 0
+            ? unannotated
+            : annotated.map((i) => ({ path: i.path, message: i.message })),
+        cause,
+    });
+}
 function parseWithSchema(schema, data) {
     return value_1.Value.Parse(schema, data);
 }
@@ -22,7 +140,7 @@ function parse(schema, data) {
     catch (cause) {
         if (cause instanceof value_1.ParseError) {
             const errors = value_1.Value.Errors(schema, data);
-            return result_1.Result.err(new index_js_1.ValidationError({ errors, cause }));
+            return result_1.Result.err(buildValidationError(schema, data, errors, cause));
         }
         return result_1.Result.err(new index_js_1.UnexpectedError({ cause }));
     }
@@ -35,11 +153,12 @@ function parseSchema(schema, data) {
     catch (cause) {
         if (cause instanceof value_1.ParseError) {
             const errors = value_1.Value.Errors(raw, data);
-            return result_1.Result.err(new index_js_1.ValidationError({ errors, cause }));
+            return result_1.Result.err(buildValidationError(raw, data, errors, cause));
         }
         return result_1.Result.err(new index_js_1.UnexpectedError({ cause }));
     }
 }
+/** Parses unknown JSON-compatible data with an arbitrary Trellis schema. */
 function parseUnknownSchema(schema, data) {
     const raw = (0, contracts_js_1.unwrapSchema)(schema);
     try {
@@ -48,7 +167,7 @@ function parseUnknownSchema(schema, data) {
     catch (cause) {
         if (cause instanceof value_1.ParseError) {
             const errors = value_1.Value.Errors(raw, data);
-            return result_1.Result.err(new index_js_1.ValidationError({ errors, cause }));
+            return result_1.Result.err(buildValidationError(raw, data, errors, cause));
         }
         return result_1.Result.err(new index_js_1.UnexpectedError({ cause }));
     }
@@ -60,7 +179,7 @@ function encode(schema, data) {
     catch (cause) {
         if (cause instanceof value_1.EncodeError) {
             const errors = value_1.Value.Errors(schema, data);
-            return result_1.Result.err(new index_js_1.ValidationError({ errors, cause }));
+            return result_1.Result.err(buildValidationError(schema, data, errors, cause));
         }
         return result_1.Result.err(new index_js_1.UnexpectedError({ cause }));
     }
@@ -73,7 +192,7 @@ function encodeSchema(schema, data) {
     catch (cause) {
         if (cause instanceof value_1.EncodeError) {
             const errors = value_1.Value.Errors(raw, data);
-            return result_1.Result.err(new index_js_1.ValidationError({ errors, cause }));
+            return result_1.Result.err(buildValidationError(raw, data, errors, cause));
         }
         return result_1.Result.err(new index_js_1.UnexpectedError({ cause }));
     }

package/script/contract_support/canonical.d.ts

@@ -5,8 +5,11 @@ export declare function isJsonValue(value: unknown): value is JsonValue;
 export declare function canonicalizeJson(value: JsonValue): string;
 export declare function base64url(bytes: Uint8Array): string;
 export declare function sha256Bytes(data: Uint8Array): Uint8Array;
+/** Computes a synchronous SHA-256 digest encoded as base64url. */
 export declare function sha256Base64urlSync(text: string): string;
+/** Computes a SHA-256 digest encoded as base64url. */
 export declare function sha256Base64url(text: string): Promise<string>;
+/** Canonicalizes JSON and computes its SHA-256 base64url digest. */
 export declare function digestJson(value: JsonValue): Promise<{
     canonical: string;
     digest: string;

package/script/contract_support/canonical.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/contract_support/canonical.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/B,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAiB9D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAoBzD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAKnD;AAMD,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAsIxD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAID"}
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/contract_support/canonical.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/B,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAiB9D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAoBzD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAKnD;AAMD,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAsIxD;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,sDAAsD;AACtD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE;AAED,oEAAoE;AACpE,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAID"}

package/script/contract_support/canonical.js

@@ -181,9 +181,11 @@ function sha256Bytes(data) {
     }
     return out;
 }
+/** Computes a synchronous SHA-256 digest encoded as base64url. */
 function sha256Base64urlSync(text) {
     return base64url(sha256Bytes(new TextEncoder().encode(text)));
 }
+/** Computes a SHA-256 digest encoded as base64url. */
 async function sha256Base64url(text) {
     if (typeof crypto !== "undefined" && crypto.subtle) {
         const data = new TextEncoder().encode(text);
@@ -192,6 +194,7 @@ async function sha256Base64url(text) {
     }
     return sha256Base64urlSync(text);
 }
+/** Canonicalizes JSON and computes its SHA-256 base64url digest. */
 async function digestJson(value) {
     const canonical = canonicalizeJson(value);
     const digest = await sha256Base64url(canonical);

package/script/contract_support/mod.d.ts

@@ -7,11 +7,11 @@ import type { StateDeleteInput, StateDeleteResponse } from "../models/trellis/rp
 import type { StateGetInput, StateGetResponse } from "../models/trellis/rpc/StateGet.js";
 import type { StateListInput, StateListResponse } from "../models/trellis/rpc/StateList.js";
 import type { StatePutInput, StatePutResponse } from "../models/trellis/rpc/StatePut.js";
-import { canonicalizeJson, digestJson, isJsonValue, type JsonValue } from "./canonical.js";
+import { canonicalizeJson, digestJson, isJsonValue, type JsonValue, sha256Base64urlSync } from "./canonical.js";
 import { type EventDesc, type FeedDesc, type InferRuntimeRpcError, type InferSchemaType, type OperationDesc, type RPCDesc, type RpcErrorClass, type RuntimeRpcErrorDesc, type Schema, schema, type SchemaLike, type SerializableErrorData, type TrellisAPI, unwrapSchema } from "./runtime.js";
 import { type SubjectParam } from "./schema_pointers.js";
-import { type ContractEventConsumers } from "./protocol.js";
-export { buildCursorPage, buildPageResponse, type ContractEventConsumerGroup, ContractEventConsumerGroupSchema, type ContractEventConsumers, type ContractEventConsumerSelf, ContractEventConsumerSelfSchema, ContractEventConsumersSchema, type ContractEventConsumerUses, ContractEventConsumerUsesSchema, ContractJobQueueSchema, ContractJobsSchema, ContractKvResourceSchema, ContractResourceBindingsSchema, ContractResourcesSchema, ContractSchemaRefSchema, ContractStateSchema, ContractStateStoreSchema, ContractStoreResourceSchema, type CursorPage, type CursorPageInfo, CursorPageInfoSchema, type CursorPageResponseSchema, CursorPageSchema, type CursorQuery, type CursorQueryOptions, CursorQuerySchema, type EventConsumerResourceBinding, EventConsumerResourceBindingSchema, type EventHeader, EventHeaderSchema, type InstalledServiceContract, InstalledServiceContractSchema, IsoDateSchema, type JobsQueueBinding, JobsQueueBindingSchema, type JobsResourceBinding, JobsResourceBindingSchema, type KvResourceBinding, KvResourceBindingSchema, normalizeCursorQuery, type NormalizedCursorQuery, normalizePageQuery, type PageRequest, PageRequestSchema, type PageResponse, PageResponseSchema, type StoreResourceBinding, StoreResourceBindingSchema, } from "./protocol.js";
+import { type ContractEventConsumers, type JobKeyConcurrency, type JobQueueDepth } from "./protocol.js";
+export { buildCursorPage, buildPageResponse, type ContractEventConsumerGroup, ContractEventConsumerGroupSchema, type ContractEventConsumers, type ContractEventConsumerSelf, ContractEventConsumerSelfSchema, ContractEventConsumersSchema, type ContractEventConsumerUses, ContractEventConsumerUsesSchema, ContractJobQueueSchema, ContractJobsSchema, ContractKvResourceSchema, type ContractResourceBindings, ContractResourceBindingsSchema, ContractResourcesSchema, ContractSchemaRefSchema, ContractStateSchema, ContractStateStoreSchema, ContractStoreResourceSchema, type CursorPage, type CursorPageInfo, CursorPageInfoSchema, type CursorPageResponseSchema, CursorPageSchema, type CursorQuery, type CursorQueryOptions, CursorQuerySchema, type EventConsumerResourceBinding, EventConsumerResourceBindingSchema, type InstalledServiceContract, InstalledServiceContractSchema, IsoDateSchema, type JobKeyConcurrency, JobKeyConcurrencySchema, type JobQueueDepth, JobQueueDepthSchema, type JobsQueueBinding, JobsQueueBindingSchema, type JobsQueueDepthBinding, JobsQueueDepthBindingSchema, type JobsQueueKeyConcurrencyBinding, JobsQueueKeyConcurrencyBindingSchema, type JobsResourceBinding, JobsResourceBindingSchema, type KvResourceBinding, KvResourceBindingSchema, normalizeCursorQuery, type NormalizedCursorQuery, normalizePageQuery, type PageRequest, PageRequestSchema, type PageResponse, PageResponseSchema, type StoreResourceBinding, StoreResourceBindingSchema, } from "./protocol.js";
 export { assertDataPointersExistAndAreTokenable, getSubschemaAtDataPointer, } from "./schema_pointers.js";
 export declare const CONTRACT_FORMAT_V1: "trellis.contract.v1";
 export declare const CATALOG_FORMAT_V1: "trellis.catalog.v1";
@@ -169,6 +169,9 @@ export declare const TrellisContractV1Schema: Type.TObject<{
         output: Type.TObject<{
             schema: Type.TString;
         }>;
+        errors: Type.TOptional<Type.TArray<Type.TObject<{
+            type: Type.TString;
+        }>>>;
         transfer: Type.TOptional<Type.TObject<{
             direction: Type.TLiteral<"send">;
             store: Type.TString;
@@ -253,6 +256,17 @@ export declare const TrellisContractV1Schema: Type.TObject<{
         logs: Type.TOptional<Type.TBoolean>;
         dlq: Type.TOptional<Type.TBoolean>;
         concurrency: Type.TOptional<Type.TInteger>;
+        keyConcurrency: Type.TOptional<Type.TObject<{
+            key: Type.TArray<Type.TString>;
+            maxActive: Type.TOptional<Type.TInteger>;
+            heartbeatIntervalMs: Type.TOptional<Type.TInteger>;
+            heartbeatTtlMs: Type.TOptional<Type.TInteger>;
+            stalePolicy: Type.TOptional<Type.TUnion<[Type.TLiteral<"fail-stale">, Type.TLiteral<"block">]>>;
+        }>>;
+        queue: Type.TOptional<Type.TObject<{
+            maxQueuedPerKey: Type.TOptional<Type.TInteger>;
+            whenFull: Type.TOptional<Type.TUnion<[Type.TLiteral<"reject">, Type.TLiteral<"coalesce">, Type.TLiteral<"replace-oldest">]>>;
+        }>>;
         docs: Type.TOptional<Type.TObject<{
             summary: Type.TOptional<Type.TString>;
             markdown: Type.TString;
@@ -383,13 +397,13 @@ export type ContractRpcMethod = {
     subject: string;
     input: ContractSchemaRef;
     output: ContractSchemaRef;
+    errors?: ContractErrorRef[];
     transfer?: {
         direction: "receive";
     };
     capabilities?: {
         call?: Capability[];
     };
-    errors?: ContractErrorRef[];
     internal?: boolean;
     docs?: ContractDocs;
 };
@@ -403,6 +417,7 @@ export type ContractOperation = {
     input: ContractSchemaRef;
     progress?: ContractSchemaRef;
     output: ContractSchemaRef;
+    errors?: ContractErrorRef[];
     transfer?: {
         direction: "send";
         store: string;
@@ -454,6 +469,8 @@ export type ContractJobQueueResource = {
     logs?: boolean;
     dlq?: boolean;
     concurrency?: number;
+    keyConcurrency?: JobKeyConcurrency;
+    queue?: JobQueueDepth;
     docs?: ContractDocs;
 };
 export type ContractJobQueue = ContractJobQueueResource;
@@ -600,11 +617,12 @@ export type ContractSourceOperationSignal<TSchemaName extends string = string> =
     input: ContractSchemaRef<TSchemaName>;
     docs?: ContractDocs;
 };
-export type ContractSourceOperation<TSchemaName extends string = string, TCapability extends string = Capability> = {
+export type ContractSourceOperation<TSchemaName extends string = string, TErrorName extends string = string, TCapability extends string = Capability> = {
     version: `v${number}`;
     input: ContractSchemaRef<TSchemaName>;
     progress?: ContractSchemaRef<TSchemaName>;
     output: ContractSchemaRef<TSchemaName>;
+    errors?: readonly TErrorName[];
     transfer?: {
         direction: "send";
         store: string;
@@ -657,6 +675,17 @@ export type ContractSourceJobQueue<TSchemaName extends string = string> = {
     logs?: boolean;
     dlq?: boolean;
     concurrency?: number;
+    keyConcurrency?: {
+        key: readonly string[];
+        maxActive?: number;
+        heartbeatIntervalMs?: number;
+        heartbeatTtlMs?: number;
+        stalePolicy?: "fail-stale" | "block";
+    };
+    queue?: {
+        maxQueuedPerKey?: number;
+        whenFull?: "reject" | "coalesce" | "replace-oldest";
+    };
     docs?: ContractDocs;
 };
 export type ContractSourceJobs<TSchemaName extends string = string> = Record<string, ContractSourceJobQueue<TSchemaName>>;
@@ -947,11 +976,40 @@ type ProjectedRpcMethod<TMethod extends ContractSourceRpcMethod, TSchemas, _TErr
 type ProjectedRpc<T, TSchemas, TErrors> = T extends Readonly<Record<string, ContractSourceRpcMethod>> ? {
     [K in keyof T]: ProjectedRpcMethod<T[K], TSchemas, TErrors>;
 } : {};
-type ProjectedOperations<T, TSchemas> = T extends Readonly<Record<string, ContractSourceOperation>> ? {
-    [K in keyof T]: OperationDesc<ResolveSchemaFromMap<TSchemas, T[K]["input"]>, ResolveSchemaFromMap<TSchemas, T[K]["progress"]>, ResolveSchemaFromMap<TSchemas, T[K]["output"]>> & (T[K]["transfer"] extends undefined ? {} : {
+type ProjectedOperations<T, TSchemas, TId, TCapabilities, TErrors> = T extends Readonly<Record<string, ContractSourceOperation>> ? {
+    [K in keyof T]: OperationDesc<ResolveSchemaFromMap<TSchemas, T[K]["input"]>, ResolveSchemaFromMap<TSchemas, T[K]["progress"]>, ResolveSchemaFromMap<TSchemas, T[K]["output"]>> & {
+        subject: ProjectedOperationSubject<K, T[K]>;
+        callerCapabilities: ProjectedOperationCapabilities<T[K], "call", TId, TCapabilities>;
+        observeCapabilities: ProjectedOperationCapabilities<T[K], "observe", TId, TCapabilities>;
+        cancelCapabilities: ProjectedOperationCapabilities<T[K], "cancel", TId, TCapabilities>;
+        controlCapabilities: ProjectedOperationCapabilities<T[K], "control", TId, TCapabilities>;
+    } & {
+        errors?: T[K]["errors"];
+        runtimeErrors?: readonly RuntimeRpcErrorDesc[];
+        declaredErrorTypes?: readonly string[];
+    } & (T[K]["transfer"] extends undefined ? {} : {
         transfer: T[K]["transfer"];
-    });
+    }) & (T[K] extends {
+        cancel: infer TCancel extends boolean;
+    } ? {
+        cancel: TCancel;
+    } : {});
 } : {};
+type ProjectedOperationSubject<TKey, TOperation> = TOperation extends {
+    subject: infer TSubject extends string;
+} ? TSubject : TOperation extends {
+    version: infer TVersion extends `v${number}`;
+} ? `operations.${TVersion}.${Extract<TKey, string>}` : string;
+type ProjectedCapabilityNamespace<TId extends string> = TId extends `${infer TNamespace}@v${number}` ? TNamespace : TId;
+type ProjectedCapability<TCapability, TId, TCapabilities> = TCapability extends string ? TCapability extends PlatformCapability | GlobalCapability ? TCapability : TCapability extends Extract<keyof NonNullable<TCapabilities>, string> ? `${ProjectedCapabilityNamespace<Extract<TId, string>>}::${TCapability}` : TCapability : never;
+type ProjectedCapabilityList<TList, TId, TCapabilities> = TList extends readonly string[] ? {
+    readonly [K in keyof TList]: ProjectedCapability<TList[K], TId, TCapabilities>;
+} : readonly [];
+type ProjectedOperationCapabilities<TOperation, TKind extends "call" | "observe" | "cancel" | "control", TId, TCapabilities> = TOperation extends {
+    capabilities: infer TOperationCapabilities;
+} ? TOperationCapabilities extends {
+    [K in TKind]?: infer TList;
+} ? ProjectedCapabilityList<TList, TId, TCapabilities> : readonly [] : readonly [];
 type ProjectedEvents<T, TSchemas> = T extends Readonly<Record<string, ContractSourceEvent>> ? {
     [K in keyof T]: EventDesc<ResolveSchemaFromMap<TSchemas, T[K]["event"]>>;
 } : {};
@@ -959,6 +1017,8 @@ type ProjectedFeeds<T, TSchemas> = T extends Readonly<Record<string, ContractSou
     [K in keyof T]: FeedDesc<ResolveSchemaFromMap<TSchemas, T[K]["input"]>, ResolveSchemaFromMap<TSchemas, T[K]["event"]>>;
 } : {};
 export type OwnedApiFromSource<T extends {
+    id?: unknown;
+    capabilities?: unknown;
     schemas?: Readonly<Record<string, TSchema>>;
     errors?: unknown;
     rpc?: unknown;
@@ -967,7 +1027,7 @@ export type OwnedApiFromSource<T extends {
     feeds?: unknown;
 }> = {
     rpc: ProjectedRpc<T["rpc"], T["schemas"], T["errors"]>;
-    operations: ProjectedOperations<T["operations"], T["schemas"]>;
+    operations: ProjectedOperations<T["operations"], T["schemas"], T["id"], T["capabilities"], T["errors"]>;
     events: ProjectedEvents<T["events"], T["schemas"]>;
     feeds: ProjectedFeeds<T["feeds"], T["schemas"]>;
     subjects: {};
@@ -1160,6 +1220,61 @@ export declare function digestContractManifest(contract: TrellisContractV1): str
  * and reconstruction logic needed by `defineServiceContract(...)`.
  */
 export declare function defineError<const TType extends string, const TFields extends TProperties>(options: DefineErrorOptions<TType, TFields>): DefinedErrorClass<TType, TFields>;
+/**
+ * Hints for a single schema validation keyword failure.
+ *
+ * Provides per-keyway UX metadata that a UI can surface when a field-level
+ * validation error occurs for this schema node.
+ */
+export type TrellisValidationIssueHint = {
+    code: string;
+    message: string;
+    note?: string;
+    label?: string;
+    i18nKey?: string;
+    severity?: "error" | "warning" | "info";
+};
+/**
+ * Extension metadata attached to a TypeBox schema node via
+ * `withTrellisValidation`.
+ *
+ * Carries the label, note, uiPath, and per-keyword issue hints that the
+ * runtime uses to produce structured field-level validation errors.
+ */
+export type TrellisValidationExtension = {
+    label?: string;
+    note?: string;
+    uiPath?: string;
+    issues?: Record<string, TrellisValidationIssueHint>;
+};
+/**
+ * Attaches Trellis validation UX metadata to a TypeBox schema node.
+ *
+ * When a request fails schema validation before handler dispatch, the metadata
+ * is used to produce a `SchemaValidationError` with stable field-level issue
+ * information that UIs can use without needing service-specific error handling.
+ *
+ * @template T The schema type.
+ * @param schema The TypeBox schema to annotate.
+ * @param extension The validation extension with labels, notes, and per-keyword issue hints.
+ * @returns The same schema type with `x-trellis-validation` attached.
+ *
+ * @example
+ * ```ts
+ * const MySchema = Type.Object({
+ *   name: withTrellisValidation(Type.String({ minLength: 1 }), {
+ *     label: "Name",
+ *     issues: {
+ *       minLength: {
+ *         code: "my.name.required",
+ *         message: "Enter a name.",
+ *       },
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export declare function withTrellisValidation<T extends TSchema>(schema: T, extension: TrellisValidationExtension): T;
 export declare function defineServiceContract<const TErrors extends Readonly<Record<string, unknown>> | undefined, const TRegistry extends DefineContractRegistry<Readonly<Record<string, TSchema>> | undefined, TErrors>, const TCapabilities extends ContractCapabilities | undefined, const TUses extends AuthorContractUses | undefined, const TRpc extends Readonly<Record<string, ContractSourceRpcMethod<SchemaNameOf<RegistrySchemas<TRegistry>>, ErrorNameOf<RegistryErrors<TRegistry>>, CapabilityRef<TCapabilities>>>> | undefined, const TOperations extends Readonly<Record<string, ContractSourceOperation<SchemaNameOf<RegistrySchemas<TRegistry>>, CapabilityRef<TCapabilities>>>> | undefined, const TEvents extends Readonly<Record<string, ContractSourceEvent<SchemaNameOf<RegistrySchemas<TRegistry>>, CapabilityRef<TCapabilities>>>> | undefined, const TBody extends ServiceContractBodyInput<TCapabilities, RegistrySchemas<TRegistry>, TUses, RegistryErrors<TRegistry>, TRpc, TOperations, TEvents>>(registry: TRegistry & {
     capabilities?: never;
     exports?: never;
@@ -1180,5 +1295,5 @@ export declare function defineDeviceContract<const TSchemas extends Readonly<Rec
 }, build: (ref: ContractRefBuilder<TSchemas>) => TBody): DefinedContract<OwnedApiFromSource<BuiltContractSource<ClientContractRegistry<TSchemas>, WithKind<TBody, "device">>>, UsedApiFromSource<BuiltContractSource<ClientContractRegistry<TSchemas>, WithKind<TBody, "device">>>, MergeApis<OwnedApiFromSource<BuiltContractSource<ClientContractRegistry<TSchemas>, WithKind<TBody, "device">>>, UsedApiFromSource<BuiltContractSource<ClientContractRegistry<TSchemas>, WithKind<TBody, "device">>>>, TBody["id"], {}, ProjectedState<StateFromSource<BuiltContractSource<ClientContractRegistry<TSchemas>, WithKind<TBody, "device">>>, SchemasFromSource<BuiltContractSource<ClientContractRegistry<TSchemas>, WithKind<TBody, "device">>>>>;
 export declare function defineDeviceContract<const TUses extends AuthorContractUses | undefined, const TBody extends ClientContractBodyInput<undefined, TUses>>(build: () => TBody): DefinedContract<OwnedApiFromSource<WithKind<TBody, "device">>, UsedApiFromSource<WithKind<TBody, "device">>, MergeApis<OwnedApiFromSource<WithKind<TBody, "device">>, UsedApiFromSource<WithKind<TBody, "device">>>, TBody["id"], {}, ProjectedState<StateFromSource<WithKind<TBody, "device">>, SchemasFromSource<WithKind<TBody, "device">>>>;
 export type { EventDesc, FeedDesc, InferRuntimeRpcError, InferSchemaType, JsonValue, RPCDesc, RpcErrorClass, RuntimeRpcErrorDesc, Schema, SchemaLike, SerializableErrorData, TrellisAPI, };
-export { canonicalizeJson, digestJson, isJsonValue, schema, unwrapSchema };
+export { canonicalizeJson, digestJson, isJsonValue, schema, sha256Base64urlSync, unwrapSchema, };
 //# sourceMappingURL=mod.d.ts.map