@earendil-works/chord 1.3.0 → 1.5.0

package/dist/next/data/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/next/data/errors.ts"],"names":[],"mappings":"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","sourcesContent":["// ChordError: Chord's one error type, its codes and reasons (link protocol) and its wire form; and PluginError, what a\n// plugin throws to give its callers a code of its own.\n\nimport type { JsonValue } from \"../../json.ts\";\n\n/** Version of the error table below on links; adding or moving a code or reason bumps it. */\nexport const PROTOCOL_VERSION = 1;\n\n/** Every code with the reasons it may carry. `invalid` requires a reason; every other code may omit it. */\nexport const CHORD_ERROR_REASONS = {\n\tinvalid: [\"args\", \"params\", \"member\", \"host_address\", \"reentrant\", \"read_after_bulk\", \"cycle\"],\n\tcontract_mismatch: [\"updating\"],\n\tforbidden: [\"revoked\"],\n\tgone: [],\n\tnot_ready: [],\n\t// No reason: released by its holder. `ended`: its object ended; `closed`: its host, store or native closed;\n\t// `settled`: used after the call or run it belonged to settled; `version`: an old handle after a migration;\n\t// `discarded`: a transaction cut at the seal.\n\treleased: [\"ended\", \"closed\", \"settled\", \"version\", \"discarded\"],\n\ttoo_large: [\"part\"],\n\t// `undeclared`: a registry no plugin serves on this host.\n\tunavailable: [\"locked\", \"park_timeout\", \"busy\", \"storage_failed\", \"undeclared\"],\n\taborted: [],\n} as const;\n\nexport type ChordErrorCode = keyof typeof CHORD_ERROR_REASONS;\n\nexport type ChordErrorReason<C extends ChordErrorCode = ChordErrorCode> = (typeof CHORD_ERROR_REASONS)[C][number];\n\n/** The wire form of a ChordError and its constructor argument: one member per code, so wrong pairings fail to type. */\ntype ChordErrorJson = { [C in ChordErrorCode]: ErrorFields<C> }[ChordErrorCode];\n\ntype ErrorFields<C extends ChordErrorCode> = {\n\treadonly code: C;\n\treadonly message: string;\n\treadonly details?: JsonValue;\n} & (C extends \"invalid\"\n\t? { readonly reason: ChordErrorReason<C> }\n\t: [ChordErrorReason<C>] extends [never]\n\t\t? { readonly reason?: undefined }\n\t\t: { readonly reason?: ChordErrorReason<C> });\n\nclass ChordErrorClass extends Error {\n\treadonly code: ChordErrorCode;\n\treadonly reason: ChordErrorReason | undefined;\n\treadonly details: JsonValue | undefined;\n\n\tconstructor(init: ChordErrorJson, options?: ErrorOptions) {\n\t\tsuper(init.message, options);\n\t\tthis.name = \"ChordError\";\n\t\tthis.code = init.code;\n\t\tthis.reason = init.reason;\n\t\tthis.details = init.details;\n\t}\n\n\t/** The wire form; stack and cause never cross a link. */\n\ttoJSON(): ChordErrorJson {\n\t\tconst { code, reason, message, details } = this;\n\t\t// The fields were copied from a ChordErrorJson, so the pairing holds.\n\t\treturn {\n\t\t\tcode,\n\t\t\t...(reason === undefined ? {} : { reason }),\n\t\t\tmessage,\n\t\t\t...(details === undefined ? {} : { details }),\n\t\t} as ChordErrorJson;\n\t}\n}\n\n/** A Chord failure. Narrowing on `code` narrows `reason`. */\nexport type ChordError = ChordErrorClass & ChordErrorJson;\n\n/**\n * Creates a ChordError: `new ChordError({ code: \"invalid\", reason: \"args\", message })`. A class cannot declare its\n * instances as a tagged union; this constructor signature does.\n */\nexport const ChordError = ChordErrorClass as new (init: ChordErrorJson, options?: ErrorOptions) => ChordError;\n\n/** Whether `error` is a ChordError, optionally with the given code. */\nexport function isChordError<C extends ChordErrorCode = ChordErrorCode>(\n\terror: unknown,\n\tcode?: C,\n): error is Extract<ChordError, { readonly code: C }> {\n\treturn error instanceof ChordError && (code === undefined || error.code === code);\n}\n\n/**\n * An error a plugin throws for its callers: its own `code`, a message and JSON `details`. Only these cross a link\n * (never a stack or a cause); a consumer rethrows it as a PluginError.\n */\nexport class PluginError extends Error {\n\treadonly code: string;\n\treadonly details: JsonValue | undefined;\n\n\tconstructor(code: string, message: string, details?: JsonValue) {\n\t\tsuper(message);\n\t\tthis.name = \"PluginError\";\n\t\tthis.code = code;\n\t\tthis.details = details;\n\t}\n}\n\n/** An `invalid` error with the given reason. */\nexport function invalid(\n\treason: ChordErrorReason<\"invalid\">,\n\tmessage: string,\n\tdetails?: JsonValue,\n): Extract<ChordError, { readonly code: \"invalid\" }> {\n\t// The constructor's return type cannot narrow on its argument.\n\treturn new ChordError({ code: \"invalid\", reason, message, details }) as Extract<ChordError, { code: \"invalid\" }>;\n}\n\n/** `error` itself when it is a ChordError, otherwise an `unavailable` error naming `label`, with `error` as cause. */\nexport function asChordError(error: unknown, label: string): ChordError {\n\tif (isChordError(error)) return error;\n\tconst message = error instanceof Error ? error.message : String(error);\n\treturn new ChordError({ code: \"unavailable\", message: `${label}: ${message}` }, { cause: error });\n}\n\n/**\n * Rebuilds a ChordError from a link. Checks the envelope only: a known code, a reason allowed for it (required for\n * `invalid`), a string message, no other keys. `details` is kept by reference.\n */\nexport function chordErrorFromJson(raw: unknown): ChordError {\n\t// Trust boundary: `raw` is fresh JSON from the link decoder.\n\tif (typeof raw !== \"object\" || raw === null || Array.isArray(raw)) throw envelopeError(\"not an object\");\n\tconst json = raw as Record<string, unknown>;\n\tfor (const key of Object.keys(json)) if (!ENVELOPE_KEYS.has(key)) throw envelopeError(`unknown key \"${key}\"`);\n\tconst { code, reason, message } = json;\n\tif (typeof code !== \"string\" || !Object.hasOwn(CHORD_ERROR_REASONS, code)) throw envelopeError(\"unknown code\");\n\tconst reasons: readonly string[] = CHORD_ERROR_REASONS[code as ChordErrorCode];\n\tif (reason === undefined ? code === \"invalid\" : !reasons.includes(reason as string)) {\n\t\tthrow envelopeError(`reason not allowed for ${code}`);\n\t}\n\tif (typeof message !== \"string\") throw envelopeError(\"message is not a string\");\n\t// The checks above establish the pairing.\n\treturn new ChordError(json as ChordErrorJson);\n}\n\nconst ENVELOPE_KEYS = new Set([\"code\", \"reason\", \"message\", \"details\"]);\n\nfunction envelopeError(problem: string): Error {\n\treturn new Error(`Invalid ChordError JSON: ${problem}`);\n}\n"]}

