@earendil-works/chord 1.4.0 → 1.5.1

package/dist/contracts/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/contracts/schema.ts"],"names":[],"mappings":"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","sourcesContent":["// Schema helpers: Chord's short constructors over pi-schema's builders (plain JSON Schema, typed with the values they\n// accept), and method and keyed member declarations. The helpers keep the shapes contracts were fingerprinted with:\n// literals carry their `type`, `oneOf` is a union of literals, `map` a pattern-property record.\n\nimport {\n\tarr as arrSchema,\n\tbool as boolSchema,\n\tbytes as bytesSchema,\n\tint as intSchema,\n\tnul as nulSchema,\n\tnum as numSchema,\n\tOptional,\n\tobj as objSchema,\n\ttype Properties,\n\ttype Schema,\n\ttype Static,\n\ttype StaticObject,\n\tstr as strSchema,\n\tunion as unionSchema,\n\tunknown as unknownSchema,\n} from \"@earendil-works/pi-schema\";\n\nexport { Optional, opt, type Schema, type Static } from \"@earendil-works/pi-schema\";\n\n/** Bounds of a string length, a number or an array length. */\nexport type Bounds = { readonly min?: number; readonly max?: number };\n\n/** A declared default value: a table column with one may be left out of a `put` (slice 6a §5). */\nexport type Defaulted<T> = { readonly default: T };\n\n// Interfaces, not intersections: declarations of apps' exported contracts and tables name them (an intersection with\n// `Schema<T>` would print pi-schema's private brand, which declaration files cannot name).\n\n/** A string schema (`str()`), told apart from the other scalars by its `type`. */\nexport interface StringSchema extends Schema<string> {\n\treadonly type: \"string\";\n}\n\n/** A number schema (`num()`). */\nexport interface NumberSchema extends Schema<number> {\n\treadonly type: \"number\";\n}\n\n/** An integer schema (`int()`). */\nexport interface IntegerSchema extends Schema<number> {\n\treadonly type: \"integer\";\n}\n\n/** A boolean schema (`bool()`). */\nexport interface BooleanSchema extends Schema<boolean> {\n\treadonly type: \"boolean\";\n}\n\n/** The `null` schema (`nul()`): also the omitted side of a method. */\nexport interface NullSchema extends Schema<null> {\n\treadonly type: \"null\";\n}\n\n/** A union of literals (`oneOf(...)`). */\nexport interface LiteralsSchema<V extends Literal> extends Schema<V> {\n\treadonly anyOf: readonly Schema<V>[];\n}\n\n/** A string, with optional length bounds, pattern and default. */\nexport function str(\n\toptions: Bounds & { readonly pattern?: string; readonly default: string },\n): StringSchema & Defaulted<string>;\nexport function str(options?: Bounds & { readonly pattern?: string }): StringSchema;\nexport function str(options: Bounds & { readonly pattern?: string; readonly default?: string } = {}): StringSchema {\n\tconst pattern = options.pattern === undefined ? {} : { pattern: options.pattern };\n\treturn strSchema({\n\t\t...limits(options, \"minLength\", \"maxLength\"),\n\t\t...pattern,\n\t\t...defaultOf(options),\n\t}) as StringSchema;\n}\n\n/** A finite number within optional bounds, with an optional default. */\nexport function num(options: Bounds & { readonly default: number }): NumberSchema & Defaulted<number>;\nexport function num(options?: Bounds): NumberSchema;\nexport function num(options: Bounds & { readonly default?: number } = {}): NumberSchema {\n\treturn numSchema({ ...limits(options, \"minimum\", \"maximum\"), ...defaultOf(options) }) as NumberSchema;\n}\n\n/** An integer within optional bounds, with an optional default. */\nexport function int(options: Bounds & { readonly default: number }): IntegerSchema & Defaulted<number>;\nexport function int(options?: Bounds): IntegerSchema;\nexport function int(options: Bounds & { readonly default?: number } = {}): IntegerSchema {\n\treturn intSchema({ ...limits(options, \"minimum\", \"maximum\"), ...defaultOf(options) }) as IntegerSchema;\n}\n\n/** A boolean, with an optional default. */\nexport function bool(options: { readonly default: boolean }): BooleanSchema & Defaulted<boolean>;\nexport function bool(options?: Record<never, never>): BooleanSchema;\nexport function bool(options: { readonly default?: boolean } = {}): BooleanSchema {\n\treturn boolSchema(defaultOf(options)) as BooleanSchema;\n}\n\n/** The `default` keyword of `options`, left out when absent (snapshots refuse `undefined`). */\nfunction defaultOf<T extends string | number | boolean>(options: { readonly default?: T }): { default?: T } {\n\treturn options.default === undefined ? {} : { default: options.default };\n}\n\n/** `null`; also the omitted side of a method. */\nexport function nul(): NullSchema {\n\t// The builder's `type: \"null\"`, typed as such.\n\treturn nulSchema() as NullSchema;\n}\n\n/** Exactly the given value, with its JSON type (`{ type: \"string\", const: \"a\" }`). */\nexport function lit<const V extends Literal>(value: V): Schema<V> {\n\treturn { type: typeof value, const: value };\n}\n\n/** A value `lit(...)` and `oneOf(...)` take. */\nexport type Literal = string | number | boolean;\n\n/** One of the given literals: a union of `lit(...)` schemas, in order. */\nexport function oneOf<const V extends Literal[]>(...values: V): LiteralsSchema<V[number]> {\n\treturn { anyOf: values.map((value) => lit(value)) };\n}\n\n/** Any of the given schemas. */\nexport function union<const S extends readonly Schema[]>(schemas: S): Schema<Static<S[number]>> {\n\treturn unionSchema(schemas);\n}\n\n/** A closed object: unknown fields are refused; `opt(...)` marks an optional field. */\nexport function obj<const P extends Properties>(properties: P): Schema<StaticObject<P>> {\n\treturn objSchema(properties);\n}\n\n/** An array, with optional length bounds. */\nexport function arr<T>(items: Schema<T>, options: Bounds = {}): Schema<T[]> {\n\treturn arrSchema(items, limits(options, \"minItems\", \"maxItems\"));\n}\n\n/** A string-keyed record: one pattern property matching every key. */\nexport function map<T>(value: Schema<T>): Schema<Record<string, T>> {\n\treturn { type: \"object\", patternProperties: { \"^.*$\": value } };\n}\n\n/** Any value. */\nexport function unknown(): Schema<unknown> {\n\treturn unknownSchema();\n}\n\n/**\n * A `Uint8Array` leaf, checked by `instanceof` and length, never enumerated: `{ type: \"bytes\", minLength?, maxLength? }`\n * (pi-schema's extension of JSON Schema for values that never pass through JSON).\n */\nexport function bytes(options: Bounds = {}): Schema<Uint8Array> {\n\treturn bytesSchema(limits(options, \"minLength\", \"maxLength\"));\n}\n\n/** Builder options for the given bounds; an absent bound is left out, since snapshots refuse `undefined`. */\nfunction limits(options: Bounds, min: string, max: string): { [keyword: string]: number } {\n\tconst result: { [keyword: string]: number } = {};\n\tif (options.min !== undefined) result[min] = options.min;\n\tif (options.max !== undefined) result[max] = options.max;\n\treturn result;\n}\n\n/** Whether a declared object field is `opt(...)`. */\nexport function isOptional(value: unknown): value is Optional {\n\treturn value instanceof Optional;\n}\n\n/** A method declaration: its argument and result schemas; an omitted side is `null` on the wire. */\nexport class Method<A extends Schema = Schema, R extends Schema = Schema> {\n\treadonly args: A;\n\treadonly result: R;\n\n\tconstructor(args: A, result: R) {\n\t\tthis.args = args;\n\t\tthis.result = result;\n\t}\n}\n\n/** A keyed state member's declaration (slice 6a §12): documents of `schema` by string key; only in `local` contracts. */\nexport class KeyedMember<S extends Schema = Schema> {\n\treadonly schema: S;\n\n\tconstructor(schema: S) {\n\t\tthis.schema = schema;\n\t}\n}\n\n/** Declares a keyed state member of a `local` contract: documents of `schema` by string key, each watchable. */\nexport function keyed<S extends Schema>(schema: S): KeyedMember<S> {\n\treturn new KeyedMember(schema);\n}\n\n/** Declares a method: `method()`, `method(args)`, `method(args, result)` or `method(undefined, result)`. */\nexport function method(): Method<NullSchema, NullSchema>;\nexport function method<A extends Schema>(args: A): Method<A, NullSchema>;\nexport function method<R extends Schema>(args: undefined, result: R): Method<NullSchema, R>;\nexport function method<A extends Schema, R extends Schema>(args: A, result: R): Method<A, R>;\nexport function method(args?: Schema, result?: Schema): Method {\n\treturn new Method(args ?? nul(), result ?? nul());\n}\n"]}

