@earendil-works/chord 1.5.0 → 1.5.1

package/dist/data/principal.js

@@ -0,0 +1,49 @@
+// Principals: the app's caller identities, and the keys Chord derives from them.
+import { chordMetrics } from "../telemetry.js";
+/**
+ * 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) {
+    chordMetrics(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(",")}}`;
+}
+/**
+ * Whether `principal` is `other`: the same default key (canonical JSON), each computed once per principal object; no
+ * principal (`undefined`) is none.
+ */
+export function samePrincipal(principal, other, context) {
+    return principal !== undefined && principalKey(principal, context) === principalKey(other, context);
+}
+//# sourceMappingURL=principal.js.map

package/dist/data/principal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.js","sourceRoot":"","sources":["../../src/data/principal.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAIjF,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAQ/C;;;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,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3E,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;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,SAAgC,EAAE,KAAgB,EAAE,OAAgB;IACjG,OAAO,SAAS,KAAK,SAAS,IAAI,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACrG,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\";\nimport { chordMetrics } from \"../telemetry.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\tchordMetrics(context.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\n/**\n * Whether `principal` is `other`: the same default key (canonical JSON), each computed once per principal object; no\n * principal (`undefined`) is none.\n */\nexport function samePrincipal(principal: Principal | undefined, other: Principal, context: Context): boolean {\n\treturn principal !== undefined && principalKey(principal, context) === principalKey(other, context);\n}\n"]}

package/dist/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/data/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/data/validator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,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/data/validator.js