package/dist/next/data/failure.d.ts

@@ -0,0 +1,26 @@
+import { ChordError } from "./errors.ts";
+/** Why an object, or a request, is failed; the kind comes from the failing stage, never from the error code. */
+export type FailureCause = {
+    readonly kind: "transient";
+    readonly error: ChordError;
+} | {
+    readonly kind: "broken";
+    readonly error: ChordError;
+} | {
+    readonly kind: "waiting";
+    readonly error: ChordError;
+};
+/** Marks an open's failure as broken (bad configuration): `throw broken(error)`. */
+export declare function broken(cause: unknown): Error;
+/** The cause of a value thrown by an open: broken when it came from `broken()`, transient otherwise. */
+export declare function openFailure(thrown: unknown, label: string): FailureCause;
+/**
+ * The `waiting` cause of a dependent parked on `blocker`, which failed with `error`: `unavailable`, its message always
+ * "waiting for <blocker>: <root cause>" (the root found through any "waiting for …: " of `error`'s message), so a ring
+ * of waiting attempts passing causes round reaches the same message after one round; within 500 characters, the
+ * label clipped first, the root only past its share. `error` is its cause.
+ */
+export declare function waitingFor(blocker: string, error: ChordError): FailureCause;
+/** Whether two failure causes say the same (a wake compares causes by value): kind, code, reason and message. */
+export declare function sameCause(a: FailureCause, b: FailureCause): boolean;
+//# sourceMappingURL=failure.d.ts.map

package/dist/next/data/failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../../../src/next/data/failure.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvD,gHAAgH;AAChH,MAAM,MAAM,YAAY,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAE5D,oFAAoF;AACpF,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAE5C;AAED,wGAAwG;AACxG,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAGxE;AAiBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,YAAY,CAW3E;AAkBD,iHAAiH;AACjH,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CAMnE"}

package/dist/next/data/failure.js

@@ -0,0 +1,72 @@
+// Failure causes: transient (the object's own effect failed: retry later), broken (its own code, a cycle or authority:
+// retry by hand) or waiting (not its fault: no provider, no fitting version, a dependency that failed; woken by an
+// event). The failing stage decides, never the error code.
+import { asChordError, ChordError } from "./errors.js";
+/** Marks an open's failure as broken (bad configuration): `throw broken(error)`. */
+export function broken(cause) {
+    return new BrokenOpen(cause);
+}
+/** The cause of a value thrown by an open: broken when it came from `broken()`, transient otherwise. */
+export function openFailure(thrown, label) {
+    if (thrown instanceof BrokenOpen)
+        return { kind: "broken", error: asChordError(thrown.cause, label) };
+    return { kind: "transient", error: asChordError(thrown, label) };
+}
+/** The longest message a `waiting` cause of a dependent carries (telemetry's rule for error messages). */
+const MESSAGE_LIMIT = 500;
+/** How a dependent's message names its blocker: the nearest one first. */
+const PREFIX = "waiting for ";
+/** The separator after a blocker's label. */
+const SEPARATOR = ": ";
+/** The marker of a clipped label or root. */
+const CLIPPED = "…";
+/** The most of the 500 characters the root cause takes when both are long: the nearest blocker keeps the rest. */
+const ROOT_LIMIT = 320;
+/**
+ * The `waiting` cause of a dependent parked on `blocker`, which failed with `error`: `unavailable`, its message always
+ * "waiting for <blocker>: <root cause>" (the root found through any "waiting for …: " of `error`'s message), so a ring
+ * of waiting attempts passing causes round reaches the same message after one round; within 500 characters, the
+ * label clipped first, the root only past its share. `error` is its cause.
+ */
+export function waitingFor(blocker, error) {
+    let root = rootMessage(error.message);
+    let label = blocker;
+    const room = MESSAGE_LIMIT - PREFIX.length - SEPARATOR.length;
+    if (label.length + root.length > room) {
+        const rootRoom = Math.max(ROOT_LIMIT, room - label.length);
+        if (root.length > rootRoom)
+            root = clipped(root, rootRoom);
+        if (label.length + root.length > room)
+            label = clipped(label, room - root.length);
+    }
+    const message = `${PREFIX}${label}${SEPARATOR}${root}`;
+    return { kind: "waiting", error: new ChordError({ code: "unavailable", message }, { cause: error }) };
+}
+/** `text` within `length` characters, clipped with "…" when longer. */
+function clipped(text, length) {
+    return text.length <= length ? text : `${text.slice(0, length - CLIPPED.length)}${CLIPPED}`;
+}
+/** The root cause in a "waiting for X: root" message: past every leading "waiting for …: ". */
+function rootMessage(message) {
+    let rest = message;
+    while (rest.startsWith(PREFIX)) {
+        const end = rest.indexOf(SEPARATOR, PREFIX.length);
+        if (end < 0)
+            break;
+        rest = rest.slice(end + SEPARATOR.length);
+    }
+    return rest;
+}
+/** Whether two failure causes say the same (a wake compares causes by value): kind, code, reason and message. */
+export function sameCause(a, b) {
+    const { error: left } = a;
+    const { error: right } = b;
+    return (a.kind === b.kind && left.code === right.code && left.reason === right.reason && left.message === right.message);
+}
+class BrokenOpen extends Error {
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.name = "BrokenOpen";
+    }
+}
+//# sourceMappingURL=failure.js.map

