@sqlite-sync/ai 0.8.2 → 0.9.1

package/dist/index.js

@@ -1,401 +1,495 @@
-// src/db-access.ts
-import {
-  CrdtEventValidationError,
-  generateId
-} from "@sqlite-sync/core";
-
-// src/query-guard.ts
+import { CrdtEventValidationError, generateId } from "@sqlite-sync/core";
+import { jsonSchema, tool } from "ai";
+//#region src/policy.ts
+/**
+* Flattens the AI access declared on the schema's table builders into the lookups the doc
+* generator and the enforcement points share, so they cannot disagree. Access is table-level:
+* see {@link AiAccess}.
+*/
+function resolveAiPolicy(opts) {
+	const tables = opts.syncDbSchema.tablesConfig.map(({ crdtTableName, baseTableName }) => ({
+		crdtTableName,
+		baseTableName,
+		access: opts.syncDbSchema.tables[crdtTableName].aiAccess
+	}));
+	const byName = /* @__PURE__ */ new Map();
+	for (const table of tables) {
+		byName.set(table.crdtTableName, table);
+		byName.set(table.baseTableName, table);
+	}
+	return {
+		tables,
+		hasHiddenTables: tables.some((table) => table.access === "hidden"),
+		readableBaseTableNames: tables.filter((table) => table.access !== "hidden").map((table) => table.baseTableName),
+		tableAccess(dataset) {
+			return byName.get(dataset)?.access ?? "hidden";
+		}
+	};
+}
+//#endregion
+//#region src/query-guard.ts
 var QueryGuardError = class extends Error {
-  rejection;
-  constructor(rejection) {
-    super(rejection.message);
-    this.name = "QueryGuardError";
-    this.rejection = rejection;
-  }
+	rejection;
+	constructor(rejection) {
+		super(rejection.message);
+		this.name = "QueryGuardError";
+		this.rejection = rejection;
+	}
 };
