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

package/esm/client_connect.js

@@ -9,11 +9,12 @@ import { importEd25519PrivateKeyFromSeedBase64url, publicKeyBase64urlFromSeed, s
 import { DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS, } from "./runtime_transport.js";
 import { Trellis, } from "./trellis.js";
 import { TransportError } from "./errors/index.js";
-import { AsyncResult, Result, UnexpectedError } from "@qlever-llc/result";
+import { AsyncResult, BaseError, Result, UnexpectedError, } from "@qlever-llc/result";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { bindFlowSig, oauthInitSig, signBytes, } from "./auth/browser/session.js";
 import { observeNatsTrellisConnection, } from "./connection.js";
+import { recordTrellisDuration } from "./telemetry/mod.js";
 function createConnectedClient(args) {
     const trellis = new Trellis(args.name, args.nc, {
         sessionKey: args.sessionKey,
@@ -25,17 +26,26 @@ function createConnectedClient(args) {
     return trellis;
 }
 function clientConnectResult(promise) {
-    return AsyncResult.from(promise.then((value) => Result.ok(value), (cause) => Result.err(cause instanceof TransportError
+    return AsyncResult.from(promise.then((value) => Result.ok(value), (cause) => Result.err(cause instanceof TransportError ||
+        cause instanceof ClientAuthHandledError
         ? cause
         : new UnexpectedError({ cause }))));
 }
 /**
  * Error raised when client authentication was delegated to caller-owned routing.
  */
-export class ClientAuthHandledError extends Error {
+export class ClientAuthHandledError extends BaseError {
     constructor() {
         super("Client authentication was handled by the caller");
-        this.name = "ClientAuthHandledError";
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "ClientAuthHandledError"
+        });
+    }
+    toSerializable() {
+        return this.baseSerializable();
     }
 }
 const ClientTransportEndpointsSchema = Type.Object({
@@ -230,6 +240,7 @@ async function resolveClientIdentity(auth) {
     };
 }
 async function bindClientFlow(args) {
+    const startedAt = performance.now();
     const response = await fetch(`${args.trellisUrl}/auth/flow/${encodeURIComponent(args.flowId)}/bind`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -286,8 +297,14 @@ async function bindClientFlow(args) {
             },
         });
     }
+    recordTrellisDuration("trellis.connect.duration", performance.now() - startedAt, {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+    });
 }
 async function fetchClientBootstrap(args) {
+    const startedAt = performance.now();
     const response = await fetch(`${args.trellisUrl}/bootstrap/client`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -319,12 +336,27 @@ async function fetchClientBootstrap(args) {
         });
     }
     if (Value.Check(ClientBootstrapReadySchema, payload)) {
+        recordTrellisDuration("trellis.connect.duration", performance.now() - startedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
         return payload;
     }
     if (Value.Check(ClientBootstrapAuthRequiredSchema, payload)) {
+        recordTrellisDuration("trellis.connect.duration", performance.now() - startedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
         return payload;
     }
     if (Value.Check(ClientBootstrapNotReadySchema, payload)) {
+        recordTrellisDuration("trellis.connect.duration", performance.now() - startedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
         return payload;
     }
     throw createTransportError({
@@ -343,6 +375,7 @@ function updateClockOffsetFromServer(args) {
 }
 async function fetchClientBootstrapWithRetry(args) {
     for (let attempt = 0; attempt < 2; attempt += 1) {
+        const attemptStartedAt = performance.now();
         const requestStartedAtMs = args.deps.now();
         const iat = correctedIatSeconds(requestStartedAtMs, args.offsetState.serverClockOffsetMs);
         const response = await fetchClientBootstrap({
@@ -352,6 +385,11 @@ async function fetchClientBootstrapWithRetry(args) {
             bootstrapSig: await args.identity.bootstrapSig(iat),
         });
         const responseReceivedAtMs = args.deps.now();
+        recordTrellisDuration("trellis.connect.duration", performance.now() - attemptStartedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
         updateClockOffsetFromServer({
             offsetState: args.offsetState,
             requestStartedAtMs,
@@ -514,6 +552,7 @@ function bootstrapTargetsRequestedContract(bootstrap, args) {
         bootstrap.connectInfo.contractDigest === requestedDigest;
 }
 async function buildSessionKeyLoginUrl(args) {
+    const startedAt = performance.now();
     const context = authRequestContextRecord(args.context);
     let response = await fetch(`${args.trellisUrl}/auth/requests`, {
         method: "POST",
@@ -528,6 +567,11 @@ async function buildSessionKeyLoginUrl(args) {
         }),
     });
     if (await authStartNeedsManifest(response)) {
+        recordTrellisDuration("trellis.connect.duration", performance.now() - startedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
         response = await fetch(`${args.trellisUrl}/auth/requests`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
@@ -560,6 +604,11 @@ async function buildSessionKeyLoginUrl(args) {
     if (payload && typeof payload === "object" &&
         payload.status === "flow_started" &&
         typeof payload.loginUrl === "string") {
+        recordTrellisDuration("trellis.connect.duration", performance.now() - startedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
         return {
             status: "flow_started",
             loginUrl: payload.loginUrl,
@@ -567,6 +616,11 @@ async function buildSessionKeyLoginUrl(args) {
     }
     if (payload && typeof payload === "object" &&
         payload.status === "bound") {
+        recordTrellisDuration("trellis.connect.duration", performance.now() - startedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
         return { status: "bound" };
     }
     throw createTransportError({
@@ -596,6 +650,7 @@ async function authStartNeedsManifest(response) {
     return (await response.clone().text()).includes("manifest_required");
 }
 export async function connectClientWithDeps(args, deps) {
+    const totalStartedAt = performance.now();
     const trellisUrl = normalizeTrellisUrl(args.trellisUrl);
     const identity = await resolveClientIdentity(args.auth);
     const currentUrl = args.auth?.mode === "session_key"
@@ -640,6 +695,7 @@ export async function connectClientWithDeps(args, deps) {
             }
         }
     }
+    const initialBootstrapStartedAt = performance.now();
     const initialBootstrap = await fetchClientBootstrapWithRetry({
         trellisUrl,
         sessionKey: identity.sessionKey,
@@ -647,10 +703,21 @@ export async function connectClientWithDeps(args, deps) {
         deps,
         offsetState,
     });
+    recordTrellisDuration("trellis.connect.duration", performance.now() - initialBootstrapStartedAt, {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+    });
+    const authStartedAt = performance.now();
     const bootstrap = needsReauth(initialBootstrap) ||
         !bootstrapTargetsRequestedContract(initialBootstrap, args)
         ? await resolveAuthRequired(args, identity, currentUrl, deps, offsetState)
         : initialBootstrap;
+    recordTrellisDuration("trellis.connect.duration", performance.now() - authStartedAt, {
+        phase: "auth_resolution",
+        participantKind: "client",
+        outcome: "ok",
+    });
     if (bootstrap.status !== "ready") {
         if (bootstrap.status === "not_ready") {
             throw createTransportError({
@@ -730,12 +797,18 @@ export async function connectClientWithDeps(args, deps) {
     });
     let nc;
     try {
+        const natsStartedAt = performance.now();
         nc = await transport.connect({
             servers: selectClientRuntimeTransportServers(bootstrap.connectInfo.transports),
             maxReconnectAttempts: DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS,
             inboxPrefix: bootstrap.connectInfo.transport.inboxPrefix,
             authenticator: runtimeAuth.authenticators,
         });
+        recordTrellisDuration("trellis.connect.duration", performance.now() - natsStartedAt, {
+            phase: "nats_connect",
+            participantKind: "client",
+            outcome: "ok",
+        });
     }
     catch (error) {
         runtimeAuth.stop();
@@ -775,7 +848,7 @@ export async function connectClientWithDeps(args, deps) {
         throw new Error("Contract is missing an owned or trellis API view");
     }
     const state = args.contract[CONTRACT_STATE_METADATA];
-    return createConnectedClient({
+    const client = createConnectedClient({
         name: clientOpts.name ?? "client",
         nc,
         connection,
@@ -791,6 +864,12 @@ export async function connectClientWithDeps(args, deps) {
             onSessionNotFound: handleSessionNotFound,
         },
     });
+    recordTrellisDuration("trellis.connect.duration", performance.now() - totalStartedAt, {
+        phase: "total",
+        participantKind: "client",
+        outcome: "ok",
+    });
+    return client;
 }
 async function resolveAuthRequired(args, identity, currentUrl, deps, offsetState) {
     const browserAuth = args.auth?.mode === "session_key" ? {} : args.auth ?? {};
@@ -825,37 +904,63 @@ async function resolveAuthRequired(args, identity, currentUrl, deps, offsetState
             context: browserAuth.context,
         });
     if (authStart.status === "bound") {
-        return await fetchClientBootstrapWithRetry({
+        const bootstrapStartedAt = performance.now();
+        const bootstrap = await fetchClientBootstrapWithRetry({
             trellisUrl: normalizeTrellisUrl(args.trellisUrl),
             sessionKey: identity.sessionKey,
             identity,
             deps,
             offsetState,
         });
+        recordTrellisDuration("trellis.connect.duration", performance.now() - bootstrapStartedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
+        return bootstrap;
     }
     const loginUrl = authStart.loginUrl;
+    const continuationStartedAt = performance.now();
     const continuation = await args.onAuthRequired?.({
         loginUrl,
         sessionKey: identity.sessionKey,
         mode: identity.mode,
     });
+    recordTrellisDuration("trellis.connect.duration", performance.now() - continuationStartedAt, {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+    });
     if (continuation && continuation.status === "handled") {
         throw new ClientAuthHandledError();
     }
     if (continuation && continuation.status === "bound") {
+        const bindStartedAt = performance.now();
         await bindClientFlow({
             trellisUrl: normalizeTrellisUrl(args.trellisUrl),
             sessionKey: identity.sessionKey,
             flowId: continuation.flowId,
             sig: await identity.bindFlowSig(continuation.flowId),
         });
-        return await fetchClientBootstrapWithRetry({
+        recordTrellisDuration("trellis.connect.duration", performance.now() - bindStartedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
+        const bootstrapStartedAt = performance.now();
+        const bootstrap = await fetchClientBootstrapWithRetry({
             trellisUrl: normalizeTrellisUrl(args.trellisUrl),
             sessionKey: identity.sessionKey,
             identity,
             deps,
             offsetState,
         });
+        recordTrellisDuration("trellis.connect.duration", performance.now() - bootstrapStartedAt, {
+            phase: "bootstrap",
+            participantKind: "client",
+            outcome: "ok",
+        });
+        return bootstrap;
     }
     if (isBrowserRuntime()) {
         globalThis.location.href = loginUrl;

package/esm/codec.d.ts

@@ -1,13 +1,14 @@
 import { type InferSchemaType, type SchemaLike } from "./contracts.js";
 import { Result } from "@qlever-llc/result";
 import type { StaticDecode, TSchema } from "typebox";
-import { UnexpectedError, ValidationError } from "./errors/index.js";
+import { SchemaValidationError, UnexpectedError, ValidationError } from "./errors/index.js";
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-export declare function parse<T extends TSchema>(schema: T, data: JsonValue): Result<StaticDecode<T>, ValidationError | UnexpectedError>;
-export declare function parseSchema<S extends SchemaLike>(schema: S, data: JsonValue): Result<InferSchemaType<S>, ValidationError | UnexpectedError>;
-export declare function parseUnknownSchema(schema: SchemaLike, data: JsonValue): Result<unknown, ValidationError | UnexpectedError>;
-export declare function encode<T extends TSchema>(schema: T, data: unknown): Result<string, ValidationError | UnexpectedError>;
-export declare function encodeSchema(schema: SchemaLike, data: unknown): Result<string, ValidationError | UnexpectedError>;
+export declare function parse<T extends TSchema>(schema: T, data: JsonValue): Result<StaticDecode<T>, SchemaValidationError | ValidationError | UnexpectedError>;
+export declare function parseSchema<S extends SchemaLike>(schema: S, data: JsonValue): Result<InferSchemaType<S>, SchemaValidationError | ValidationError | UnexpectedError>;
+/** Parses unknown JSON-compatible data with an arbitrary Trellis schema. */
+export declare function parseUnknownSchema(schema: SchemaLike, data: JsonValue): Result<unknown, SchemaValidationError | ValidationError | UnexpectedError>;
+export declare function encode<T extends TSchema>(schema: T, data: unknown): Result<string, SchemaValidationError | ValidationError | UnexpectedError>;
+export declare function encodeSchema(schema: SchemaLike, data: unknown): Result<string, SchemaValidationError | ValidationError | UnexpectedError>;
 //# sourceMappingURL=codec.d.ts.map

package/esm/codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,UAAU,EAEhB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAErE,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B,CAAC;AAUJ,wBAAgB,KAAK,CAAC,CAAC,SAAS,OAAO,EACrC,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,SAAS,GACd,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,eAAe,GAAG,eAAe,CAAC,CAU5D;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAC9C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,SAAS,GACd,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,GAAG,eAAe,CAAC,CAa/D;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,SAAS,GACd,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAAC,CAWpD;AAED,wBAAgB,MAAM,CAAC,CAAC,SAAS,OAAO,EACtC,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAAC,CAUnD;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAAC,CAWnD"}
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,UAAU,EAEhB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAErD,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAQ3B,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B,CAAC;AAwKJ,wBAAgB,KAAK,CAAC,CAAC,SAAS,OAAO,EACrC,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,SAAS,GACd,MAAM,CACP,YAAY,CAAC,CAAC,CAAC,EACf,qBAAqB,GAAG,eAAe,GAAG,eAAe,CAC1D,CAUA;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAC9C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,SAAS,GACd,MAAM,CACP,eAAe,CAAC,CAAC,CAAC,EAClB,qBAAqB,GAAG,eAAe,GAAG,eAAe,CAC1D,CAaA;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,SAAS,GACd,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,GAAG,eAAe,CAAC,CAW5E;AAED,wBAAgB,MAAM,CAAC,CAAC,SAAS,OAAO,EACtC,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,GAAG,eAAe,CAAC,CAU3E;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,GAAG,eAAe,CAAC,CAW3E"}

package/esm/codec.js

@@ -1,7 +1,125 @@
 import { unwrapSchema, } from "./contracts.js";
 import { Result } from "@qlever-llc/result";
 import { EncodeError, ParseError, Value } from "typebox/value";
-import { UnexpectedError, ValidationError } from "./errors/index.js";
+import { SchemaValidationError, UnexpectedError, ValidationError, } from "./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 SchemaValidationError({ issues: annotated, cause });
+    }
+    return new ValidationError({
+        errors: unannotated.length > 0
+            ? unannotated
+            : annotated.map((i) => ({ path: i.path, message: i.message })),
+        cause,
+    });
+}
 function parseWithSchema(schema, data) {
     return Value.Parse(schema, data);
 }
@@ -15,7 +133,7 @@ export function parse(schema, data) {
     catch (cause) {
         if (cause instanceof ParseError) {
             const errors = Value.Errors(schema, data);
-            return Result.err(new ValidationError({ errors, cause }));
+            return Result.err(buildValidationError(schema, data, errors, cause));
         }
         return Result.err(new UnexpectedError({ cause }));
     }
@@ -28,11 +146,12 @@ export function parseSchema(schema, data) {
     catch (cause) {
         if (cause instanceof ParseError) {
             const errors = Value.Errors(raw, data);
-            return Result.err(new ValidationError({ errors, cause }));
+            return Result.err(buildValidationError(raw, data, errors, cause));
         }
         return Result.err(new UnexpectedError({ cause }));
     }
 }
+/** Parses unknown JSON-compatible data with an arbitrary Trellis schema. */
 export function parseUnknownSchema(schema, data) {
     const raw = unwrapSchema(schema);
     try {
@@ -41,7 +160,7 @@ export function parseUnknownSchema(schema, data) {
     catch (cause) {
         if (cause instanceof ParseError) {
             const errors = Value.Errors(raw, data);
-            return Result.err(new ValidationError({ errors, cause }));
+            return Result.err(buildValidationError(raw, data, errors, cause));
         }
         return Result.err(new UnexpectedError({ cause }));
     }
@@ -53,7 +172,7 @@ export function encode(schema, data) {
     catch (cause) {
         if (cause instanceof EncodeError) {
             const errors = Value.Errors(schema, data);
-            return Result.err(new ValidationError({ errors, cause }));
+            return Result.err(buildValidationError(schema, data, errors, cause));
         }
         return Result.err(new UnexpectedError({ cause }));
     }
@@ -66,7 +185,7 @@ export function encodeSchema(schema, data) {
     catch (cause) {
         if (cause instanceof EncodeError) {
             const errors = Value.Errors(raw, data);
-            return Result.err(new ValidationError({ errors, cause }));
+            return Result.err(buildValidationError(raw, data, errors, cause));
         }
         return Result.err(new UnexpectedError({ cause }));
     }

package/esm/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/esm/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/esm/contract_support/canonical.js

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