package/dist/next/data/failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.js","sourceRoot":"","sources":["../../../src/next/data/failure.ts"],"names":[],"mappings":"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","sourcesContent":["// Failure causes: transient (the object's own effect failed: retry later), broken (its own code, a cycle or authority:\n// retry by hand) or waiting (not its fault: no provider, no fitting version, a dependency that failed; woken by an\n// event). The failing stage decides, never the error code.\n\nimport { asChordError, ChordError } from \"./errors.ts\";\n\n/** Why an object, or a request, is failed; the kind comes from the failing stage, never from the error code. */\nexport type FailureCause =\n\t| { readonly kind: \"transient\"; readonly error: ChordError }\n\t| { readonly kind: \"broken\"; readonly error: ChordError }\n\t| { readonly kind: \"waiting\"; readonly error: ChordError };\n\n/** Marks an open's failure as broken (bad configuration): `throw broken(error)`. */\nexport function broken(cause: unknown): Error {\n\treturn new BrokenOpen(cause);\n}\n\n/** The cause of a value thrown by an open: broken when it came from `broken()`, transient otherwise. */\nexport function openFailure(thrown: unknown, label: string): FailureCause {\n\tif (thrown instanceof BrokenOpen) return { kind: \"broken\", error: asChordError(thrown.cause, label) };\n\treturn { kind: \"transient\", error: asChordError(thrown, label) };\n}\n\n/** The longest message a `waiting` cause of a dependent carries (telemetry's rule for error messages). */\nconst MESSAGE_LIMIT = 500;\n\n/** How a dependent's message names its blocker: the nearest one first. */\nconst PREFIX = \"waiting for \";\n\n/** The separator after a blocker's label. */\nconst SEPARATOR = \": \";\n\n/** The marker of a clipped label or root. */\nconst CLIPPED = \"…\";\n\n/** The most of the 500 characters the root cause takes when both are long: the nearest blocker keeps the rest. */\nconst ROOT_LIMIT = 320;\n\n/**\n * The `waiting` cause of a dependent parked on `blocker`, which failed with `error`: `unavailable`, its message always\n * \"waiting for <blocker>: <root cause>\" (the root found through any \"waiting for …: \" of `error`'s message), so a ring\n * of waiting attempts passing causes round reaches the same message after one round; within 500 characters, the\n * label clipped first, the root only past its share. `error` is its cause.\n */\nexport function waitingFor(blocker: string, error: ChordError): FailureCause {\n\tlet root = rootMessage(error.message);\n\tlet label = blocker;\n\tconst room = MESSAGE_LIMIT - PREFIX.length - SEPARATOR.length;\n\tif (label.length + root.length > room) {\n\t\tconst rootRoom = Math.max(ROOT_LIMIT, room - label.length);\n\t\tif (root.length > rootRoom) root = clipped(root, rootRoom);\n\t\tif (label.length + root.length > room) label = clipped(label, room - root.length);\n\t}\n\tconst message = `${PREFIX}${label}${SEPARATOR}${root}`;\n\treturn { kind: \"waiting\", error: new ChordError({ code: \"unavailable\", message }, { cause: error }) };\n}\n\n/** `text` within `length` characters, clipped with \"…\" when longer. */\nfunction clipped(text: string, length: number): string {\n\treturn text.length <= length ? text : `${text.slice(0, length - CLIPPED.length)}${CLIPPED}`;\n}\n\n/** The root cause in a \"waiting for X: root\" message: past every leading \"waiting for …: \". */\nfunction rootMessage(message: string): string {\n\tlet rest = message;\n\twhile (rest.startsWith(PREFIX)) {\n\t\tconst end = rest.indexOf(SEPARATOR, PREFIX.length);\n\t\tif (end < 0) break;\n\t\trest = rest.slice(end + SEPARATOR.length);\n\t}\n\treturn rest;\n}\n\n/** Whether two failure causes say the same (a wake compares causes by value): kind, code, reason and message. */\nexport function sameCause(a: FailureCause, b: FailureCause): boolean {\n\tconst { error: left } = a;\n\tconst { error: right } = b;\n\treturn (\n\t\ta.kind === b.kind && left.code === right.code && left.reason === right.reason && left.message === right.message\n\t);\n}\n\nclass BrokenOpen extends Error {\n\tconstructor(cause: unknown) {\n\t\tsuper(cause instanceof Error ? cause.message : String(cause), { cause });\n\t\tthis.name = \"BrokenOpen\";\n\t}\n}\n"]}

package/dist/next/data/index.d.ts

@@ -0,0 +1,4 @@
+export { ChordError, type ChordErrorCode, type ChordErrorReason, isChordError, PluginError, } from "./errors.ts";
+export { broken, type FailureCause } from "./failure.ts";
+export type { Principal, PrincipalKeyFunction } from "./principal.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/next/data/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/next/data/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,YAAY,EACZ,WAAW,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AACzD,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/next/data/index.js

@@ -0,0 +1,4 @@
+// Data for apps: Chord's errors and plugin errors, principals, and how a plugin's open reports a broken configuration.
+export { ChordError, isChordError, PluginError, } from "./errors.js";
+export { broken } from "./failure.js";
+//# sourceMappingURL=index.js.map

package/dist/next/data/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/next/data/index.ts"],"names":[],"mappings":"AAAA,uHAAuH;AAEvH,OAAO,EACN,UAAU,EAGV,YAAY,EACZ,WAAW,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAqB,MAAM,cAAc,CAAC","sourcesContent":["// Data for apps: Chord's errors and plugin errors, principals, and how a plugin's open reports a broken configuration.\n\nexport {\n\tChordError,\n\ttype ChordErrorCode,\n\ttype ChordErrorReason,\n\tisChordError,\n\tPluginError,\n} from \"./errors.ts\";\nexport { broken, type FailureCause } from \"./failure.ts\";\nexport type { Principal, PrincipalKeyFunction } from \"./principal.ts\";\n"]}

package/dist/next/data/internal.d.ts

@@ -0,0 +1,7 @@
+export { bindProvider, binds, type CheckedArgs, checkArgs, type Provider, type Value } from "./args.ts";
+export { asChordError, CHORD_ERROR_REASONS, chordErrorFromJson, invalid, PROTOCOL_VERSION, } from "./errors.ts";
+export { openFailure, sameCause, waitingFor } from "./failure.ts";
+export { checkAddress, checkParams, identityKey } from "./params.ts";
+export { canonicalJson, principalKey } from "./principal.ts";
+export { check, validatorFor } from "./validator.ts";
+//# sourceMappingURL=internal.d.ts.map

package/dist/next/data/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../../src/next/data/internal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AACxG,OAAO,EACN,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,OAAO,EACP,gBAAgB,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/next/data/internal.js

