@earendil-works/chord 1.5.0 → 1.5.1

package/dist/store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,KAAK,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3D,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EACN,GAAG,EACH,GAAG,EACH,KAAK,SAAS,EACd,KAAK,SAAS,EACd,QAAQ,EACR,MAAM,EACN,KAAK,UAAU,EACf,EAAE,EACF,EAAE,EACF,GAAG,EACH,OAAO,EACP,MAAM,EACN,EAAE,EACF,GAAG,EACH,GAAG,EACH,GAAG,EACH,EAAE,EACF,GAAG,EACH,EAAE,EACF,MAAM,EACN,aAAa,EACb,KAAK,KAAK,EACV,GAAG,EACH,IAAI,GACJ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC9F,OAAO,EACN,KAAK,WAAW,EAChB,WAAW,EACX,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,eAAe,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,0EAA0E;AAG1E,OAAO,EAAgB,aAAa,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EACN,GAAG,EACH,GAAG,EAGH,QAAQ,EACR,MAAM,EAEN,EAAE,EACF,EAAE,EACF,GAAG,EACH,OAAO,EACP,MAAM,EACN,EAAE,EACF,GAAG,EACH,GAAG,EACH,GAAG,EACH,EAAE,EACF,GAAG,EACH,EAAE,EACF,MAAM,EACN,aAAa,EAEb,GAAG,EACH,IAAI,GACJ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAiD,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAA+B,KAAK,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,SAAS,EAAiC,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,WAAW,EAAuD,MAAM,YAAY,CAAC;AAC9F,OAAO,EAEN,WAAW,GAIX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC","sourcesContent":["// The store for apps: opening it over a backend, tables with their queries, writes and migrations, export and\n// import of archives (with their JSONL encoding), the outbox, text order.\n\nexport type { ArchiveManifest, ArchivePart } from \"./archive.ts\";\nexport { type Backend, sqliteBackend } from \"./backend.ts\";\nexport type { Columns, PutRowOf, RowOf } from \"./columns.ts\";\nexport {\n\tadd,\n\tand,\n\ttype ColumnRef,\n\ttype Condition,\n\tcoalesce,\n\tconcat,\n\ttype Expression,\n\teq,\n\tgt,\n\tgte,\n\tinArray,\n\tisNull,\n\tlt,\n\tlte,\n\tmax,\n\tmin,\n\tne,\n\tnot,\n\tor,\n\tprefix,\n\treplacePrefix,\n\ttype SetOf,\n\tsub,\n\twhen,\n} from \"./expression.ts\";\nexport { importStore } from \"./import.ts\";\nexport { type JsonColumnOptions, type JsonColumnSchema, json } from \"./json-column.ts\";\nexport { decodeJsonl, encodeJsonl } from \"./jsonl.ts\";\nexport type { Outbox, OutboxCommit } from \"./outbox.ts\";\nexport { type ColumnRefs, type Query, query } from \"./query.ts\";\nexport { openStore, type Store, type StoreOptions } from \"./store.ts\";\nexport { defineTable, type KeyOf, type TableDefinition, type TableOptions } from \"./table.ts\";\nexport {\n\ttype AddedColumn,\n\tevolveTable,\n\ttype PatchOf,\n\ttype TableEditor,\n\ttype TableTailEditor,\n} from \"./table-evolve.ts\";\nexport type { Page, PageOptions, Table, TableOf } from \"./table-handle.ts\";\nexport { compareText } from \"./text.ts\";\nexport type { StoreWrite } from \"./writes.ts\";\n"]}

package/dist/store/json-column.d.ts

@@ -0,0 +1,33 @@
+import type { JsonSchema } from "@earendil-works/pi-schema";
+import type { Context } from "../context/index.ts";
+import type { Schema, Static } from "../contracts/index.ts";
+import type { JsonValue } from "../json.ts";
+/** What `json(...)` takes besides the schema. */
+export type JsonColumnOptions<T> = {
+    /** The version of the cells' shape; a cell stores the version it was written at. */
+    readonly version: number;
+    /** Maps a cell of an older version `from` to this version's shape; pure. Without it older cells are refused. */
+    readonly migrate?: (old: JsonValue, from: number) => T;
+};
+/** A `json(...)` column as `columns` takes it: a schema of the cells' type carrying the column. */
+export interface JsonColumnSchema<T> extends Schema<T> {
+    readonly json: JsonColumn;
+}
+/** A column holding one JSON value of `schema` per row, at `version`; wrap it in `opt(...)` to make it nullable. */
+export declare function json<S extends Schema>(schema: S, options: JsonColumnOptions<Static<S>>): JsonColumnSchema<Static<S>>;
+/** A `json(...)` column's definition: its schema snapshot, version and fingerprint, and the read of a stored cell. */
+export declare class JsonColumn {
+    #private;
+    readonly schema: JsonSchema;
+    readonly version: number;
+    /** The fingerprint of the schema's normal form, recorded with the table: the same version with another is `broken`. */
+    readonly fingerprint: string;
+    constructor(schema: Schema, version: number, migrate: ((old: JsonValue, from: number) => unknown) | undefined);
+    /**
+     * The value of a stored cell written at `version`: parsed; an older one migrated and checked once (R8, counted). A
+     * newer version, a missing or throwing `migrate` and an invalid result throw `unavailable` (`what` names the cell);
+     * the caller fails the owner (slice 6a §1.4), the data stays.
+     */
+    read(text: string, version: number, what: string, context: Context): unknown;
+}
+//# sourceMappingURL=json-column.d.ts.map

package/dist/store/json-column.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-column.d.ts","sourceRoot":"","sources":["../../src/store/json-column.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAK5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,iDAAiD;AACjD,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IAClC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gHAAgH;IAChH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC,CAAC;CACvD,CAAC;AAEF,mGAAmG;AACnG,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,MAAM,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC1B;AAED,oHAAoH;AACpH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAGpH;AAED,sHAAsH;AACtH,qBAAa,UAAU;;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uHAAuH;IACvH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAG7B,YAAY,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,EAS5G;IAED;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAgB3E;CACD"}

package/dist/store/json-column.js

