@aventara/core 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/contracts/client-contract-structure.validator.js

@@ -1,4 +1,5 @@
-import { PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
+import { isAccessPath, isAccessUrl } from "./access-route.rules.js";
+import { FILTER_MODES, PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
 import { AVENTARA_PROTOCOL_VERSION } from "./contract-protocol.js";
 import { LIFECYCLE_TRAITS } from "./lifecycle-trait.js";
 import { REFERENCE_WRITE_LIMITS } from "./reference-write-limit.js";
@@ -10,13 +11,16 @@ function literal(values) {
     return { is: "literal", values };
 }
 function list(item) {
-    return { is: "list", item, nonEmpty: false, unique: false };
+    return { is: "list", item, minimum: 0, unique: false };
 }
 function nonEmptyList(item) {
-    return { is: "list", item, nonEmpty: true, unique: false };
+    return { is: "list", item, minimum: 1, unique: false };
+}
+function pairOrMoreList(item) {
+    return { is: "list", item, minimum: 2, unique: false };
 }
 function uniqueList(item) {
-    return { is: "list", item, nonEmpty: false, unique: true };
+    return { is: "list", item, minimum: 0, unique: true };
 }
 function registry(entry) {
     return { is: "registry", entry };
@@ -93,6 +97,127 @@ const RELATION_MUTATION = union(list(literal(RELATION_MUTATION_DIRECTIVES)), obj
     directives: list(literal(RELATION_MUTATION_DIRECTIVES)),
     scopes: WRITE_SCOPE_LIST,
 }));
+const NAMED_FORMATS = [
+    "lowercase",
+    "uppercase",
+    "email",
+    "url",
+    "emoji",
+    "uuid",
+    "guid",
+    "nanoid",
+    "cuid",
+    "cuid2",
+    "ulid",
+    "xid",
+    "ksuid",
+    "datetime",
+    "date",
+    "time",
+    "duration",
+    "ipv4",
+    "ipv6",
+    "cidrv4",
+    "cidrv6",
+    "base64",
+    "base64url",
+    "json_string",
+    "e164",
+    "credit_card",
+    "iban",
+    "jwt",
+];
+const STRING_FORMAT_CHECK = union(object({
+    check: literal(["string_format"]),
+    format: literal(["regex"]),
+    pattern: object({ source: STRING, flags: STRING }),
+}), object({
+    check: literal(["string_format"]),
+    format: literal(["includes"]),
+    includes: STRING,
+}), object({
+    check: literal(["string_format"]),
+    format: literal(["starts_with"]),
+    prefix: STRING,
+}), object({
+    check: literal(["string_format"]),
+    format: literal(["ends_with"]),
+    suffix: STRING,
+}), object({
+    check: literal(["string_format"]),
+    format: literal(NAMED_FORMATS),
+}));
+const STRING_LENGTH_CHECKS = {
+    max_length: object({ check: literal(["max_length"]), maximum: NUMBER }),
+    min_length: object({ check: literal(["min_length"]), minimum: NUMBER }),
+    length_equals: object({ check: literal(["length_equals"]), length: NUMBER }),
+    string_format: STRING_FORMAT_CHECK,
+};
+const FIELD_CHECK = {
+    is: "variants",
+    key: "check",
+    arms: {
+        less_than: object({
+            check: literal(["less_than"]),
+            value: union(NUMBER, STRING),
+            inclusive: BOOLEAN,
+        }),
+        greater_than: object({
+            check: literal(["greater_than"]),
+            value: union(NUMBER, STRING),
+            inclusive: BOOLEAN,
+        }),
+        multiple_of: object({
+            check: literal(["multiple_of"]),
+            value: union(NUMBER, STRING),
+        }),
+        max_length: object({ check: literal(["max_length"]), maximum: NUMBER }, { list: literal([true]) }),
+        min_length: object({ check: literal(["min_length"]), minimum: NUMBER }, { list: literal([true]) }),
+        length_equals: STRING_LENGTH_CHECKS.length_equals,
+        string_format: STRING_FORMAT_CHECK,
+        max_size: object({ check: literal(["max_size"]), maximum: NUMBER }),
+        min_size: object({ check: literal(["min_size"]), minimum: NUMBER }),
+        size_equals: object({ check: literal(["size_equals"]), size: NUMBER }),
+    },
+};
+const JSON_STRING_CHECK = {
+    is: "variants",
+    key: "check",
+    arms: STRING_LENGTH_CHECKS,
+};
+const JSON_NUMBER_CHECK = {
+    is: "variants",
+    key: "check",
+    arms: {
+        less_than: object({
+            check: literal(["less_than"]),
+            value: NUMBER,
+            inclusive: BOOLEAN,
+        }),
+        greater_than: object({
+            check: literal(["greater_than"]),
+            value: NUMBER,
+            inclusive: BOOLEAN,
+        }),
+        multiple_of: object({ check: literal(["multiple_of"]), value: NUMBER }),
+    },
+};
+const JSON_LIST_CHECK = {
+    is: "variants",
+    key: "check",
+    arms: {
+        max_length: object({
+            check: literal(["max_length"]),
+            maximum: NUMBER,
+            list: literal([true]),
+        }),
+        min_length: object({
+            check: literal(["min_length"]),
+            minimum: NUMBER,
+            list: literal([true]),
+        }),
+    },
+};
 const SCALAR_FIELD = object({
     kind: literal(["scalar"]),
     type: union(object({ scalar: STRING }), object({ enum: STRING })),
@@ -102,12 +227,19 @@ const SCALAR_FIELD = object({
     capabilities: object({}, {
         select: BOOLEAN,
         filter: list(literal(SCALAR_FILTER_OPERATORS)),
+        filterModes: list(literal(FILTER_MODES)),
+        pathFilterModes: list(literal(FILTER_MODES)),
         order: BOOLEAN,
         orderNulls: BOOLEAN,
         create: list(literal(SCALAR_MUTATION_DIRECTIVES)),
         update: list(literal(SCALAR_MUTATION_DIRECTIVES)),
     }),
-}, { format: STRING, json: { is: "jsonSchema" } });
+}, {
+    format: STRING,
+    json: { is: "jsonSchema" },
+    validators: list(FIELD_CHECK),
+    governed: literal([true]),
+});
 const RELATION_FIELD = object({
     kind: literal(["relation"]),
     target: STRING,
@@ -127,6 +259,10 @@ const RELATION_FIELD = object({
         update: RELATION_MUTATION,
         nestedWriteFilter: literal(["scalar"]),
     }),
+}, {
+    inverse: STRING,
+    referenceFields: nonEmptyList(STRING),
+    governed: literal([true]),
 });
 const OPERATION_AVAILABILITY = union(literal([true]), object({ projection: literal(PROJECTION_SCOPES) }, { write: literal(WRITE_SCOPES) }), object({ write: literal(WRITE_SCOPES) }, { projection: literal(PROJECTION_SCOPES) }));
 const RESOURCE = object({
@@ -162,6 +298,32 @@ const RESOURCE = object({
         }),
         upsert: object({}, { unique: OPERATION_AVAILABILITY }),
     }),
+}, {
+    createRequirements: object({}, {
+        required: nonEmptyList(STRING),
+        oneOf: nonEmptyList(pairOrMoreList(STRING)),
+        parentSupplies: registry(registry(nonEmptyList(STRING))),
+    }),
+});
+const ACCESS_VERB = object({
+    method: literal(["GET", "POST"]),
+    path: { is: "route", form: "path" },
+    result: { is: "jsonSchema" },
+}, { args: { is: "jsonSchema" } });
+const ACCESS = object({}, {
+    url: { is: "route", form: "url" },
+    verbs: object({}, {
+        signIn: ACCESS_VERB,
+        signUp: ACCESS_VERB,
+        signOut: ACCESS_VERB,
+        resetPassword: ACCESS_VERB,
+        me: ACCESS_VERB,
+        switchUser: ACCESS_VERB,
+        lock: ACCESS_VERB,
+        setPin: ACCESS_VERB,
+        enrollDevice: ACCESS_VERB,
+        revokeDevice: ACCESS_VERB,
+    }),
 });
 export const CLIENT_CONTRACT_STRUCTURE = object({
     scalars: registry(object({ builtin: literal([true]) })),
@@ -173,13 +335,14 @@ export const CLIENT_CONTRACT_STRUCTURE = object({
         maxListLimit: NUMBER,
         maxTransactionOperations: NUMBER,
         maxBooleanNodes: NUMBER,
+        maxJsonDepth: NUMBER,
     }),
     transactions: literal(TRANSACTION_CAPABILITIES),
     protocol: object({
         version: literal([AVENTARA_PROTOCOL_VERSION]),
         hash: { is: "prefixed", prefix: "sha256:" },
     }),
-}, { referenceWrites: literal(REFERENCE_WRITE_LIMITS) });
+}, { referenceWrites: literal(REFERENCE_WRITE_LIMITS), access: ACCESS });
 export function validateClientContractStructure(value) {
     const defect = defectOf(CLIENT_CONTRACT_STRUCTURE, value, "$", 0);
     if (defect !== undefined) {
@@ -201,6 +364,13 @@ function defectOf(node, value, path, depth) {
                 (value.startsWith(node.prefix)
                     ? undefined
                     : at(path, depth, `is ${JSON.stringify(value)}, which does not begin with ${JSON.stringify(node.prefix)}`)));
+        case "route":
+            return (kindDefect(value, "string", path, depth) ??
+                ((node.form === "url" ? isAccessUrl : isAccessPath)(value)
+                    ? undefined
+                    : at(path, depth, node.form === "url"
+                        ? "is no absolute http(s) URL and no root-relative path"
+                        : 'is no path under the url, starting with one "/"')));
         case "list":
             return listDefect(node, value, path, depth);
         case "registry": {
@@ -272,13 +442,20 @@ function jsonSchemaDefect(value, path, depth) {
     switch (keys) {
         case "type":
             return literalDefect(JSON_SCHEMA_SCALAR_TYPES, schema.type, `${path}.type`, depth + 1);
+        case "checks,type":
+            return (literalDefect(["string", "number", "integer"], schema.type, `${path}.type`, depth + 1) ??
+                defectOf(list(schema.type === "string" ? JSON_STRING_CHECK : JSON_NUMBER_CHECK), schema.checks, `${path}.checks`, depth + 1));
+        case "checks,items,type":
+            return (literalDefect(["array"], schema.type, `${path}.type`, depth + 1) ??
+                child("items", schema.items) ??
+                defectOf(list(JSON_LIST_CHECK), schema.checks, `${path}.checks`, depth + 1));
         case "const":
             return Object.is(schema.const, null)
                 ? undefined
                 : defectOf(JSON_PRIMITIVE, schema.const, `${path}.const`, depth + 1);
         case "enum,type":
             return (literalDefect(["string"], schema.type, `${path}.type`, depth + 1) ??
-                defectOf({ is: "list", item: STRING, nonEmpty: true, unique: true }, schema.enum, `${path}.enum`, depth + 1));
+                defectOf({ is: "list", item: STRING, minimum: 1, unique: true }, schema.enum, `${path}.enum`, depth + 1));
         case "additionalProperties,properties,type":
         case "additionalProperties,properties,required,type": {
             const typeDefect = literalDefect(["object"], schema.type, `${path}.type`, depth + 1) ??
@@ -296,7 +473,7 @@ function jsonSchemaDefect(value, path, depth) {
             }
             if (!Object.hasOwn(schema, "required"))
                 return undefined;
-            const requiredDefect = defectOf({ is: "list", item: STRING, nonEmpty: false, unique: true }, schema.required, `${path}.required`, depth + 1);
+            const requiredDefect = defectOf({ is: "list", item: STRING, minimum: 0, unique: true }, schema.required, `${path}.required`, depth + 1);
             if (requiredDefect !== undefined)
                 return requiredDefect;
             const undeclared = schema.required.findIndex((name) => !Object.hasOwn(properties, name));
@@ -348,8 +525,10 @@ function listDefect(node, value, path, depth) {
     if (kind !== undefined)
         return kind;
     const entries = value;
-    if (node.nonEmpty && entries.length === 0) {
-        return at(path, depth, "is an empty JSON array, and needs at least one entry");
+    if (entries.length < node.minimum) {
+        return at(path, depth, entries.length === 0
+            ? `is an empty JSON array, and needs at least ${node.minimum === 1 ? "one entry" : "two entries"}`
+            : "is a JSON array of one entry, and needs at least two");
     }
     const firstIndexOf = new Map();
     for (let index = 0; index < entries.length; index += 1) {

package/dist/contracts/contract-access.d.ts

@@ -0,0 +1,29 @@
+import type { JsonSchema } from "./json-shape.js";
+/**
+ * The ClientContract's `access` section: present exactly when the framework's
+ * `access` option is configured, and then it marks the `POST /_access/can`
+ * route. `url` and `verbs` say where Aventara Access is mounted and each of its
+ * `$access` verbs, when the provider states them.
+ */
+export type AvContractClientAccess = {
+    /** Where the app mounted Access: absolute, or root-relative (`"/api/auth"`). */
+    readonly url?: string;
+    /**
+     * Each `$access` verb the provider offers: its route under `url`, and the
+     * JSON Schema of its arguments and result. A verb left out is no verb of
+     * `$access` (a `service` profile has no `signIn` or `signUp`; only a
+     * `kiosk` profile has `switchUser`, `lock`, `setPin`, `enrollDevice` and
+     * `revokeDevice`).
+     */
+    readonly verbs?: {
+        readonly [Verb in "signIn" | "signUp" | "signOut" | "resetPassword" | "me" | "switchUser" | "lock" | "setPin" | "enrollDevice" | "revokeDevice"]?: {
+            readonly method: "GET" | "POST";
+            /** Under `url`: `"/sign-in/email"`. */
+            readonly path: string;
+            /** The arguments' JSON Schema; absent when the verb takes none. */
+            readonly args?: JsonSchema;
+            /** The result's JSON Schema (`me`: the value when someone is signed in). */
+            readonly result: JsonSchema;
+        };
+    };
+};

package/dist/contracts/contract-access.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/contract-canonicalizer.d.ts

@@ -1,11 +1,35 @@
-import type { Contract } from "./contract.js";
+import type { AvContract } from "./contract.js";
 /**
  * Thrown when a value cannot be written as canonical JSON (RFC 8785). It is a
  * `TypeError`.
  */
-export declare class CanonicalJsonError extends TypeError {
+export declare class AvCanonicalJsonError extends TypeError {
 }
 /** Canonical JSON (RFC 8785) for a JSON-safe value. */
 export declare function canonicalizeJson(value: unknown): string;
+/**
+ * Canonical JSON (RFC 8785) for a value as JSON carries it: a key holding
+ * `undefined` is left out, and an array element holding it (or a hole) is
+ * `null`, as `JSON.stringify` writes them. Everything else as
+ * {@link canonicalizeJson}.
+ */
+export declare function canonicalizeWireJson(value: unknown): string;
+/** One top-level member of a canonical Contract: its key and its value's canonical text. */
+type CanonicalContractMember = {
+    readonly key: string;
+    readonly text: string;
+};
+/** The Contract as canonical JSON (RFC 8785), one top-level member at a time, in order. */
+export declare function canonicalizeContractMembers<C extends AvContract>(contract: C): readonly CanonicalContractMember[];
+/** The canonical object text the members write: `{"key":text,…}`, in their order. */
+export declare function joinCanonicalContractMembers(members: readonly CanonicalContractMember[]): string;
 /** The Contract as canonical JSON (RFC 8785): the same bytes for the same Contract. */
-export declare function canonicalizeContract<C extends Contract>(contract: C): string;
+export declare function canonicalizeContract<C extends AvContract>(contract: C): string;
+/** Records `text` as the canonical text `contract` was parsed from. */
+export declare function recordCanonicalContractText(contract: AvContract, text: string): void;
+/**
+ * The Contract's canonical text: the text it was identified from, when the compiler
+ * recorded one, else written now. Both are the same bytes for the same Contract.
+ */
+export declare function canonicalContractTextOf<C extends AvContract>(contract: C): string;
+export {};

package/dist/contracts/contract-canonicalizer.js

@@ -1,10 +1,12 @@
-import { PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
+import { brandCoreClass } from "../runtime/core-class.brand.js";
+import { FILTER_MODES, PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
 import { LIFECYCLE_TRAITS } from "./lifecycle-trait.js";
 import { projectionScopeOf, writeScopeOf } from "./resource-operations.js";
 const PAGINATION_ORDER = ["limit", "offset", "cursor"];
 const REDUCER_ORDER = ["$count"];
-export class CanonicalJsonError extends TypeError {
+export class AvCanonicalJsonError extends TypeError {
 }
+brandCoreClass(AvCanonicalJsonError, "AvCanonicalJsonError");
 function compareCodeUnits(left, right) {
     if (left === right) {
         return 0;
@@ -61,6 +63,12 @@ function normalizeCapabilities(capabilities) {
     if (Array.isArray(filter)) {
         normalized.filter = normalizeStringSet(filter);
     }
+    for (const key of ["filterModes", "pathFilterModes"]) {
+        const modes = normalized[key];
+        if (Array.isArray(modes)) {
+            normalized[key] = normalizeStringSet(modes, FILTER_MODES);
+        }
+    }
     for (const key of ["create", "update"]) {
         const value = normalized[key];
         if (Array.isArray(value)) {
@@ -103,7 +111,7 @@ function normalizeJsonSchema(schema) {
                 normalizeJsonSchema(child),
             ]));
         }
-        else if (key === "const" || key === "enum") {
+        else if (key === "const" || key === "enum" || key === "checks") {
             normalized[key] = value;
         }
         else {
@@ -173,8 +181,56 @@ function normalizeResource(resource) {
         fields,
         identifiers,
         operations: normalizeOperations(resource.operations),
+        ...(resource.createRequirements === undefined
+            ? {}
+            : {
+                createRequirements: normalizeCreateRequirements(resource.createRequirements),
+            }),
+        ...coreResourceFacts(resource),
+    };
+}
+function coreResourceFacts(resource) {
+    const facts = resource;
+    return {
+        ...(facts.schema === undefined ? {} : { schema: facts.schema }),
+        ...(facts.managedElsewhere === undefined
+            ? {}
+            : { managedElsewhere: facts.managedElsewhere }),
     };
 }
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeCreateRequirements(requirements) {
+    if (!isJsonObject(requirements)) {
+        return requirements;
+    }
+    const normalized = { ...requirements };
+    if (Array.isArray(requirements.required)) {
+        normalized.required = normalizeStringSet(requirements.required);
+    }
+    if (Array.isArray(requirements.oneOf)) {
+        normalized.oneOf = requirements.oneOf
+            .map((group) => Array.isArray(group) && group.length > 0
+            ? [group[0], ...normalizeStringSet(group.slice(1))]
+            : group)
+            .sort((left, right) => compareCodeUnits(canonicalizeJson(left), canonicalizeJson(right)));
+    }
+    if (isJsonObject(requirements.parentSupplies)) {
+        normalized.parentSupplies = Object.fromEntries(Object.entries(requirements.parentSupplies).map(([parent, byRelation]) => [
+            parent,
+            isJsonObject(byRelation)
+                ? Object.fromEntries(Object.entries(byRelation).map(([relation, members]) => [
+                    relation,
+                    Array.isArray(members)
+                        ? normalizeStringSet(members)
+                        : members,
+                ]))
+                : byRelation,
+        ]));
+    }
+    return normalized;
+}
 function normalizeContract(contract) {
     const scalars = Object.fromEntries(Object.keys(contract.scalars)
         .sort(compareCodeUnits)
@@ -201,17 +257,24 @@ function assertValidUnicode(value, path) {
         if (code >= 0xd800 && code <= 0xdbff) {
             const next = value.charCodeAt(index + 1);
             if (!(next >= 0xdc00 && next <= 0xdfff)) {
-                throw new CanonicalJsonError(`invalid Unicode surrogate at ${path}`);
+                throw new AvCanonicalJsonError(`invalid Unicode surrogate at ${path()}`);
             }
             index += 1;
             continue;
         }
         if (code >= 0xdc00 && code <= 0xdfff) {
-            throw new CanonicalJsonError(`invalid Unicode surrogate at ${path}`);
+            throw new AvCanonicalJsonError(`invalid Unicode surrogate at ${path()}`);
         }
     }
 }
-function canonicalizeValue(value, path) {
+function pathOf(link) {
+    const segments = [];
+    for (let current = link; current !== undefined; current = current.parent) {
+        segments.push(current.segment);
+    }
+    return `$${segments.reverse().join("")}`;
+}
+function canonicalizePrimitive(value, link) {
     if (value === null) {
         return "null";
     }
@@ -220,47 +283,123 @@ function canonicalizeValue(value, path) {
             return value ? "true" : "false";
         case "number": {
             if (!Number.isFinite(value)) {
-                throw new CanonicalJsonError(`non-finite number at ${path}`);
+                throw new AvCanonicalJsonError(`non-finite number at ${pathOf(link)}`);
             }
             const serialized = JSON.stringify(value);
             if (serialized === undefined) {
-                throw new CanonicalJsonError(`number at ${path} is not JSON serializable`);
+                throw new AvCanonicalJsonError(`number at ${pathOf(link)} is not JSON serializable`);
             }
             return serialized;
         }
         case "string":
-            assertValidUnicode(value, path);
+            assertValidUnicode(value, () => pathOf(link));
             return JSON.stringify(value);
         case "undefined":
-            throw new CanonicalJsonError(`undefined value at ${path}`);
+            throw new AvCanonicalJsonError(`undefined value at ${pathOf(link)}`);
         case "bigint":
         case "function":
         case "symbol":
-            throw new CanonicalJsonError(`${typeof value} value at ${path} is not JSON serializable`);
-        case "object":
-            break;
+            throw new AvCanonicalJsonError(`${typeof value} value at ${pathOf(link)} is not JSON serializable`);
+        default:
+            return undefined;
     }
-    if (Array.isArray(value)) {
-        return `[${Array.prototype.map
-            .call(value, (entry, index) => canonicalizeValue(entry, `${path}[${index}]`))
-            .join(",")}]`;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    if (prototype !== Object.prototype && prototype !== null) {
-        throw new CanonicalJsonError(`non-plain object at ${path} is not canonical JSON`);
+}
+function canonicalizeValue(value, link = undefined, undefinedAsJson = false) {
+    const output = [];
+    const stack = [{ kind: "value", value, link }];
+    while (stack.length > 0) {
+        const task = stack.pop();
+        if (task.kind === "text") {
+            output.push(task.text);
+            continue;
+        }
+        if (task.kind === "key") {
+            assertValidUnicode(task.key, () => `${pathOf(task.link)} key`);
+            output.push(`${JSON.stringify(task.key)}:`);
+            continue;
+        }
+        const { value: current, link } = task;
+        const primitive = canonicalizePrimitive(current, link);
+        if (primitive !== undefined) {
+            output.push(primitive);
+            continue;
+        }
+        if (Array.isArray(current)) {
+            output.push("[");
+            stack.push({ kind: "text", text: "]" });
+            for (let index = current.length - 1; index >= 0; index -= 1) {
+                if (undefinedAsJson && current[index] === undefined) {
+                    stack.push({ kind: "text", text: "null" });
+                }
+                else if (index in current) {
+                    stack.push({
+                        kind: "value",
+                        value: current[index],
+                        link: { parent: link, segment: `[${index}]` },
+                    });
+                }
+                if (index > 0) {
+                    stack.push({ kind: "text", text: "," });
+                }
+            }
+            continue;
+        }
+        const prototype = Object.getPrototypeOf(current);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new AvCanonicalJsonError(`non-plain object at ${pathOf(link)} is not canonical JSON`);
+        }
+        const record = current;
+        const keys = Object.keys(record)
+            .filter((key) => !undefinedAsJson || record[key] !== undefined)
+            .sort(compareCodeUnits);
+        output.push("{");
+        stack.push({ kind: "text", text: "}" });
+        for (let index = keys.length - 1; index >= 0; index -= 1) {
+            const key = keys[index];
+            stack.push({
+                kind: "value",
+                value: record[key],
+                link: { parent: link, segment: `.${key}` },
+            });
+            stack.push({ kind: "key", key, link });
+            if (index > 0) {
+                stack.push({ kind: "text", text: "," });
+            }
+        }
     }
-    const record = value;
-    const entries = Object.keys(record)
+    return output.join("");
+}
+export function canonicalizeJson(value) {
+    return canonicalizeValue(value);
+}
+export function canonicalizeWireJson(value) {
+    return canonicalizeValue(value, undefined, true);
+}
+export function canonicalizeContractMembers(contract) {
+    const record = normalizeContract(contract);
+    return Object.keys(record)
         .sort(compareCodeUnits)
         .map((key) => {
-        assertValidUnicode(key, `${path} key`);
-        return `${JSON.stringify(key)}:${canonicalizeValue(record[key], `${path}.${key}`)}`;
+        assertValidUnicode(key, () => "$ key");
+        return {
+            key,
+            text: canonicalizeValue(record[key], {
+                parent: undefined,
+                segment: `.${key}`,
+            }),
+        };
     });
-    return `{${entries.join(",")}}`;
 }
-export function canonicalizeJson(value) {
-    return canonicalizeValue(value, "$");
+export function joinCanonicalContractMembers(members) {
+    return `{${members.map(({ key, text }) => `${JSON.stringify(key)}:${text}`).join(",")}}`;
 }
 export function canonicalizeContract(contract) {
-    return canonicalizeJson(normalizeContract(contract));
+    return joinCanonicalContractMembers(canonicalizeContractMembers(contract));
+}
+const canonicalTexts = new WeakMap();
+export function recordCanonicalContractText(contract, text) {
+    canonicalTexts.set(contract, text);
+}
+export function canonicalContractTextOf(contract) {
+    return canonicalTexts.get(contract) ?? canonicalizeContract(contract);
 }

package/dist/contracts/contract-hash.d.ts

@@ -1,11 +1,15 @@
-import type { ClientContract } from "./contract.js";
-import type { ContractHash, ContractProtocol } from "./contract-protocol.js";
+import type { AvContractClient } from "./contract.js";
+import type { AvContractHash, AvContractProtocol } from "./contract-protocol.js";
 /** A ClientContract whose `protocol` does not carry the hash yet. */
-export type ClientContractHashInput = Omit<ClientContract, "protocol"> & {
-    readonly protocol: ContractProtocol;
+export type AvContractClientHashInput = Omit<AvContractClient, "protocol"> & {
+    readonly protocol: AvContractProtocol;
 };
-export declare function createClientContractHashInput(contract: ClientContract | ClientContractHashInput): ClientContractHashInput;
 /** Computes a ClientContract's `sha256:` hash, ignoring `protocol.hash` itself. */
-export declare function computeClientContractHash(contract: ClientContract | ClientContractHashInput): Promise<ContractHash>;
+export declare function computeClientContractHash(contract: AvContractClient | AvContractClientHashInput): Promise<AvContractHash>;
+/**
+ * The `sha256:` hash of a hash input's canonical text, already written: what
+ * {@link computeClientContractHash} answers for the input that text is of.
+ */
+export declare function hashCanonicalContractText(canonical: string): Promise<AvContractHash>;
 /** Whether a ClientContract's `protocol.hash` matches its content. */
-export declare function verifyClientContractHash(contract: ClientContract): Promise<boolean>;
+export declare function verifyClientContractHash(contract: AvContractClient): Promise<boolean>;

package/dist/contracts/contract-hash.js

@@ -1,5 +1,5 @@
 import { canonicalizeContract } from "./contract-canonicalizer.js";
-export function createClientContractHashInput(contract) {
+function createClientContractHashInput(contract) {
     const { protocol, ...semantic } = contract;
     return {
         ...semantic,
@@ -10,8 +10,9 @@ function digestHex(digest) {
     return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 export async function computeClientContractHash(contract) {
-    const input = createClientContractHashInput(contract);
-    const canonical = canonicalizeContract(input);
+    return hashCanonicalContractText(canonicalizeContract(createClientContractHashInput(contract)));
+}
+export async function hashCanonicalContractText(canonical) {
     const bytes = new TextEncoder().encode(canonical);
     const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
     return `sha256:${digestHex(digest)}`;