@@ -0,0 +1,8 @@
+// Data for Chord's layers: per-call checks of params and arguments, principal keys, and errors on the wire.
+export { bindProvider, binds, checkArgs } from "./args.js";
+export { asChordError, CHORD_ERROR_REASONS, chordErrorFromJson, invalid, PROTOCOL_VERSION, } from "./errors.js";
+export { openFailure, sameCause, waitingFor } from "./failure.js";
+export { checkAddress, checkParams, identityKey } from "./params.js";
+export { canonicalJson, principalKey } from "./principal.js";
+export { check, validatorFor } from "./validator.js";
+//# sourceMappingURL=internal.js.map

package/dist/next/data/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../../src/next/data/internal.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAE5G,OAAO,EAAE,YAAY,EAAE,KAAK,EAAoB,SAAS,EAA6B,MAAM,WAAW,CAAC;AACxG,OAAO,EACN,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,OAAO,EACP,gBAAgB,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["// Data for Chord's layers: per-call checks of params and arguments, principal keys, and errors on the wire.\n\nexport { bindProvider, binds, type CheckedArgs, checkArgs, type Provider, type Value } from \"./args.ts\";\nexport {\n\tasChordError,\n\tCHORD_ERROR_REASONS,\n\tchordErrorFromJson,\n\tinvalid,\n\tPROTOCOL_VERSION,\n} from \"./errors.ts\";\nexport { openFailure, sameCause, waitingFor } from \"./failure.ts\";\nexport { checkAddress, checkParams, identityKey } from \"./params.ts\";\nexport { canonicalJson, principalKey } from \"./principal.ts\";\nexport { check, validatorFor } from \"./validator.ts\";\n"]}

package/dist/next/data/params.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from "../../context/index.ts";
+import { type Contract, type ParamsOf, type ShapeOf } from "../contracts/contract.ts";
+import { type Address } from "../contracts/host-kind.ts";
+import { type ParamsData } from "../contracts/params.ts";
+/**
+ * Checks `raw` against the contract's params with one compiled closed-object check (`invalid/params` on failure) and
+ * returns the caller's own object with its key: the field values in declared order, each escaped, joined with `|`.
+ */
+export declare function checkParams<C extends Contract>(contract: C, raw: unknown, context: Context): {
+    readonly params: ParamsOf<C>;
+    readonly key: string;
+};
+/** The in-process identity of an object: `name|key|principalKey`, each part escaped; `local` has no principal. */
+export declare function identityKey<C extends Contract>(contract: C, key: string, ...principalKey: ShapeOf<C>["kind"] extends "local" ? [] : [principalKey: string]): string;
+/**
+ * An address from a kind's name and params as a hold names it or a `hostAddress` returned it: the params checked
+ * against the kind's with one compiled closed-object check (`invalid/host_address` on failure), the key computed.
+ */
+export declare function checkAddress(kind: string, params: ParamsData, raw: unknown, context: Context): Address;
+//# sourceMappingURL=params.d.ts.map

package/dist/next/data/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../../src/next/data/params.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,KAAK,QAAQ,EAAgB,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACpG,OAAO,EAAE,KAAK,OAAO,EAAc,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGlE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,QAAQ,EAC7C,QAAQ,EAAE,CAAC,EACX,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,OAAO,GACd;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAMxD;AAED,kHAAkH;AAClH,wBAAgB,WAAW,CAAC,CAAC,SAAS,QAAQ,EAC7C,QAAQ,EAAE,CAAC,EACX,GAAG,EAAE,MAAM,EACX,GAAG,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,OAAO,GAAG,EAAE,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,GAC/E,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAKtG"}

package/dist/next/data/params.js

@@ -0,0 +1,31 @@
+// Params and identity: the checked params of a get, their key, and the in-process identity of an object.
+import { contractData } from "../contracts/contract.js";
+import { addressKey } from "../contracts/host-kind.js";
+import { joinKey } from "../contracts/params.js";
+import { check, validatorFor } from "./validator.js";
+/**
+ * Checks `raw` against the contract's params with one compiled closed-object check (`invalid/params` on failure) and
+ * returns the caller's own object with its key: the field values in declared order, each escaped, joined with `|`.
+ */
+export function checkParams(contract, raw, context) {
+    const { params } = contractData(contract);
+    check(validatorFor(params, context), raw, "params", context);
+    // The check above establishes the params type.
+    const checked = raw;
+    return { params: checked, key: joinKey(params.fields.map((field) => String(checked[field]))) };
+}
+/** The in-process identity of an object: `name|key|principalKey`, each part escaped; `local` has no principal. */
+export function identityKey(contract, key, ...principalKey) {
+    return joinKey([contract.name, key, ...principalKey]);
+}
+/**
+ * An address from a kind's name and params as a hold names it or a `hostAddress` returned it: the params checked
+ * against the kind's with one compiled closed-object check (`invalid/host_address` on failure), the key computed.
+ */
+export function checkAddress(kind, params, raw, context) {
+    check(validatorFor(params, context), raw, "host_address", context);
+    // The check above establishes a flat record of the kind's scalar fields.
+    const values = raw;
+    return { kind, params: values, key: addressKey(kind, params, values) };
+}
+//# sourceMappingURL=params.js.map

