@sqlite-sync/ai 0.8.2 → 0.9.1

package/README.md

@@ -8,7 +8,7 @@ AI agent tools for [@sqlite-sync](https://github.com/krolebord-dev/sqlite-sync)
 - `createAiDbAccess` — server-side access object living next to the storage; its methods double as an RPC contract for cross-Durable-Object setups.
 - `createDbTools` — AI SDK v6 `ToolSet` (`getDbSchema` and `queryDb` tools, plus optional `mutateDb`) backed by an `AiDbAccess` or a stub proxying to one.
 
-`queryDb` is strictly read-only: a single `SELECT`/`WITH`/`VALUES` statement, verified against SQLite's `EXPLAIN` bytecode for write opcodes, and executed inside a transaction that is always rolled back. Reads are **not** restricted by table — the agent can query every table in the database file (including sqlite-sync's internal event log), so don't colocate data the agent must not see. Results are capped (default 200 rows, 2000 chars per cell) and report `truncated` so the agent can narrow its query.
+`queryDb` is strictly read-only: a single `SELECT`/`WITH`/`VALUES` statement, verified against SQLite's `EXPLAIN` bytecode for write opcodes, and executed inside a transaction that is always rolled back. By default reads are **not** restricted by table — the agent can query every table in the database file (including sqlite-sync's internal event log), so don't colocate data the agent must not see unless you hide it (see below). Results are capped (default 200 rows, 2000 chars per cell) and report `truncated` so the agent can narrow its query.
 
 `mutateDb` is opt-in. It applies `item-created`, `item-updated`, and `item-deleted` CRDT events through sqlite-sync's own-event path, so writes are validated, persisted to the event log, applied locally, and synced normally. It does not run arbitrary write SQL. For `item-created` events, omit `item_id` and `payload.id`; the tool generates ids, injects them into the CRDT events, and returns them as `createdIds`.
 
