@thomasfosterau/legation 0.0.0 → 0.1.0

package/dist/sql/index.js

@@ -0,0 +1,969 @@
+import { t as __exportAll } from "../rolldown-runtime-D8jQpDG7.js";
+import { $t as apply, Mn as BackendError, Sn as test, _ as transaction, b as make$3, dn as isIn, h as Backend, mn as isNullish, s as InvalidationBus, vt as contentHash, wn as filterDeclarationOf, xn as resolveExists } from "../MemoryBackend-DxP8t4ge.js";
+import * as Arr from "effect/Array";
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+import * as P from "effect/Predicate";
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as R from "effect/Record";
+import * as Schedule from "effect/Schedule";
+import * as MutableHashMap from "effect/MutableHashMap";
+import * as MutableHashSet from "effect/MutableHashSet";
+// src/sql/Sql.ts
+var Sql_exports = /* @__PURE__ */ __exportAll({
+	compileSelect: () => compileSelect,
+	compileWhere: () => compileWhere,
+	postgres: () => postgres,
+	sqlite: () => sqlite
+});
+const quoteDouble = (identifier) => `"${identifier.replace(/"/g, "\"\"")}"`;
+/**
+* SQLite: `?` placeholders, `COLLATE BINARY`, booleans as `0`/`1`, a `UNION
+* ALL` arm's row as its own columns by position (`pragma_table_info`).
+*/
+const sqlite = {
+	placeholder: () => "?",
+	quote: quoteDouble,
+	textCollation: "BINARY",
+	boolean: (value) => value ? 1 : 0,
+	greatest: (left, right) => `MAX(${left}, ${right})`,
+	unionRows: {
+		_tag: "Columns",
+		columnsOf: (relation) => ({
+			text: `SELECT name FROM pragma_table_info(?)`,
+			params: [relation]
+		})
+	}
+};
+/**
+* PostgreSQL: `$1`, `$2`, … placeholders, `COLLATE "C"`, native booleans,
+* SERIALIZABLE transactions, a `UNION ALL` arm's row as JSON (`row_to_json`).
+*/
+const postgres = {
+	placeholder: (index) => `$${index}`,
+	quote: quoteDouble,
+	textCollation: `"C"`,
+	boolean: (value) => value,
+	greatest: (left, right) => `GREATEST(${left}, ${right})`,
+	serializable: "SET TRANSACTION ISOLATION LEVEL SERIALIZABLE",
+	unionRows: {
+		_tag: "Json",
+		rowJson: (alias) => `row_to_json(${alias})::text`
+	}
+};
+const comparators = {
+	eq: "=",
+	ne: "<>",
+	gt: ">",
+	gte: ">=",
+	lt: "<",
+	lte: "<="
+};
+/** Accumulates bind params so placeholders get the right 1-based index. */
+var Params = class {
+	dialect;
+	values = [];
+	constructor(dialect) {
+		this.dialect = dialect;
+	}
+	bind(value) {
+		this.values.push(value);
+		return this.dialect.placeholder(this.values.length);
+	}
+};
+/** The JS type a literal of each kind has. */
+const jsTypeOf = {
+	text: "string",
+	instant: "string",
+	integer: "number",
+	double: "number",
+	boolean: "boolean"
+};
+/** Whether a literal can bind as the declared kind: `null` always, else by JS type. */
+const conforms = (kind, value) => value === null || kind === void 0 || typeof value === jsTypeOf[kind];
+/** The column operand: quoted, with the collation clause when declared `text`. */
+const operand = (compilation, field) => {
+	const column = compilation.dialect.quote(field);
+	return compilation.kinds?.[field] === "text" ? `${column} COLLATE ${compilation.dialect.textCollation}` : column;
+};
+/**
+* Bind one literal under the field's declared kind: a conforming literal as
+* itself (booleans as the dialect stores them), a cross-type literal as
+* `NULL` (unknown, rule (d)).
+*/
+const bindLiteral = (compilation, field, value) => {
+	const { params, dialect, kinds } = compilation;
+	if (!conforms(kinds?.[field], value)) return params.bind(null);
+	return params.bind(P.isBoolean(value) ? dialect.boolean(value) : value);
+};
+/**
+* The literals of an `In`/`NotIn` list that can bind under the declared
+* kind. A cross-type literal matches nothing, so it is dropped; a non-empty
+* list left with nothing binds one `NULL`, which makes the membership
+* unknown — `Predicate.evaluate`'s verdict when no listed literal has the
+* field's type.
+*/
+const bindableList = (compilation, field, values) => {
+	const kind = compilation.kinds?.[field];
+	const kept = values.filter((value) => conforms(kind, value));
+	return Arr.isReadonlyArrayEmpty(kept) ? [null] : kept;
+};
+const compileCompare = (node, compilation) => `${operand(compilation, node.field)} ${comparators[node.op]} ${bindLiteral(compilation, node.field, node.value)}`;
+/** `In` / `NotIn`: an empty list is the constant `FALSE` / `TRUE` (ADR-0028 §3). */
+const compileList = (node, compilation) => {
+	if (Arr.isReadonlyArrayEmpty(node.values)) return node._tag === "In" ? "1 = 0" : "1 = 1";
+	const placeholders = bindableList(compilation, node.field, node.values).map((value) => bindLiteral(compilation, node.field, value)).join(", ");
+	return `${operand(compilation, node.field)} ${node._tag === "In" ? "IN" : "NOT IN"} (${placeholders})`;
+};
+/** Correlated set membership: `localField IN (SELECT foreignField FROM … WHERE …)`. */
+const compileExists = (node, compilation) => {
+	const kinds = compilation.foreignKinds?.[node.collection];
+	const inner = compileNode(node.where, {
+		...compilation,
+		kinds
+	});
+	const { quote } = compilation.dialect;
+	return `${quote(node.localField)} IN (SELECT ${quote(node.foreignField)} FROM ${quote(node.collection)} WHERE ${inner})`;
+};
+const compileNode = (predicate, compilation) => {
+	switch (predicate._tag) {
+		case "True": return "1 = 1";
+		case "Compare": return compileCompare(predicate, compilation);
+		case "In":
+		case "NotIn": return compileList(predicate, compilation);
+		case "IsNull": return `${compilation.dialect.quote(predicate.field)} IS ${predicate.negated === true ? "NOT " : ""}NULL`;
+		case "And":
+			if (Arr.isReadonlyArrayEmpty(predicate.predicates)) return "1 = 1";
+			return predicate.predicates.map((inner) => compileNode(inner, compilation)).join(" AND ");
+		case "Or":
+			if (Arr.isReadonlyArrayEmpty(predicate.predicates)) return "1 = 0";
+			return `(${predicate.predicates.map((inner) => compileNode(inner, compilation)).join(" OR ")})`;
+		case "Not": return `NOT (${compileNode(predicate.predicate, compilation)})`;
+		case "Exists": return compileExists(predicate, compilation);
+		case "InSet": return "1 = 0";
+	}
+};
+/**
+* Compile a predicate into a `WHERE`-ready fragment for a dialect. Pass
+* `options.kinds` (field → literal kind) so declared-text fields get their
+* collation clause and literals bind by the declared kind; without a
+* declaration nothing collates and a literal binds as its JS type (see the
+* module doc).
+*/
+const compileWhere = (predicate, dialect = sqlite, options = {}) => {
+	const params = new Params(dialect);
+	return {
+		text: compileNode(predicate, {
+			dialect,
+			params,
+			kinds: options.kinds,
+			foreignKinds: options.foreignKinds
+		}),
+		params: params.values
+	};
+};
+/**
+* Compile a `SELECT * FROM <table> WHERE <predicate>` for a subset. The
+* `WHERE` is exact (see the module doc). Order, limit and cursor are not
+* pushed down: this statement may later grow an `ORDER BY … LIMIT` for
+* backends that want it, but today the backend's `Subset.apply` finalises
+* them locally, so this stays a single, safe statement.
+*/
+const compileSelect = (options) => {
+	const dialect = options.dialect ?? sqlite;
+	const { text, params } = compileWhere(options.where, dialect, {
+		kinds: options.kinds,
+		foreignKinds: options.foreignKinds
+	});
+	return {
+		text: `SELECT * FROM ${dialect.quote(options.table)} WHERE ${text}`,
+		params
+	};
+};
+// src/sql/SqlBackend.ts
+/**
+* SqlBackend
+*
+* A reference implementation of the core `Backend` contract (ADR-0009) over a
+* SQL database, addressing the audit's "turnkey backend" gap with a
+* driver-agnostic adapter: the app provides a tiny `SqlExecutor` (wrapping
+* `better-sqlite3`, `effect/sql`, `pg`, …) and per-collection table
+* mappings, and this backend supplies subset evaluation, row fetching, and the
+* transactional mutation-id ledger.
+*
+* Reads go through the `Sql` translator (`Subset` predicate → `WHERE`, exact
+* under ADR-0028 on both dialects), then `Subset.apply` finalises
+* order/limit/cursor locally. A table mapping may declare its columns'
+* literal kinds (`TableMapping.kinds`) so the compiler collates declared-text
+* columns and binds literals by kind (booleans per dialect); the row decoder
+* maps SQLite's `0`/`1` back to booleans for columns declared `boolean`, and
+* otherwise leaves rows as the driver returns them (values stay opaque,
+* ADR-0014). Writes run app-provided handlers inside one transaction (on an
+* executor that has transactions), and each mutation is first claimed in the
+* client's ledger row: a conditional UPDATE
+* from `id - 1` to `id` that runs before its handler. The database evaluates
+* that WHERE against the latest committed row, so of two calls racing for one
+* mutation only one claim matches and the other is a replay the ledger covers.
+* The watermark only ever moves from `id - 1` to `id`, so it cannot fall. This
+* gives the contract's exactly-once, in-order guarantee for one client group,
+* with the claim alone needing no stronger isolation than READ COMMITTED.
+* An executor without transactions (`transactional: false`) cannot commit a
+* claim together with its handler's writes, so it keeps the handler-then-bump
+* order instead (see D1 below).
+*
+* A permanent rejection is remembered in the client's ledger row, in the same
+* transaction as the claim (#366), in a `rejections` column that holds a JSON
+* object of mutation id → reason. A replayed copy lists its mutation in
+* `rejected` with the stored reason, so every copy reports the committed outcome
+* (guarantee 1). A copy that a concurrent call committed first is dropped on
+* each dialect: on SQLite it lists its mutation in `rejected` directly; on
+* PostgreSQL it is refused with a transient `BackendError` (SQLSTATE 40001), and
+* its retry, a replay, lists it. A push forgets the rejections below its lowest
+* id per client. The memory is bounded per client: a client that never pushes
+* again keeps its last push's rejections. It assumes one journal per `clientId`,
+* which backend contiguity already requires.
+*
+* Mutations from different client groups are serialisable (guarantee 1, #353),
+* per dialect:
+*
+* - SQLite serialises transactions on its one connection, and the client takes
+*   the write lock with `BEGIN IMMEDIATE`, so a handler's reads and its writes
+*   never interleave with another group's transaction. It conforms.
+* - PostgreSQL runs each `applyMutations` transaction at SERIALIZABLE: the
+*   dialect's `serializable` statement (`SET TRANSACTION ISOLATION LEVEL
+*   SERIALIZABLE`) runs first, before any read. It must be the transaction's
+*   first statement in a top-level transaction: PostgreSQL refuses it inside a
+*   subtransaction (a nested `transaction`, which a savepoint runs), so
+*   `applyMutations` then fails with a `BackendError` rather than running at
+*   READ COMMITTED. A transaction that read a row another transaction changed
+*   and committed first is refused at its write with SQLSTATE 40001, and rolls
+*   back. The executor reports that as a
+*   `BackendError`, which the client treats as transient and retries, and the
+*   retry runs the handler on the committed state. A handler therefore never
+*   commits a write computed from a stale read. This is not retried inside the
+*   backend: the client already re-sends an unacknowledged batch, so the
+*   transient path covers it without a second retry policy. A PostgreSQL
+*   executor that sets `transactional: false` loses this guarantee, since the
+*   ordering then has no transaction to isolate.
+* - D1 is non-conforming (#342, #353). It has no interactive transactions, so its
+*   executor sets `transactional: false` and each statement commits on its own.
+*   `applyMutations` then keeps trunk's order: the handler runs, then the
+*   ledger is bumped to the larger of the stored and the new id, so an
+*   overlapping call that finishes late cannot move the watermark back. The
+*   handler's writes commit before the bump, so a pull between the two carries
+*   the effect without the watermark; a crash after the writes and before the
+*   bump makes the retry run the handler again; and a transient failure leaves
+*   the writes committed for the retry to repeat. A rejection recorded before a
+*   failed bump is forgotten when the retry applies the id (#425). Nothing
+*   isolates a handler's reads from another group's writes, so a lost update is
+*   possible. The claim order is not used on D1 because a claim committed on its
+*   own would leave a crash between the claim and the handler's commit claimed
+*   and unapplied, so a retry would skip the mutation (#359).
+*
+* An executor on another database must provide the same isolation, or the
+* handlers' reads must be version-checked, before it can claim guarantee 1.
+*
+* A mapping's reads run against `readRelation` when given (issue #204): a
+* real app's current-state relation is often a view — one that resolves each
+* node's current version and joins the leaf at exactly that version — never
+* the table mutator handlers write through. A mapping's `tombstone`
+* predicate (the engine's own `Predicate` vocabulary, evaluated with
+* `Predicate.test`) marks a row a soft delete rather than a live one: such a
+* row is dropped from `evaluate`'s returned entries, so it simply isn't in
+* the next CVR view and `Cvr.diff` reports it as a delete for that id,
+* exactly as a row that vanished from the relation outright would (fail-open
+* would be a bug: a soft-deleted row must never keep syncing as a put).
+*
+* A pull's subsets are evaluated together by `evaluateMany` (#505): one
+* `UNION ALL` statement whose arms each select their subset's index and their
+* row, plus one statement per `Exists` node, as in `evaluate`. On SQLite, whose
+* `UNION ALL` columns take any type per row, an arm carries the relation's own
+* columns by position, so each value reaches the backend exactly as `evaluate`
+* reads it. On PostgreSQL an arm carries its row as JSON (`row_to_json`): the
+* two agree wherever JSON carries a column's value as the driver does
+* (`BackendContract` rule 14 checks it over the generated corpus), the README
+* lists the column types it does not, and a pull whose rows hold a number
+* JSON cannot carry exactly (an integer beyond ±(2^53 − 1), a `numeric` with
+* more digits than a double, such a number inside a `jsonb` column) is
+* answered by `evaluate` per subset instead, with an {@link InexactJsonNumber}
+* warning naming the column. Integer, double and text values belong in typed
+* columns (`integer`, `double precision`, `text`) rather than in JSON. The rows read back are finished
+* by the same code as `evaluate`'s.
+*/
+var SqlBackend_exports = /* @__PURE__ */ __exportAll({
+	InexactJsonNumber: () => InexactJsonNumber,
+	fromCollection: () => fromCollection,
+	make: () => make$2,
+	versionOf: () => versionOf
+});
+const decodeArgs = (definition, args, name) => Schema.decodeUnknownEffect(definition.args)(args).pipe(Effect.mapError((cause) => new BackendError({
+	message: `Invalid args for mutator "${name}"`,
+	cause
+})));
+/** The `rejections` column's value: a JSON object of mutation id → reason, or `null` when none is remembered. */
+const encodeRejections = (rejections) => rejections.size === 0 ? null : JSON.stringify(Object.fromEntries(rejections));
+/** Decode the `rejections` column (`null` and absent both mean none remembered). */
+const decodeRejections = (text, mutationsTable) => {
+	if (text === null || text === void 0) return Effect.succeed(/* @__PURE__ */ new Map());
+	return Effect.try({
+		try: () => {
+			if (!P.isString(text)) throw new TypeError("not text");
+			return new Map(Object.entries(JSON.parse(text)).map(([id, reason]) => [Number(id), String(reason)]));
+		},
+		catch: (cause) => new BackendError({
+			message: `The "rejections" column of the mutation ledger "${mutationsTable}" holds a value that is not a rejection memory`,
+			cause
+		})
+	});
+};
+/**
+* Derive a `TableMapping` from a `Collection`: column kinds come from its
+* declared filterable set (`Collection.filterDeclarationOf`, #154) instead of
+* being restated by hand — the common case. `table`, and optionally
+* `readRelation` / `idColumn` / `versionColumn` / `tombstone`, are still
+* given explicitly; the hand-written record shape (this function's return
+* type) remains the override path for a mapping derivation can't cover.
+*/
+const fromCollection = (collection, options) => {
+	const { filterable } = filterDeclarationOf(collection);
+	const kinds = Object.fromEntries(Object.entries(filterable).map(([field, declared]) => [field, declared.kind]));
+	return {
+		...options,
+		kinds
+	};
+};
+/**
+* The alias each arm of `evaluateMany`'s statement gives its relation: a
+* `Json` dialect's `rowJson` names the row by it, so it must not be a column
+* of any mapping.
+*/
+const MANY_ROW_ALIAS = "__legation_row";
+/** The subset index each row of `evaluateMany`'s statement carries. */
+const ManyIndex = Schema.Struct({ subset: Schema.Int });
+/** A row a `Json` dialect's arm carries: JSON text holding an object. */
+const ManyJsonRow = Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown));
+/** A failure to decode a row of `evaluateMany`'s statement, as a `BackendError`. */
+const undecodable = (cause) => new BackendError({
+	message: "evaluateMany read a row it could not decode",
+	cause
+});
+/** The subset index of a row of `evaluateMany`'s statement. */
+const decodeManyIndex = (row) => Schema.decodeUnknownEffect(ManyIndex)(row).pipe(Effect.mapError(undecodable));
+/** The row a `Json` dialect's arm carried, from its JSON text. */
+const decodeManyJson = (text) => Schema.decodeEffect(ManyJsonRow)(text).pipe(Effect.mapError(undecodable));
+/**
+* Why a pull fell back from its batched statement to one `evaluate` per
+* subset: a number in a JSON row (PostgreSQL's `row_to_json`) that JSON
+* cannot carry exactly (#505). `JSON.parse` reads every JSON number as a
+* double, so one with more significant digits than a double holds (a `bigint`
+* past ±(2^53 − 1), a `numeric` of high precision, such a number inside a
+* `json` / `jsonb` column) would read back as a different value than the
+* database holds, and an integer past ±(2^53 − 1) is read by the driver as
+* text, not a number. `evaluateMany` then answers the pull with `evaluate`
+* per subset, whose values are the driver's, and logs this once per
+* collection and column at `Warning` level, as the log's cause: declare the
+* column `integer`, `double precision` or `text` in the read relation (a view
+* can cast it) so the pull stays one statement.
+*
+* Logged, never raised: the pull still succeeds.
+*/
+var InexactJsonNumber = class extends Schema.TaggedError()("InexactJsonNumber", {
+	message: Schema.String,
+	/** The collection whose read relation holds the column. */
+	collection: Schema.String,
+	/** The read relation's column the number sits in (top-level key of the row's JSON). */
+	column: Schema.String
+}) {};
+/**
+* A JSON number's decimal value, as `<sign><digits>e<scale>` with the digits'
+* leading and trailing zeros dropped (the value is `0.<digits> × 10^scale`),
+* so two spellings of one value (`1.50`, `15e-1`) give the same key.
+*/
+const decimalKey = (token) => {
+	const match = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(token);
+	if (match === null) return token;
+	const [, sign = "", whole = "", fraction = "", exponent = "0"] = match;
+	const digits = `${whole}${fraction}`;
+	const significant = digits.replace(/^0+/, "");
+	const trimmed = significant.replace(/0+$/, "");
+	if (trimmed === "") return "0";
+	return `${sign}${trimmed}e${whole.length - (digits.length - significant.length) + Number(exponent)}`;
+};
+/**
+* Whether `JSON.parse` reads a JSON number token as exactly the value it
+* spells, and as a number the driver would also give: its decimal value equals
+* the double it parses to, and that double is not an integer past
+* ±(2^53 − 1) (which the driver reads as text).
+*/
+const isExactJsonNumber = (token) => {
+	const value = Number(token);
+	return (!Number.isInteger(value) || Number.isSafeInteger(value)) && decimalKey(token) === decimalKey(String(value));
+};
+/** JSON's tokens, for {@link inexactColumns}: strings, numbers and punctuation. */
+const JSON_TOKEN = /"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|[{}[\]:,]/g;
+/** How a JSON token changes the nesting depth: `{` / `[` open, `}` / `]` close. */
+const nestingOf = (token) => {
+	if (token === "{" || token === "[") return 1;
+	return token === "}" || token === "]" ? -1 : 0;
+};
+/** Whether a JSON token is a number `JSON.parse` cannot carry exactly. */
+const isInexactNumberToken = (token) => /^-?\d/.test(token) && !isExactJsonNumber(token);
+/** A JSON string token's value (a column name, escapes decoded). */
+const decodeJsonString = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.String));
+/**
+* The columns of a JSON row whose values hold a number JSON cannot carry
+* exactly (see {@link InexactJsonNumber}), nested values included: each
+* distinct top-level key such a number sits under, in order.
+*/
+const inexactColumns = (text) => {
+	const tokens = Array.from(text.matchAll(JSON_TOKEN), (match) => match[0]);
+	const [, found] = Arr.mapAccum(tokens, {
+		depth: 0,
+		key: "",
+		previous: ""
+	}, (state, token) => {
+		const depth = state.depth + nestingOf(token);
+		const key = token === ":" && state.depth === 1 ? Option.getOrElse(decodeJsonString(state.previous), () => state.previous) : state.key;
+		const inexact = isInexactNumberToken(token) ? Option.some(key) : Option.none();
+		return [{
+			depth,
+			key,
+			previous: token
+		}, inexact];
+	});
+	return Arr.dedupe(Arr.getSomes(found));
+};
+/** Content-hash fallback version when no version column is mapped. */
+const versionOf = contentHash;
+/**
+* A {@link Backend.Backend} over a {@link SqlExecutor}: subset evaluation, row fetch and the
+* transactional, idempotent mutation-id ledger.
+*/
+const make$2 = (config) => {
+	const dialect = config.dialect ?? sqlite;
+	const executor = config.executor;
+	const transactional = executor.transactional ?? true;
+	const mutationsTable = config.mutationsTable ?? "sync_mutations";
+	const ph = (index) => dialect.placeholder(index);
+	const q = (id) => dialect.quote(id);
+	const idOf = (collection) => config.tables[collection]?.idColumn ?? "id";
+	const versionFor = (collection, row) => {
+		const column = config.tables[collection]?.versionColumn;
+		return column !== void 0 ? row[column] : versionOf(row);
+	};
+	const readTableOf = (mapping) => mapping.readRelation ?? mapping.table;
+	const isLive = (collection, value) => {
+		const tombstone = config.tables[collection]?.tombstone;
+		return tombstone === void 0 || !test(tombstone, value);
+	};
+	const foreignKinds = Object.fromEntries(Object.entries(config.tables).flatMap(([collection, mapping]) => mapping.kinds === void 0 ? [] : [[collection, mapping.kinds]]));
+	const booleanColumns = Object.fromEntries(Object.entries(config.tables).map(([collection, mapping]) => [collection, Object.entries(mapping.kinds ?? {}).filter(([, kind]) => kind === "boolean").map(([field]) => field)]));
+	const decodeRow = (collection, row) => {
+		let decoded;
+		Arr.forEach(booleanColumns[collection] ?? [], (field) => {
+			const value = row[field];
+			if (value !== 0 && value !== 1) return;
+			decoded ??= { ...row };
+			decoded[field] = value === 1;
+		});
+		return decoded ?? row;
+	};
+	const resolveExistsNode = (node) => {
+		const mapping = config.tables[node.collection];
+		if (mapping === void 0) return Effect.succeed([]);
+		const where = compileWhere(node.where, dialect, {
+			kinds: mapping.kinds,
+			foreignKinds
+		});
+		return executor.query({
+			text: `SELECT DISTINCT ${q(node.foreignField)} FROM ${q(readTableOf(mapping))} WHERE ${where.text}`,
+			params: where.params
+		}).pipe(Effect.map((rows) => rows.flatMap((row) => {
+			const decoded = decodeRow(node.collection, row);
+			if (!isLive(node.collection, decoded)) return [];
+			const value = decoded[node.foreignField];
+			return isNullish(value) ? [] : [value];
+		})));
+	};
+	const entriesOf = (subset, where, rows) => {
+		const idColumn = idOf(subset.collection);
+		const values = rows.map((row) => ({
+			id: String(row[idColumn]),
+			value: decodeRow(subset.collection, row)
+		})).filter((row) => isLive(subset.collection, row.value));
+		return apply(values, {
+			...subset,
+			where
+		}).map((row) => ({
+			id: row.id,
+			version: versionFor(subset.collection, row.value)
+		}));
+	};
+	const evaluate = (_context, subset) => Effect.gen(function* () {
+		const mapping = config.tables[subset.collection];
+		if (mapping === void 0) return [];
+		const where = yield* resolveExists(subset.where, resolveExistsNode);
+		const rows = yield* executor.query(compileSelect({
+			table: readTableOf(mapping),
+			where,
+			dialect,
+			kinds: mapping.kinds,
+			foreignKinds
+		}));
+		return entriesOf(subset, where, rows);
+	});
+	const columnCache = MutableHashMap.empty();
+	const columnsOf = (union, relation) => {
+		if (P.isTagged(union, "Json")) return Effect.succeed([]);
+		return Option.match(MutableHashMap.get(columnCache, relation), {
+			onSome: Effect.succeed,
+			onNone: () => executor.query(union.columnsOf(relation)).pipe(Effect.map((rows) => rows.map((row) => String(row["name"]))), Effect.tap((columns) => Effect.sync(() => {
+				if (Arr.isReadonlyArrayNonEmpty(columns)) MutableHashMap.set(columnCache, relation, columns);
+			})))
+		});
+	};
+	const manyArm = (union) => (subset, index) => {
+		const mapping = config.tables[subset.collection];
+		if (mapping === void 0) return Effect.succeedNone;
+		return Effect.all({
+			where: resolveExists(subset.where, resolveExistsNode),
+			columns: columnsOf(union, readTableOf(mapping))
+		}, { concurrency: 1 }).pipe(Effect.map(({ where, columns }) => Option.some({
+			index,
+			subset,
+			mapping,
+			where,
+			columns
+		})));
+	};
+	const projection = (union, arm, width) => {
+		const alias = q(MANY_ROW_ALIAS);
+		if (P.isTagged(union, "Json")) return `${union.rowJson(alias)} AS ${q("row")}`;
+		return Arr.makeBy(width, (position) => {
+			const column = arm.columns[position];
+			return `${column === void 0 ? "NULL" : `${alias}.${q(column)}`} AS ${q(`c${position}`)}`;
+		}).join(", ");
+	};
+	const readManyRow = (union, arms) => (row) => Effect.gen(function* () {
+		const { subset } = yield* decodeManyIndex(row);
+		if (P.isTagged(union, "Json")) {
+			const text = String(row["row"]);
+			return {
+				subset,
+				row: yield* decodeManyJson(text),
+				inexact: inexactColumns(text)
+			};
+		}
+		const columns = Option.match(arms[subset] ?? Option.none(), {
+			onNone: () => [],
+			onSome: (arm) => arm.columns
+		});
+		return {
+			subset,
+			row: R.fromEntries(columns.map((name, position) => [name, row[`c${position}`]])),
+			inexact: Arr.empty()
+		};
+	});
+	const warnedInexact = MutableHashSet.empty();
+	const warnInexact = ({ collection, column }) => Effect.suspend(() => {
+		const key = `${collection}\u0000${column}`;
+		if (MutableHashSet.has(warnedInexact, key)) return Effect.void;
+		MutableHashSet.add(warnedInexact, key);
+		const message = `evaluateMany: column "${column}" of collection "${collection}" holds a number JSON cannot carry exactly, so the pull falls back to one evaluate per subset; declare it integer, double precision or text in the read relation`;
+		return Effect.logWarning(message, new InexactJsonNumber({
+			message,
+			collection,
+			column
+		}));
+	});
+	const evaluateMany = (union) => ((context, subsets) => Effect.gen(function* () {
+		const arms = yield* Effect.forEach(subsets, manyArm(union), { concurrency: 1 });
+		const present = Arr.getSomes(arms);
+		const width = Math.max(0, ...present.map((arm) => arm.columns.length));
+		const [params, texts] = Arr.mapAccum(present, [], (bound, arm) => {
+			const offset = bound.length;
+			const compiled = compileWhere(arm.where, {
+				...dialect,
+				placeholder: (bind) => dialect.placeholder(offset + bind)
+			}, {
+				kinds: arm.mapping.kinds,
+				foreignKinds
+			});
+			const relation = q(readTableOf(arm.mapping));
+			return [[...bound, ...compiled.params], `SELECT ${arm.index} AS ${q("subset")}, ${projection(union, arm, width)} FROM ${relation} AS ${q(MANY_ROW_ALIAS)} WHERE ${compiled.text}`];
+		});
+		const rows = Arr.isReadonlyArrayNonEmpty(texts) ? yield* executor.query({
+			text: texts.join(" UNION ALL "),
+			params
+		}) : [];
+		const read = yield* Effect.forEach(rows, readManyRow(union, arms), { concurrency: 1 });
+		const inexact = read.flatMap((row) => row.inexact.map((column) => ({
+			collection: subsets[row.subset]?.collection ?? "",
+			column
+		})));
+		if (Arr.isReadonlyArrayNonEmpty(inexact)) {
+			yield* Effect.forEach(inexact, warnInexact, {
+				concurrency: 1,
+				discard: true
+			});
+			return yield* Effect.forEach(subsets, (subset) => evaluate(context, subset), { concurrency: 1 });
+		}
+		const bySubset = Arr.groupBy(read, (row) => String(row.subset));
+		return arms.map((arm) => Option.match(arm, {
+			onNone: () => [],
+			onSome: ({ index, subset, where }) => entriesOf(subset, where, (bySubset[String(index)] ?? []).map((row) => row.row))
+		}));
+	}));
+	const queryRowsById = (collection, ids) => {
+		const mapping = config.tables[collection];
+		if (mapping === void 0 || Arr.isReadonlyArrayEmpty(ids)) return Effect.succeed([]);
+		return executor.query(compileSelect({
+			table: readTableOf(mapping),
+			where: isIn(idOf(collection), [...ids]),
+			dialect,
+			kinds: mapping.kinds
+		})).pipe(Effect.map((rows) => rows.map((row) => decodeRow(collection, row)).filter((row) => isLive(collection, row))));
+	};
+	const getRows = (_context, collection, ids) => queryRowsById(collection, ids).pipe(Effect.map((rows) => rows.map((row) => ({
+		id: String(row[idOf(collection)]),
+		version: versionFor(collection, row),
+		value: row
+	}))));
+	const rowValuesFor = (collection, ids) => queryRowsById(collection, ids).pipe(Effect.map((rows) => rows.map((row) => ({
+		id: String(row[idOf(collection)]),
+		value: row
+	}))));
+	const enrichHint = (hint) => config.tables[hint.collection] === void 0 ? Effect.succeed(hint) : rowValuesFor(hint.collection, hint.ids).pipe(Effect.map((values) => ({
+		...hint,
+		values
+	})));
+	const readLastIds = (clientGroupId) => executor.query({
+		text: `SELECT ${q("client_id")}, ${q("last_mutation_id")} FROM ${q(mutationsTable)} WHERE ${q("client_group_id")} = ${ph(1)}`,
+		params: [clientGroupId]
+	}).pipe(Effect.map((rows) => Object.fromEntries(rows.map((row) => [String(row.client_id), Number(row.last_mutation_id)]))));
+	const readLedger = (clientGroupId) => executor.query({
+		text: `SELECT ${q("client_id")}, ${q("last_mutation_id")}, ${q("rejections")} FROM ${q(mutationsTable)} WHERE ${q("client_group_id")} = ${ph(1)}`,
+		params: [clientGroupId]
+	}).pipe(Effect.mapError((cause) => new BackendError({
+		message: `The mutation ledger "${mutationsTable}" could not be read with its "rejections" column. If the column is missing, check for it, then run \`ALTER TABLE ${mutationsTable} ADD COLUMN rejections TEXT\` (the sql README's "Ledger without the \`rejections\` column" section).`,
+		cause
+	})), Effect.flatMap((rows) => Effect.forEach(rows, (row) => decodeRejections(row.rejections, mutationsTable).pipe(Effect.map((rejections) => [String(row.client_id), {
+		last: Number(row.last_mutation_id),
+		rejections
+	}])))), Effect.map((entries) => new Map(entries)));
+	const writeRejections = (clientGroupId, clientId, rejections) => executor.run({
+		text: `UPDATE ${q(mutationsTable)} SET ${q("rejections")} = ${ph(1)} WHERE ${q("client_group_id")} = ${ph(2)} AND ${q("client_id")} = ${ph(3)}`,
+		params: [
+			encodeRejections(rejections),
+			clientGroupId,
+			clientId
+		]
+	});
+	const recordRejection = (clientGroupId, clientId, mutationId, reason) => Effect.gen(function* () {
+		yield* ensureLedgerRow(clientGroupId, clientId);
+		const row = (yield* readLedger(clientGroupId)).get(clientId);
+		const rejections = new Map(row?.rejections ?? []);
+		rejections.set(mutationId, reason);
+		yield* writeRejections(clientGroupId, clientId, rejections);
+	});
+	const forgetRejections = (clientGroupId, floors) => Effect.gen(function* () {
+		if (floors.size === 0) return;
+		const ledger = yield* readLedger(clientGroupId);
+		yield* Effect.forEach(floors, ([clientId, floor]) => Effect.gen(function* () {
+			const row = ledger.get(clientId);
+			if (row === void 0 || row.rejections.size === 0) return;
+			const kept = new Map([...row.rejections].filter(([mutationId]) => mutationId >= floor));
+			if (kept.size !== row.rejections.size) yield* writeRejections(clientGroupId, clientId, kept);
+		}), {
+			concurrency: 1,
+			discard: true
+		});
+	});
+	const ensureLedgerRow = (clientGroupId, clientId) => executor.run({
+		text: `INSERT INTO ${q(mutationsTable)} (${q("client_group_id")}, ${q("client_id")}, ${q("last_mutation_id")}) VALUES (${ph(1)}, ${ph(2)}, 0) ON CONFLICT (${q("client_group_id")}, ${q("client_id")}) DO NOTHING`,
+		params: [clientGroupId, clientId]
+	});
+	const claimLedger = (clientGroupId, clientId, mutationId) => executor.query({
+		text: `UPDATE ${q(mutationsTable)} SET ${q("last_mutation_id")} = ${ph(1)} WHERE ${q("client_group_id")} = ${ph(2)} AND ${q("client_id")} = ${ph(3)} AND ${q("last_mutation_id")} = ${ph(4)} RETURNING ${q("last_mutation_id")}`,
+		params: [
+			mutationId,
+			clientGroupId,
+			clientId,
+			mutationId - 1
+		]
+	}).pipe(Effect.map((rows) => Arr.isReadonlyArrayNonEmpty(rows)));
+	const unitOf = (batch, mutation, staleRejection) => {
+		const savepoint = q(`legation_sp_${batch.savepoints.next}`);
+		batch.savepoints.next += 1;
+		return {
+			context: batch.context,
+			mutation,
+			savepoint,
+			staleRejection
+		};
+	};
+	const openClaimFirst = (batch, mutation) => Effect.gen(function* () {
+		const { clientGroupId } = batch.context;
+		yield* ensureLedgerRow(clientGroupId, mutation.clientId);
+		if (yield* claimLedger(clientGroupId, mutation.clientId, mutation.mutationId)) return {
+			_tag: "Opened",
+			unit: unitOf(batch, mutation, false)
+		};
+		const row = (yield* readLedger(clientGroupId)).get(mutation.clientId);
+		return {
+			_tag: "Watermark",
+			lastMutationId: row?.last ?? 0,
+			rejection: Option.fromUndefinedOr(row?.rejections.get(mutation.mutationId))
+		};
+	});
+	const openBumpAfter = (batch, mutation) => readLedger(batch.context.clientGroupId).pipe(Effect.map((ledger) => {
+		const row = ledger.get(mutation.clientId);
+		const last = row?.last ?? 0;
+		return mutation.mutationId === last + 1 ? {
+			_tag: "Opened",
+			unit: unitOf(batch, mutation, row?.rejections.has(mutation.mutationId) === true)
+		} : {
+			_tag: "Watermark",
+			lastMutationId: last,
+			rejection: Option.fromUndefinedOr(row?.rejections.get(mutation.mutationId))
+		};
+	}));
+	const bumpLastId = (clientGroupId, clientId, mutationId) => executor.run({
+		text: `INSERT INTO ${q(mutationsTable)} (${q("client_group_id")}, ${q("client_id")}, ${q("last_mutation_id")}) VALUES (${ph(1)}, ${ph(2)}, ${ph(3)}) ON CONFLICT (${q("client_group_id")}, ${q("client_id")}) DO UPDATE SET ${q("last_mutation_id")} = ` + dialect.greatest(`${q(mutationsTable)}.${q("last_mutation_id")}`, `excluded.${q("last_mutation_id")}`),
+		params: [
+			clientGroupId,
+			clientId,
+			mutationId
+		]
+	});
+	const releaseClaim = (clientGroupId, clientId, mutationId) => executor.run({
+		text: `UPDATE ${q(mutationsTable)} SET ${q("last_mutation_id")} = ${ph(1)} WHERE ${q("client_group_id")} = ${ph(2)} AND ${q("client_id")} = ${ph(3)} AND ${q("last_mutation_id")} = ${ph(4)}`,
+		params: [
+			mutationId - 1,
+			clientGroupId,
+			clientId,
+			mutationId
+		]
+	}).pipe(Effect.ignore);
+	const runHandler = (unit, handler, mutation) => Effect.gen(function* () {
+		const definition = config.mutators.get(mutation.mutator);
+		if (definition === void 0) return yield* make$3(mutation.mutator);
+		const args = yield* decodeArgs(definition, mutation.args, mutation.mutator);
+		yield* executor.run({
+			text: `SAVEPOINT ${unit.savepoint}`,
+			params: []
+		});
+		return yield* handler(args, executor, unit.context);
+	});
+	const commitOutcome = (unit, outcome) => Effect.gen(function* () {
+		const { clientGroupId } = unit.context;
+		const { clientId, mutationId } = unit.mutation;
+		if (outcome._tag === "Rejected") {
+			yield* executor.run({
+				text: `ROLLBACK TO SAVEPOINT ${unit.savepoint}`,
+				params: []
+			});
+			yield* executor.run({
+				text: `RELEASE SAVEPOINT ${unit.savepoint}`,
+				params: []
+			});
+			yield* recordRejection(clientGroupId, clientId, mutationId, outcome.reason);
+		} else {
+			yield* executor.run({
+				text: `RELEASE SAVEPOINT ${unit.savepoint}`,
+				params: []
+			});
+			if (!transactional && unit.staleRejection) {
+				const row = (yield* readLedger(clientGroupId)).get(clientId);
+				const rejections = new Map(row?.rejections ?? []);
+				rejections.delete(mutationId);
+				yield* writeRejections(clientGroupId, clientId, rejections);
+			}
+		}
+		if (!transactional) yield* bumpLastId(clientGroupId, clientId, mutationId);
+		return { _tag: "Committed" };
+	});
+	const serializable = transactional ? dialect.serializable : void 0;
+	const atomically = (_context, effect) => executor.transaction(serializable === void 0 ? effect : executor.run({
+		text: serializable,
+		params: []
+	}).pipe(Effect.mapError((cause) => new BackendError({
+		message: "SERIALIZABLE isolation could not be set for this mutation batch. On PostgreSQL the executor's transaction must be top-level, with this statement first: SET TRANSACTION fails inside a nested transaction (a savepoint) or after another statement.",
+		cause
+	})), Effect.andThen(effect)));
+	const applyMutations = transaction({
+		handlers: config.handlers,
+		atomically,
+		maxAttempts: 1,
+		begin: (context, floors) => forgetRejections(context.clientGroupId, floors).pipe(Effect.as({
+			context,
+			savepoints: { next: 0 }
+		})),
+		open: transactional ? openClaimFirst : openBumpAfter,
+		run: runHandler,
+		commit: commitOutcome,
+		release: transactional ? (unit) => releaseClaim(unit.context.clientGroupId, unit.mutation.clientId, unit.mutation.mutationId) : () => Effect.void,
+		finish: ({ context }, applied) => Effect.all({
+			lastMutationIds: readLastIds(context.clientGroupId),
+			hints: Effect.forEach(applied.flat(), enrichHint)
+		}, { concurrency: 1 })
+	});
+	const rememberedRejections = (clientGroupId) => readLedger(clientGroupId).pipe(Effect.map((ledger) => [...ledger].flatMap(([clientId, row]) => [...row.rejections].map(([mutationId, reason]) => ({
+		clientId,
+		mutationId,
+		reason
+	})))));
+	return Backend.of({
+		applyMutations,
+		lastMutationIds: (context) => readLastIds(context.clientGroupId),
+		rejections: (context) => rememberedRejections(context.clientGroupId),
+		evaluate,
+		evaluateMany: dialect.unionRows === void 0 ? void 0 : evaluateMany(dialect.unionRows),
+		getRows
+	});
+};
+// src/sql/PollingHintSource.ts
+/**
+* PollingHintSource
+*
+* A tier-2 change-data-capture hint source (ADR-0019): a scoped fibre polls
+* each configured table on an interval for a cheap change-detector and, when a
+* table's detector moves between polls, publishes a value-less `ChangeHint` for
+* that collection to the InvalidationBus. Out-of-band writes (cron jobs, admin
+* tools, another service, psql) that never went through a mutator therefore
+* still poke subscribed clients, at a bounded staleness of one poll interval.
+*
+* It uses only the existing `SqlExecutor` seam — no new driver dependency
+* (ADR-0006) — so any backend that can already run the `SqlBackend` can also run
+* this.
+*
+* The published hint is value-less (`ids: []`), so the #42 fan-out matcher falls
+* back to a collection-level match: every group subscribed to the collection is
+* poked and the next pull reconciles. That is sound — over-matching a poke costs
+* an empty pull; poke is never a correctness dependency (ADR-0009).
+*
+* Detector coverage (be honest about it): the detector is
+* `SELECT COUNT(*) AS n, MAX(version) AS v` when a `versionColumn` is mapped,
+* else `SELECT COUNT(*) AS n`. `COUNT(*) + MAX(version)` catches inserts,
+* deletes, and version-bumping updates. A table with NO monotonic
+* `versionColumn` can only detect row-count changes: an in-place update that
+* keeps the row count and has no version column is missed. Map a `versionColumn`
+* (or an `updated_at`) for full coverage.
+*/
+var PollingHintSource_exports = /* @__PURE__ */ __exportAll({ make: () => make$1 });
+const quote = sqlite.quote;
+/**
+* The cheap change-detector query for a table: count plus (if a version column
+* is mapped) its running maximum.
+*/
+const detectorQuery = (mapping) => {
+	const table = quote(mapping.table);
+	return mapping.versionColumn !== void 0 ? {
+		text: `SELECT COUNT(*) AS n, MAX(${quote(mapping.versionColumn)}) AS v FROM ${table}`,
+		params: []
+	} : {
+		text: `SELECT COUNT(*) AS n FROM ${table}`,
+		params: []
+	};
+};
+/** Collapse a detector row to a comparable signature `${count}|${maxVersion}`. */
+const signatureOf = (rows) => {
+	const row = rows[0] ?? {};
+	const version = row.v === void 0 || row.v === null ? "" : String(row.v);
+	return `${String(row.n ?? 0)}|${version}`;
+};
+/**
+* A `HintSource` that polls each mapped table for a cheap change detector and publishes a hint
+* when a collection changes out of band.
+*/
+const make$1 = (config) => {
+	const collections = config.collections ?? Object.keys(config.tables);
+	const signatureFor = (collection) => {
+		const mapping = config.tables[collection];
+		if (mapping === void 0) return Effect.succeed(void 0);
+		return config.executor.query(detectorQuery(mapping)).pipe(Effect.map(signatureOf));
+	};
+	const tick = (bus, state) => Effect.gen(function* () {
+		const previous = yield* Ref.get(state);
+		const next = new Map(previous);
+		const changed = [];
+		yield* Effect.forEach(collections, (collection) => Effect.gen(function* () {
+			const signature = yield* signatureFor(collection);
+			if (signature === void 0) return;
+			if (previous.has(collection) && previous.get(collection) !== signature) changed.push({
+				collection,
+				ids: []
+			});
+			next.set(collection, signature);
+		}), {
+			concurrency: 1,
+			discard: true
+		});
+		yield* Ref.set(state, next);
+		yield* bus.publish(changed);
+	});
+	return { run: Effect.flatMap(InvalidationBus, (bus) => Effect.gen(function* () {
+		const state = yield* Ref.make(/* @__PURE__ */ new Map());
+		yield* Effect.forkScoped(tick(bus, state).pipe(Effect.catch(() => Effect.void), Effect.repeat(Schedule.spaced(config.interval))));
+	})) };
+};
+// src/sql/PgExecutor.ts
+/**
+* PgExecutor
+*
+* A `SqlBackend` executor over a PostgreSQL `SqlClient` from `effect/sql`
+* (#203). Pair it with `dialect: Sql.postgres`:
+*
+* ```ts
+* const sql = yield* SqlClient; // from `PgClient.layer(...)` (`@effect/sql-pg`)
+* const backend = SqlBackend.make({
+*   executor: PgExecutor.make(sql),
+*   dialect: Sql.postgres,
+*   tables,
+*   mutators,
+*   handlers,
+* });
+* ```
+*
+* The executor needs only the `SqlClient` service, which ships in `effect`
+* itself, so this package gains no dependency (ADR-0006): the driver
+* (`@effect/sql-pg`) and its connection settings are the app's choice, and it
+* provides the `SqlClient` layer.
+*
+* **Transactions:** `transaction` is the client's `withTransaction`, so each
+* mutation batch is one real PostgreSQL transaction on one connection, and
+* `SqlBackend` claims each mutation id in the same transaction as its handler's
+* writes. `Sql.postgres` sets SERIALIZABLE as the transaction's first
+* statement, so a handler that read a row another transaction then changed is
+* refused with SQLSTATE 40001 and rolled back; that surfaces as a
+* `BackendError`, which the client retries. The transaction must be top-level:
+* calling the backend inside an outer `withTransaction` makes this a savepoint,
+* where PostgreSQL refuses `SET TRANSACTION` and the batch fails instead.
+*
+* **Statements run unprepared** (`.unprepared`): each is parsed per call rather
+* than cached by name on the connection. A transaction-mode pooler in front of
+* the database (PgBouncer, a managed pooler) can hand consecutive statements to
+* different server connections, where a named statement prepared on one does not
+* exist on the next. The cost is a parse per statement.
+*/
+var PgExecutor_exports = /* @__PURE__ */ __exportAll({ make: () => make });
+const asBackendError = (message) => (cause) => new BackendError({
+	message,
+	cause
+});
+/**
+* The executor over `sql`: unprepared statements, and a real transaction per `transaction` call.
+*
+* A failed statement or transaction fails as a `BackendError` that carries the driver's `SqlError`
+* as its `cause` (a serialization refusal included), with the statement text, never its parameters,
+* in the message.
+*/
+const make = (sql) => ({
+	query: (fragment) => sql.unsafe(fragment.text, fragment.params).unprepared.pipe(Effect.mapError(asBackendError(`query failed: ${fragment.text}`))),
+	run: (fragment) => sql.unsafe(fragment.text, fragment.params).unprepared.pipe(Effect.asVoid, Effect.mapError(asBackendError(`statement failed: ${fragment.text}`))),
+	transaction: (effect) => sql.withTransaction(effect).pipe(Effect.catchTag("SqlError", (error) => Effect.fail(asBackendError("transaction failed")(error))))
+});
+export { PgExecutor_exports as PgExecutor, PollingHintSource_exports as PollingHintSource, Sql_exports as Sql, SqlBackend_exports as SqlBackend };
+
+//# sourceMappingURL=index.js.map