package/dist/next/data/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../../src/next/data/params.ts"],"names":[],"mappings":"AAAA,yGAAyG;AAGzG,OAAO,EAAiB,YAAY,EAA+B,MAAM,0BAA0B,CAAC;AACpG,OAAO,EAAgB,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,OAAO,EAAmB,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;GAGG;AACH,MAAM,UAAU,WAAW,CAC1B,QAAW,EACX,GAAY,EACZ,OAAgB;IAEhB,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC1C,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7D,+CAA+C;IAC/C,MAAM,OAAO,GAAG,GAA4E,CAAC;IAC7F,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAChG,CAAC;AAED,kHAAkH;AAClH,MAAM,UAAU,WAAW,CAC1B,QAAW,EACX,GAAW,EACX,GAAG,YAA8E;IAEjF,OAAO,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAkB,EAAE,GAAY,EAAE,OAAgB;IAC5F,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;IACnE,yEAAyE;IACzE,MAAM,MAAM,GAAG,GAA8D,CAAC;IAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;AACxE,CAAC","sourcesContent":["// Params and identity: the checked params of a get, their key, and the in-process identity of an object.\n\nimport type { Context } from \"../../context/index.ts\";\nimport { type Contract, contractData, type ParamsOf, type ShapeOf } from \"../contracts/contract.ts\";\nimport { type Address, addressKey } from \"../contracts/host-kind.ts\";\nimport { joinKey, type ParamsData } from \"../contracts/params.ts\";\nimport { check, validatorFor } from \"./validator.ts\";\n\n/**\n * Checks `raw` against the contract's params with one compiled closed-object check (`invalid/params` on failure) and\n * returns the caller's own object with its key: the field values in declared order, each escaped, joined with `|`.\n */\nexport function checkParams<C extends Contract>(\n\tcontract: C,\n\traw: unknown,\n\tcontext: Context,\n): { readonly params: ParamsOf<C>; readonly key: string } {\n\tconst { params } = contractData(contract);\n\tcheck(validatorFor(params, context), raw, \"params\", context);\n\t// The check above establishes the params type.\n\tconst checked = raw as ParamsOf<C> & { readonly [field: string]: string | number | boolean };\n\treturn { params: checked, key: joinKey(params.fields.map((field) => String(checked[field]))) };\n}\n\n/** The in-process identity of an object: `name|key|principalKey`, each part escaped; `local` has no principal. */\nexport function identityKey<C extends Contract>(\n\tcontract: C,\n\tkey: string,\n\t...principalKey: ShapeOf<C>[\"kind\"] extends \"local\" ? [] : [principalKey: string]\n): string {\n\treturn joinKey([contract.name, key, ...principalKey]);\n}\n\n/**\n * An address from a kind's name and params as a hold names it or a `hostAddress` returned it: the params checked\n * against the kind's with one compiled closed-object check (`invalid/host_address` on failure), the key computed.\n */\nexport function checkAddress(kind: string, params: ParamsData, raw: unknown, context: Context): Address {\n\tcheck(validatorFor(params, context), raw, \"host_address\", context);\n\t// The check above establishes a flat record of the kind's scalar fields.\n\tconst values = raw as { readonly [field: string]: string | number | boolean };\n\treturn { kind, params: values, key: addressKey(kind, params, values) };\n}\n"]}

package/dist/next/data/principal.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from "../../context/index.ts";
+import type { JsonValue } from "../../json.ts";
+/** An app's principal: plain JSON with a `kind`. Chord never persists it. */
+export type Principal = {
+    readonly kind: string;
+    readonly [field: string]: JsonValue;
+};
+/** An app's own principal key; it must be the same function on every host. */
+export type PrincipalKeyFunction<P extends Principal = Principal> = (principal: P) => string;
+/**
+ * The key of a principal: its canonical JSON, or `customKey(principal)`. Cached per principal object; a custom key's
+ * cache is keyed by the function too, so a live principal never retains a dropped function.
+ */
+export declare function principalKey<P extends Principal>(principal: P, context: Context, customKey?: PrincipalKeyFunction<P>): string;
+/** Canonical JSON: sorted object keys, `-0` written as `0`. Counts one walk. */
+export declare function canonicalJson(value: JsonValue, context: Context): string;
+//# sourceMappingURL=principal.d.ts.map

package/dist/next/data/principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.d.ts","sourceRoot":"","sources":["../../../src/next/data/principal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEvF,8EAA8E;AAC9E,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,MAAM,CAAC;AAE7F;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAC/C,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,OAAO,EAChB,SAAS,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,GACjC,MAAM,CAQR;AAeD,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAGxE"}

package/dist/next/data/principal.js