@@ -16,13 +16,13 @@ AI agent tools for [@sqlite-sync](https://github.com/krolebord-dev/sqlite-sync)
 
 ```ts
 import { createAiDbAccess } from "@sqlite-sync/ai";
-import { createKyselyExecutor, durableObjectAdapter } from "@sqlite-sync/cloudflare";
+import { durableObjectAdapter } from "@sqlite-sync/cloudflare";
 
 // In the DO that owns the synced database:
 async onStart() {
   const { syncDb } = await durableObjectAdapter.createCrdtStorage({ syncDbSchema, storage: this.ctx.storage, /* ... */ });
   this.aiDbAccess = createAiDbAccess({
-    executor: createKyselyExecutor(this.ctx.storage),
+    executor: syncDb.unsafe,
     storage: syncDb, // optional; enables mutate() on the access object
     syncDbSchema,
     context: {
@@ -65,3 +65,34 @@ getTools() {
 The doc skips the internal `tombstone` column and renders enum columns with their allowed values and boolean columns with a `0/1` hint. Table and column descriptions come from `.describe()` on the builders.
 
 The generated doc always includes a built-in preamble (after your `overview`) explaining sqlite-sync mechanics — that the database syncs between devices and that the listed tables are read-only views with soft-deleted rows already filtered out. Prefer keeping domain semantics in the schema with `.describe()` and using `context.overview` for app-level notes.
+
+## Limiting what the agent may touch
+
+Declare AI access next to the schema. Tables are `"read-write"` unless narrowed:
+
+```ts
+const syncDbSchema = defineSyncSchema({
+  tables: {
+    todos: t.table({ title: t.text() }),
+    // Queryable and documented, never mutated by the agent.
+    audit: t.table({ note: t.text() }).ai("read-only"),
+    // Not in the doc, and queries that read it are rejected.
+    billing: t.table({ card_last4: t.text() }).ai("hidden"),
+  },
+  migrations,
+});
+```
+
+What each level enforces:
+
+- `"read-only"` keeps the table in the schema doc, labelled read-only, and makes `mutateDb` reject events for it.
+- `"hidden"` removes it from the doc and makes `queryDb` reject any statement that reads it. Enforcement works off the root pages a compiled statement opens, so views, aliases, CTEs, subqueries and quoting tricks all resolve to the same check.
+
+Access is table-level. There is no per-column setting: SQLite bytecode identifies tables rather than columns, so a column could not be hidden from reads, and blocking writes to a required column would make rows impossible to create. Put data the agent must not touch in its own table.
+
+Hiding a table has two side effects worth knowing:
+
+- Reads switch to an allow-list of the remaining base tables, so any other table in the same database file (including non-synced tables you created yourself) becomes unreadable too.
+- `change_history` is dropped from the doc and denied. That view reads the raw event log, which holds every dataset's payloads, so it cannot be filtered per table.
+
+Names and columns of hidden tables can still be discovered through SQLite's schema introspection in principle; the guard rejects `pragma_*` table-valued functions and reads of `sqlite_schema` while restricted, but treat hiding as row-level protection rather than proof the table does not exist.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { SyncDbSchema, CrdtEventType, CrdtStorage } from '@sqlite-sync/core';
-import { ToolSet } from 'ai';
-
+import { AiAccess, CrdtEventType, CrdtStorage, SyncDbSchema } from "@sqlite-sync/core";
+import { ToolSet } from "ai";
+//#region src/schema-doc.d.ts
 type SchemaDocContext = {
-    overview?: string;
+  overview?: string;
 };
 /**
  * Generates a markdown schema doc for an AI agent from the declared sync schema's table
@@ -10,61 +10,66 @@ type SchemaDocContext = {
  * 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.
  */
 declare function createSchemaDoc(opts: {
-    syncDbSchema: SyncDbSchema;
-    context?: SchemaDocContext;
+  syncDbSchema: SyncDbSchema;
+  context?: SchemaDocContext;
 }): string;
-
+//#endregion
+//#region src/db-access.d.ts
 type AiDbExecuteParams = {
-    sql: string;
-    parameters: readonly unknown[];
+  sql: string;
+  parameters: readonly unknown[];
 };
 /**
- * Minimal executor contract for AI database access. Runtime-specific — inject the one that
- * matches where the storage lives; @sqlite-sync/cloudflare's `createKyselyExecutor` satisfies it.
+ * Minimal executor contract for AI database access. Runtime-specific — inject the raw SQL
+ * capability that matches where the storage lives; a Cloudflare `ServerSyncDb`'s `unsafe`
+ * executor satisfies it.
  */
 type AiDbExecutor = {
-    execute<TResult = unknown>(query: AiDbExecuteParams): {
-        rows: TResult[];
-    };
-    transaction(callback: (tx: Pick<AiDbExecutor, "execute">) => void): void;
+  execute<TResult = unknown>(query: AiDbExecuteParams): {
+    rows: TResult[];
+  };
+  transaction(callback: (tx: Pick<AiDbExecutor, "execute">) => void): void;
 };
 type AiQueryInput = {
-    sql: string;
-    parameters?: readonly unknown[];
+  sql: string;
+  parameters?: readonly unknown[];
 };
 type AiQueryResult = {
-    rows: Record<string, unknown>[];
-    rowCount: number;
-    truncated: boolean;
+  rows: Record<string, unknown>[];
+  rowCount: number;
+  truncated: boolean;
 } | {
-    error: string;
+  error: string;
 };
 type AiMutationEvent = {
-    type: "item-created";
-    dataset: string;
-    item_id?: never;
-    payload?: Record<string, unknown>;
+  type: "item-created";
+  dataset: string;
+  item_id?: never;
+  payload?: Record<string, unknown>;
 } | {
-    type: Exclude<CrdtEventType, "item-created">;
-    dataset: string;
-    item_id: string;
-    payload?: Record<string, unknown>;
+  type: Exclude<CrdtEventType, "item-created">;
+  dataset: string;
+  item_id: string;
+  payload?: Record<string, unknown>;
 };
 type AiMutationInput = {
-    events: AiMutationEvent[];
+  events: AiMutationEvent[];
 };
 type AiMutationResult = {
-    applied: true;
-    eventCount: number;
-    createdIds: string[];
+  applied: true;
+  eventCount: number;
+  createdIds: string[];
 } | {
-    error: string;
-    errors?: string[];
+  error: string;
+  errors?: string[];
 };
 /**
  * AI access to a synced database. Lives where the storage lives; its method names
@@ -72,61 +77,95 @@ type AiMutationResult = {
  * (promise-wrapped) and satisfies the tool layer's `DbToolsAccess`.
  *
  * `query` enforces read-only (single SELECT/WITH/VALUES statement, no write opcodes, executed
- * in a forced-rollback transaction) but reads are not restricted by table — the whole database
- * file is in scope for the agent, so don't colocate data the agent must not see.
+ * in a forced-rollback transaction). Reads are restricted by table only once the schema declares
+ * a table `.ai("hidden")`; until then the whole database file is in scope for the agent, so don't
+ * colocate data the agent must not see.
  *
  * `mutate` is only present when `createAiDbAccess` receives a CRDT storage. Mutations are CRDT
- * events applied through sqlite-sync's normal own-event path, never direct SQL writes.
+ * events applied through sqlite-sync's normal own-event path, never direct SQL writes, and are
+ * rejected for tables the schema declares read-only or hidden.
  */
 type AiDbAccess = {
-    getSchemaDoc(): string;
-    query(input: AiQueryInput): AiQueryResult;
-    mutate?(input: AiMutationInput): AiMutationResult;
+  getSchemaDoc(): string;
+  query(input: AiQueryInput): AiQueryResult;
+  mutate?(input: AiMutationInput): AiMutationResult;
 };
 declare function createAiDbAccess(opts: {
-    executor: AiDbExecutor;
-    storage?: Pick<CrdtStorage, "applyOwnEvents">;
-    syncDbSchema: SyncDbSchema;
-    context?: SchemaDocContext;
-    limits?: {
-        maxRows?: number;
-        maxCellChars?: number;
-    };
+  executor: AiDbExecutor;
+  storage?: Pick<CrdtStorage, "applyOwnEvents">;
+  syncDbSchema: SyncDbSchema;
+  context?: SchemaDocContext;
+  limits?: {
+    maxRows?: number;
+    maxCellChars?: number;
+  };
 }): AiDbAccess;
-
+//#endregion
+//#region src/policy.d.ts
+type ResolvedTablePolicy = {
+  crdtTableName: string;
+  baseTableName: string;
+  access: AiAccess;
+};
+type ResolvedAiPolicy = {
+  /** In schema declaration order, hidden tables included. */
+  tables: ResolvedTablePolicy[];
+  hasHiddenTables: boolean;
+  /** Base table names the agent may read. Only meaningful when `hasHiddenTables` is true. */
+  readableBaseTableNames: string[];
+  /** Resolves either the crdt or the base table name; anything unknown is "hidden". */
+  tableAccess(dataset: string): AiAccess;
+};
+/**
+ * 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}.
+ */
+declare function resolveAiPolicy(opts: {
+  syncDbSchema: SyncDbSchema;
+}): ResolvedAiPolicy;
+//#endregion
+//#region src/query-guard.d.ts
 type QueryGuardInput = {
-    sql: string;
-    parameters?: readonly unknown[];
+  sql: string;
+  parameters?: readonly unknown[];
 };
 type QueryGuardRejection = {
-    allowed: false;
-    code: "invalid-statement" | "multi-statement" | "invalid-sql" | "write-detected";
-    message: string;
+  allowed: false;
+  code: "invalid-statement" | "multi-statement" | "invalid-sql" | "write-detected" | "table-denied";
+  message: string;
 };
 type QueryGuardVerdict = {
-    allowed: true;
+  allowed: true;
 } | QueryGuardRejection;
 declare class QueryGuardError extends Error {
-    readonly rejection: QueryGuardRejection;
-    constructor(rejection: QueryGuardRejection);
+  readonly rejection: QueryGuardRejection;
+  constructor(rejection: QueryGuardRejection);
 }
 type QueryGuard = {
-    /**
-     * Statically verifies the query is a read-only single statement. Reads are not restricted
-     * by table — the whole database file is in scope for the agent, so don't colocate data the
-     * agent must not see.
-     */
-    check(input: QueryGuardInput): QueryGuardVerdict;
-    /**
-     * `check` + execute inside a forced-rollback transaction (the unconditional backstop for
-     * anything the analysis might miss). Throws {@link QueryGuardError} when the check rejects.
-     */
-    execute<TResult = unknown>(input: QueryGuardInput): {
-        rows: TResult[];
-    };
+  /**
+   * Statically verifies the query is a read-only single statement, and — when the guard was
+   * created with `readableTables` — that it only reads those tables. Without `readableTables`
+   * reads are unrestricted: the whole database file is in scope for the agent, so don't
+   * colocate data the agent must not see.
+   */
+  check(input: QueryGuardInput): QueryGuardVerdict;
+  /**
+   * `check` + execute inside a forced-rollback transaction (the unconditional backstop for
+   * anything the analysis might miss). Throws {@link QueryGuardError} when the check rejects.
+   */
+  execute<TResult = unknown>(input: QueryGuardInput): {
+    rows: TResult[];
+  };
 };
 declare function createQueryGuard(opts: {
-    executor: AiDbExecutor;
+  executor: AiDbExecutor;
+  /**
+   * Restrict reads to these tables (matched case-insensitively, indexes on them included).
+   * Views are resolved through their base tables, so pass base table names. Omit for
+   * unrestricted reads.
+   */
+  readableTables?: readonly string[];
 }): QueryGuard;
 /**
  * Runs `callback` in a transaction that is always rolled back (via a sentinel throw, relying
@@ -134,26 +173,28 @@ declare function createQueryGuard(opts: {
  * unconditional write guard backing any gap in the static analysis.
  */
 declare function runWithForcedRollback<T>(executor: Pick<AiDbExecutor, "transaction">, callback: (tx: Pick<AiDbExecutor, "execute">) => T): T;
-
+//#endregion
+//#region src/tools.d.ts
 type MaybePromise<T> = T | Promise<T>;
 /**
  * What the tools need from the database side. Satisfied directly by `AiDbAccess`, or by a
  * Durable Object stub whose RPC methods delegate to one (RPC wraps returns in promises).
  */
 type DbToolsAccess = {
-    getSchemaDoc(): MaybePromise<string>;
-    query(input: AiQueryInput): MaybePromise<AiQueryResult>;
-    mutate?(input: AiMutationInput): MaybePromise<AiMutationResult>;
+  getSchemaDoc(): MaybePromise<string>;
+  query(input: AiQueryInput): MaybePromise<AiQueryResult>;
+  mutate?(input: AiMutationInput): MaybePromise<AiMutationResult>;
 };
 type CreateDbToolsOptions = {
-    access: () => MaybePromise<DbToolsAccess>;
-    /** Expose the write-capable `mutateDb` tool. The access object must also implement `mutate`. */
-    mutations?: boolean;
+  access: () => MaybePromise<DbToolsAccess>;
+  /** Expose the write-capable `mutateDb` tool. The access object must also implement `mutate`. */
+  mutations?: boolean;
 };
 /**
  * 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).
  */
 declare function createDbTools(opts: CreateDbToolsOptions): ToolSet;
-
-export { type AiDbAccess, type AiDbExecuteParams, type AiDbExecutor, type AiMutationEvent, type AiMutationInput, type AiMutationResult, type AiQueryInput, type AiQueryResult, type CreateDbToolsOptions, type DbToolsAccess, type QueryGuard, QueryGuardError, type QueryGuardInput, type QueryGuardRejection, type QueryGuardVerdict, type SchemaDocContext, createAiDbAccess, createDbTools, createQueryGuard, createSchemaDoc, runWithForcedRollback };
+//#endregion
+export { type AiDbAccess, type AiDbExecuteParams, type AiDbExecutor, type AiMutationEvent, type AiMutationInput, type AiMutationResult, type AiQueryInput, type AiQueryResult, type CreateDbToolsOptions, type DbToolsAccess, type QueryGuard, QueryGuardError, type QueryGuardInput, type QueryGuardRejection, type QueryGuardVerdict, type ResolvedAiPolicy, type ResolvedTablePolicy, type SchemaDocContext, createAiDbAccess, createDbTools, createQueryGuard, createSchemaDoc, resolveAiPolicy, runWithForcedRollback };
+//# sourceMappingURL=index.d.ts.map