@@ -0,0 +1,62 @@
+// `json(schema, { version, migrate? })` table columns (decision "The `json(...)` column helper", W11): one JSON `TEXT`
+// cell with its own version, typed when read, migrated on access (the result checked once, R8), never walked on write
+// (R9).
+import { fingerprintOf } from "../contracts/internal.js";
+import { snapshotSchema } from "../contracts/snapshot.js";
+import { ChordError } from "../data/index.js";
+import { validatorFor } from "../data/internal.js";
+import { chordMetrics } from "../telemetry.js";
+/** A column holding one JSON value of `schema` per row, at `version`; wrap it in `opt(...)` to make it nullable. */
+export function json(schema, options) {
+    // Typed as the cells' schema, so `opt(...)` and `Static` take it; the table reads its `json` field.
+    return { json: new JsonColumn(schema, options.version, options.migrate) };
+}
+/** A `json(...)` column's definition: its schema snapshot, version and fingerprint, and the read of a stored cell. */
+export class JsonColumn {
+    schema;
+    version;
+    /** The fingerprint of the schema's normal form, recorded with the table: the same version with another is `broken`. */
+    fingerprint;
+    #migrate;
+    constructor(schema, version, migrate) {
+        // Declaration policy: JavaScript callers reach this check.
+        if (!Number.isSafeInteger(version) || version < 1)
+            throw new Error(`json(...): version ${version} is not a positive integer`);
+        const snapshot = snapshotSchema(schema, "json(...)");
+        this.schema = snapshot.schema;
+        this.version = version;
+        this.fingerprint = fingerprintOf(snapshot.normal);
+        this.#migrate = migrate;
+    }
+    /**
+     * The value of a stored cell written at `version`: parsed; an older one migrated and checked once (R8, counted). A
+     * newer version, a missing or throwing `migrate` and an invalid result throw `unavailable` (`what` names the cell);
+     * the caller fails the owner (slice 6a §1.4), the data stays.
+     */
+    read(text, version, what, context) {
+        const value = JSON.parse(text);
+        if (version === this.version)
+            return value;
+        if (version > this.version)
+            throw refused(`${what}: stored at version ${version}, newer than ${this.version}`);
+        if (this.#migrate === undefined)
+            throw refused(`${what}: no migrate from version ${version} to ${this.version}`);
+        let migrated;
+        try {
+            migrated = this.#migrate(value, version);
+        }
+        catch (error) {
+            throw refused(`${what}: migrate from version ${version} threw`, error);
+        }
+        chordMetrics(context.telemetry.metrics).counter("chord.data.validations").add(1);
+        if (!validatorFor(this, context).check(migrated)) {
+            throw refused(`${what}: migrate from version ${version} does not match the schema`);
+        }
+        return migrated;
+    }
+}
+/** The error of a cell the code cannot read: the owner fails `broken` with it. */
+function refused(message, cause) {
+    return new ChordError({ code: "unavailable", message }, cause === undefined ? undefined : { cause });
+}
+//# sourceMappingURL=json-column.js.map

package/dist/store/json-column.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-column.js","sourceRoot":"","sources":["../../src/store/json-column.ts"],"names":[],"mappings":"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","sourcesContent":["// `json(schema, { version, migrate? })` table columns (decision \"The `json(...)` column helper\", W11): one JSON `TEXT`\n// cell with its own version, typed when read, migrated on access (the result checked once, R8), never walked on write\n// (R9).\n\nimport type { JsonSchema } from \"@earendil-works/pi-schema\";\nimport type { Context } from \"../context/index.ts\";\nimport type { Schema, Static } from \"../contracts/index.ts\";\nimport { fingerprintOf } from \"../contracts/internal.ts\";\nimport { snapshotSchema } from \"../contracts/snapshot.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport { validatorFor } from \"../data/internal.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport { chordMetrics } from \"../telemetry.ts\";\n\n/** What `json(...)` takes besides the schema. */\nexport type JsonColumnOptions<T> = {\n\t/** The version of the cells' shape; a cell stores the version it was written at. */\n\treadonly version: number;\n\t/** Maps a cell of an older version `from` to this version's shape; pure. Without it older cells are refused. */\n\treadonly migrate?: (old: JsonValue, from: number) => T;\n};\n\n/** A `json(...)` column as `columns` takes it: a schema of the cells' type carrying the column. */\nexport interface JsonColumnSchema<T> extends Schema<T> {\n\treadonly json: JsonColumn;\n}\n\n/** A column holding one JSON value of `schema` per row, at `version`; wrap it in `opt(...)` to make it nullable. */\nexport function json<S extends Schema>(schema: S, options: JsonColumnOptions<Static<S>>): JsonColumnSchema<Static<S>> {\n\t// Typed as the cells' schema, so `opt(...)` and `Static` take it; the table reads its `json` field.\n\treturn { json: new JsonColumn(schema, options.version, options.migrate) };\n}\n\n/** A `json(...)` column's definition: its schema snapshot, version and fingerprint, and the read of a stored cell. */\nexport class JsonColumn {\n\treadonly schema: JsonSchema;\n\treadonly version: number;\n\t/** The fingerprint of the schema's normal form, recorded with the table: the same version with another is `broken`. */\n\treadonly fingerprint: string;\n\treadonly #migrate: ((old: JsonValue, from: number) => unknown) | undefined;\n\n\tconstructor(schema: Schema, version: number, migrate: ((old: JsonValue, from: number) => unknown) | undefined) {\n\t\t// Declaration policy: JavaScript callers reach this check.\n\t\tif (!Number.isSafeInteger(version) || version < 1)\n\t\t\tthrow new Error(`json(...): version ${version} is not a positive integer`);\n\t\tconst snapshot = snapshotSchema(schema, \"json(...)\");\n\t\tthis.schema = snapshot.schema;\n\t\tthis.version = version;\n\t\tthis.fingerprint = fingerprintOf(snapshot.normal);\n\t\tthis.#migrate = migrate;\n\t}\n\n\t/**\n\t * The value of a stored cell written at `version`: parsed; an older one migrated and checked once (R8, counted). A\n\t * newer version, a missing or throwing `migrate` and an invalid result throw `unavailable` (`what` names the cell);\n\t * the caller fails the owner (slice 6a §1.4), the data stays.\n\t */\n\tread(text: string, version: number, what: string, context: Context): unknown {\n\t\tconst value = JSON.parse(text) as JsonValue;\n\t\tif (version === this.version) return value;\n\t\tif (version > this.version) throw refused(`${what}: stored at version ${version}, newer than ${this.version}`);\n\t\tif (this.#migrate === undefined) throw refused(`${what}: no migrate from version ${version} to ${this.version}`);\n\t\tlet migrated: unknown;\n\t\ttry {\n\t\t\tmigrated = this.#migrate(value, version);\n\t\t} catch (error) {\n\t\t\tthrow refused(`${what}: migrate from version ${version} threw`, error);\n\t\t}\n\t\tchordMetrics(context.telemetry.metrics).counter(\"chord.data.validations\").add(1);\n\t\tif (!validatorFor(this, context).check(migrated)) {\n\t\t\tthrow refused(`${what}: migrate from version ${version} does not match the schema`);\n\t\t}\n\t\treturn migrated;\n\t}\n}\n\n/** The error of a cell the code cannot read: the owner fails `broken` with it. */\nfunction refused(message: string, cause?: unknown): ChordError {\n\treturn new ChordError({ code: \"unavailable\", message }, cause === undefined ? undefined : { cause });\n}\n"]}

package/dist/store/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../../src/store/jsonl.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,wDAAwD;AACxD,wBAAuB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAW/F;AAED;;;GAGG;AACH,wBAAuB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAgC3F"}

package/dist/store/jsonl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.js","sourceRoot":"","sources":["../../src/store/jsonl.ts"],"names":[],"mappings":"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","sourcesContent":["// Plain JSONL for archives (slice 6a §13): one part per line, UTF-8. The store yields and takes parts; this is the\n// encoding it ships (others, compressed ones, come later without touching the applier).\n\nimport { invalid } from \"../data/internal.ts\";\nimport type { ArchivePart } from \"./archive.ts\";\n\n/** The bytes a chunk of encoded lines collects before it is yielded. */\nconst CHUNK = 64 * 1024;\n\n/** `parts` as JSONL bytes, in chunks of whole lines. */\nexport async function* encodeJsonl(parts: AsyncIterable<ArchivePart>): AsyncIterable<Uint8Array> {\n\tconst encoder = new TextEncoder();\n\tlet lines = \"\";\n\tfor await (const part of parts) {\n\t\tlines += `${JSON.stringify(part)}\\n`;\n\t\tif (lines.length >= CHUNK) {\n\t\t\tyield encoder.encode(lines);\n\t\t\tlines = \"\";\n\t\t}\n\t}\n\tif (lines.length > 0) yield encoder.encode(lines);\n}\n\n/**\n * The values of JSONL `bytes`, one per nonempty line, for `importStore` to check (a trust boundary: bytes that are\n * no UTF-8 and a line that is no JSON are `invalid/args`).\n */\nexport async function* decodeJsonl(bytes: AsyncIterable<Uint8Array>): AsyncIterable<unknown> {\n\tconst decoder = new TextDecoder(\"utf-8\", { fatal: true });\n\tlet rest = \"\";\n\tlet line = 0;\n\tconst parse = (text: string): unknown => {\n\t\ttry {\n\t\t\treturn JSON.parse(text);\n\t\t} catch {\n\t\t\tthrow invalid(\"args\", `jsonl: line ${line} is not JSON`);\n\t\t}\n\t};\n\tconst decode = (chunk?: Uint8Array): string => {\n\t\ttry {\n\t\t\treturn chunk === undefined ? decoder.decode() : decoder.decode(chunk, { stream: true });\n\t\t} catch {\n\t\t\tthrow invalid(\"args\", `jsonl: line ${line + 1} is not UTF-8`);\n\t\t}\n\t};\n\tfor await (const chunk of bytes) {\n\t\trest += decode(chunk);\n\t\tlet start = 0;\n\t\tfor (let end = rest.indexOf(\"\\n\"); end >= 0; end = rest.indexOf(\"\\n\", start)) {\n\t\t\tconst text = rest.slice(start, end);\n\t\t\tstart = end + 1;\n\t\t\tline++;\n\t\t\tif (text.trim().length > 0) yield parse(text);\n\t\t}\n\t\trest = rest.slice(start);\n\t}\n\trest += decode();\n\tline++;\n\tif (rest.trim().length > 0) yield parse(rest);\n}\n"]}

package/dist/store/live-query.d.ts

@@ -0,0 +1,108 @@
+import type { Context } from "../context/index.ts";
+import type { JsonValue } from "../json.ts";
+import type { SqliteValue } from "../sqlite/index.ts";
+import { type Batch, Source, type WatchStart } from "../state/internal.ts";
+import type { Query } from "./query.ts";
+import type { StagedWrite, Step } from "./step.ts";
+import type { TableDefinition } from "./table.ts";
+import type { TableHandle } from "./table-handle.ts";
+/** Who a live query belongs to: its object, and where its failures after activation are reported (`query_failed`). */
+export type QueryOwner = {
+    readonly label: string;
+    report(error: unknown): void;
+};
+/**
+ * The rows of one run: in order, and by key with the stored row each was decoded from, which the next run compares
+ * against to keep an unchanged row the same object.
+ */
+type Rows = {
+    readonly value: JsonValue[];
+    readonly byKey: ReadonlyMap<unknown, Decoded>;
+};
+/** A row as a run decoded it, with the stored row it came from. */
+type Decoded = {
+    readonly stored: StoredRow;
+    readonly row: JsonValue;
+};
+/** One run of a live query in a commit step: its rows, or why it could not read them. */
+type QueryRun = {
+    readonly kind: "rows";
+    readonly rows: Rows;
+} | {
+    readonly kind: "failed";
+    readonly error: unknown;
+};
+/** A stored row as the backend returns it. */
+type StoredRow = {
+    readonly [column: string]: SqliteValue;
+};
+/**
+ * Refuses what the types cannot (plugin code is bundled without type checks; declaration policy): a query of another
+ * table than `table`, and a `limit` that is no positive integer (a live query must be bounded: one run per commit
+ * that writes its table reads at most `limit` rows).
+ */
+export declare function checkLiveQuery(table: TableDefinition, q: Query, limit: unknown, label: string): void;
+/** The live queries of one object by table (its SQL name), across its attempts: what its commits re-run. */
+export declare class LiveQueries {
+    #private;
+    /** Adds `query` (its attempt declared it): re-run by every commit writing its table from now on. */
+    add(query: LiveQuery): void;
+    /** Removes `query` (its attempt ended). */
+    delete(query: LiveQuery): void;
+    /** The live queries over `table`, if any. */
+    on(table: string): ReadonlySet<LiveQuery> | undefined;
+}
+/**
+ * The re-run of the live queries over the tables a transaction writes (`handles`), `undefined` when none has one (the
+ * common case: a map lookup per written table, nothing more). `context` is the transaction's: the runs count through it.
+ */
+export declare function refreshOf(handles: Iterable<TableHandle>, context: Context): QueryRefresh | undefined;
+/**
+ * The re-run of live queries in one commit: `write` reads them in the commit step after the commit's own writes (the
+ * last write of the last phase), and `adopt` publishes their rows in the commit's batch; a refused step adopts nothing.
+ * A transaction stages it as its own change (`Staged`).
+ */
+export declare class QueryRefresh {
+    #private;
+    /** The staged write that reads the queries; it writes nothing and records nothing in the outbox. */
+    readonly write: StagedWrite;
+    constructor(queries: readonly LiveQuery[], context: Context);
+    /** Publishes each query's new rows (or its failure), inside the commit's batch. */
+    adopt(): void;
+    committed(): void;
+    discarded(): void;
+}
+/**
+ * A live query: the rows of `query` (at most `limit`, in its order) over its object's table `handle`, as a JSON source
+ * (a state member, a derive source, an `on` source). Its statement is compiled once; each run decodes only the rows
+ * whose stored columns changed and keeps the others the same objects, so its frame, the diff from the rows its watches
+ * had, compares unchanged rows by identity (a window shifted by one row: one insert and one removal, not a comparison
+ * of every row with every other).
+ */
+export declare class LiveQuery extends Source {
+    #private;
+    readonly handle: TableHandle;
+    constructor(handle: TableHandle, query: Query, limit: number, owner: QueryOwner, batch: Batch);
+    get value(): JsonValue[];
+    /** Its rows, or while failed its failure and last good rows (a detached query throws). */
+    start(): WatchStart;
+    /**
+     * The first run, before its object goes live (activation, after its tables are prepared): a failure throws and fails
+     * the activation. Rows a commit adopted meanwhile are newer and stay.
+     */
+    load(context: Context): Promise<void>;
+    /** A run inside the commit step `step`, after its writes: the rows, or the failure; it never throws. */
+    rerun(step: Step, context: Context): Promise<QueryRun>;
+    /**
+     * Takes a commit's run, inside its batch: listed for a frame when watched, its dependents marked. A failed run makes
+     * the query a failed member (as a throwing derive): its watches get one failure call, the owner a report per
+     * failure episode; the next good run replaces the value whole.
+     */
+    adopt(run: QueryRun): void;
+    /** Delivers the frame: the diff from the rows its watches had, or one failure call when they had rows. */
+    deliver(context: Context): void;
+    /** Its attempt ended: no commit re-runs it, reads throw `error` (the object's), its watches end `ended`. */
+    detach(error: Error): void;
+}
+export {};
+//# sourceMappingURL=live-query.d.ts.map

package/dist/store/live-query.d.ts.map

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

package/dist/store/live-query.js

@@ -0,0 +1,254 @@
+// Live queries (decision "Live queries over an object's own tables"): `self.query(table, q, limit)`, a JSON watchable
+// of a query's rows over a table of the object itself. Run once before the object goes live, then again inside the
+// commit step of every commit of the object that wrote the table (after its writes, so it sees them) and published in
+// that commit's batch as the diff from the previous rows (W1). Only the object writes its tables, so its commits are
+// the exact invalidation; a commit writing no table with a live query runs none.
+import { ChordError } from "../data/index.js";
+import { invalid } from "../data/internal.js";
+import { diffRevisions } from "../delta/index.js";
+import { handedOut, Source } from "../state/internal.js";
+import { chordMetrics } from "../telemetry.js";
+/**
+ * Refuses what the types cannot (plugin code is bundled without type checks; declaration policy): a query of another
+ * table than `table`, and a `limit` that is no positive integer (a live query must be bounded: one run per commit
+ * that writes its table reads at most `limit` rows).
+ */
+export function checkLiveQuery(table, q, limit, label) {
+    if (q.table !== table) {
+        throw invalid("args", `${label}: self.query: a query of table "${q.table.name}" over "${table.name}"`);
+    }
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+        throw invalid("args", `${label}: self.query: a limit is required, a positive integer`);
+    }
+}
+/** The live queries of one object by table (its SQL name), across its attempts: what its commits re-run. */
+export class LiveQueries {
+    #byTable = new Map();
+    /** Adds `query` (its attempt declared it): re-run by every commit writing its table from now on. */
+    add(query) {
+        const table = query.handle.sql.table;
+        let queries = this.#byTable.get(table);
+        if (queries === undefined) {
+            queries = new Set();
+            this.#byTable.set(table, queries);
+        }
+        queries.add(query);
+    }
+    /** Removes `query` (its attempt ended). */
+    delete(query) {
+        const table = query.handle.sql.table;
+        const queries = this.#byTable.get(table);
+        if (queries === undefined)
+            return;
+        queries.delete(query);
+        if (queries.size === 0)
+            this.#byTable.delete(table);
+    }
+    /** The live queries over `table`, if any. */
+    on(table) {
+        return this.#byTable.get(table);
+    }
+}
+/**
+ * The re-run of the live queries over the tables a transaction writes (`handles`), `undefined` when none has one (the
+ * common case: a map lookup per written table, nothing more). `context` is the transaction's: the runs count through it.
+ */
+export function refreshOf(handles, context) {
+    let queries;
+    for (const handle of handles) {
+        const on = handle.owner.queries.on(handle.sql.table);
+        if (on === undefined)
+            continue;
+        queries ??= new Set();
+        for (const query of on)
+            queries.add(query);
+    }
+    return queries === undefined ? undefined : new QueryRefresh([...queries], context);
+}
+const NO_WRITES = [];
+/**
+ * The re-run of live queries in one commit: `write` reads them in the commit step after the commit's own writes (the
+ * last write of the last phase), and `adopt` publishes their rows in the commit's batch; a refused step adopts nothing.
+ * A transaction stages it as its own change (`Staged`).
+ */
+export class QueryRefresh {
+    #queries;
+    #context;
+    #runs = [];
+    /** The staged write that reads the queries; it writes nothing and records nothing in the outbox. */
+    write;
+    constructor(queries, context) {
+        this.#queries = queries;
+        this.#context = context;
+        this.write = { order: "write", apply: (step) => this.#rerun(step) };
+    }
+    async #rerun(step) {
+        // A grouped commit that rolled back applies again alone (store.ts): only the last application's runs count.
+        this.#runs.length = 0;
+        for (const query of this.#queries)
+            this.#runs.push(await query.rerun(step, this.#context));
+        return NO_WRITES;
+    }
+    /** Publishes each query's new rows (or its failure), inside the commit's batch. */
+    adopt() {
+        for (const [index, query] of this.#queries.entries())
+            query.adopt(this.#runs[index]);
+    }
+    committed() { }
+    discarded() { }
+}
+/** What the watches of a failed live query had: no rows, so its next rows replace the value whole. */
+const NO_VALUE = Symbol("no value");
+const NO_ROWS = new Map();
+/**
+ * A live query: the rows of `query` (at most `limit`, in its order) over its object's table `handle`, as a JSON source
+ * (a state member, a derive source, an `on` source). Its statement is compiled once; each run decodes only the rows
+ * whose stored columns changed and keeps the others the same objects, so its frame, the diff from the rows its watches
+ * had, compares unchanged rows by identity (a window shifted by one row: one insert and one removal, not a comparison
+ * of every row with every other).
+ */
+export class LiveQuery extends Source {
+    handle;
+    #owner;
+    #statement;
+    #state = { kind: "loading" };
+    /** The last adopted rows by key, with the stored rows they were decoded from (the next run reuses unchanged ones). */
+    #byKey = NO_ROWS;
+    /** The rows this query's watches have, kept from its adoption to its frame in the batch; `undefined`: not listed. */
+    #framed;
+    /** Commits adopted so far: an activation run that a commit overtook keeps the commit's newer rows. */
+    #adopted = 0;
+    /** Set from a failed run until the next good one: a failure episode is reported once. */
+    #failing = false;
+    constructor(handle, query, limit, owner, batch) {
+        super(batch);
+        this.handle = handle;
+        this.#owner = owner;
+        this.#statement = handle.sql.select(query.condition, query.order, undefined, limit);
+    }
+    get value() {
+        const state = this.#state;
+        if (state.kind === "rows")
+            return state.value;
+        if (state.kind === "loading") {
+            throw new ChordError({ code: "not_ready", message: `${this.#owner.label}: a live query read before it ran` });
+        }
+        throw state.error;
+    }
+    /** Its rows, or while failed its failure and last good rows (a detached query throws). */
+    start() {
+        const state = this.#state;
+        if (state.kind === "failed")
+            return { kind: "failed", error: state.error, last: state.last };
+        return { kind: "value", value: this.value };
+    }
+    /**
+     * The first run, before its object goes live (activation, after its tables are prepared): a failure throws and fails
+     * the activation. Rows a commit adopted meanwhile are newer and stay.
+     */
+    async load(context) {
+        const adopted = this.#adopted;
+        this.#count(context);
+        const { sql, params } = this.#statement;
+        const stored = await this.handle.store.read((executor) => executor.all(sql, ...params), context);
+        // Decoded outside the store's read: a row the code cannot read is this query's failure, not the backend's.
+        const rows = this.#decode(stored, context);
+        if (this.#adopted !== adopted)
+            return;
+        this.#byKey = rows.byKey;
+        this.#state = { kind: "rows", value: rows.value };
+    }
+    /** A run inside the commit step `step`, after its writes: the rows, or the failure; it never throws. */
+    async rerun(step, context) {
+        try {
+            this.#count(context);
+            const { sql, params } = this.#statement;
+            return { kind: "rows", rows: this.#decode(await step.all(sql, ...params), context) };
+        }
+        catch (error) {
+            return { kind: "failed", error };
+        }
+    }
+    /**
+     * Takes a commit's run, inside its batch: listed for a frame when watched, its dependents marked. A failed run makes
+     * the query a failed member (as a throwing derive): its watches get one failure call, the owner a report per
+     * failure episode; the next good run replaces the value whole.
+     */
+    adopt(run) {
+        const state = this.#state;
+        if (state.kind === "detached")
+            return;
+        this.#adopted++;
+        if (this.watched && this.#framed === undefined)
+            this.#framed = state.kind === "rows" ? state.value : NO_VALUE;
+        if (run.kind === "rows") {
+            this.#failing = false;
+            this.#byKey = run.rows.byKey;
+            this.#state = { kind: "rows", value: run.rows.value };
+        }
+        else {
+            if (!this.#failing)
+                this.#owner.report(handedOut(run.error));
+            this.#failing = true;
+            const last = state.kind === "rows" ? state.value : state.kind === "failed" ? state.last : undefined;
+            this.#state = { kind: "failed", error: run.error, last };
+        }
+        this.changed();
+    }
+    /** Delivers the frame: the diff from the rows its watches had, or one failure call when they had rows. */
+    deliver(context) {
+        const before = this.#framed;
+        this.#framed = undefined;
+        const state = this.#state;
+        if (state.kind === "rows") {
+            // Listed by `adopt`, so `before` was kept (a detach in the batch leaves no rows).
+            const after = state.value;
+            const ops = before === NO_VALUE ? [["r", after]] : diffRevisions(before, after);
+            if (ops.length > 0)
+                this.publish(after, ops, false, context);
+            return;
+        }
+        // Still failed since the last call: nothing new for the watches.
+        if (state.kind === "failed" && before !== NO_VALUE)
+            this.failWatches(state.error, context);
+    }
+    /** Its attempt ended: no commit re-runs it, reads throw `error` (the object's), its watches end `ended`. */
+    detach(error) {
+        this.handle.owner.queries.delete(this);
+        this.#state = { kind: "detached", error };
+        this.#framed = undefined;
+        this.endWatches();
+    }
+    /** One run, counted where it happens (the cost guard: a commit not writing the table runs none). */
+    #count(context) {
+        chordMetrics(context.telemetry.metrics).counter("chord.query.runs").add(1);
+    }
+    /**
+     * The rows of `stored`: a row whose stored columns are all the same as in the last adopted run is that run's object
+     * (one comparison per physical column), any other is decoded.
+     */
+    #decode(stored, context) {
+        const { key, rows } = this.handle.definition;
+        const value = [];
+        const byKey = new Map();
+        for (const each of stored) {
+            const id = key.length === 1 ? each[key[0]] : JSON.stringify(key.map((column) => each[column]));
+            const before = this.#byKey.get(id);
+            const row = before !== undefined && sameStored(before.stored, each, rows.physical)
+                ? before.row
+                : // A table's rows hold its columns' values: scalars and JSON.
+                    rows.decode(each, context);
+            value.push(row);
+            byKey.set(id, { stored: each, row });
+        }
+        return { value, byKey };
+    }
+}
+/** Whether two stored rows have the same value in every physical column (SQLite values compare by `===`). */
+function sameStored(a, b, physical) {
+    for (const column of physical)
+        if (a[column] !== b[column])
+            return false;
+    return true;
+}
+//# sourceMappingURL=live-query.js.map

package/dist/store/live-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-query.js","sourceRoot":"","sources":["../../src/store/live-query.ts"],"names":[],"mappings":"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","sourcesContent":["// Live queries (decision \"Live queries over an object's own tables\"): `self.query(table, q, limit)`, a JSON watchable\n// of a query's rows over a table of the object itself. Run once before the object goes live, then again inside the\n// commit step of every commit of the object that wrote the table (after its writes, so it sees them) and published in\n// that commit's batch as the diff from the previous rows (W1). Only the object writes its tables, so its commits are\n// the exact invalidation; a commit writing no table with a live query runs none.\n\nimport type { Context } from \"../context/index.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport { invalid } from \"../data/internal.ts\";\nimport { diffRevisions, type Op } from \"../delta/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport type { SqliteValue } from \"../sqlite/index.ts\";\nimport { type Batch, handedOut, Source, type WatchStart } from \"../state/internal.ts\";\nimport { chordMetrics } from \"../telemetry.ts\";\nimport type { Query } from \"./query.ts\";\nimport type { Statement } from \"./sql.ts\";\nimport type { StagedWrite, Step } from \"./step.ts\";\nimport type { TableDefinition } from \"./table.ts\";\nimport type { TableHandle } from \"./table-handle.ts\";\nimport type { StoreWrite } from \"./writes.ts\";\n\n/** Who a live query belongs to: its object, and where its failures after activation are reported (`query_failed`). */\nexport type QueryOwner = {\n\treadonly label: string;\n\treport(error: unknown): void;\n};\n\n/**\n * The rows of one run: in order, and by key with the stored row each was decoded from, which the next run compares\n * against to keep an unchanged row the same object.\n */\ntype Rows = { readonly value: JsonValue[]; readonly byKey: ReadonlyMap<unknown, Decoded> };\n\n/** A row as a run decoded it, with the stored row it came from. */\ntype Decoded = { readonly stored: StoredRow; readonly row: JsonValue };\n\n/** One run of a live query in a commit step: its rows, or why it could not read them. */\ntype QueryRun = { readonly kind: \"rows\"; readonly rows: Rows } | { readonly kind: \"failed\"; readonly error: unknown };\n\n/**\n * Where a live query stands: before its first run (activation), with rows, failed (its last run threw; its last good\n * rows kept for a watch opened meanwhile), or detached (its attempt ended).\n */\ntype QueryState =\n\t| { readonly kind: \"loading\" }\n\t| { readonly kind: \"rows\"; readonly value: JsonValue[] }\n\t| { readonly kind: \"failed\"; readonly error: unknown; readonly last: JsonValue[] | undefined }\n\t| { readonly kind: \"detached\"; readonly error: unknown };\n\n/** A stored row as the backend returns it. */\ntype StoredRow = { readonly [column: string]: SqliteValue };\n\n/**\n * Refuses what the types cannot (plugin code is bundled without type checks; declaration policy): a query of another\n * table than `table`, and a `limit` that is no positive integer (a live query must be bounded: one run per commit\n * that writes its table reads at most `limit` rows).\n */\nexport function checkLiveQuery(table: TableDefinition, q: Query, limit: unknown, label: string): void {\n\tif (q.table !== table) {\n\t\tthrow invalid(\"args\", `${label}: self.query: a query of table \"${q.table.name}\" over \"${table.name}\"`);\n\t}\n\tif (!Number.isSafeInteger(limit) || (limit as number) < 1) {\n\t\tthrow invalid(\"args\", `${label}: self.query: a limit is required, a positive integer`);\n\t}\n}\n\n/** The live queries of one object by table (its SQL name), across its attempts: what its commits re-run. */\nexport class LiveQueries {\n\treadonly #byTable = new Map<string, Set<LiveQuery>>();\n\n\t/** Adds `query` (its attempt declared it): re-run by every commit writing its table from now on. */\n\tadd(query: LiveQuery): void {\n\t\tconst table = query.handle.sql.table;\n\t\tlet queries = this.#byTable.get(table);\n\t\tif (queries === undefined) {\n\t\t\tqueries = new Set();\n\t\t\tthis.#byTable.set(table, queries);\n\t\t}\n\t\tqueries.add(query);\n\t}\n\n\t/** Removes `query` (its attempt ended). */\n\tdelete(query: LiveQuery): void {\n\t\tconst table = query.handle.sql.table;\n\t\tconst queries = this.#byTable.get(table);\n\t\tif (queries === undefined) return;\n\t\tqueries.delete(query);\n\t\tif (queries.size === 0) this.#byTable.delete(table);\n\t}\n\n\t/** The live queries over `table`, if any. */\n\ton(table: string): ReadonlySet<LiveQuery> | undefined {\n\t\treturn this.#byTable.get(table);\n\t}\n}\n\n/**\n * The re-run of the live queries over the tables a transaction writes (`handles`), `undefined` when none has one (the\n * common case: a map lookup per written table, nothing more). `context` is the transaction's: the runs count through it.\n */\nexport function refreshOf(handles: Iterable<TableHandle>, context: Context): QueryRefresh | undefined {\n\tlet queries: Set<LiveQuery> | undefined;\n\tfor (const handle of handles) {\n\t\tconst on = handle.owner.queries.on(handle.sql.table);\n\t\tif (on === undefined) continue;\n\t\tqueries ??= new Set();\n\t\tfor (const query of on) queries.add(query);\n\t}\n\treturn queries === undefined ? undefined : new QueryRefresh([...queries], context);\n}\n\nconst NO_WRITES: readonly StoreWrite[] = [];\n\n/**\n * The re-run of live queries in one commit: `write` reads them in the commit step after the commit's own writes (the\n * last write of the last phase), and `adopt` publishes their rows in the commit's batch; a refused step adopts nothing.\n * A transaction stages it as its own change (`Staged`).\n */\nexport class QueryRefresh {\n\treadonly #queries: readonly LiveQuery[];\n\treadonly #context: Context;\n\treadonly #runs: QueryRun[] = [];\n\t/** The staged write that reads the queries; it writes nothing and records nothing in the outbox. */\n\treadonly write: StagedWrite;\n\n\tconstructor(queries: readonly LiveQuery[], context: Context) {\n\t\tthis.#queries = queries;\n\t\tthis.#context = context;\n\t\tthis.write = { order: \"write\", apply: (step) => this.#rerun(step) };\n\t}\n\n\tasync #rerun(step: Step): Promise<readonly StoreWrite[]> {\n\t\t// A grouped commit that rolled back applies again alone (store.ts): only the last application's runs count.\n\t\tthis.#runs.length = 0;\n\t\tfor (const query of this.#queries) this.#runs.push(await query.rerun(step, this.#context));\n\t\treturn NO_WRITES;\n\t}\n\n\t/** Publishes each query's new rows (or its failure), inside the commit's batch. */\n\tadopt(): void {\n\t\tfor (const [index, query] of this.#queries.entries()) query.adopt(this.#runs[index]!);\n\t}\n\n\tcommitted(): void {}\n\n\tdiscarded(): void {}\n}\n\n/** What the watches of a failed live query had: no rows, so its next rows replace the value whole. */\nconst NO_VALUE: unique symbol = Symbol(\"no value\");\n\nconst NO_ROWS: ReadonlyMap<unknown, Decoded> = new Map();\n\n/**\n * A live query: the rows of `query` (at most `limit`, in its order) over its object's table `handle`, as a JSON source\n * (a state member, a derive source, an `on` source). Its statement is compiled once; each run decodes only the rows\n * whose stored columns changed and keeps the others the same objects, so its frame, the diff from the rows its watches\n * had, compares unchanged rows by identity (a window shifted by one row: one insert and one removal, not a comparison\n * of every row with every other).\n */\nexport class LiveQuery extends Source {\n\treadonly handle: TableHandle;\n\treadonly #owner: QueryOwner;\n\treadonly #statement: Statement;\n\t#state: QueryState = { kind: \"loading\" };\n\t/** The last adopted rows by key, with the stored rows they were decoded from (the next run reuses unchanged ones). */\n\t#byKey: ReadonlyMap<unknown, Decoded> = NO_ROWS;\n\t/** The rows this query's watches have, kept from its adoption to its frame in the batch; `undefined`: not listed. */\n\t#framed: JsonValue[] | typeof NO_VALUE | undefined;\n\t/** Commits adopted so far: an activation run that a commit overtook keeps the commit's newer rows. */\n\t#adopted = 0;\n\t/** Set from a failed run until the next good one: a failure episode is reported once. */\n\t#failing = false;\n\n\tconstructor(handle: TableHandle, query: Query, limit: number, owner: QueryOwner, batch: Batch) {\n\t\tsuper(batch);\n\t\tthis.handle = handle;\n\t\tthis.#owner = owner;\n\t\tthis.#statement = handle.sql.select(query.condition, query.order, undefined, limit);\n\t}\n\n\tget value(): JsonValue[] {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"rows\") return state.value;\n\t\tif (state.kind === \"loading\") {\n\t\t\tthrow new ChordError({ code: \"not_ready\", message: `${this.#owner.label}: a live query read before it ran` });\n\t\t}\n\t\tthrow state.error;\n\t}\n\n\t/** Its rows, or while failed its failure and last good rows (a detached query throws). */\n\toverride start(): WatchStart {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"failed\") return { kind: \"failed\", error: state.error, last: state.last };\n\t\treturn { kind: \"value\", value: this.value };\n\t}\n\n\t/**\n\t * The first run, before its object goes live (activation, after its tables are prepared): a failure throws and fails\n\t * the activation. Rows a commit adopted meanwhile are newer and stay.\n\t */\n\tasync load(context: Context): Promise<void> {\n\t\tconst adopted = this.#adopted;\n\t\tthis.#count(context);\n\t\tconst { sql, params } = this.#statement;\n\t\tconst stored = await this.handle.store.read((executor) => executor.all<StoredRow>(sql, ...params), context);\n\t\t// Decoded outside the store's read: a row the code cannot read is this query's failure, not the backend's.\n\t\tconst rows = this.#decode(stored, context);\n\t\tif (this.#adopted !== adopted) return;\n\t\tthis.#byKey = rows.byKey;\n\t\tthis.#state = { kind: \"rows\", value: rows.value };\n\t}\n\n\t/** A run inside the commit step `step`, after its writes: the rows, or the failure; it never throws. */\n\tasync rerun(step: Step, context: Context): Promise<QueryRun> {\n\t\ttry {\n\t\t\tthis.#count(context);\n\t\t\tconst { sql, params } = this.#statement;\n\t\t\treturn { kind: \"rows\", rows: this.#decode(await step.all<StoredRow>(sql, ...params), context) };\n\t\t} catch (error) {\n\t\t\treturn { kind: \"failed\", error };\n\t\t}\n\t}\n\n\t/**\n\t * Takes a commit's run, inside its batch: listed for a frame when watched, its dependents marked. A failed run makes\n\t * the query a failed member (as a throwing derive): its watches get one failure call, the owner a report per\n\t * failure episode; the next good run replaces the value whole.\n\t */\n\tadopt(run: QueryRun): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"detached\") return;\n\t\tthis.#adopted++;\n\t\tif (this.watched && this.#framed === undefined) this.#framed = state.kind === \"rows\" ? state.value : NO_VALUE;\n\t\tif (run.kind === \"rows\") {\n\t\t\tthis.#failing = false;\n\t\t\tthis.#byKey = run.rows.byKey;\n\t\t\tthis.#state = { kind: \"rows\", value: run.rows.value };\n\t\t} else {\n\t\t\tif (!this.#failing) this.#owner.report(handedOut(run.error));\n\t\t\tthis.#failing = true;\n\t\t\tconst last = state.kind === \"rows\" ? state.value : state.kind === \"failed\" ? state.last : undefined;\n\t\t\tthis.#state = { kind: \"failed\", error: run.error, last };\n\t\t}\n\t\tthis.changed();\n\t}\n\n\t/** Delivers the frame: the diff from the rows its watches had, or one failure call when they had rows. */\n\tdeliver(context: Context): void {\n\t\tconst before = this.#framed;\n\t\tthis.#framed = undefined;\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"rows\") {\n\t\t\t// Listed by `adopt`, so `before` was kept (a detach in the batch leaves no rows).\n\t\t\tconst after = state.value;\n\t\t\tconst ops: readonly Op[] = before === NO_VALUE ? [[\"r\", after]] : diffRevisions(before!, after);\n\t\t\tif (ops.length > 0) this.publish(after, ops, false, context);\n\t\t\treturn;\n\t\t}\n\t\t// Still failed since the last call: nothing new for the watches.\n\t\tif (state.kind === \"failed\" && before !== NO_VALUE) this.failWatches(state.error, context);\n\t}\n\n\t/** Its attempt ended: no commit re-runs it, reads throw `error` (the object's), its watches end `ended`. */\n\tdetach(error: Error): void {\n\t\tthis.handle.owner.queries.delete(this);\n\t\tthis.#state = { kind: \"detached\", error };\n\t\tthis.#framed = undefined;\n\t\tthis.endWatches();\n\t}\n\n\t/** One run, counted where it happens (the cost guard: a commit not writing the table runs none). */\n\t#count(context: Context): void {\n\t\tchordMetrics(context.telemetry.metrics).counter(\"chord.query.runs\").add(1);\n\t}\n\n\t/**\n\t * The rows of `stored`: a row whose stored columns are all the same as in the last adopted run is that run's object\n\t * (one comparison per physical column), any other is decoded.\n\t */\n\t#decode(stored: readonly StoredRow[], context: Context): Rows {\n\t\tconst { key, rows } = this.handle.definition;\n\t\tconst value: JsonValue[] = [];\n\t\tconst byKey = new Map<unknown, Decoded>();\n\t\tfor (const each of stored) {\n\t\t\tconst id = key.length === 1 ? each[key[0]!] : JSON.stringify(key.map((column) => each[column]));\n\t\t\tconst before = this.#byKey.get(id);\n\t\t\tconst row =\n\t\t\t\tbefore !== undefined && sameStored(before.stored, each, rows.physical)\n\t\t\t\t\t? before.row\n\t\t\t\t\t: // A table's rows hold its columns' values: scalars and JSON.\n\t\t\t\t\t\t(rows.decode(each, context) as JsonValue);\n\t\t\tvalue.push(row);\n\t\t\tbyKey.set(id, { stored: each, row });\n\t\t}\n\t\treturn { value, byKey };\n\t}\n}\n\n/** Whether two stored rows have the same value in every physical column (SQLite values compare by `===`). */\nfunction sameStored(a: StoredRow, b: StoredRow, physical: readonly string[]): boolean {\n\tfor (const column of physical) if (a[column] !== b[column]) return false;\n\treturn true;\n}\n"]}

package/dist/store/outbox.d.ts

@@ -0,0 +1,26 @@
+import type { Context } from "../context/index.ts";
+import type { ChordStore } from "./store.ts";
+import type { StoreWrite } from "./writes.ts";
+/** The write vocabulary's version an outbox commit is stored in; a newer one is refused, data intact. */
+export declare const OUTBOX_FORMAT = 1;
+/** One commit as the outbox gives it: its seq, the allocator's value it persisted (D3) and its writes in applied order. */
+export type OutboxCommit = {
+    readonly seq: number;
+    readonly nextId: number;
+    readonly writes: readonly StoreWrite[];
+};
+/** A store's outbox: its commits after the floor (the seq it was turned on at, advanced by `trim`). */
+export declare class Outbox {
+    #private;
+    constructor(store: ChordStore, floor: number);
+    /** The seq the outbox starts after: `read` takes any `afterSeq` from it to `lastSeq`. */
+    get floor(): number;
+    /** Up to `limit` commits after `afterSeq`, in seq order; `afterSeq` outside floor..lastSeq is `invalid/args`. */
+    read(afterSeq: number, limit: number, context: Context): Promise<OutboxCommit[]>;
+    /**
+     * Drops the commits through `throughSeq` and advances the floor; idempotent; beyond `lastSeq` is `invalid/args`.
+     * Trims run one at a time, so the stored floor only rises and equals the one in memory.
+     */
+    trim(throughSeq: number, context: Context): Promise<void>;
+}
+//# sourceMappingURL=outbox.d.ts.map

package/dist/store/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../src/store/outbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,yGAAyG;AACzG,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,2HAA2H;AAC3H,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAIrH,uGAAuG;AACvG,qBAAa,MAAM;;IASlB,YAAY,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAG3C;IAED,yFAAyF;IACzF,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,iHAAiH;IAC3G,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAIrF;IAED;;;OAGG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAUxD;CA6CD"}

package/dist/store/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../src/store/outbox.ts"],"names":[],"mappings":"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","sourcesContent":["// The outbox (slice 6a §2; decisions \"The outbox is optional, internal and versioned\", small items 3-4): the store's\n// commits as the sync layer reads them, one `{ seq, writes }` per commit from its floor on, in the current format.\n\nimport type { Context } from \"../context/index.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport { invalid } from \"../data/internal.ts\";\nimport { TABLES } from \"./schema.ts\";\nimport type { ChordStore } from \"./store.ts\";\nimport type { StoreWrite } from \"./writes.ts\";\n\n/** The write vocabulary's version an outbox commit is stored in; a newer one is refused, data intact. */\nexport const OUTBOX_FORMAT = 1;\n\n/** One commit as the outbox gives it: its seq, the allocator's value it persisted (D3) and its writes in applied order. */\nexport type OutboxCommit = { readonly seq: number; readonly nextId: number; readonly writes: readonly StoreWrite[] };\n\nconst NOTHING = (): void => {};\n\n/** A store's outbox: its commits after the floor (the seq it was turned on at, advanced by `trim`). */\nexport class Outbox {\n\treadonly #store: ChordStore;\n\t#floor: number;\n\t/**\n\t * The outbox's reads and trims, one at a time: a read checks the floor and reads with no trim running (a trim's\n\t * commit may have deleted rows before its floor is set), a trim waits for the reads in flight.\n\t */\n\t#queue: Promise<void> = Promise.resolve();\n\n\tconstructor(store: ChordStore, floor: number) {\n\t\tthis.#store = store;\n\t\tthis.#floor = floor;\n\t}\n\n\t/** The seq the outbox starts after: `read` takes any `afterSeq` from it to `lastSeq`. */\n\tget floor(): number {\n\t\treturn this.#floor;\n\t}\n\n\t/** Up to `limit` commits after `afterSeq`, in seq order; `afterSeq` outside floor..lastSeq is `invalid/args`. */\n\tasync read(afterSeq: number, limit: number, context: Context): Promise<OutboxCommit[]> {\n\t\tif (!Number.isSafeInteger(afterSeq)) throw invalid(\"args\", `outbox: read after ${afterSeq}, not an integer`);\n\t\tif (!Number.isSafeInteger(limit) || limit < 1) throw invalid(\"args\", \"outbox: limit is a positive integer\");\n\t\treturn this.#queued(() => this.#read(afterSeq, limit, context));\n\t}\n\n\t/**\n\t * Drops the commits through `throughSeq` and advances the floor; idempotent; beyond `lastSeq` is `invalid/args`.\n\t * Trims run one at a time, so the stored floor only rises and equals the one in memory.\n\t */\n\ttrim(throughSeq: number, context: Context): Promise<void> {\n\t\ttry {\n\t\t\tcontext.abortSignal?.throwIfAborted();\n\t\t\tif (!Number.isSafeInteger(throughSeq) || throughSeq > this.#store.lastSeq) {\n\t\t\t\tthrow invalid(\"args\", `outbox: trim through ${throughSeq}, beyond ${this.#store.lastSeq}`);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\treturn Promise.reject(error);\n\t\t}\n\t\treturn this.#queued(() => this.#trim(throughSeq));\n\t}\n\n\t/** Runs `operation` once the outbox operations before it settled. */\n\t#queued<T>(operation: () => Promise<T>): Promise<T> {\n\t\tconst run = this.#queue.then(operation);\n\t\tthis.#queue = run.then(NOTHING, NOTHING);\n\t\treturn run;\n\t}\n\n\t/** `read`, its turn come: the floor as no trim moves it. */\n\tasync #read(afterSeq: number, limit: number, context: Context): Promise<OutboxCommit[]> {\n\t\tif (afterSeq < this.#floor || afterSeq > this.#store.lastSeq) {\n\t\t\tthrow invalid(\"args\", `outbox: read after ${afterSeq}, outside ${this.#floor}..${this.#store.lastSeq}`);\n\t\t}\n\t\tconst rows = await this.#store.read(\n\t\t\t(executor) =>\n\t\t\t\texecutor.all<{\n\t\t\t\t\treadonly seq: number;\n\t\t\t\t\treadonly format: number;\n\t\t\t\t\treadonly next_id: number;\n\t\t\t\t\treadonly writes: string;\n\t\t\t\t}>(\n\t\t\t\t\t`SELECT seq, format, next_id, writes FROM ${TABLES.outbox} WHERE seq > ? ORDER BY seq LIMIT ?`,\n\t\t\t\t\tafterSeq,\n\t\t\t\t\tlimit,\n\t\t\t\t),\n\t\t\tcontext,\n\t\t);\n\t\treturn rows.map(({ seq, format, next_id, writes }) => {\n\t\t\tif (format !== OUTBOX_FORMAT) {\n\t\t\t\tconst message = `outbox: commit ${seq} is in format ${format}, newer than ${OUTBOX_FORMAT}`;\n\t\t\t\tthrow new ChordError({ code: \"unavailable\", message });\n\t\t\t}\n\t\t\treturn { seq, nextId: next_id, writes: JSON.parse(writes) as StoreWrite[] };\n\t\t});\n\t}\n\n\tasync #trim(throughSeq: number): Promise<void> {\n\t\tif (throughSeq <= this.#floor) return;\n\t\tawait this.#store.maintain(async (executor) => {\n\t\t\tawait executor.run(`DELETE FROM ${TABLES.outbox} WHERE seq <= ?`, throughSeq);\n\t\t\tawait executor.run(`UPDATE ${TABLES.meta} SET outbox_floor = ? WHERE singleton = 1`, throughSeq);\n\t\t});\n\t\tthis.#floor = throughSeq;\n\t}\n}\n"]}