@@ -0,0 +1,41 @@
+// Principals: the app's caller identities, and the keys Chord derives from them.
+/**
+ * The key of a principal: its canonical JSON, or `customKey(principal)`. Cached per principal object; a custom key's
+ * cache is keyed by the function too, so a live principal never retains a dropped function.
+ */
+export function principalKey(principal, context, customKey) {
+    const cache = customKey === undefined ? defaultKeys : customKeyCache(customKey);
+    let key = cache.get(principal);
+    if (key === undefined) {
+        key = customKey === undefined ? canonicalJson(principal, context) : customKey(principal);
+        cache.set(principal, key);
+    }
+    return key;
+}
+const defaultKeys = new WeakMap();
+const customKeys = new WeakMap();
+function customKeyCache(customKey) {
+    let cache = customKeys.get(customKey);
+    if (cache === undefined) {
+        cache = new WeakMap();
+        customKeys.set(customKey, cache);
+    }
+    return cache;
+}
+/** Canonical JSON: sorted object keys, `-0` written as `0`. Counts one walk. */
+export function canonicalJson(value, context) {
+    context.telemetry.metrics?.counter("chord.data.walks").add(1);
+    return canonical(value);
+}
+function canonical(value) {
+    // JSON.stringify writes -0 as 0.
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const fields = Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`);
+    return `{${fields.join(",")}}`;
+}
+//# sourceMappingURL=principal.js.map

package/dist/next/data/principal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.js","sourceRoot":"","sources":["../../../src/next/data/principal.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAWjF;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC3B,SAAY,EACZ,OAAgB,EAChB,SAAmC;IAEnC,MAAM,KAAK,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAChF,IAAI,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACvB,GAAG,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACzF,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,MAAM,WAAW,GAAG,IAAI,OAAO,EAAqB,CAAC;AAErD,MAAM,UAAU,GAAG,IAAI,OAAO,EAA2D,CAAC;AAE1F,SAAS,cAAc,CAAC,SAAsC;IAC7D,IAAI,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,KAAK,GAAG,IAAI,OAAO,EAAE,CAAC;QACtB,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,KAAgB,EAAE,OAAgB;IAC/D,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9D,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,SAAS,CAAC,KAAgB;IAClC,iCAAiC;IACjC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACvE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;SAC/B,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,GAAG,CAAE,CAAC,EAAE,CAAC,CAAC;IACnE,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAChC,CAAC","sourcesContent":["// Principals: the app's caller identities, and the keys Chord derives from them.\n\nimport type { Context } from \"../../context/index.ts\";\nimport type { JsonValue } from \"../../json.ts\";\n\n/** An app's principal: plain JSON with a `kind`. Chord never persists it. */\nexport type Principal = { readonly kind: string; readonly [field: string]: JsonValue };\n\n/** An app's own principal key; it must be the same function on every host. */\nexport type PrincipalKeyFunction<P extends Principal = Principal> = (principal: P) => string;\n\n/**\n * The key of a principal: its canonical JSON, or `customKey(principal)`. Cached per principal object; a custom key's\n * cache is keyed by the function too, so a live principal never retains a dropped function.\n */\nexport function principalKey<P extends Principal>(\n\tprincipal: P,\n\tcontext: Context,\n\tcustomKey?: PrincipalKeyFunction<P>,\n): string {\n\tconst cache = customKey === undefined ? defaultKeys : customKeyCache(customKey);\n\tlet key = cache.get(principal);\n\tif (key === undefined) {\n\t\tkey = customKey === undefined ? canonicalJson(principal, context) : customKey(principal);\n\t\tcache.set(principal, key);\n\t}\n\treturn key;\n}\n\nconst defaultKeys = new WeakMap<Principal, string>();\n\nconst customKeys = new WeakMap<PrincipalKeyFunction<never>, WeakMap<Principal, string>>();\n\nfunction customKeyCache(customKey: PrincipalKeyFunction<never>): WeakMap<Principal, string> {\n\tlet cache = customKeys.get(customKey);\n\tif (cache === undefined) {\n\t\tcache = new WeakMap();\n\t\tcustomKeys.set(customKey, cache);\n\t}\n\treturn cache;\n}\n\n/** Canonical JSON: sorted object keys, `-0` written as `0`. Counts one walk. */\nexport function canonicalJson(value: JsonValue, context: Context): string {\n\tcontext.telemetry.metrics?.counter(\"chord.data.walks\").add(1);\n\treturn canonical(value);\n}\n\nfunction canonical(value: JsonValue): string {\n\t// JSON.stringify writes -0 as 0.\n\tif (value === null || typeof value !== \"object\") return JSON.stringify(value);\n\tif (Array.isArray(value)) return `[${value.map(canonical).join(\",\")}]`;\n\tconst fields = Object.keys(value)\n\t\t.sort()\n\t\t.map((key) => `${JSON.stringify(key)}:${canonical(value[key]!)}`);\n\treturn `{${fields.join(\",\")}}`;\n}\n"]}

package/dist/next/data/validator.d.ts

@@ -0,0 +1,12 @@
+import { type JsonSchema, type Validator } from "@earendil-works/pi-schema";
+import type { Context } from "../../context/index.ts";
+/** A Chord-owned record holding a schema: a snapshot, or a contract's params. */
+type SchemaOwner = {
+    readonly schema: JsonSchema;
+};
+/** The validator of an owner's schema, compiled on first use (counted) and cached weakly by the owner. */
+export declare function validatorFor(owner: SchemaOwner, context: Context): Validator;
+/** Checks `value` (counted); a failure throws `invalid/<reason>` with the first error's JSON Pointer path. */
+export declare function check(validator: Validator, value: unknown, reason: "args" | "params" | "host_address", context: Context): void;
+export {};
+//# sourceMappingURL=validator.d.ts.map

package/dist/next/data/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/next/data/validator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAGtD,iFAAiF;AACjF,KAAK,WAAW,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAEnD,0GAA0G;AAC1G,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CAS5E;AAID,8GAA8G;AAC9G,wBAAgB,KAAK,CACpB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,cAAc,EAC1C,OAAO,EAAE,OAAO,GACd,IAAI,CAGN"}

package/dist/next/data/validator.js

@@ -0,0 +1,34 @@
+// Compiled checks: pi-schema validators of Chord-owned schemas, and the `invalid` error of a failed check.
+import { compile } from "@earendil-works/pi-schema";
+import { invalid } from "./errors.js";
+/** The validator of an owner's schema, compiled on first use (counted) and cached weakly by the owner. */
+export function validatorFor(owner, context) {
+    let validator = validators.get(owner);
+    if (validator === undefined) {
+        context.telemetry.metrics?.counter("chord.data.compilations").add(1);
+        // `format` is an annotation (decided for the schema switch): no format checks are compiled in.
+        validator = compile(owner.schema);
+        validators.set(owner, validator);
+    }
+    return validator;
+}
+const validators = new WeakMap();
+/** Checks `value` (counted); a failure throws `invalid/<reason>` with the first error's JSON Pointer path. */
+export function check(validator, value, reason, context) {
+    context.telemetry.metrics?.counter("chord.data.validations").add(1);
+    if (!validator.check(value))
+        throw failedCheck(validator, value, reason, context);
+}
+/**
+ * The error of a failed check: the first error of the validator's explanation (counted: it walks the schema). A
+ * missing field is reported at the field ("missing"), an unknown one at its own path ("unknown field"); the value
+ * itself at `/`.
+ */
+function failedCheck(validator, value, reason, context) {
+    context.telemetry.metrics?.counter("chord.data.walks").add(1);
+    // A value that failed the check has at least one error.
+    const error = validator.errors(value)[0];
+    const path = error.path || "/";
+    return invalid(reason, `${reason}${path === "/" ? "" : path}: ${error.message}`, { path });
+}
+//# sourceMappingURL=validator.js.map

package/dist/next/data/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../src/next/data/validator.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAE3G,OAAO,EAAE,OAAO,EAAmC,MAAM,2BAA2B,CAAC;AAErF,OAAO,EAAmB,OAAO,EAAE,MAAM,aAAa,CAAC;AAKvD,0GAA0G;AAC1G,MAAM,UAAU,YAAY,CAAC,KAAkB,EAAE,OAAgB;IAChE,IAAI,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACrE,+FAA+F;QAC/F,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAClC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,GAAG,IAAI,OAAO,EAA0B,CAAC;AAEzD,8GAA8G;AAC9G,MAAM,UAAU,KAAK,CACpB,SAAoB,EACpB,KAAc,EACd,MAA0C,EAC1C,OAAgB;IAEhB,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACpE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,MAAM,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACnF,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CACnB,SAAoB,EACpB,KAAc,EACd,MAA0C,EAC1C,OAAgB;IAEhB,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9D,wDAAwD;IACxD,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC;IAC/B,OAAO,OAAO,CAAC,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AAC5F,CAAC","sourcesContent":["// Compiled checks: pi-schema validators of Chord-owned schemas, and the `invalid` error of a failed check.\n\nimport { compile, type JsonSchema, type Validator } from \"@earendil-works/pi-schema\";\nimport type { Context } from \"../../context/index.ts\";\nimport { type ChordError, invalid } from \"./errors.ts\";\n\n/** A Chord-owned record holding a schema: a snapshot, or a contract's params. */\ntype SchemaOwner = { readonly schema: JsonSchema };\n\n/** The validator of an owner's schema, compiled on first use (counted) and cached weakly by the owner. */\nexport function validatorFor(owner: SchemaOwner, context: Context): Validator {\n\tlet validator = validators.get(owner);\n\tif (validator === undefined) {\n\t\tcontext.telemetry.metrics?.counter(\"chord.data.compilations\").add(1);\n\t\t// `format` is an annotation (decided for the schema switch): no format checks are compiled in.\n\t\tvalidator = compile(owner.schema);\n\t\tvalidators.set(owner, validator);\n\t}\n\treturn validator;\n}\n\nconst validators = new WeakMap<SchemaOwner, Validator>();\n\n/** Checks `value` (counted); a failure throws `invalid/<reason>` with the first error's JSON Pointer path. */\nexport function check(\n\tvalidator: Validator,\n\tvalue: unknown,\n\treason: \"args\" | \"params\" | \"host_address\",\n\tcontext: Context,\n): void {\n\tcontext.telemetry.metrics?.counter(\"chord.data.validations\").add(1);\n\tif (!validator.check(value)) throw failedCheck(validator, value, reason, context);\n}\n\n/**\n * The error of a failed check: the first error of the validator's explanation (counted: it walks the schema). A\n * missing field is reported at the field (\"missing\"), an unknown one at its own path (\"unknown field\"); the value\n * itself at `/`.\n */\nfunction failedCheck(\n\tvalidator: Validator,\n\tvalue: unknown,\n\treason: \"args\" | \"params\" | \"host_address\",\n\tcontext: Context,\n): ChordError {\n\tcontext.telemetry.metrics?.counter(\"chord.data.walks\").add(1);\n\t// A value that failed the check has at least one error.\n\tconst error = validator.errors(value)[0]!;\n\tconst path = error.path || \"/\";\n\treturn invalid(reason, `${reason}${path === \"/\" ? \"\" : path}: ${error.message}`, { path });\n}\n"]}

package/dist/next/documents/address-source.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from "../../context/index.ts";
+import type { Prepared } from "../../delta/index.ts";
+import { Source } from "../state/internal.ts";
+import type { JsonObject } from "./definition.ts";
+/** A source following one document address; `value` is the document's, or `initial()` while it is absent. */
+export declare abstract class AddressSource extends Source {
+    #private;
+    abstract get value(): JsonObject;
+    deliver(context: Context): void;
+    /**
+     * A commit wrote the document, which read `before`: its ops, or a root replacement when the draft started from
+     * another base or the document was retired earlier in the batch.
+     */
+    written(before: JsonObject, prepared: Prepared<JsonObject>): void;
+    /** The document was retired: it reads `initial` again, and the frame says so. */
+    retired(initial: JsonObject): void;
+    /** The value changed outside a commit (a migration, a load): a root replacement. */
+    replaced(): void;
+}
+//# sourceMappingURL=address-source.d.ts.map

package/dist/next/documents/address-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-source.d.ts","sourceRoot":"","sources":["../../../src/next/documents/address-source.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAM,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,6GAA6G;AAC7G,8BAAsB,aAAc,SAAQ,MAAM;;IAKjD,aAAsB,KAAK,IAAI,UAAU,CAAC;IAE1C,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAI9B;IAED;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAIhE;IAED,iFAAiF;IACjF,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAQjC;IAED,oFAAoF;IACpF,QAAQ,IAAI,IAAI,CAGf;CACD"}

package/dist/next/documents/address-source.js

@@ -0,0 +1,44 @@
+// Watchable document addresses (slice 6a §11; decision "One retirement mechanism"): the frames of a source that
+// follows one address, a singleton's slot or one key of a keyed slot. A change arrives with its ops, a write over
+// another base as a root replacement, a retirement as `[["r", initial()]]` with the `retired` flag, and a document
+// created after a retirement in the same batch as one root replacement with the flag.
+import { Source } from "../state/internal.js";
+const NO_OPS = [];
+/** A source following one document address; `value` is the document's, or `initial()` while it is absent. */
+export class AddressSource extends Source {
+    /** The ops of the current batch's frame, and whether the document was retired in it. */
+    #ops = NO_OPS;
+    #retired = false;
+    deliver(context) {
+        this.publish(this.value, this.#ops, this.#retired, context);
+        this.#ops = NO_OPS;
+        this.#retired = false;
+    }
+    /**
+     * A commit wrote the document, which read `before`: its ops, or a root replacement when the draft started from
+     * another base or the document was retired earlier in the batch.
+     */
+    written(before, prepared) {
+        // The ops are kept for a frame, which only a watched source gets: an unwatched one keeps none.
+        if (this.watched)
+            this.#ops = prepared.base === before && !this.#retired ? prepared.ops : [["r", prepared.value]];
+        this.changed();
+    }
+    /** The document was retired: it reads `initial` again, and the frame says so. */
+    retired(initial) {
+        // Reset by the frame, which only a watched source gets.
+        if (this.watched) {
+            this.#ops = [["r", initial]];
+            this.#retired = true;
+        }
+        this.changed();
+        this.retiredInBatch();
+    }
+    /** The value changed outside a commit (a migration, a load): a root replacement. */
+    replaced() {
+        if (this.watched)
+            this.#ops = [["r", this.value]];
+        this.changed();
+    }
+}
+//# sourceMappingURL=address-source.js.map

package/dist/next/documents/address-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-source.js","sourceRoot":"","sources":["../../../src/next/documents/address-source.ts"],"names":[],"mappings":"AAAA,gHAAgH;AAChH,kHAAkH;AAClH,mHAAmH;AACnH,sFAAsF;AAItF,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,MAAM,MAAM,GAAkB,EAAE,CAAC;AAEjC,6GAA6G;AAC7G,MAAM,OAAgB,aAAc,SAAQ,MAAM;IACjD,wFAAwF;IACxF,IAAI,GAAG,MAAM,CAAC;IACd,QAAQ,GAAG,KAAK,CAAC;IAIjB,OAAO,CAAC,OAAgB;QACvB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,MAAkB,EAAE,QAA8B;QACzD,+FAA+F;QAC/F,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QAClH,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;IAED,iFAAiF;IACjF,OAAO,CAAC,OAAmB;QAC1B,wDAAwD;QACxD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACtB,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,CAAC,cAAc,EAAE,CAAC;IACvB,CAAC;IAED,oFAAoF;IACpF,QAAQ;QACP,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;CACD","sourcesContent":["// Watchable document addresses (slice 6a §11; decision \"One retirement mechanism\"): the frames of a source that\n// follows one address, a singleton's slot or one key of a keyed slot. A change arrives with its ops, a write over\n// another base as a root replacement, a retirement as `[[\"r\", initial()]]` with the `retired` flag, and a document\n// created after a retirement in the same batch as one root replacement with the flag.\n\nimport type { Context } from \"../../context/index.ts\";\nimport type { Op, Prepared } from \"../../delta/index.ts\";\nimport { Source } from \"../state/internal.ts\";\nimport type { JsonObject } from \"./definition.ts\";\n\nconst NO_OPS: readonly Op[] = [];\n\n/** A source following one document address; `value` is the document's, or `initial()` while it is absent. */\nexport abstract class AddressSource extends Source {\n\t/** The ops of the current batch's frame, and whether the document was retired in it. */\n\t#ops = NO_OPS;\n\t#retired = false;\n\n\tabstract override get value(): JsonObject;\n\n\tdeliver(context: Context): void {\n\t\tthis.publish(this.value, this.#ops, this.#retired, context);\n\t\tthis.#ops = NO_OPS;\n\t\tthis.#retired = false;\n\t}\n\n\t/**\n\t * A commit wrote the document, which read `before`: its ops, or a root replacement when the draft started from\n\t * another base or the document was retired earlier in the batch.\n\t */\n\twritten(before: JsonObject, prepared: Prepared<JsonObject>): void {\n\t\t// The ops are kept for a frame, which only a watched source gets: an unwatched one keeps none.\n\t\tif (this.watched) this.#ops = prepared.base === before && !this.#retired ? prepared.ops : [[\"r\", prepared.value]];\n\t\tthis.changed();\n\t}\n\n\t/** The document was retired: it reads `initial` again, and the frame says so. */\n\tretired(initial: JsonObject): void {\n\t\t// Reset by the frame, which only a watched source gets.\n\t\tif (this.watched) {\n\t\t\tthis.#ops = [[\"r\", initial]];\n\t\t\tthis.#retired = true;\n\t\t}\n\t\tthis.changed();\n\t\tthis.retiredInBatch();\n\t}\n\n\t/** The value changed outside a commit (a migration, a load): a root replacement. */\n\treplaced(): void {\n\t\tif (this.watched) this.#ops = [[\"r\", this.value]];\n\t\tthis.changed();\n\t}\n}\n"]}

package/dist/next/documents/definition.d.ts

@@ -0,0 +1,84 @@
+import type { Context } from "../../context/index.ts";
+import type { Op } from "../../delta/index.ts";
+import type { JsonValue } from "../../json.ts";
+import type { Schema, Static } from "../contracts/index.ts";
+/** A document root: a JSON object. */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * When a commit reaches the store (Durable's `CommitPersistence`): `immediate`, the default, before the commit
+ * resolves; `deferred` (a persisted run's state change, D8): adopted and published at once, stored with the next
+ * immediate change, the run's outcome, the object's close, or about `withinMs` (default 1,000 ms) later.
+ */
+export type CommitPersistence = {
+    readonly kind: "immediate";
+} | {
+    readonly kind: "deferred";
+    readonly withinMs?: number;
+};
+/** What a persisted document's `checkpointWhen` learns of its stored revisions. */
+export type CheckpointInfo = {
+    /** The deltas stored after its newest base, without the change being decided. */
+    readonly deltasSinceBase: number;
+};
+/** Whether a commit's change of a persisted document is stored as a whole new base (`true`) or as a delta. */
+export type CheckpointWhen<T> = (value: T, ops: readonly Op[], info: CheckpointInfo) => boolean;
+/** What `defineState` takes for any document. */
+type StateOptions<S extends Schema, K extends boolean> = {
+    readonly schema: S;
+    readonly version: number;
+    readonly initial: () => DocumentOf<S>;
+    /** Maps a value of an older version `from` to this version's shape; pure. Required to read older values. */
+    readonly migrate?: (old: JsonObject, from: number) => DocumentOf<S>;
+    readonly keyed?: K;
+};
+/** What a persisted document adds (slice 6a §10): `checkpointWhen` is required. */
+type PersistOptions<S extends Schema> = {
+    /** Stored in the host's store; only in `local` types with empty params (P3). */
+    readonly persist: true;
+    /** Called once per commit per changed document; creations and version changes always store a base. */
+    readonly checkpointWhen: CheckpointWhen<DocumentOf<S>>;
+};
+/**
+ * Declares a document: a singleton per object, or with `keyed: true` many per object, each by a string key; with
+ * `persist: true` stored in the host's store. Its name is a restricted name (lowercase `[a-z0-9@/._~-]`).
+ */
+export declare function defineState<S extends Schema, K extends boolean = false>(name: string, options: StateOptions<S, K> & {
+    readonly persist?: false;
+    readonly checkpointWhen?: never;
+}): StateDefinition<DocumentOf<S>, K, false>;
+export declare function defineState<S extends Schema, K extends boolean = false>(name: string, options: StateOptions<S, K> & PersistOptions<S>): StateDefinition<DocumentOf<S>, K, true>;
+/** The value of a document whose schema is `S`: its static type, which must be a JSON object. */
+type DocumentOf<S extends Schema> = Static<S> extends JsonObject ? Static<S> : never;
+/** A declared document; `T` is its value, `K` whether it is keyed, `P` whether it is persisted. */
+export declare class StateDefinition<T extends JsonObject, K extends boolean, P extends boolean = false> {
+    #private;
+    readonly name: string;
+    readonly schema: Schema;
+    readonly version: number;
+    readonly keyed: boolean;
+    readonly persist: boolean;
+    /**
+     * `hash64` of the schema's normal form (descriptions and titles ignored), computed once: the same version with
+     * another fingerprint is a schema changed without a version bump.
+     */
+    readonly fingerprint: string;
+    /** Type only: whether the definition is keyed. */
+    readonly "~keyed"?: K;
+    /** Type only: whether the definition is persisted. */
+    readonly "~persist"?: P;
+    constructor(name: string, schema: Schema, version: number, initial: () => T, migrate: ((old: JsonObject, from: number) => T) | undefined, keyed: boolean, persist: boolean, checkpointWhen: CheckpointWhen<T> | undefined);
+    /** Whether a persisted document's change is stored as a new base (its `checkpointWhen`); never asked in memory. */
+    checkpointWhen(value: T, ops: readonly Op[], info: CheckpointInfo): boolean;
+    /** A fresh `initial()` value; the first is checked against the schema (counted), later ones are not (R8). */
+    initial(context: Context): T;
+    /**
+     * `old`, a value of version `from`, migrated to this version and checked against the schema once, as it is
+     * produced (R8, counted). Throws without a `migrate` (the access is refused, the data kept) and when the result does
+     * not match.
+     */
+    migrate(old: JsonObject, from: number, context: Context): T;
+}
+export {};
+//# sourceMappingURL=definition.d.ts.map

package/dist/next/documents/definition.d.ts.map

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