-var WRITE_OPCODES = /* @__PURE__ */ new Set([
-  "OpenWrite",
-  "Clear",
-  "Destroy",
-  "CreateBtree",
-  "SqlExec",
-  "ParseSchema",
-  "DropTable",
-  "DropIndex",
-  "DropTrigger",
-  "SetCookie",
-  "JournalMode",
-  "Vacuum",
-  "IncrVacuum",
-  "Checkpoint",
-  "MaxPgcnt",
-  "Expire",
-  "AutoCommit",
-  "VUpdate",
-  "VCreate",
-  "VDestroy",
-  "Program"
+/**
+* Opcodes that prove a statement is not read-only. `OpenWrite` covers row-level writes (every
+* real-table mutation opens its cursor through it), `Clear`/`Destroy` cover whole-table
+* deletes that skip cursors (truncate optimization), the rest cover DDL, pragma-class
+* statements (which a transaction rollback would NOT undo), virtual-table writes, and trigger
+* subprograms. `Insert`/`Delete`/`IdxInsert` are deliberately absent — they also run against
+* ephemeral/sorter cursors in ordinary SELECTs (DISTINCT, ORDER BY) and are only dangerous on
+* a cursor an `OpenWrite` would have created.
+*/
+const WRITE_OPCODES = /* @__PURE__ */ new Set([
+	"OpenWrite",
+	"Clear",
+	"Destroy",
+	"CreateBtree",
+	"SqlExec",
+	"ParseSchema",
+	"DropTable",
+	"DropIndex",
+	"DropTrigger",
+	"SetCookie",
+	"JournalMode",
+	"Vacuum",
+	"IncrVacuum",
+	"Checkpoint",
+	"MaxPgcnt",
+	"Expire",
+	"AutoCommit",
+	"VUpdate",
+	"VCreate",
+	"VDestroy",
+	"Program"
 ]);
-var READ_STATEMENT_PREFIXES = ["select", "with", "values"];
+/**
+* Opcodes that open a b-tree cursor for reading. `p2` is the root page of the table or index
+* and `p3` the database it lives in (0 = main), which is how a statement's real table set is
+* recovered — views are already flattened into their base tables by the time bytecode exists,
+* so aliases, CTEs, subqueries and quoting tricks all resolve here.
+*/
+const READ_CURSOR_OPCODES = /* @__PURE__ */ new Set(["OpenRead", "ReopenIdx"]);
+/**
+* Table-valued pragma functions (`pragma_table_list()`, ...) read the schema through a virtual
+* table, so no root page identifies them. They expose names and columns rather than rows, but a
+* hidden table should not be enumerable either, so they are rejected outright when restricted.
+*/
+const PRAGMA_FUNCTION_PATTERN = /\bpragma_[a-z_]+\s*\(/i;
+const READ_STATEMENT_PREFIXES = [
+	"select",
+	"with",
+	"values"
+];
 function createQueryGuard(opts) {
-  function reject(code, message) {
-    return { allowed: false, code, message };
-  }
-  function check(input) {
-    let body = input.sql.trim();
-    while (body.endsWith(";")) {
-      body = body.slice(0, -1).trimEnd();
-    }
-    if (body.includes(";")) {
-      return reject(
-        "multi-statement",
-        "Only a single SQL statement is allowed per query, and semicolons are only allowed at the very end. If the semicolon is inside a string literal, pass the value as a bound parameter instead."
-      );
-    }
-    const lowered = body.toLowerCase();
-    if (!READ_STATEMENT_PREFIXES.some((keyword) => lowered.startsWith(keyword))) {
-      return reject(
-        "invalid-statement",
-        "Only read-only queries are allowed: the statement must start directly with SELECT, WITH, or VALUES (no leading comments)."
-      );
-    }
-    let operations;
-    try {
-      operations = opts.executor.execute({
-        sql: `EXPLAIN ${input.sql}`,
-        parameters: input.parameters ?? []
-      }).rows;
-    } catch (error) {
-      return reject("invalid-sql", `SQL error: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    for (const operation of operations) {
-      if (WRITE_OPCODES.has(operation.opcode)) {
-        return reject(
-          "write-detected",
-          `The statement was rejected because it would modify the database (${operation.opcode}). This tool is strictly read-only; rewrite the query as a pure SELECT.`
-        );
-      }
-    }
-    return { allowed: true };
-  }
-  return {
-    check,
-    execute(input) {
-      const verdict = check(input);
-      if (!verdict.allowed) {
-        throw new QueryGuardError(verdict);
-      }
-      return runWithForcedRollback(opts.executor, (tx) => {
-        return tx.execute({ sql: input.sql, parameters: input.parameters ?? [] });
-      });
-    }
-  };
+	const readableTables = opts.readableTables ? new Set(opts.readableTables.map((name) => name.toLowerCase())) : null;
+	const readableTablesLabel = opts.readableTables?.join(", ") ?? "";
+	/**
+	* Root page to table name, for every b-tree in the main database. Re-read per query instead of
+	* cached: a migration can drop a table and hand its root page to another one, and a stale map
+	* would then resolve that page to the wrong (possibly allowed) name.
+	*/
+	function readRootPages() {
+		const rows = opts.executor.execute({
+			sql: `SELECT "tbl_name", "rootpage" FROM "sqlite_master" WHERE "rootpage" IS NOT NULL AND "rootpage" > 0`,
+			parameters: []
+		}).rows;
+		return new Map(rows.map((row) => [Number(row.rootpage), row.tbl_name]));
+	}
+	function checkReadableTables(sql, operations) {
+		if (!readableTables) return null;
+		if (PRAGMA_FUNCTION_PATTERN.test(sql)) return reject("table-denied", `Pragma functions are not available. You can only read these tables: ${readableTablesLabel}.`);
+		const cursors = operations.filter((operation) => READ_CURSOR_OPCODES.has(operation.opcode));
+		if (cursors.length === 0) return null;
+		let rootPages;
+		try {
+			rootPages = readRootPages();
+		} catch {
+			return reject("table-denied", "The tables this statement reads could not be verified, so it was rejected.");
+		}
+		for (const cursor of cursors) {
+			const name = Number(cursor.p3) === 0 ? rootPages.get(Number(cursor.p2)) : void 0;
+			if (!name || !readableTables.has(name.toLowerCase())) return reject("table-denied", `${name ? `Table "${name}"` : "A table this statement reads"} is not available to you. You can only read these tables: ${readableTablesLabel}.`);
+		}
+		return null;
+	}
+	function reject(code, message) {
+		return {
+			allowed: false,
+			code,
+			message
+		};
+	}
+	function check(input) {
+		let body = input.sql.trim();
+		while (body.endsWith(";")) body = body.slice(0, -1).trimEnd();
+		if (body.includes(";")) return reject("multi-statement", "Only a single SQL statement is allowed per query, and semicolons are only allowed at the very end. If the semicolon is inside a string literal, pass the value as a bound parameter instead.");
+		const lowered = body.toLowerCase();
+		if (!READ_STATEMENT_PREFIXES.some((keyword) => lowered.startsWith(keyword))) return reject("invalid-statement", "Only read-only queries are allowed: the statement must start directly with SELECT, WITH, or VALUES (no leading comments).");
+		let operations;
+		try {
+			operations = opts.executor.execute({
+				sql: `EXPLAIN ${input.sql}`,
+				parameters: input.parameters ?? []
+			}).rows;
+		} catch (error) {
+			return reject("invalid-sql", `SQL error: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		for (const operation of operations) if (WRITE_OPCODES.has(operation.opcode)) return reject("write-detected", `The statement was rejected because it would modify the database (${operation.opcode}). This tool is strictly read-only; rewrite the query as a pure SELECT.`);
+		const denied = checkReadableTables(body, operations);
+		if (denied) return denied;
+		return { allowed: true };
+	}
+	return {
+		check,
+		execute(input) {
+			const verdict = check(input);
+			if (!verdict.allowed) throw new QueryGuardError(verdict);
+			return runWithForcedRollback(opts.executor, (tx) => {
+				return tx.execute({
+					sql: input.sql,
+					parameters: input.parameters ?? []
+				});
+			});
+		}
+	};
 }
+/**
+* Runs `callback` in a transaction that is always rolled back (via a sentinel throw, relying
+* on the {@link AiDbExecutor} contract that a throwing callback rolls back). This is the
+* unconditional write guard backing any gap in the static analysis.
+*/
 function runWithForcedRollback(executor, callback) {
-  let result;
-  let completed = false;
-  const rollbackSentinel = new Error("forced read-only rollback");
-  try {
-    executor.transaction((tx) => {
-      result = callback(tx);
-      completed = true;
-      throw rollbackSentinel;
-    });
-  } catch (error) {
-    if (error !== rollbackSentinel) {
-      throw error;
-    }
-  }
-  if (!completed) {
-    throw new Error("Transaction completed without running the callback");
-  }
-  return result;
+	let result;
+	let completed = false;
+	const rollbackSentinel = /* @__PURE__ */ new Error("forced read-only rollback");
+	try {
+		executor.transaction((tx) => {
+			result = callback(tx);
+			completed = true;
+			throw rollbackSentinel;
+		});
+	} catch (error) {
+		if (error !== rollbackSentinel) throw error;
+	}
+	if (!completed) throw new Error("Transaction completed without running the callback");
+	return result;
 }
-
-// src/schema-doc.ts
-var SCHEMA_DOC_PREAMBLE = [
-  "This is a synced SQLite database \u2014 data replicates automatically between the user's devices.",
-  "All writes go through a sync event log, which is why the tables listed below are exposed as",
-  "read-only SQL views; soft-deleted rows are already filtered out, so query them directly",
-  "without any tombstone filtering. Every table has a unique `id` text primary key."
+//#endregion
+//#region src/schema-doc.ts
+const SCHEMA_DOC_PREAMBLE = [
+	"This is a synced SQLite database — data replicates automatically between the user's devices.",
+	"All writes go through a sync event log, which is why the tables listed below are exposed as",
+	"read-only SQL views; soft-deleted rows are already filtered out, so query them directly",
+	"without any tombstone filtering. Every table has a unique `id` text primary key."
 ].join("\n");
+const RESTRICTED_READS_NOTE = ["Only the tables documented below are readable. Queries that touch any other table are", "rejected, including the internal sync event log, so there is no change history available."].join("\n");
 function renderColumn(name, meta) {
-  let line = `- \`${name}\` ${meta.sqlType.toUpperCase()}`;
-  if (!meta.nullable) {
-    line += " NOT NULL";
-  }
-  if (meta.kind === "boolean") {
-    line += " (boolean 0/1)";
-  } else if (meta.kind === "enum") {
-    line += ` (one of ${(meta.enumValues ?? []).map((value) => `"${value}"`).join(" | ")})`;
-  }
-  return meta.description ? `${line} \u2014 ${meta.description}` : line;
+	let line = `- \`${name}\` ${meta.sqlType.toUpperCase()}`;
+	if (!meta.nullable) line += " NOT NULL";
+	if (meta.kind === "boolean") line += " (boolean 0/1)";
+	else if (meta.kind === "enum") line += ` (one of ${(meta.enumValues ?? []).map((value) => `"${value}"`).join(" | ")})`;
+	return meta.description ? `${line} — ${meta.description}` : line;
 }
+/**
+* Generates a markdown schema doc for an AI agent from the declared sync schema's table
+* builders — no database access needed. Tables are presented under the view names the agent
+* queries; descriptions come from `.describe()` on the table and column builders.
+* The internal `tombstone` column is omitted.
+*
+* Tables declared `.ai("hidden")` are left out entirely, and read-only ones are labelled so the
+* agent does not attempt a mutation that would be rejected.
+*
+* The doc always includes a built-in preamble explaining sqlite-sync mechanics (read-only
+* views, soft-deletes already filtered) after the consumer's `overview` — consumers only
+* need to describe their own domain.
+*/
 function createSchemaDoc(opts) {
-  const sections = [];
-  const overview = opts.context?.overview?.trim();
-  if (overview) {
-    sections.push(overview);
-  }
-  sections.push(SCHEMA_DOC_PREAMBLE);
-  for (const [crdtTableName, table] of Object.entries(opts.syncDbSchema.tables)) {
-    const lines = [`## ${crdtTableName}`];
-    if (table.description) {
-      lines.push("", table.description.trim());
-    }
-    lines.push("", "Columns:");
-    for (const [name, meta] of Object.entries(table.columns)) {
-      if (name === "tombstone") continue;
-      lines.push(renderColumn(name, meta));
-    }
-    sections.push(lines.join("\n"));
-  }
-  sections.push(CHANGE_HISTORY_DOC);
-  return sections.join("\n\n");
+	const policy = resolveAiPolicy({ syncDbSchema: opts.syncDbSchema });
+	const sections = [];
+	const overview = opts.context?.overview?.trim();
+	if (overview) sections.push(overview);
+	sections.push(SCHEMA_DOC_PREAMBLE);
+	if (policy.hasHiddenTables) sections.push(RESTRICTED_READS_NOTE);
+	for (const [crdtTableName, table] of Object.entries(opts.syncDbSchema.tables)) {
+		const access = policy.tableAccess(crdtTableName);
+		if (access === "hidden") continue;
+		const lines = [`## ${crdtTableName}`];
+		if (table.description) lines.push("", table.description.trim());
+		if (access === "read-only") lines.push("", "Read-only: you can query this table but cannot create, update, or delete its rows.");
+		lines.push("", "Columns:");
+		for (const [name, meta] of Object.entries(table.columns)) {
+			if (name === "tombstone") continue;
+			lines.push(renderColumn(name, meta));
+		}
+		sections.push(lines.join("\n"));
+	}
+	if (!policy.hasHiddenTables) sections.push(CHANGE_HISTORY_DOC);
+	return sections.join("\n\n");
 }
-var CHANGE_HISTORY_DOC = [
-  "## change_history",
-  "",
-  "A read-only, append-only log of every change across all tables, one row per sync event.",
-  "Query it like any other view. Unlike the tables above, soft-delete filtering does NOT apply",
-  "here \u2014 it includes changes to items that were later deleted, so treat it as an audit log.",
-  "",
-  "Columns:",
-  "- `seq` INTEGER NOT NULL \u2014 monotonic sequence number; **order history by this** (ascending = oldest first)",
-  "- `dataset` TEXT NOT NULL \u2014 which table the change applies to (matches a table name above)",
-  "- `item_id` TEXT NOT NULL \u2014 the `id` of the affected row",
-  '- `change_type` TEXT NOT NULL (one of "item-created" | "item-updated" | "item-deleted")',
-  '- `status` TEXT NOT NULL (one of "applied" | "pending" | "failed" | "deduped") \u2014 "applied" took effect; "failed" did not; filter to `status = \'applied\'` for the effective history',
-  '- `origin` TEXT NOT NULL \u2014 where the change came from (e.g. "own", "remote", "local")',
-  "- `timestamp` TEXT NOT NULL \u2014 opaque hybrid-logical-clock string; do NOT parse it as a date, order by `seq` instead",
-  "- `changes` TEXT NOT NULL \u2014 JSON of what the change set: the changed columns only for item-updated, the full initial row for item-created, `{}` for item-deleted. Use `json_extract(changes, '$.column')` to read a field."
+const CHANGE_HISTORY_DOC = [
+	"## change_history",
+	"",
+	"A read-only, append-only log of every change across all tables, one row per sync event.",
+	"Query it like any other view. Unlike the tables above, soft-delete filtering does NOT apply",
+	"here — it includes changes to items that were later deleted, so treat it as an audit log.",
+	"",
+	"Columns:",
+	"- `seq` INTEGER NOT NULL — monotonic sequence number; **order history by this** (ascending = oldest first)",
+	"- `dataset` TEXT NOT NULL — which table the change applies to (matches a table name above)",
+	"- `item_id` TEXT NOT NULL — the `id` of the affected row",
+	"- `change_type` TEXT NOT NULL (one of \"item-created\" | \"item-updated\" | \"item-deleted\")",
+	"- `status` TEXT NOT NULL (one of \"applied\" | \"pending\" | \"failed\" | \"deduped\") — \"applied\" took effect; \"failed\" did not; filter to `status = 'applied'` for the effective history",
+	"- `origin` TEXT NOT NULL — where the change came from (e.g. \"own\", \"remote\", \"local\")",
+	"- `timestamp` TEXT NOT NULL — opaque hybrid-logical-clock string; do NOT parse it as a date, order by `seq` instead",
+	"- `changes` TEXT NOT NULL — JSON of what the change set: the changed columns only for item-updated, the full initial row for item-created, `{}` for item-deleted. Use `json_extract(changes, '$.column')` to read a field."
 ].join("\n");
-
-// src/db-access.ts
+//#endregion
+//#region src/db-access.ts
 function toBase64(bytes) {
-  let binary = "";
-  for (const byte of bytes) {
-    binary += String.fromCharCode(byte);
-  }
-  return btoa(binary);
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
 }
 function createAiDbAccess(opts) {
-  const schemaDoc = createSchemaDoc({ syncDbSchema: opts.syncDbSchema, context: opts.context });
-  const guard = createQueryGuard({ executor: opts.executor });
-  const maxRows = opts.limits?.maxRows ?? 200;
-  const maxCellChars = opts.limits?.maxCellChars ?? 2e3;
-  const access = {
-    getSchemaDoc() {
-      return schemaDoc;
-    },
-    query(input) {
-      let resultRows;
-      try {
-        resultRows = guard.execute(input).rows;
-      } catch (error) {
-        if (error instanceof QueryGuardError) {
-          return { error: error.message };
-        }
-        throw error;
-      }
-      let truncated = resultRows.length > maxRows;
-      function shapeCell(value) {
-        if (value instanceof Uint8Array) {
-          if (Math.ceil(value.byteLength / 3) * 4 <= maxCellChars) {
-            return `<blob base64 ${toBase64(value)}>`;
-          }
-          truncated = true;
-          return `<blob ${value.byteLength} bytes>`;
-        }
-        if (typeof value === "string" && value.length > maxCellChars) {
-          truncated = true;
-          return `${value.slice(0, maxCellChars)}\u2026`;
-        }
-        return value;
-      }
-      const rows = resultRows.slice(0, maxRows).map((row) => Object.fromEntries(Object.entries(row).map(([column, value]) => [column, shapeCell(value)])));
-      return { rows, rowCount: resultRows.length, truncated };
-    }
-  };
-  const storage = opts.storage;
-  if (storage) {
-    access.mutate = (input) => {
-      const errors = [];
-      const createdIds = [];
-      const events = [];
-      for (const [index, event] of input.events.entries()) {
-        if (event.type === "item-created") {
-          const looseEvent = event;
-          const payload = event.payload ?? {};
-          if (looseEvent.item_id !== void 0) {
-            errors.push(`[${index}] item-created events must omit item_id; an id is generated automatically`);
-          }
-          if ("id" in payload) {
-            errors.push(`[${index}] item-created payload must omit id; an id is generated automatically`);
-          }
-          if (looseEvent.item_id !== void 0 || "id" in payload) {
-            continue;
-          }
-          const id = generateId();
-          createdIds.push(id);
-          events.push({
-            type: "item-created",
-            dataset: event.dataset,
-            item_id: id,
-            payload: JSON.stringify({ ...payload, id })
-          });
-          continue;
-        }
-        events.push({
-          type: event.type,
-          dataset: event.dataset,
-          item_id: event.item_id,
-          payload: JSON.stringify(event.payload ?? {})
-        });
-      }
-      if (errors.length > 0) {
-        return { error: `Invalid mutation events: ${errors.join("; ")}`, errors };
-      }
-      try {
-        storage.applyOwnEvents(events);
-      } catch (error) {
-        if (error instanceof CrdtEventValidationError) {
-          return { error: error.message, errors: error.errors };
-        }
-        throw error;
-      }
-      return { applied: true, eventCount: events.length, createdIds };
-    };
-  }
-  return access;
+	const policy = resolveAiPolicy({ syncDbSchema: opts.syncDbSchema });
+	const schemaDoc = createSchemaDoc({
+		syncDbSchema: opts.syncDbSchema,
+		context: opts.context
+	});
+	const guard = createQueryGuard({
+		executor: opts.executor,
+		readableTables: policy.hasHiddenTables ? policy.readableBaseTableNames : void 0
+	});
+	const maxRows = opts.limits?.maxRows ?? 200;
+	const maxCellChars = opts.limits?.maxCellChars ?? 2e3;
+	const access = {
+		getSchemaDoc() {
+			return schemaDoc;
+		},
+		query(input) {
+			let resultRows;
+			try {
+				resultRows = guard.execute(input).rows;
+			} catch (error) {
+				if (error instanceof QueryGuardError) return { error: error.message };
+				throw error;
+			}
+			let truncated = resultRows.length > maxRows;
+			function shapeCell(value) {
+				if (value instanceof Uint8Array) {
+					if (Math.ceil(value.byteLength / 3) * 4 <= maxCellChars) return `<blob base64 ${toBase64(value)}>`;
+					truncated = true;
+					return `<blob ${value.byteLength} bytes>`;
+				}
+				if (typeof value === "string" && value.length > maxCellChars) {
+					truncated = true;
+					return `${value.slice(0, maxCellChars)}…`;
+				}
+				return value;
+			}
+			return {
+				rows: resultRows.slice(0, maxRows).map((row) => Object.fromEntries(Object.entries(row).map(([column, value]) => [column, shapeCell(value)]))),
+				rowCount: resultRows.length,
+				truncated
+			};
+		}
+	};
+	const storage = opts.storage;
+	if (storage) access.mutate = (input) => {
+		const errors = [];
+		const createdIds = [];
+		const events = [];
+		for (const [index, event] of input.events.entries()) {
+			const tableAccess = policy.tableAccess(event.dataset);
+			if (tableAccess === "hidden") {
+				errors.push(`[${index}] unknown or unavailable dataset "${event.dataset}"`);
+				continue;
+			}
+			if (tableAccess === "read-only") {
+				errors.push(`[${index}] dataset "${event.dataset}" is read-only and cannot be modified`);
+				continue;
+			}
+			if (event.type === "item-created") {
+				const looseEvent = event;
+				const payload = event.payload ?? {};
+				if (looseEvent.item_id !== void 0) errors.push(`[${index}] item-created events must omit item_id; an id is generated automatically`);
+				if ("id" in payload) errors.push(`[${index}] item-created payload must omit id; an id is generated automatically`);
+				if (looseEvent.item_id !== void 0 || "id" in payload) continue;
+				const id = generateId();
+				createdIds.push(id);
+				events.push({
+					type: "item-created",
+					dataset: event.dataset,
+					item_id: id,
+					payload: JSON.stringify({
+						...payload,
+						id
+					})
+				});
+				continue;
+			}
+			events.push({
+				type: event.type,
+				dataset: event.dataset,
+				item_id: event.item_id,
+				payload: JSON.stringify(event.payload ?? {})
+			});
+		}
+		if (errors.length > 0) return {
+			error: `Invalid mutation events: ${errors.join("; ")}`,
+			errors
+		};
+		try {
+			storage.applyOwnEvents(events);
+		} catch (error) {
+			if (error instanceof CrdtEventValidationError) return {
+				error: error.message,
+				errors: error.errors
+			};
+			throw error;
+		}
+		return {
+			applied: true,
+			eventCount: events.length,
+			createdIds
+		};
+	};
+	return access;
 }
-
-// src/tools.ts
-import { jsonSchema, tool } from "ai";
-var emptyInputSchema = jsonSchema({
-  type: "object",
-  properties: {},
-  additionalProperties: false
+//#endregion
+//#region src/tools.ts
+const emptyInputSchema = jsonSchema({
+	type: "object",
+	properties: {},
+	additionalProperties: false
 });
-var queryInputSchema = jsonSchema({
-  type: "object",
-  properties: {
-    sql: {
-      type: "string",
-      description: "A single read-only SQLite statement starting with SELECT, WITH, or VALUES. Use ? placeholders for values."
-    },
-    parameters: {
-      type: "array",
-      items: { type: ["string", "number", "boolean", "null"] },
-      description: "Values bound to the ? placeholders, in order."
-    }
-  },
-  required: ["sql"],
-  additionalProperties: false
+const queryInputSchema = jsonSchema({
+	type: "object",
+	properties: {
+		sql: {
+			type: "string",
+			description: "A single read-only SQLite statement starting with SELECT, WITH, or VALUES. Use ? placeholders for values."
+		},
+		parameters: {
+			type: "array",
+			items: { type: [
+				"string",
+				"number",
+				"boolean",
+				"null"
+			] },
+			description: "Values bound to the ? placeholders, in order."
+		}
+	},
+	required: ["sql"],
+	additionalProperties: false
 });
-var mutationInputSchema = jsonSchema({
-  type: "object",
-  properties: {
-    events: {
-      type: "array",
-      minItems: 1,
-      items: {
-        anyOf: [
-          {
-            type: "object",
-            properties: {
-              type: {
-                type: "string",
-                enum: ["item-created"],
-                description: "Create a synced row. Omit item_id and payload.id; the tool generates the id."
-              },
-              dataset: {
-                type: "string",
-                description: "The synced dataset/table name from the schema documentation."
-              },
-              payload: {
-                type: "object",
-                additionalProperties: true,
-                not: { required: ["id"] },
-                description: "Column values for the new row, excluding id. Include all required non-id columns from the schema."
-              }
-            },
-            required: ["type", "dataset", "payload"],
-            additionalProperties: false
-          },
-          {
-            type: "object",
-            properties: {
-              type: {
-                type: "string",
-                enum: ["item-updated", "item-deleted"],
-                description: "Update or delete an existing synced row."
-              },
-              dataset: {
-                type: "string",
-                description: "The synced dataset/table name from the schema documentation."
-              },
-              item_id: {
-                type: "string",
-                description: "The stable id of the row being updated or deleted."
-              },
-              payload: {
-                type: "object",
-                additionalProperties: true,
-                description: "Changed column values for item-updated. Omit or pass {} for item-deleted."
-              }
-            },
-            required: ["type", "dataset", "item_id"],
-            additionalProperties: false
-          }
-        ]
-      },
-      description: "One or more CRDT mutation events to apply atomically."
-    }
-  },
-  required: ["events"],
-  additionalProperties: false
+const mutationInputSchema = jsonSchema({
+	type: "object",
+	properties: { events: {
+		type: "array",
+		minItems: 1,
+		items: { anyOf: [{
+			type: "object",
+			properties: {
+				type: {
+					type: "string",
+					enum: ["item-created"],
+					description: "Create a synced row. Omit item_id and payload.id; the tool generates the id."
+				},
+				dataset: {
+					type: "string",
+					description: "The synced dataset/table name from the schema documentation."
+				},
+				payload: {
+					type: "object",
+					additionalProperties: true,
+					not: { required: ["id"] },
+					description: "Column values for the new row, excluding id. Include all required non-id columns from the schema."
+				}
+			},
+			required: [
+				"type",
+				"dataset",
+				"payload"
+			],
+			additionalProperties: false
+		}, {
+			type: "object",
+			properties: {
+				type: {
+					type: "string",
+					enum: ["item-updated", "item-deleted"],
+					description: "Update or delete an existing synced row."
+				},
+				dataset: {
+					type: "string",
+					description: "The synced dataset/table name from the schema documentation."
+				},
+				item_id: {
+					type: "string",
+					description: "The stable id of the row being updated or deleted."
+				},
+				payload: {
+					type: "object",
+					additionalProperties: true,
+					description: "Changed column values for item-updated. Omit or pass {} for item-deleted."
+				}
+			},
+			required: [
+				"type",
+				"dataset",
+				"item_id"
+			],
+			additionalProperties: false
+		}] },
+		description: "One or more CRDT mutation events to apply atomically."
+	} },
+	required: ["events"],
+	additionalProperties: false
 });
+/**
+* AI SDK tools for a synced database. `access` is a factory because acquiring the database
+* may itself be async per call (e.g. resolving a Durable Object stub from another DO).
+*/
 function createDbTools(opts) {
-  const tools = {
-    getDbSchema: tool({
-      description: "Get the schema documentation for the synced SQLite database: tables, columns, types, and data conventions. Call this before reasoning about the data.",
-      inputSchema: emptyInputSchema,
-      execute: async () => {
-        const access = await opts.access();
-        return await access.getSchemaDoc();
-      }
-    }),
-    queryDb: tool({
-      description: "Run a read-only SQL query against the synced SQLite database. Only a single SELECT/WITH/VALUES statement is allowed \u2014 anything that writes is rejected. Pass values as ? placeholders via `parameters` instead of inlining them as literals. Results are capped; ask for fewer columns or add LIMIT/WHERE if `truncated` is true.",
-      inputSchema: queryInputSchema,
-      execute: async ({ sql, parameters }) => {
-        const access = await opts.access();
-        return await access.query({ sql, parameters });
-      }
-    })
-  };
-  if (opts.mutations) {
-    tools.mutateDb = tool({
-      description: "Apply one or more CRDT mutation events to the synced database. Use this for writes instead of SQL. Query the current data first when updating or deleting existing rows. Create events must omit ids: do not provide item_id or payload.id, because the tool generates ids and returns them. Create payloads must include all required non-id columns, update events should include only changed columns, and delete events should use an empty payload.",
-      inputSchema: mutationInputSchema,
-      execute: async (input) => {
-        const access = await opts.access();
-        if (!access.mutate) {
-          return { error: "Database mutations are not enabled for this access object." };
-        }
-        return await access.mutate(input);
-      }
-    });
-  }
-  return tools;
+	const tools = {
+		getDbSchema: tool({
+			description: "Get the schema documentation for the synced SQLite database: tables, columns, types, and data conventions. Call this before reasoning about the data.",
+			inputSchema: emptyInputSchema,
+			execute: async () => {
+				return await (await opts.access()).getSchemaDoc();
+			}
+		}),
+		queryDb: tool({
+			description: "Run a read-only SQL query against the synced SQLite database. Only a single SELECT/WITH/VALUES statement is allowed — anything that writes is rejected. Pass values as ? placeholders via `parameters` instead of inlining them as literals. Results are capped; ask for fewer columns or add LIMIT/WHERE if `truncated` is true.",
+			inputSchema: queryInputSchema,
+			execute: async ({ sql, parameters }) => {
+				return await (await opts.access()).query({
+					sql,
+					parameters
+				});
+			}
+		})
+	};
+	if (opts.mutations) tools.mutateDb = tool({
+		description: "Apply one or more CRDT mutation events to the synced database. Use this for writes instead of SQL. Query the current data first when updating or deleting existing rows. Create events must omit ids: do not provide item_id or payload.id, because the tool generates ids and returns them. Create payloads must include all required non-id columns, update events should include only changed columns, and delete events should use an empty payload. Tables the schema documentation marks read-only cannot be written.",
+		inputSchema: mutationInputSchema,
+		execute: async (input) => {
+			const access = await opts.access();
+			if (!access.mutate) return { error: "Database mutations are not enabled for this access object." };
+			return await access.mutate(input);
+		}
+	});
+	return tools;
 }
-export {
-  QueryGuardError,
-  createAiDbAccess,
-  createDbTools,
-  createQueryGuard,
-  createSchemaDoc,
-  runWithForcedRollback
-};
+//#endregion
+export { QueryGuardError, createAiDbAccess, createDbTools, createQueryGuard, createSchemaDoc, resolveAiPolicy, runWithForcedRollback };
+
 //# sourceMappingURL=index.js.map