package/dist/contracts/snapshot.d.ts

@@ -0,0 +1,16 @@
+import type { JsonSchema } from "@earendil-works/pi-schema";
+import { type JsonValue } from "../json.ts";
+/**
+ * A Chord-owned copy of an app schema, its normal form, and whether it has a `bytes()` leaf (values crossing a link
+ * then carry raw byte segments); immutable by convention.
+ */
+export type Snapshot = {
+    readonly schema: JsonSchema;
+    readonly normal: JsonValue;
+    readonly bytes: boolean;
+};
+/** Snapshot of a state, result or params schema. Throws an Error naming `path` for anything outside the vocabulary. */
+export declare function snapshotSchema(source: unknown, path: string): Snapshot;
+/** Snapshot of a method's arguments: every object schema inside must also be closed (records allowed). */
+export declare function snapshotArguments(source: unknown, path: string): Snapshot;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/contracts/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/contracts/snapshot.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5G,uHAAuH;AACvH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAEtE;AAED,0GAA0G;AAC1G,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAEzE"}

package/dist/contracts/snapshot.js

@@ -0,0 +1,167 @@
+// Schema snapshots: one schema-aware walk checks an app schema against Chord's vocabulary and produces a
+// Chord-owned copy and its normal form (the fingerprint input).
+import { isJsonValue } from "../json.js";
+/** Snapshot of a state, result or params schema. Throws an Error naming `path` for anything outside the vocabulary. */
+export function snapshotSchema(source, path) {
+    return walk(source, path, "open", new Set());
+}
+/** Snapshot of a method's arguments: every object schema inside must also be closed (records allowed). */
+export function snapshotArguments(source, path) {
+    return walk(source, path, "closed", new Set());
+}
+/** Every supported keyword, grouped by how its value is walked. */
+const KEYWORD_GROUPS = {
+    schema: "additionalProperties additionalItems",
+    schemas: "anyOf allOf prefixItems",
+    items: "items",
+    schemaMap: "properties patternProperties $defs",
+    type: "type",
+    required: "required",
+    enum: "enum",
+    data: "const default $ref $id pattern format minLength maxLength minimum maximum exclusiveMinimum exclusiveMaximum " +
+        "multipleOf minItems maxItems uniqueItems minProperties maxProperties readOnly writeOnly",
+    annotation: "title description examples $comment deprecated",
+};
+const KEYWORDS = new Map(Object.entries(KEYWORD_GROUPS).flatMap(([keyword, names]) => names.split(" ").map((name) => [name, keyword])));
+const TYPES = new Set(["null", "boolean", "number", "integer", "string", "array", "object", "bytes"]);
+const BYTES_KEYWORDS = new Set(["type", "minLength", "maxLength"]);
+function walk(source, path, objects, ancestors) {
+    if (typeof source === "boolean")
+        return { schema: source, normal: source, bytes: false };
+    if (!isPlainObject(source))
+        throw new Error(`${path}: expected a schema`);
+    if (ancestors.has(source))
+        throw new Error(`${path}: cyclic schema; use $defs and $ref for recursion`);
+    const isBytes = source.type === "bytes";
+    ancestors.add(source);
+    const schema = [];
+    const normal = [];
+    let bytes = isBytes;
+    for (const [key, value] of ownEntries(source, path)) {
+        const keyword = KEYWORDS.get(key);
+        if (keyword === undefined || (isBytes && keyword !== "annotation" && !BYTES_KEYWORDS.has(key))) {
+            throw new Error(`${path}: unsupported keyword "${key}"`);
+        }
+        const copy = walkKeyword(keyword, value, `${path}.${key}`, objects, ancestors);
+        bytes ||= copy.bytes;
+        schema.push([key, copy.schema]);
+        // Annotations are dropped on schema nodes only; inside data they are ordinary keys.
+        if (keyword !== "annotation")
+            normal.push([key, copy.normal]);
+    }
+    ancestors.delete(source);
+    const node = Object.fromEntries(schema);
+    if (objects === "closed" && isOpenObject(node)) {
+        throw new Error(`${path}: argument objects must be closed (additionalProperties: false)`);
+    }
+    if (isBytes)
+        checkBytesBounds(node, path);
+    return { schema: node, normal: Object.fromEntries(normal), bytes };
+}
+function walkKeyword(keyword, value, path, objects, ancestors) {
+    switch (keyword) {
+        case "schema":
+            return walk(value, path, objects, ancestors);
+        case "schemas":
+            return walkList(value, path, objects, ancestors);
+        case "items":
+            return Array.isArray(value)
+                ? walkList(value, path, objects, ancestors)
+                : walk(value, path, objects, ancestors);
+        case "schemaMap": {
+            if (!isPlainObject(value))
+                throw new Error(`${path}: expected an object of schemas`);
+            const entries = ownEntries(value, path).map(([key, item]) => [key, walk(item, `${path}.${key}`, objects, ancestors)]);
+            return {
+                schema: Object.fromEntries(entries.map(([key, item]) => [key, item.schema])),
+                normal: Object.fromEntries(entries.map(([key, item]) => [key, item.normal])),
+                bytes: entries.some(([, item]) => item.bytes),
+            };
+        }
+        case "type":
+            if (typeof value !== "string" || !TYPES.has(value)) {
+                throw new Error(`${path}: unsupported type ${JSON.stringify(value)}`);
+            }
+            return { schema: value, normal: value, bytes: false };
+        case "required": {
+            if (!Array.isArray(value) || !value.every((name) => typeof name === "string")) {
+                throw new Error(`${path}: expected an array of strings`);
+            }
+            const names = [...value].sort();
+            return { schema: names, normal: names, bytes: false };
+        }
+        case "enum": {
+            const values = data(value, path).normal;
+            if (!Array.isArray(values))
+                throw new Error(`${path}: expected an array`);
+            const sorted = [...values].sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b)));
+            return { schema: sorted, normal: sorted, bytes: false };
+        }
+        case "data":
+        case "annotation":
+            return data(value, path);
+    }
+}
+function walkList(value, path, objects, ancestors) {
+    if (!Array.isArray(value))
+        throw new Error(`${path}: expected an array of schemas`);
+    const items = Array.from(value, (item, index) => walk(item, `${path}[${index}]`, objects, ancestors));
+    return {
+        schema: items.map((item) => item.schema),
+        normal: items.map((item) => item.normal),
+        bytes: items.some((item) => item.bytes),
+    };
+}
+/** A JSON value as a copy with sorted keys; the same copy serves as snapshot and normal form. */
+function data(value, path) {
+    if (!isJsonValue(value))
+        throw new Error(`${path}: expected JSON data (finite numbers, plain objects and arrays)`);
+    const copy = sortedCopy(value);
+    return { schema: copy, normal: copy, bytes: false };
+}
+function sortedCopy(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(sortedCopy);
+    const keys = Object.keys(value).sort();
+    return Object.fromEntries(keys.map((key) => [key, sortedCopy(value[key])]));
+}
+/** Data entries sorted by key; symbol keys, accessors and non-enumerable keys (not data) are refused. */
+function ownEntries(source, path) {
+    const entries = [];
+    for (const key of Reflect.ownKeys(source)) {
+        if (typeof key === "symbol")
+            throw new Error(`${path}: symbol keys are not supported`);
+        const descriptor = Object.getOwnPropertyDescriptor(source, key);
+        if (!("value" in descriptor))
+            throw new Error(`${path}.${key}: accessors are not supported`);
+        if (!descriptor.enumerable)
+            throw new Error(`${path}.${key}: non-enumerable keys are not supported`);
+        entries.push([key, descriptor.value]);
+    }
+    return entries.sort(([a], [b]) => compare(a, b));
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** An object schema that admits unknown fields. A record (pattern properties only) is allowed. */
+function isOpenObject(node) {
+    const isRecord = "patternProperties" in node && !("properties" in node);
+    const isObject = node.type === "object" || "properties" in node;
+    return isObject && !isRecord && node.additionalProperties !== false;
+}
+function checkBytesBounds(node, path) {
+    for (const bound of [node.minLength, node.maxLength]) {
+        if (bound !== undefined && !(Number.isSafeInteger(bound) && bound >= 0)) {
+            throw new Error(`${path}: bytes bounds must be non-negative integers`);
+        }
+    }
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/contracts/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/contracts/snapshot.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,gEAAgE;AAGhE,OAAO,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AAQzD,uHAAuH;AACvH,MAAM,UAAU,cAAc,CAAC,MAAe,EAAE,IAAY;IAC3D,OAAO,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,iBAAiB,CAAC,MAAe,EAAE,IAAY;IAC9D,OAAO,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;AAChD,CAAC;AAQD,mEAAmE;AACnE,MAAM,cAAc,GAAG;IACtB,MAAM,EAAE,sCAAsC;IAC9C,OAAO,EAAE,yBAAyB;IAClC,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,oCAAoC;IAC/C,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,MAAM;IACZ,IAAI,EACH,8GAA8G;QAC9G,yFAAyF;IAC1F,UAAU,EAAE,gDAAgD;CAC5D,CAAC;AAIF,MAAM,QAAQ,GAAG,IAAI,GAAG,CACvB,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,CAC3D,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,OAAkB,CAAC,CAAC,CAC1D,CACD,CAAC;AAEF,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtG,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AAEnE,SAAS,IAAI,CAAC,MAAe,EAAE,IAAY,EAAE,OAAgB,EAAE,SAAsB;IACpF,IAAI,OAAO,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACzF,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,qBAAqB,CAAC,CAAC;IAC1E,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,mDAAmD,CAAC,CAAC;IACvG,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;IACxC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,IAAI,KAAK,GAAG,OAAO,CAAC;IACpB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,YAAY,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAChG,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,0BAA0B,GAAG,GAAG,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;QAC/E,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC;QACrB,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAChC,oFAAoF;QACpF,IAAI,OAAO,KAAK,YAAY;YAAE,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,OAAO,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,iEAAiE,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,OAAO;QAAE,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;AACpE,CAAC;AAED,SAAS,WAAW,CAAC,OAAgB,EAAE,KAAc,EAAE,IAAY,EAAE,OAAgB,EAAE,SAAsB;IAC5G,QAAQ,OAAO,EAAE,CAAC;QACjB,KAAK,QAAQ;YACZ,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;QAC9C,KAAK,SAAS;YACb,OAAO,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;QAClD,KAAK,OAAO;YACX,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAC1B,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC;gBAC3C,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1C,KAAK,WAAW,EAAE,CAAC;YAClB,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,iCAAiC,CAAC,CAAC;YACrF,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAC1C,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,SAAS,CAAC,CAAU,CACjF,CAAC;YACF,OAAO;gBACN,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC5E,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC5E,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC;aAC7C,CAAC;QACH,CAAC;QACD,KAAK,MAAM;YACV,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,sBAAsB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACvE,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACvD,KAAK,UAAU,EAAE,CAAC;YACjB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;gBAC/E,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,gCAAgC,CAAC,CAAC;YAC1D,CAAC;YACD,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;YAChC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACvD,CAAC;QACD,KAAK,MAAM,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,MAAM,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,qBAAqB,CAAC,CAAC;YAC1E,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACzF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACzD,CAAC;QACD,KAAK,MAAM,CAAC;QACZ,KAAK,YAAY;YAChB,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;AACF,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc,EAAE,IAAY,EAAE,OAAgB,EAAE,SAAsB;IACvF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,gCAAgC,CAAC,CAAC;IACpF,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,KAAK,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IACtG,OAAO;QACN,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC;QACxC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC;QACxC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC;KACvC,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,SAAS,IAAI,CAAC,KAAc,EAAE,IAAY;IACzC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,iEAAiE,CAAC,CAAC;IACnH,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,UAAU,CAAC,KAAgB;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,CAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,yGAAyG;AACzG,SAAS,UAAU,CAAC,MAAc,EAAE,IAAY;IAC/C,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3C,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,iCAAiC,CAAC,CAAC;QACvF,MAAM,UAAU,GAAG,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAE,CAAC;QACjE,IAAI,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,IAAI,GAAG,+BAA+B,CAAC,CAAC;QAC7F,IAAI,CAAC,UAAU,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,IAAI,GAAG,yCAAyC,CAAC,CAAC;QACrG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC7D,CAAC;AAED,kGAAkG;AAClG,SAAS,YAAY,CAAC,IAA6B;IAClD,MAAM,QAAQ,GAAG,mBAAmB,IAAI,IAAI,IAAI,CAAC,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,YAAY,IAAI,IAAI,CAAC;IAChE,OAAO,QAAQ,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,oBAAoB,KAAK,KAAK,CAAC;AACrE,CAAC;AAED,SAAS,gBAAgB,CAAC,IAA6B,EAAE,IAAY;IACpE,KAAK,MAAM,KAAK,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACtD,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAK,KAAgB,IAAI,CAAC,CAAC,EAAE,CAAC;YACrF,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,8CAA8C,CAAC,CAAC;QACxE,CAAC;IACF,CAAC;AACF,CAAC;AAED,SAAS,OAAO,CAAC,CAAS,EAAE,CAAS;IACpC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC","sourcesContent":["// Schema snapshots: one schema-aware walk checks an app schema against Chord's vocabulary and produces a\n// Chord-owned copy and its normal form (the fingerprint input).\n\nimport type { JsonSchema } from \"@earendil-works/pi-schema\";\nimport { isJsonValue, type JsonValue } from \"../json.ts\";\n\n/**\n * A Chord-owned copy of an app schema, its normal form, and whether it has a `bytes()` leaf (values crossing a link\n * then carry raw byte segments); immutable by convention.\n */\nexport type Snapshot = { readonly schema: JsonSchema; readonly normal: JsonValue; readonly bytes: boolean };\n\n/** Snapshot of a state, result or params schema. Throws an Error naming `path` for anything outside the vocabulary. */\nexport function snapshotSchema(source: unknown, path: string): Snapshot {\n\treturn walk(source, path, \"open\", new Set());\n}\n\n/** Snapshot of a method's arguments: every object schema inside must also be closed (records allowed). */\nexport function snapshotArguments(source: unknown, path: string): Snapshot {\n\treturn walk(source, path, \"closed\", new Set());\n}\n\n/** Whether object schemas must set `additionalProperties: false`. */\ntype Objects = \"open\" | \"closed\";\n\n/** A copied keyword value, its normal form, and whether a schema inside it is a bytes leaf. */\ntype Copy = { readonly schema: unknown; readonly normal: JsonValue; readonly bytes: boolean };\n\n/** Every supported keyword, grouped by how its value is walked. */\nconst KEYWORD_GROUPS = {\n\tschema: \"additionalProperties additionalItems\",\n\tschemas: \"anyOf allOf prefixItems\",\n\titems: \"items\",\n\tschemaMap: \"properties patternProperties $defs\",\n\ttype: \"type\",\n\trequired: \"required\",\n\tenum: \"enum\",\n\tdata:\n\t\t\"const default $ref $id pattern format minLength maxLength minimum maximum exclusiveMinimum exclusiveMaximum \" +\n\t\t\"multipleOf minItems maxItems uniqueItems minProperties maxProperties readOnly writeOnly\",\n\tannotation: \"title description examples $comment deprecated\",\n};\n\ntype Keyword = keyof typeof KEYWORD_GROUPS;\n\nconst KEYWORDS = new Map(\n\tObject.entries(KEYWORD_GROUPS).flatMap(([keyword, names]) =>\n\t\tnames.split(\" \").map((name) => [name, keyword as Keyword]),\n\t),\n);\n\nconst TYPES = new Set([\"null\", \"boolean\", \"number\", \"integer\", \"string\", \"array\", \"object\", \"bytes\"]);\n\nconst BYTES_KEYWORDS = new Set([\"type\", \"minLength\", \"maxLength\"]);\n\nfunction walk(source: unknown, path: string, objects: Objects, ancestors: Set<object>): Snapshot {\n\tif (typeof source === \"boolean\") return { schema: source, normal: source, bytes: false };\n\tif (!isPlainObject(source)) throw new Error(`${path}: expected a schema`);\n\tif (ancestors.has(source)) throw new Error(`${path}: cyclic schema; use $defs and $ref for recursion`);\n\tconst isBytes = source.type === \"bytes\";\n\tancestors.add(source);\n\tconst schema: [string, unknown][] = [];\n\tconst normal: [string, JsonValue][] = [];\n\tlet bytes = isBytes;\n\tfor (const [key, value] of ownEntries(source, path)) {\n\t\tconst keyword = KEYWORDS.get(key);\n\t\tif (keyword === undefined || (isBytes && keyword !== \"annotation\" && !BYTES_KEYWORDS.has(key))) {\n\t\t\tthrow new Error(`${path}: unsupported keyword \"${key}\"`);\n\t\t}\n\t\tconst copy = walkKeyword(keyword, value, `${path}.${key}`, objects, ancestors);\n\t\tbytes ||= copy.bytes;\n\t\tschema.push([key, copy.schema]);\n\t\t// Annotations are dropped on schema nodes only; inside data they are ordinary keys.\n\t\tif (keyword !== \"annotation\") normal.push([key, copy.normal]);\n\t}\n\tancestors.delete(source);\n\tconst node = Object.fromEntries(schema);\n\tif (objects === \"closed\" && isOpenObject(node)) {\n\t\tthrow new Error(`${path}: argument objects must be closed (additionalProperties: false)`);\n\t}\n\tif (isBytes) checkBytesBounds(node, path);\n\treturn { schema: node, normal: Object.fromEntries(normal), bytes };\n}\n\nfunction walkKeyword(keyword: Keyword, value: unknown, path: string, objects: Objects, ancestors: Set<object>): Copy {\n\tswitch (keyword) {\n\t\tcase \"schema\":\n\t\t\treturn walk(value, path, objects, ancestors);\n\t\tcase \"schemas\":\n\t\t\treturn walkList(value, path, objects, ancestors);\n\t\tcase \"items\":\n\t\t\treturn Array.isArray(value)\n\t\t\t\t? walkList(value, path, objects, ancestors)\n\t\t\t\t: walk(value, path, objects, ancestors);\n\t\tcase \"schemaMap\": {\n\t\t\tif (!isPlainObject(value)) throw new Error(`${path}: expected an object of schemas`);\n\t\t\tconst entries = ownEntries(value, path).map(\n\t\t\t\t([key, item]) => [key, walk(item, `${path}.${key}`, objects, ancestors)] as const,\n\t\t\t);\n\t\t\treturn {\n\t\t\t\tschema: Object.fromEntries(entries.map(([key, item]) => [key, item.schema])),\n\t\t\t\tnormal: Object.fromEntries(entries.map(([key, item]) => [key, item.normal])),\n\t\t\t\tbytes: entries.some(([, item]) => item.bytes),\n\t\t\t};\n\t\t}\n\t\tcase \"type\":\n\t\t\tif (typeof value !== \"string\" || !TYPES.has(value)) {\n\t\t\t\tthrow new Error(`${path}: unsupported type ${JSON.stringify(value)}`);\n\t\t\t}\n\t\t\treturn { schema: value, normal: value, bytes: false };\n\t\tcase \"required\": {\n\t\t\tif (!Array.isArray(value) || !value.every((name) => typeof name === \"string\")) {\n\t\t\t\tthrow new Error(`${path}: expected an array of strings`);\n\t\t\t}\n\t\t\tconst names = [...value].sort();\n\t\t\treturn { schema: names, normal: names, bytes: false };\n\t\t}\n\t\tcase \"enum\": {\n\t\t\tconst values = data(value, path).normal;\n\t\t\tif (!Array.isArray(values)) throw new Error(`${path}: expected an array`);\n\t\t\tconst sorted = [...values].sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b)));\n\t\t\treturn { schema: sorted, normal: sorted, bytes: false };\n\t\t}\n\t\tcase \"data\":\n\t\tcase \"annotation\":\n\t\t\treturn data(value, path);\n\t}\n}\n\nfunction walkList(value: unknown, path: string, objects: Objects, ancestors: Set<object>): Copy {\n\tif (!Array.isArray(value)) throw new Error(`${path}: expected an array of schemas`);\n\tconst items = Array.from(value, (item, index) => walk(item, `${path}[${index}]`, objects, ancestors));\n\treturn {\n\t\tschema: items.map((item) => item.schema),\n\t\tnormal: items.map((item) => item.normal),\n\t\tbytes: items.some((item) => item.bytes),\n\t};\n}\n\n/** A JSON value as a copy with sorted keys; the same copy serves as snapshot and normal form. */\nfunction data(value: unknown, path: string): Copy {\n\tif (!isJsonValue(value)) throw new Error(`${path}: expected JSON data (finite numbers, plain objects and arrays)`);\n\tconst copy = sortedCopy(value);\n\treturn { schema: copy, normal: copy, bytes: false };\n}\n\nfunction sortedCopy(value: JsonValue): JsonValue {\n\tif (value === null || typeof value !== \"object\") return value;\n\tif (Array.isArray(value)) return value.map(sortedCopy);\n\tconst keys = Object.keys(value).sort();\n\treturn Object.fromEntries(keys.map((key) => [key, sortedCopy(value[key]!)]));\n}\n\n/** Data entries sorted by key; symbol keys, accessors and non-enumerable keys (not data) are refused. */\nfunction ownEntries(source: object, path: string): [string, unknown][] {\n\tconst entries: [string, unknown][] = [];\n\tfor (const key of Reflect.ownKeys(source)) {\n\t\tif (typeof key === \"symbol\") throw new Error(`${path}: symbol keys are not supported`);\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(source, key)!;\n\t\tif (!(\"value\" in descriptor)) throw new Error(`${path}.${key}: accessors are not supported`);\n\t\tif (!descriptor.enumerable) throw new Error(`${path}.${key}: non-enumerable keys are not supported`);\n\t\tentries.push([key, descriptor.value]);\n\t}\n\treturn entries.sort(([a], [b]) => compare(a, b));\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\n/** An object schema that admits unknown fields. A record (pattern properties only) is allowed. */\nfunction isOpenObject(node: Record<string, unknown>): boolean {\n\tconst isRecord = \"patternProperties\" in node && !(\"properties\" in node);\n\tconst isObject = node.type === \"object\" || \"properties\" in node;\n\treturn isObject && !isRecord && node.additionalProperties !== false;\n}\n\nfunction checkBytesBounds(node: Record<string, unknown>, path: string): void {\n\tfor (const bound of [node.minLength, node.maxLength]) {\n\t\tif (bound !== undefined && !(Number.isSafeInteger(bound) && (bound as number) >= 0)) {\n\t\t\tthrow new Error(`${path}: bytes bounds must be non-negative integers`);\n\t\t}\n\t}\n}\n\nfunction compare(a: string, b: string): number {\n\treturn a < b ? -1 : a > b ? 1 : 0;\n}\n"]}

package/dist/data/args.d.ts

@@ -0,0 +1,50 @@
+import type { Context } from "../context/index.ts";
+import { type AcceptedVersion, type AcceptsTable } from "../contracts/accepts.ts";
+import { type Contract, type CurrentVariants } from "../contracts/contract.ts";
+import type { MemberNames, MethodAt } from "../contracts/history.ts";
+import type { Static } from "../contracts/schema.ts";
+/** JSON plus byte leaves. Same-host values are plain data and immutable once handed over, by convention. */
+export type Value = null | boolean | number | string | Uint8Array | Value[] | {
+    [key: string]: Value;
+};
+/**
+ * A provider's binding of a contract with the older versions it accepts and their mappings (the table as checked, for
+ * the state mappings of an older consumer's binding).
+ */
+export type Provider<C extends Contract> = {
+    readonly contract: C;
+    readonly accepted: readonly AcceptedVersion[];
+    readonly accepts: AcceptsTable<C>;
+};
+/**
+ * Checked arguments: a method's arguments in the current shape with the result mapping back to the caller's version,
+ * or the old arguments for the provider's own `call` replacement (L4 dispatches it).
+ */
+export type CheckedArgs<C extends Contract, M extends string> = {
+    readonly kind: "method";
+    readonly args: ArgsOf<C, M>;
+    readonly result?: (current: Value) => Value;
+} | {
+    readonly kind: "call";
+    readonly args: Value;
+    readonly call: (args: Value, context: Context) => Promise<Value>;
+};
+type ArgsOf<C extends Contract, M extends string> = M extends MemberNames<CurrentVariants<C>, "methods"> ? Static<MethodAt<CurrentVariants<C>, M>["args"]> : Value;
+/**
+ * Binds a contract and the app's accepts table (validated once, kept as it is) into a provider. Builds the dispatch
+ * table: accepted version -> method -> schema and mapping; nothing is compiled yet.
+ */
+export declare function bindProvider<C extends Contract>(contract: C, accepts: AcceptsTable<C>): Provider<C>;
+/**
+ * Whether `provider` binds a consumer of `version` with `fingerprint`: its current version and fingerprint, or a
+ * version it accepts with the fingerprint its own history computes (R6, Q10).
+ */
+export declare function binds(provider: Provider<Contract>, version: number, fingerprint: string): boolean;
+/**
+ * Checks a call's arguments against the provider's schema for the caller's bound version: three map lookups, one
+ * compiled check, at most one direct mapping old -> current (never for current-version calls). A method without
+ * arguments gets `null` (its internal and wire form). Unknown method: `invalid/member`; version not accepted or refused: `contract_mismatch`.
+ */
+export declare function checkArgs<C extends Contract, M extends string>(provider: Provider<C>, method: M, raw: unknown, boundVersion: number, context: Context): CheckedArgs<C, M>;
+export {};
+//# sourceMappingURL=args.d.ts.map

package/dist/data/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/data/args.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAgB,MAAM,yBAAyB,CAAC;AAChG,OAAO,EACN,KAAK,QAAQ,EACb,KAAK,eAAe,EAIpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAKrD,4GAA4G;AAC5G,MAAM,MAAM,KAAK,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;CAAE,CAAC;AAEvG;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,QAAQ,IAAI;IAC1C,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;CAClC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,MAAM,IACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,KAAK,CAAA;CAAE,GACrG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,KAAK,CAAC,CAAA;CAAE,CAAC;AAErH,KAAK,MAAM,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,WAAW,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GACrG,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAC/C,KAAK,CAAC;AAET;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAcnG;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAIjG;AAuDD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,MAAM,EAC7D,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACd,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAqBnB"}

package/dist/data/args.js

@@ -0,0 +1,83 @@
+// Arguments: a provider's binding (its dispatch table per accepted version) and the per-call argument check.
+import { checkAccepts } from "../contracts/accepts.js";
+import { contractData, } from "../contracts/contract.js";
+import { ChordError, invalid } from "./errors.js";
+import { check, validatorFor } from "./validator.js";
+/**
+ * Binds a contract and the app's accepts table (validated once, kept as it is) into a provider. Builds the dispatch
+ * table: accepted version -> method -> schema and mapping; nothing is compiled yet.
+ */
+export function bindProvider(contract, accepts) {
+    const { versions: accepted } = checkAccepts(contract, accepts);
+    const { versions } = contractData(contract);
+    const current = versions.at(-1);
+    // checkAccepts established this shape.
+    const mappings = accepts;
+    const table = new Map([[current.version, dispatchEntries(current, undefined)]]);
+    for (const { version } of accepted) {
+        const data = versions.find((candidate) => candidate.version === version);
+        table.set(version, dispatchEntries(data, mappings[version]?.methods));
+    }
+    const provider = { contract, accepted, accepts };
+    dispatchTables.set(provider, table);
+    return provider;
+}
+/**
+ * Whether `provider` binds a consumer of `version` with `fingerprint`: its current version and fingerprint, or a
+ * version it accepts with the fingerprint its own history computes (R6, Q10).
+ */
+export function binds(provider, version, fingerprint) {
+    const { contract } = provider;
+    if (version === contract.version)
+        return fingerprint === contract.fingerprint;
+    return provider.accepted.some((accepted) => accepted.version === version && accepted.fingerprint === fingerprint);
+}
+const dispatchTables = new WeakMap();
+function dispatchEntries(version, mappings) {
+    const entries = new Map();
+    // A method has one signature in every variant that has it.
+    const methods = new Map([...version.variants.values()].flatMap(({ methods }) => [...methods]));
+    for (const [member, { args }] of methods) {
+        const mapping = mappings !== undefined && Object.hasOwn(mappings, member) ? mappings[member] : undefined;
+        entries.set(member, dispatchEntry(args, mapping));
+    }
+    return entries;
+}
+function dispatchEntry(args, mapping) {
+    if (mapping === "refuse")
+        return { kind: "refuse" };
+    if (mapping !== undefined && "call" in mapping) {
+        return { kind: "call", args, call: mapping.call, validator: undefined };
+    }
+    return { kind: "method", args, mapArgs: mapping?.args, mapResult: mapping?.result, validator: undefined };
+}
+/**
+ * Checks a call's arguments against the provider's schema for the caller's bound version: three map lookups, one
+ * compiled check, at most one direct mapping old -> current (never for current-version calls). A method without
+ * arguments gets `null` (its internal and wire form). Unknown method: `invalid/member`; version not accepted or refused: `contract_mismatch`.
+ */
+export function checkArgs(provider, method, raw, boundVersion, context) {
+    const name = provider.contract.name;
+    const methods = dispatchTables.get(provider).get(boundVersion);
+    if (methods === undefined) {
+        throw new ChordError({ code: "contract_mismatch", message: `${name} v${boundVersion} is not accepted` });
+    }
+    const entry = methods.get(method);
+    if (entry === undefined)
+        throw invalid("member", `${name} v${boundVersion} has no method "${method}"`);
+    if (entry.kind === "refuse") {
+        throw new ChordError({ code: "contract_mismatch", message: `${name} v${boundVersion} refuses "${method}"` });
+    }
+    entry.validator ??= validatorFor(entry.args, context);
+    check(entry.validator, raw, "args", context);
+    // The check above establishes the argument type; mapping output is trusted.
+    const args = raw;
+    if (entry.kind === "call")
+        return { kind: "call", args, call: entry.call };
+    return {
+        kind: "method",
+        args: (entry.mapArgs === undefined ? args : entry.mapArgs(args)),
+        result: entry.mapResult,
+    };
+}
+//# sourceMappingURL=args.js.map

package/dist/data/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/data/args.ts"],"names":[],"mappings":"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","sourcesContent":["// Arguments: a provider's binding (its dispatch table per accepted version) and the per-call argument check.\n\nimport type { Validator } from \"@earendil-works/pi-schema\";\nimport type { Context } from \"../context/index.ts\";\nimport { type AcceptedVersion, type AcceptsTable, checkAccepts } from \"../contracts/accepts.ts\";\nimport {\n\ttype Contract,\n\ttype CurrentVariants,\n\tcontractData,\n\ttype MethodData,\n\ttype VersionData,\n} from \"../contracts/contract.ts\";\nimport type { MemberNames, MethodAt } from \"../contracts/history.ts\";\nimport type { Static } from \"../contracts/schema.ts\";\nimport type { Snapshot } from \"../contracts/snapshot.ts\";\nimport { ChordError, invalid } from \"./errors.ts\";\nimport { check, validatorFor } from \"./validator.ts\";\n\n/** JSON plus byte leaves. Same-host values are plain data and immutable once handed over, by convention. */\nexport type Value = null | boolean | number | string | Uint8Array | Value[] | { [key: string]: Value };\n\n/**\n * A provider's binding of a contract with the older versions it accepts and their mappings (the table as checked, for\n * the state mappings of an older consumer's binding).\n */\nexport type Provider<C extends Contract> = {\n\treadonly contract: C;\n\treadonly accepted: readonly AcceptedVersion[];\n\treadonly accepts: AcceptsTable<C>;\n};\n\n/**\n * Checked arguments: a method's arguments in the current shape with the result mapping back to the caller's version,\n * or the old arguments for the provider's own `call` replacement (L4 dispatches it).\n */\nexport type CheckedArgs<C extends Contract, M extends string> =\n\t| { readonly kind: \"method\"; readonly args: ArgsOf<C, M>; readonly result?: (current: Value) => Value }\n\t| { readonly kind: \"call\"; readonly args: Value; readonly call: (args: Value, context: Context) => Promise<Value> };\n\ntype ArgsOf<C extends Contract, M extends string> = M extends MemberNames<CurrentVariants<C>, \"methods\">\n\t? Static<MethodAt<CurrentVariants<C>, M>[\"args\"]>\n\t: Value;\n\n/**\n * Binds a contract and the app's accepts table (validated once, kept as it is) into a provider. Builds the dispatch\n * table: accepted version -> method -> schema and mapping; nothing is compiled yet.\n */\nexport function bindProvider<C extends Contract>(contract: C, accepts: AcceptsTable<C>): Provider<C> {\n\tconst { versions: accepted } = checkAccepts(contract, accepts);\n\tconst { versions } = contractData(contract);\n\tconst current = versions.at(-1)!;\n\t// checkAccepts established this shape.\n\tconst mappings = accepts as CheckedAccepts;\n\tconst table: Dispatch = new Map([[current.version, dispatchEntries(current, undefined)]]);\n\tfor (const { version } of accepted) {\n\t\tconst data = versions.find((candidate) => candidate.version === version)!;\n\t\ttable.set(version, dispatchEntries(data, mappings[version]?.methods));\n\t}\n\tconst provider = { contract, accepted, accepts };\n\tdispatchTables.set(provider, table);\n\treturn provider;\n}\n\n/**\n * Whether `provider` binds a consumer of `version` with `fingerprint`: its current version and fingerprint, or a\n * version it accepts with the fingerprint its own history computes (R6, Q10).\n */\nexport function binds(provider: Provider<Contract>, version: number, fingerprint: string): boolean {\n\tconst { contract } = provider;\n\tif (version === contract.version) return fingerprint === contract.fingerprint;\n\treturn provider.accepted.some((accepted) => accepted.version === version && accepted.fingerprint === fingerprint);\n}\n\n/** An accepts table after `checkAccepts`, as the binding reads it. */\ntype CheckedAccepts = {\n\treadonly [version: string]: { readonly methods?: { readonly [member: string]: CheckedMethodMapping } };\n};\n\ntype CheckedMethodMapping =\n\t| \"refuse\"\n\t| { readonly call: (args: Value, context: Context) => Promise<Value> }\n\t| { readonly args?: (old: Value) => Value; readonly result?: (current: Value) => Value };\n\n/** Accepted version -> method -> entry. */\ntype Dispatch = Map<number, Map<string, DispatchEntry>>;\n\ntype DispatchEntry =\n\t| { readonly kind: \"refuse\" }\n\t| {\n\t\t\treadonly kind: \"call\";\n\t\t\treadonly args: Snapshot;\n\t\t\treadonly call: (args: Value, context: Context) => Promise<Value>;\n\t\t\tvalidator: Validator | undefined;\n\t  }\n\t| {\n\t\t\treadonly kind: \"method\";\n\t\t\treadonly args: Snapshot;\n\t\t\treadonly mapArgs: ((old: Value) => Value) | undefined;\n\t\t\treadonly mapResult: ((current: Value) => Value) | undefined;\n\t\t\tvalidator: Validator | undefined;\n\t  };\n\nconst dispatchTables = new WeakMap<Provider<Contract>, Dispatch>();\n\nfunction dispatchEntries(\n\tversion: VersionData,\n\tmappings: { readonly [member: string]: CheckedMethodMapping } | undefined,\n): Map<string, DispatchEntry> {\n\tconst entries = new Map<string, DispatchEntry>();\n\t// A method has one signature in every variant that has it.\n\tconst methods = new Map<string, MethodData>([...version.variants.values()].flatMap(({ methods }) => [...methods]));\n\tfor (const [member, { args }] of methods) {\n\t\tconst mapping = mappings !== undefined && Object.hasOwn(mappings, member) ? mappings[member] : undefined;\n\t\tentries.set(member, dispatchEntry(args, mapping));\n\t}\n\treturn entries;\n}\n\nfunction dispatchEntry(args: Snapshot, mapping: CheckedMethodMapping | undefined): DispatchEntry {\n\tif (mapping === \"refuse\") return { kind: \"refuse\" };\n\tif (mapping !== undefined && \"call\" in mapping) {\n\t\treturn { kind: \"call\", args, call: mapping.call, validator: undefined };\n\t}\n\treturn { kind: \"method\", args, mapArgs: mapping?.args, mapResult: mapping?.result, validator: undefined };\n}\n\n/**\n * Checks a call's arguments against the provider's schema for the caller's bound version: three map lookups, one\n * compiled check, at most one direct mapping old -> current (never for current-version calls). A method without\n * arguments gets `null` (its internal and wire form). Unknown method: `invalid/member`; version not accepted or refused: `contract_mismatch`.\n */\nexport function checkArgs<C extends Contract, M extends string>(\n\tprovider: Provider<C>,\n\tmethod: M,\n\traw: unknown,\n\tboundVersion: number,\n\tcontext: Context,\n): CheckedArgs<C, M> {\n\tconst name = provider.contract.name;\n\tconst methods = dispatchTables.get(provider)!.get(boundVersion);\n\tif (methods === undefined) {\n\t\tthrow new ChordError({ code: \"contract_mismatch\", message: `${name} v${boundVersion} is not accepted` });\n\t}\n\tconst entry = methods.get(method);\n\tif (entry === undefined) throw invalid(\"member\", `${name} v${boundVersion} has no method \"${method}\"`);\n\tif (entry.kind === \"refuse\") {\n\t\tthrow new ChordError({ code: \"contract_mismatch\", message: `${name} v${boundVersion} refuses \"${method}\"` });\n\t}\n\tentry.validator ??= validatorFor(entry.args, context);\n\tcheck(entry.validator, raw, \"args\", context);\n\t// The check above establishes the argument type; mapping output is trusted.\n\tconst args = raw as Value;\n\tif (entry.kind === \"call\") return { kind: \"call\", args, call: entry.call };\n\treturn {\n\t\tkind: \"method\",\n\t\targs: (entry.mapArgs === undefined ? args : entry.mapArgs(args)) as ArgsOf<C, M>,\n\t\tresult: entry.mapResult,\n\t};\n}\n"]}

package/dist/data/errors.d.ts

@@ -0,0 +1,80 @@
+import type { JsonValue } from "../json.ts";
+/** Version of the error table below on links; adding or moving a code or reason bumps it. */
+export declare const PROTOCOL_VERSION = 1;
+/** Every code with the reasons it may carry. `invalid` requires a reason; every other code may omit it. */
+export declare const CHORD_ERROR_REASONS: {
+    readonly invalid: readonly ["args", "params", "member", "host_address", "reentrant", "read_after_bulk", "cycle"];
+    readonly contract_mismatch: readonly ["updating"];
+    readonly forbidden: readonly ["revoked"];
+    readonly gone: readonly [];
+    readonly not_ready: readonly [];
+    readonly released: readonly ["ended", "closed", "settled", "version", "discarded"];
+    readonly too_large: readonly ["part"];
+    readonly unavailable: readonly ["locked", "park_timeout", "busy", "storage_failed", "undeclared", "version", "reload_cycle"];
+    readonly aborted: readonly [];
+};
+export type ChordErrorCode = keyof typeof CHORD_ERROR_REASONS;
+export type ChordErrorReason<C extends ChordErrorCode = ChordErrorCode> = (typeof CHORD_ERROR_REASONS)[C][number];
+/** The wire form of a ChordError and its constructor argument: one member per code, so wrong pairings fail to type. */
+type ChordErrorJson = {
+    [C in ChordErrorCode]: ErrorFields<C>;
+}[ChordErrorCode];
+type ErrorFields<C extends ChordErrorCode> = {
+    readonly code: C;
+    readonly message: string;
+    readonly details?: JsonValue;
+} & (C extends "invalid" ? {
+    readonly reason: ChordErrorReason<C>;
+} : [ChordErrorReason<C>] extends [never] ? {
+    readonly reason?: undefined;
+} : {
+    readonly reason?: ChordErrorReason<C>;
+});
+declare class ChordErrorClass extends Error {
+    readonly code: ChordErrorCode;
+    readonly reason: ChordErrorReason | undefined;
+    readonly details: JsonValue | undefined;
+    constructor(init: ChordErrorJson, options?: ErrorOptions);
+    /** The wire form; stack and cause never cross a link. */
+    toJSON(): ChordErrorJson;
+}
+/** A Chord failure. Narrowing on `code` narrows `reason`. */
+export type ChordError = ChordErrorClass & ChordErrorJson;
+/**
+ * Creates a ChordError: `new ChordError({ code: "invalid", reason: "args", message })`. A class cannot declare its
+ * instances as a tagged union; this constructor signature does.
+ */
+export declare const ChordError: new (init: ChordErrorJson, options?: ErrorOptions) => ChordError;
+/** Whether `error` is a ChordError, optionally with the given code. */
+export declare function isChordError<C extends ChordErrorCode = ChordErrorCode>(error: unknown, code?: C): error is Extract<ChordError, {
+    readonly code: C;
+}>;
+/**
+ * An error a plugin throws for its callers: its own `code`, a message and JSON `details`. Only these cross a link
+ * (never a stack or a cause); a consumer rethrows it as a PluginError.
+ */
+export declare class PluginError extends Error {
+    readonly code: string;
+    readonly details: JsonValue | undefined;
+    constructor(code: string, message: string, details?: JsonValue);
+}
+/** An `invalid` error with the given reason: a plugin throws it for arguments or params it refuses. */
+export declare function invalid(reason: ChordErrorReason<"invalid">, message: string, details?: JsonValue): Extract<ChordError, {
+    readonly code: "invalid";
+}>;
+/**
+ * A `forbidden` error without a reason: what a plugin or an `authorize` throws for a principal it refuses (`revoked` is
+ * Chord's own, for a revoked authority).
+ */
+export declare function forbidden(message: string, details?: JsonValue): Extract<ChordError, {
+    readonly code: "forbidden";
+}>;
+/** `error` itself when it is a ChordError, otherwise an `unavailable` error naming `label`, with `error` as cause. */
+export declare function asChordError(error: unknown, label: string): ChordError;
+/**
+ * Rebuilds a ChordError from a link. Checks the envelope only: a known code, a reason allowed for it (required for
+ * `invalid`), a string message, no other keys. `details` is kept by reference.
+ */
+export declare function chordErrorFromJson(raw: unknown): ChordError;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/data/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/data/errors.ts"],"names":[],"mappings":"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"}

package/dist/data/errors.js

@@ -0,0 +1,116 @@
+// ChordError: Chord's one error type, its codes and reasons (link protocol) and its wire form; and PluginError, what a
+// plugin throws to give its callers a code of its own.
+/** Version of the error table below on links; adding or moving a code or reason bumps it. */
+export const PROTOCOL_VERSION = 1;
+/** Every code with the reasons it may carry. `invalid` requires a reason; every other code may omit it. */
+export const CHORD_ERROR_REASONS = {
+    invalid: ["args", "params", "member", "host_address", "reentrant", "read_after_bulk", "cycle"],
+    contract_mismatch: ["updating"],
+    forbidden: ["revoked"],
+    gone: [],
+    not_ready: [],
+    // No reason: released by its holder. `ended`: its object ended; `closed`: its host, store or native closed;
+    // `settled`: used after the call or run it belonged to settled; `version`: an old handle after a migration;
+    // `discarded`: a transaction cut at the seal.
+    released: ["ended", "closed", "settled", "version", "discarded"],
+    too_large: ["part"],
+    // `undeclared`: a registry no plugin serves on this host; `version`: waiting for a dependency refused for its version
+    // (it heals with another host's reload); `reload_cycle`: old work waiting on its own drain during a reload.
+    unavailable: ["locked", "park_timeout", "busy", "storage_failed", "undeclared", "version", "reload_cycle"],
+    aborted: [],
+};
+class ChordErrorClass extends Error {
+    code;
+    reason;
+    details;
+    constructor(init, options) {
+        super(init.message, options);
+        this.name = "ChordError";
+        this.code = init.code;
+        this.reason = init.reason;
+        this.details = init.details;
+    }
+    /** The wire form; stack and cause never cross a link. */
+    toJSON() {
+        const { code, reason, message, details } = this;
+        // The fields were copied from a ChordErrorJson, so the pairing holds.
+        return {
+            code,
+            ...(reason === undefined ? {} : { reason }),
+            message,
+            ...(details === undefined ? {} : { details }),
+        };
+    }
+}
+/**
+ * Creates a ChordError: `new ChordError({ code: "invalid", reason: "args", message })`. A class cannot declare its
+ * instances as a tagged union; this constructor signature does.
+ */
+export const ChordError = ChordErrorClass;
+/** Whether `error` is a ChordError, optionally with the given code. */
+export function isChordError(error, code) {
+    return error instanceof ChordError && (code === undefined || error.code === code);
+}
+/**
+ * An error a plugin throws for its callers: its own `code`, a message and JSON `details`. Only these cross a link
+ * (never a stack or a cause); a consumer rethrows it as a PluginError.
+ */
+export class PluginError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "PluginError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/** An `invalid` error with the given reason: a plugin throws it for arguments or params it refuses. */
+export function invalid(reason, message, details) {
+    // The constructor's return type cannot narrow on its argument.
+    return new ChordError({ code: "invalid", reason, message, details });
+}
+/**
+ * A `forbidden` error without a reason: what a plugin or an `authorize` throws for a principal it refuses (`revoked` is
+ * Chord's own, for a revoked authority).
+ */
+export function forbidden(message, details) {
+    // The constructor's return type cannot narrow on its argument.
+    return new ChordError({ code: "forbidden", message, details });
+}
+/** `error` itself when it is a ChordError, otherwise an `unavailable` error naming `label`, with `error` as cause. */
+export function asChordError(error, label) {
+    if (isChordError(error))
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new ChordError({ code: "unavailable", message: `${label}: ${message}` }, { cause: error });
+}
+/**
+ * Rebuilds a ChordError from a link. Checks the envelope only: a known code, a reason allowed for it (required for
+ * `invalid`), a string message, no other keys. `details` is kept by reference.
+ */
+export function chordErrorFromJson(raw) {
+    // Trust boundary: `raw` is fresh JSON from the link decoder.
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw envelopeError("not an object");
+    const json = raw;
+    for (const key of Object.keys(json))
+        if (!ENVELOPE_KEYS.has(key))
+            throw envelopeError(`unknown key "${key}"`);
+    const { code, reason, message } = json;
+    if (typeof code !== "string" || !Object.hasOwn(CHORD_ERROR_REASONS, code))
+        throw envelopeError("unknown code");
+    const reasons = CHORD_ERROR_REASONS[code];
+    if (reason === undefined ? code === "invalid" : !reasons.includes(reason)) {
+        throw envelopeError(`reason not allowed for ${code}`);
+    }
+    if (typeof message !== "string")
+        throw envelopeError("message is not a string");
+    // The checks above establish the pairing.
+    return new ChordError(json);
+}
+const ENVELOPE_KEYS = new Set(["code", "reason", "message", "details"]);
+function envelopeError(problem) {
+    return new Error(`Invalid ChordError JSON: ${problem}`);
+}
+//# sourceMappingURL=errors.js.map