@@ -0,0 +1,35 @@
+// 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 { chordMetrics } from "../telemetry.js";
+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) {
+        chordMetrics(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) {
+    chordMetrics(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) {
+    chordMetrics(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/data/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/data/validator.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAE3G,OAAO,EAAE,OAAO,EAAmC,MAAM,2BAA2B,CAAC;AAErF,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,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,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAClF,+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,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjF,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,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3E,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 { chordMetrics } from \"../telemetry.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\tchordMetrics(context.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\tchordMetrics(context.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\tchordMetrics(context.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/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/documents/address-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-source.d.ts","sourceRoot":"","sources":["../../src/documents/address-source.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAM,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACtD,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/documents/address-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-source.js","sourceRoot":"","sources":["../../src/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/documents/definition.d.ts

@@ -0,0 +1,84 @@
+import type { Context } from "../context/index.ts";
+import type { Schema, Static } from "../contracts/index.ts";
+import type { Op } from "../delta/index.ts";
+import type { JsonValue } from "../json.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/documents/definition.d.ts.map

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

package/dist/documents/definition.js

@@ -0,0 +1,74 @@
+// Document definitions: `defineState(name, ...)`, its fingerprint, the one check of a definition's `initial()` (R8),
+// the checked `migrate` of an older value and, for a persisted document, its checkpoint rule (slice 6a §10).
+import { checkName, fingerprintOf } from "../contracts/internal.js";
+import { snapshotSchema } from "../contracts/snapshot.js";
+import { validatorFor } from "../data/internal.js";
+import { chordMetrics } from "../telemetry.js";
+export function defineState(name, options) {
+    checkName(name, "A state name");
+    const { schema, version, initial, migrate, keyed, persist, checkpointWhen } = options;
+    return new StateDefinition(name, schema, version, initial, migrate, keyed ?? false, persist ?? false, checkpointWhen);
+}
+const NEVER = () => false;
+/** A declared document; `T` is its value, `K` whether it is keyed, `P` whether it is persisted. */
+export class StateDefinition {
+    name;
+    schema;
+    version;
+    keyed;
+    persist;
+    /**
+     * `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.
+     */
+    fingerprint;
+    #initial;
+    #migrate;
+    /** Method-typed so that a definition of a narrower `T` still is a `StateDefinition<JsonObject, ...>`. */
+    #checkpointWhen;
+    #checked = false;
+    constructor(name, schema, version, initial, migrate, keyed, persist, checkpointWhen) {
+        this.name = name;
+        this.schema = schema;
+        this.version = version;
+        this.#initial = initial;
+        this.#migrate = migrate;
+        this.keyed = keyed;
+        this.persist = persist;
+        this.#checkpointWhen = checkpointWhen ?? NEVER;
+        this.fingerprint = fingerprintOf(snapshotSchema(schema, name).normal);
+    }
+    /** Whether a persisted document's change is stored as a new base (its `checkpointWhen`); never asked in memory. */
+    checkpointWhen(value, ops, info) {
+        return this.#checkpointWhen(value, ops, info);
+    }
+    /** A fresh `initial()` value; the first is checked against the schema (counted), later ones are not (R8). */
+    initial(context) {
+        const value = this.#initial();
+        if (this.#checked)
+            return value;
+        this.#check(value, "initial()", context);
+        this.#checked = true;
+        return value;
+    }
+    /**
+     * `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, from, context) {
+        if (this.#migrate === undefined) {
+            throw new Error(`${this.name}: no migrate from version ${from} to ${this.version}`);
+        }
+        const value = this.#migrate(old, from);
+        this.#check(value, `migrate() from version ${from}`, context);
+        return value;
+    }
+    #check(value, what, context) {
+        chordMetrics(context.telemetry.metrics).counter("chord.data.validations").add(1);
+        if (!validatorFor(this, context).check(value)) {
+            throw new Error(`${this.name}: ${what} does not match the schema`);
+        }
+    }
+}
+//# sourceMappingURL=definition.js.map

package/dist/documents/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/documents/definition.ts"],"names":[],"mappings":"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","sourcesContent":["// Document definitions: `defineState(name, ...)`, its fingerprint, the one check of a definition's `initial()` (R8),\n// the checked `migrate` of an older value and, for a persisted document, its checkpoint rule (slice 6a §10).\n\nimport type { Context } from \"../context/index.ts\";\nimport type { Schema, Static } from \"../contracts/index.ts\";\nimport { checkName, fingerprintOf } from \"../contracts/internal.ts\";\nimport { snapshotSchema } from \"../contracts/snapshot.ts\";\nimport { validatorFor } from \"../data/internal.ts\";\nimport type { Op } from \"../delta/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport { chordMetrics } from \"../telemetry.ts\";\n\n/** A document root: a JSON object. */\nexport type JsonObject = { [key: string]: JsonValue };\n\n/**\n * When a commit reaches the store (Durable's `CommitPersistence`): `immediate`, the default, before the commit\n * resolves; `deferred` (a persisted run's state change, D8): adopted and published at once, stored with the next\n * immediate change, the run's outcome, the object's close, or about `withinMs` (default 1,000 ms) later.\n */\nexport type CommitPersistence =\n\t| { readonly kind: \"immediate\" }\n\t| { readonly kind: \"deferred\"; readonly withinMs?: number };\n\n/** What a persisted document's `checkpointWhen` learns of its stored revisions. */\nexport type CheckpointInfo = {\n\t/** The deltas stored after its newest base, without the change being decided. */\n\treadonly deltasSinceBase: number;\n};\n\n/** Whether a commit's change of a persisted document is stored as a whole new base (`true`) or as a delta. */\nexport type CheckpointWhen<T> = (value: T, ops: readonly Op[], info: CheckpointInfo) => boolean;\n\n/** What `defineState` takes for any document. */\ntype StateOptions<S extends Schema, K extends boolean> = {\n\treadonly schema: S;\n\treadonly version: number;\n\treadonly initial: () => DocumentOf<S>;\n\t/** Maps a value of an older version `from` to this version's shape; pure. Required to read older values. */\n\treadonly migrate?: (old: JsonObject, from: number) => DocumentOf<S>;\n\treadonly keyed?: K;\n};\n\n/** What a persisted document adds (slice 6a §10): `checkpointWhen` is required. */\ntype PersistOptions<S extends Schema> = {\n\t/** Stored in the host's store; only in `local` types with empty params (P3). */\n\treadonly persist: true;\n\t/** Called once per commit per changed document; creations and version changes always store a base. */\n\treadonly checkpointWhen: CheckpointWhen<DocumentOf<S>>;\n};\n\n/**\n * Declares a document: a singleton per object, or with `keyed: true` many per object, each by a string key; with\n * `persist: true` stored in the host's store. Its name is a restricted name (lowercase `[a-z0-9@/._~-]`).\n */\nexport function defineState<S extends Schema, K extends boolean = false>(\n\tname: string,\n\toptions: StateOptions<S, K> & { readonly persist?: false; readonly checkpointWhen?: never },\n): StateDefinition<DocumentOf<S>, K, false>;\nexport function defineState<S extends Schema, K extends boolean = false>(\n\tname: string,\n\toptions: StateOptions<S, K> & PersistOptions<S>,\n): StateDefinition<DocumentOf<S>, K, true>;\nexport function defineState<S extends Schema, K extends boolean>(\n\tname: string,\n\toptions: StateOptions<S, K> & {\n\t\treadonly persist?: boolean;\n\t\treadonly checkpointWhen?: CheckpointWhen<DocumentOf<S>>;\n\t},\n): StateDefinition<DocumentOf<S>, K, boolean> {\n\tcheckName(name, \"A state name\");\n\tconst { schema, version, initial, migrate, keyed, persist, checkpointWhen } = options;\n\treturn new StateDefinition(\n\t\tname,\n\t\tschema,\n\t\tversion,\n\t\tinitial,\n\t\tmigrate,\n\t\tkeyed ?? false,\n\t\tpersist ?? false,\n\t\tcheckpointWhen,\n\t);\n}\n\n/** The value of a document whose schema is `S`: its static type, which must be a JSON object. */\ntype DocumentOf<S extends Schema> = Static<S> extends JsonObject ? Static<S> : never;\n\nconst NEVER: CheckpointWhen<JsonObject> = () => false;\n\n/** A declared document; `T` is its value, `K` whether it is keyed, `P` whether it is persisted. */\nexport class StateDefinition<T extends JsonObject, K extends boolean, P extends boolean = false> {\n\treadonly name: string;\n\treadonly schema: Schema;\n\treadonly version: number;\n\treadonly keyed: boolean;\n\treadonly persist: boolean;\n\t/**\n\t * `hash64` of the schema's normal form (descriptions and titles ignored), computed once: the same version with\n\t * another fingerprint is a schema changed without a version bump.\n\t */\n\treadonly fingerprint: string;\n\t/** Type only: whether the definition is keyed. */\n\tdeclare readonly \"~keyed\"?: K;\n\t/** Type only: whether the definition is persisted. */\n\tdeclare readonly \"~persist\"?: P;\n\treadonly #initial: () => T;\n\treadonly #migrate: ((old: JsonObject, from: number) => T) | undefined;\n\t/** Method-typed so that a definition of a narrower `T` still is a `StateDefinition<JsonObject, ...>`. */\n\treadonly #checkpointWhen: { rule(value: T, ops: readonly Op[], info: CheckpointInfo): boolean }[\"rule\"];\n\t#checked = false;\n\n\tconstructor(\n\t\tname: string,\n\t\tschema: Schema,\n\t\tversion: number,\n\t\tinitial: () => T,\n\t\tmigrate: ((old: JsonObject, from: number) => T) | undefined,\n\t\tkeyed: boolean,\n\t\tpersist: boolean,\n\t\tcheckpointWhen: CheckpointWhen<T> | undefined,\n\t) {\n\t\tthis.name = name;\n\t\tthis.schema = schema;\n\t\tthis.version = version;\n\t\tthis.#initial = initial;\n\t\tthis.#migrate = migrate;\n\t\tthis.keyed = keyed;\n\t\tthis.persist = persist;\n\t\tthis.#checkpointWhen = checkpointWhen ?? NEVER;\n\t\tthis.fingerprint = fingerprintOf(snapshotSchema(schema, name).normal);\n\t}\n\n\t/** Whether a persisted document's change is stored as a new base (its `checkpointWhen`); never asked in memory. */\n\tcheckpointWhen(value: T, ops: readonly Op[], info: CheckpointInfo): boolean {\n\t\treturn this.#checkpointWhen(value, ops, info);\n\t}\n\n\t/** A fresh `initial()` value; the first is checked against the schema (counted), later ones are not (R8). */\n\tinitial(context: Context): T {\n\t\tconst value = this.#initial();\n\t\tif (this.#checked) return value;\n\t\tthis.#check(value, \"initial()\", context);\n\t\tthis.#checked = true;\n\t\treturn value;\n\t}\n\n\t/**\n\t * `old`, a value of version `from`, migrated to this version and checked against the schema once, as it is\n\t * produced (R8, counted). Throws without a `migrate` (the access is refused, the data kept) and when the result does\n\t * not match.\n\t */\n\tmigrate(old: JsonObject, from: number, context: Context): T {\n\t\tif (this.#migrate === undefined) {\n\t\t\tthrow new Error(`${this.name}: no migrate from version ${from} to ${this.version}`);\n\t\t}\n\t\tconst value = this.#migrate(old, from);\n\t\tthis.#check(value, `migrate() from version ${from}`, context);\n\t\treturn value;\n\t}\n\n\t#check(value: T, what: string, context: Context): void {\n\t\tchordMetrics(context.telemetry.metrics).counter(\"chord.data.validations\").add(1);\n\t\tif (!validatorFor(this, context).check(value)) {\n\t\t\tthrow new Error(`${this.name}: ${what} does not match the schema`);\n\t\t}\n\t}\n}\n"]}

package/dist/documents/documents.d.ts

@@ -0,0 +1,126 @@
+import type { TelemetryContext } from "@earendil-works/pi-telemetry";
+import type { Context } from "../context/index.ts";
+import { ChordError } from "../data/index.ts";
+import type { Batch } from "../state/internal.ts";
+import type { ChordStore } from "../store/store.ts";
+import type { CommitPersistence, JsonObject, StateDefinition } from "./definition.ts";
+import { SealToken } from "./fence.ts";
+import { type HandleOf, type KeyDeclarer } from "./handles.ts";
+import { Line } from "./line.ts";
+import { Residency } from "./residency.ts";
+import { type AnyDefinition } from "./slot.ts";
+import { Transaction } from "./transaction.ts";
+/**
+ * A transaction (a document change or retirement, `self.tx`, a job start) that did not commit because the context it
+ * was started with ended first: a root whose `fn` settled, a handler or routine whose object ended, a caller that
+ * cancelled. `error` is that context's abort reason, naming the scope that ended (decision "Mistakes that wait are
+ * reported at once" (e)).
+ */
+export type TransactionCancelled = {
+    readonly kind: "transaction_cancelled";
+    readonly object: string;
+    readonly error: unknown;
+};
+/**
+ * Who owns an object's documents: the object's name, batch and context, its store address, its live failure, and where
+ * a cancelled transaction is reported.
+ */
+export type DocumentsOwner = {
+    /** The owner's name in errors. */
+    readonly label: string;
+    readonly batch: Batch;
+    /** The object's context: shared cold loads run under it (rule 11). */
+    readonly context: Context;
+    /** The host's store and the object's owner name in it (its type, R2), when it has one. */
+    readonly store: {
+        readonly store: ChordStore;
+        readonly owner: string;
+    } | undefined;
+    /** A document the code cannot read fails the live object `broken` (slice 6a §1.4); ignored when it is not live. */
+    fail(error: ChordError): void;
+    /** Reports a transaction its context's end cancelled (the host's `onError`). */
+    report(error: TransactionCancelled): void;
+    /** The host's telemetry adapter: commit durations go to its metrics. */
+    readonly telemetry: TelemetryContext;
+};
+/**
+ * The documents of one object, from its first activation to its end: one slot per declared name, kept across
+ * attempts, and the line. Each attempt declares its handles under its own seal token; the object's own transactions
+ * (job outcomes) run under `own`, sealed only by the object's end.
+ */
+export declare class Documents {
+    #private;
+    /** The owner's name in errors. */
+    readonly label: string;
+    readonly batch: Batch;
+    /** The object's context. */
+    readonly context: Context;
+    readonly line: Line;
+    /**
+     * The idle persisted keyed documents and their eviction. A sweep's only rejection is `onLine`'s `released` once
+     * the object ended (a sweep itself drops trackers in memory and does not throw): nothing to report.
+     */
+    readonly residency: Residency;
+    /** The token of the object's own transactions: sealed with the object (`seal`). */
+    readonly own: SealToken;
+    constructor(owner: DocumentsOwner);
+    /**
+     * A handle to `definition`'s slot for an attempt sealed by `token`, whose `at(key)` pins `declarer` takes: the slot
+     * made by the first declaration of its name, checked against the values for later ones (`SlotDefinition.check`).
+     * "Declared twice" is the attempt's check.
+     */
+    declare<D extends StateDefinition<JsonObject, boolean, boolean>>(definition: D, token: SealToken, declarer: KeyDeclarer): HandleOf<D>;
+    /**
+     * Checks a declaration of `definition` as `declare` would, changing nothing (a reload's staging: a recording factory
+     * declares against the documents the object has).
+     */
+    check(definition: AnyDefinition): void;
+    /**
+     * Takes an attempt's declarations once its factory returned: its `at(key)` pins replace the previous factory's, the
+     * slots it no longer declares are dropped (their watches end; persisted ones load again when declared again), every
+     * declared one hydrated (`initial()`, migrations; a throw fails the activation).
+     */
+    hydrate(declared: ReadonlyMap<string, AnyDefinition>, pins: readonly (() => void)[], context: Context): void;
+    /**
+     * Loads, in one line job, every persisted singleton not loaded yet and every pinned key not loaded since it was
+     * pinned (an attempt's activation, before it goes live, rule 6); `undefined` when nothing is persisted. A failure
+     * fails the activation.
+     */
+    load(context: Context): Promise<void> | undefined;
+    /**
+     * Runs `job` on the line (a cold load, a page of keys, an eviction sweep); refused `released` once the object is
+     * ending or `token` (the handle's that asks, when the job is one handle's) is sealed, a job queued before either
+     * included (anything taking the line after the seal is refused, rule 4).
+     */
+    onLine<T>(job: () => Promise<T>, token?: SealToken): Promise<T>;
+    /**
+     * Runs `fn` as one transaction on the line under `token` and commits what it drafted (§9): a throw, an abort of
+     * `context`, the token's seal or the object's end discards everything; one that did not commit while `context` was
+     * aborted is also reported (`transaction_cancelled`): an empty `catch` cannot hide a change that never happened.
+     * `persistence` defers storing a run state's change (D8).
+     */
+    tx<R>(fn: (tx: Transaction) => R | Promise<R>, token: SealToken, context: Context, persistence?: CommitPersistence): Promise<R>;
+    /**
+     * Seals `token` (the seal fence): its transactions are refused from now on, and the one holding the line is
+     * discarded and the line released.
+     */
+    fence(token: SealToken): void;
+    /** Throws `released` once the object ended. */
+    assertLive(): void;
+    /** Throws `released` once `token` is sealed or the object is ending: no new work takes the line. */
+    assertAdmitted(token: SealToken): void;
+    /** The live object fails `broken` with `error` (a document the code cannot read); ignored when it is not live. */
+    fail(error: ChordError): void;
+    /** The object is ending: every transaction is refused, the one holding the line discarded; documents stay readable. */
+    seal(): void;
+    /**
+     * Resolves once the line is free. After `seal` only an admitted step can hold it (every other holder was cut):
+     * the object's teardown waits here, so the step adopts into documents that still exist (slice 6a §1.3).
+     */
+    settled(): Promise<void>;
+    /** Drops every document and pin; watches end `ended`, and every later use throws `released`. */
+    end(): void;
+    /** The `released` error of this object's documents. */
+    released(): ChordError;
+}
+//# sourceMappingURL=documents.d.ts.map

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

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