@persql/sdk 0.1.0 → 1.1.0

package/dist/cli.cjs

@@ -5,6 +5,28 @@
 var import_promises = require("fs/promises");
 
 // src/local.ts
+function checkLocalExpect(e, r) {
+  const rows = r.rows.length;
+  if (e.rows != null && rows !== e.rows) {
+    return `expected rows=${e.rows}, got ${rows}`;
+  }
+  if (e.rowsAtLeast != null && rows < e.rowsAtLeast) {
+    return `expected rows>=${e.rowsAtLeast}, got ${rows}`;
+  }
+  if (e.rowsAtMost != null && rows > e.rowsAtMost) {
+    return `expected rows<=${e.rowsAtMost}, got ${rows}`;
+  }
+  if (e.rowsWritten != null && r.rowsWritten !== e.rowsWritten) {
+    return `expected rowsWritten=${e.rowsWritten}, got ${r.rowsWritten}`;
+  }
+  if (e.rowsWrittenAtLeast != null && r.rowsWritten < e.rowsWrittenAtLeast) {
+    return `expected rowsWritten>=${e.rowsWrittenAtLeast}, got ${r.rowsWritten}`;
+  }
+  if (e.rowsWrittenAtMost != null && r.rowsWritten > e.rowsWrittenAtMost) {
+    return `expected rowsWritten<=${e.rowsWrittenAtMost}, got ${r.rowsWritten}`;
+  }
+  return null;
+}
 var PROPOSAL_TTL_DEFAULT_SEC = 600;
 var PROPOSAL_TTL_MAX_SEC = 3600;
 function newLocalProposalId() {
@@ -43,7 +65,16 @@ var LocalDriver = class {
   }
   async batch(statements, transaction) {
     const db = await this.open();
-    const exec = () => statements.map((s) => runOne(db, s.sql, s.params ?? []));
+    const exec = () => statements.map((s, i) => {
+      const r = runOne(db, s.sql, s.params ?? []);
+      if (s.expect) {
+        const violation = checkLocalExpect(s.expect, r);
+        if (violation) {
+          throw new Error(`Assertion failed on statement ${i}: ${violation}`);
+        }
+      }
+      return r;
+    });
     if (transaction) return db.transaction(exec)();
     return exec();
   }
@@ -205,6 +236,19 @@ var PerSQL = class _PerSQL {
   close() {
     this.local?.close();
   }
+  /**
+   * Resolve the bearer token's namespace + live usage. Use this once
+   * per agent run so you know the slug to put in URLs and how much
+   * monthly budget / prepaid balance remains before a 402.
+   *
+   * Throws in local mode — no server, nothing to ask.
+   */
+  async me() {
+    if (this.local) {
+      throw new Error("PerSQL: me() is not available in local mode.");
+    }
+    return this.request("GET", "/v1/me");
+  }
   /**
    * Redeem a handoff token (`phand_…`) for a regular PerSQL client
    * scoped to the handed-off (database, branch, role). Single use:
@@ -278,40 +322,74 @@ var PerSQL = class _PerSQL {
     }
     return envelope.data;
   }
-  /** @internal — raw upload (e.g. blob PUT) returning the ApiResponse data. */
-  async requestRaw(method, path, body, contentType) {
-    const res = await this._fetch(`${this.baseURL}${path}`, {
-      method,
-      headers: {
-        Authorization: `Bearer ${this.token}`,
-        "Content-Type": contentType ?? "application/octet-stream"
-      },
-      body,
-      // @ts-expect-error — duplex is required by Node fetch for streaming bodies
-      duplex: "half"
-    });
-    if (res.status === 429) {
-      const retryAfter = Number(res.headers.get("retry-after") ?? "60");
-      throw new RateLimitError(retryAfter);
-    }
-    let envelope = null;
-    try {
-      envelope = await res.json();
-    } catch {
-    }
-    if (!res.ok || !envelope?.success) {
-      const message = envelope?.error ?? `Request failed (${res.status})`;
-      throw new PerSQLError(res.status, message, envelope?.errorDetail);
-    }
-    return envelope.data;
-  }
-  /** @internal — raw fetch returning the underlying Response (used by blob GET). */
+  /** @internal — raw fetch returning the underlying Response. */
   fetchRaw(method, path) {
     return this._fetch(`${this.baseURL}${path}`, {
       method,
       headers: { Authorization: `Bearer ${this.token}` }
     });
   }
+  /**
+   * File a support ticket directly from your SDK code. Tickets land in
+   * the customer console at `/support`; staff reply from the admin
+   * app. Useful for agents and background jobs that hit a PerSQL
+   * error and want a human to see it.
+   *
+   * ```ts
+   * try {
+   *   await db.query("UPDATE ...");
+   * } catch (err) {
+   *   await persql.support.createTicket({
+   *     subject: "Branch merge keeps 500ing",
+   *     body: "Repro: ...",
+   *     error: err,
+   *   });
+   * }
+   * ```
+   */
+  get support() {
+    return new SupportClient(this);
+  }
+};
+function errorContextFor(err) {
+  if (err instanceof PerSQLError) {
+    return {
+      errorName: err.name,
+      errorMessage: err.message,
+      status: err.status,
+      detail: err.detail ?? null
+    };
+  }
+  if (err instanceof Error) {
+    return { errorName: err.name, errorMessage: err.message };
+  }
+  if (err !== void 0 && err !== null) {
+    return { errorMessage: String(err) };
+  }
+  return {};
+}
+var SupportClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async createTicket(opts) {
+    if (this.client.local) {
+      throw new Error("support.createTicket is not supported in local mode");
+    }
+    const errorContext = {
+      ...errorContextFor(opts.error),
+      ...opts.errorContext ?? {}
+    };
+    return this.client.request(
+      "POST",
+      "/v1/support/tickets",
+      {
+        subject: opts.subject,
+        body: opts.body,
+        errorContext: Object.keys(errorContext).length > 0 ? errorContext : void 0
+      }
+    );
+  }
 };
 var PerSQLDatabase = class {
   constructor(client, namespace, slug) {
@@ -365,6 +443,25 @@ var PerSQLDatabase = class {
   transaction(statements, options = {}) {
     return this.batch(statements, { ...options, transaction: true });
   }
+  /**
+   * Mint a short-lived session JWT for an end user. The server (which
+   * holds the bearer token) calls this and hands the resulting token
+   * to an untrusted client (browser, mobile app, agent run). The
+   * client uses the JWT to call this database's published `/p/*`
+   * endpoints on behalf of `userId`. TTL defaults to 1 hour; max 24h.
+   */
+  async createSession(opts) {
+    if (this.client.local) {
+      throw new Error("createSession is not supported in local mode");
+    }
+    return this.client.request("POST", "/v1/sessions", {
+      namespaceSlug: this.namespace,
+      databaseSlug: this.slug,
+      userId: opts.userId,
+      email: opts.email,
+      expiresIn: opts.expiresIn
+    });
+  }
   /**
    * Engine telemetry — recent /v1/query and /v1/batch calls issued
    * against this database. Backed by the in-DO `_persql_meta_query_log`
@@ -486,6 +583,61 @@ var PerSQLDatabase = class {
     if (this.client.local) return this.client.local.explain(sql, params);
     return this.client.request("POST", `/v1/db/${this.namespace}/${this.slug}/explain`, { sql, params });
   }
+  /**
+   * Parse + bind-check a SQL statement without executing it. Faster
+   * and cheaper than running the query just to catch unknown columns
+   * or wrong param counts.
+   *
+   * Returns `{ ok: true }` on success or `{ ok: false, error, errorDetail }`
+   * with the same `errorDetail` envelope as `PerSQLError.detail`.
+   */
+  async validate(sql, params = []) {
+    if (this.client.local) {
+      throw new Error("PerSQL: validate is not available in local mode.");
+    }
+    const data = await this.client.request(
+      "POST",
+      `/v1/db/${this.namespace}/${this.slug}/validate`,
+      { sql, params }
+    );
+    return data;
+  }
+  /**
+   * Compact text rendering of the database's schema — one line per
+   * table with columns, types, PKs, and FK arrows inlined. Designed
+   * to stuff into an LLM prompt with minimum token overhead. See
+   * `db.describe()` for the structured form.
+   */
+  async describeCompact() {
+    if (this.client.local) {
+      throw new Error("PerSQL: describeCompact is not available in local mode.");
+    }
+    const data = await this.client.request(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/describe?format=compact`
+    );
+    return data.text;
+  }
+  /**
+   * First N rows of a table plus per-column stats (null count,
+   * distinct count, min, max). One call to size up an unfamiliar
+   * table — replaces a hand-rolled `SELECT *`, `COUNT(*)`, and
+   * `PRAGMA table_info` sequence.
+   *
+   * `n` defaults to 10 and is capped at 100.
+   */
+  async sampleTable(table, opts = {}) {
+    if (this.client.local) {
+      throw new Error("PerSQL: sampleTable is not available in local mode.");
+    }
+    const qs = opts.n ? `?n=${Math.max(1, Math.min(100, opts.n | 0))}` : "";
+    return this.client.request(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/tables/${encodeURIComponent(
+        table
+      )}/sample${qs}`
+    );
+  }
   /**
    * Introspect the database schema. Returns one entry per user table
    * with column definitions, suitable for codegen tools (the
@@ -509,20 +661,6 @@ var PerSQLDatabase = class {
     }
     return out;
   }
-  /**
-   * Per-database semantic search via Cloudflare Vectorize. Use
-   * `vectors.upsert` to embed and store rows; `vectors.query` to
-   * retrieve the most similar by free text. Embeddings are computed
-   * server-side using bge-base-en-v1.5 (768 dim, cosine distance).
-   */
-  get vectors() {
-    if (this.client.local) {
-      throw new Error(
-        "PerSQL: vectors require Cloudflare Vectorize and Workers AI \u2014 not available in local mode. Use a server-mode token (psql_live_/psql_test_) to call vectors.upsert/query/delete."
-      );
-    }
-    return new PerSQLVectors(this.client, this.namespace, this.slug);
-  }
   /**
    * Manage preview/PR-style branches of this database. Each branch is
    * its own DO with its own SQLite file; create-or-reset by ref is
@@ -551,6 +689,19 @@ var PerSQLDatabase = class {
     }
     return new PerSQLApprovals(this.client, this.namespace, this.slug);
   }
+  /**
+   * Manage the require_approval / deny rules for this database. Reads
+   * are open to any bearer with read access; create + delete require
+   * an admin-role bearer token.
+   */
+  get approvalRules() {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: approval rules live on the server; local mode does not enforce them."
+      );
+    }
+    return new PerSQLApprovalRules(this.client, this.namespace, this.slug);
+  }
   /**
    * Pre-flight a write before running it. `propose()` validates the
    * SQL via EXPLAIN, estimates affected rows, and returns a single-use
@@ -562,20 +713,6 @@ var PerSQLDatabase = class {
   get proposals() {
     return new PerSQLProposals(this.client, this.namespace, this.slug);
   }
-  /**
-   * Per-database BLOB storage backed by R2. Use this for anything
-   * larger than a SQLite cell (images, PDFs, model weights). Each
-   * database has its own private namespace; keys may be hierarchical
-   * (`avatars/2025/foo.jpg`) but never start with `/`.
-   */
-  get blob() {
-    if (this.client.local) {
-      throw new Error(
-        "PerSQL: blob storage is backed by R2 \u2014 not available in local mode. Use a server-mode token, or store blobs in your test fixtures directly."
-      );
-    }
-    return new PerSQLBlob(this.client, this.namespace, this.slug);
-  }
   /**
    * Subscribe to row-changes via WebSocket — the SQL equivalent of
    * Postgres `LISTEN`. The callback fires once per write that
@@ -636,6 +773,55 @@ var PerSQLDatabase = class {
       }
     };
   }
+  /**
+   * Long-poll for row-changes on this database. Returns immediately
+   * if changes newer than `since` are already buffered; otherwise
+   * blocks server-side for up to `waitMs` (default 25s, max 25s).
+   *
+   * Most callers want `changes()` instead — an async iterator that
+   * loops `waitForChanges` forever, surfacing each batch as it
+   * arrives.
+   */
+  async waitForChanges(opts = {}) {
+    if (this.client.local) {
+      throw new Error(
+        "PerSQL: waitForChanges requires the DO change ring \u2014 not available in local mode."
+      );
+    }
+    const qs = new URLSearchParams();
+    if (typeof opts.since === "number") qs.set("since", String(opts.since));
+    if (typeof opts.waitMs === "number") qs.set("waitMs", String(opts.waitMs));
+    if (opts.tables && opts.tables.length > 0) qs.set("tables", opts.tables.join(","));
+    const q = qs.toString();
+    return this.client.request(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/changes${q ? `?${q}` : ""}`
+    );
+  }
+  /**
+   * Async-iterator change feed. Loops `waitForChanges` forever and
+   * yields one batch per server response. Pass an `AbortSignal` to
+   * stop the loop cleanly.
+   *
+   * ```ts
+   * const ctl = new AbortController();
+   * for await (const batch of db.changes({ signal: ctl.signal })) {
+   *   for (const c of batch.changes) console.log(c.kind, c.table);
+   * }
+   * ```
+   */
+  async *changes(opts = {}) {
+    let cursor = opts.since ?? 0;
+    while (!opts.signal?.aborted) {
+      const batch = await this.waitForChanges({
+        since: cursor,
+        waitMs: opts.waitMs,
+        tables: opts.tables
+      });
+      cursor = batch.cursor;
+      yield batch;
+    }
+  }
   /**
    * Returns the callback shape `drizzle-orm/sqlite-proxy` expects.
    * Pair with `drizzle()` from that module to get a typed,
@@ -663,42 +849,64 @@ var PerSQLDatabase = class {
     return callback;
   }
   /**
-   * Returns a tool definition for use with Anthropic / OpenAI / function-calling
-   * agents. Pair it with `runTool` to execute the call.
+   * Returns a single SQL-query tool definition in every shape PerSQL
+   * supports (Anthropic, OpenAI Chat, Vercel AI SDK, Mastra, LangChain,
+   * OpenAI Agents SDK). Same input contract as `asTools()` — the only
+   * difference is one fat `query` tool instead of typed-per-table tools.
+   *
+   * Pair the format-specific fields with `runTool` (or use the bundled
+   * `execute`/`invoke` callbacks, which call `runTool` internally).
    */
   asTool(name = "persql_query") {
-    return {
-      anthropic: {
-        name,
-        description: `Run a SQL query against the PerSQL database "${this.namespace}/${this.slug}". Returns up to 1000 rows. Use parameter binding (?) to avoid injection.`,
-        input_schema: {
-          type: "object",
-          properties: {
-            sql: { type: "string", description: "SQLite SQL statement" },
-            params: {
-              type: "array",
-              items: {},
-              description: "Positional parameters for the SQL statement"
-            }
-          },
-          required: ["sql"]
+    const description = `Run a SQL query against the PerSQL database "${this.namespace}/${this.slug}". A single result is capped at 100,000 rows and the query errors above that \u2014 add a LIMIT for large tables. Use parameter binding (?) to avoid injection.`;
+    const inputSchema = {
+      type: "object",
+      properties: {
+        sql: { type: "string", description: "SQLite SQL statement" },
+        params: {
+          type: "array",
+          items: {},
+          description: "Positional parameters for the SQL statement"
         }
       },
+      required: ["sql"],
+      // OpenAI strict function-calling rejects a schema without this; the
+      // per-table asTools() schemas already set it. Keep them consistent.
+      additionalProperties: false
+    };
+    const execute = (input) => this.runTool({
+      sql: String(input.sql ?? ""),
+      params: Array.isArray(input.params) ? input.params : []
+    });
+    return {
+      anthropic: { name, description, input_schema: inputSchema },
       openai: {
         type: "function",
-        function: {
+        function: { name, description, parameters: inputSchema }
+      },
+      aiSdk: () => ({
+        [name]: { description, inputSchema, execute }
+      }),
+      mastra: () => ({
+        [name]: {
+          id: name,
+          description,
+          inputSchema,
+          execute: ({ context }) => execute(context)
+        }
+      }),
+      langchain: () => [
+        { name, description, schema: inputSchema, invoke: execute }
+      ],
+      openaiAgents: () => [
+        {
+          type: "function",
           name,
-          description: `Run a SQL query against the PerSQL database "${this.namespace}/${this.slug}".`,
-          parameters: {
-            type: "object",
-            properties: {
-              sql: { type: "string" },
-              params: { type: "array", items: {} }
-            },
-            required: ["sql"]
-          }
+          description,
+          parameters: inputSchema,
+          invoke: execute
         }
-      }
+      ]
     };
   }
   /**
@@ -1470,106 +1678,148 @@ function sanitizeToolPart(s) {
 function quoteIdent(s) {
   return `"${s.replace(/"/g, '""')}"`;
 }
-var PerSQLBlob = class {
+var PerSQLApprovals = class {
   constructor(client, namespace, slug) {
     this.client = client;
     this.namespace = namespace;
     this.slug = slug;
   }
-  /** Upload a blob. Body can be ArrayBuffer, Blob, ReadableStream, or string. */
-  async put(key, body, opts = {}) {
-    const path = `/v1/db/${this.namespace}/${this.slug}/blobs/${encodeBlobKey(key)}`;
-    return this.client.requestRaw(
-      "PUT",
-      path,
-      body,
-      opts.contentType
+  // Tokens this client has seen via subscribe — used to dedupe poll
+  // results so onApprovalRequired fires once per token regardless of
+  // how many subscribe ticks observe it.
+  seen = /* @__PURE__ */ new Map();
+  /**
+   * Look up the status of an approval token without consuming it. The
+   * bearer must match the one that minted the original 403; cross-bearer
+   * lookup returns 403.
+   */
+  async get(approvalToken) {
+    return this.client.request(
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/approval/${encodeURIComponent(
+        approvalToken
+      )}`
     );
   }
-  /** Fetch a blob. Returns null if missing. */
-  async get(key) {
-    const path = `/v1/db/${this.namespace}/${this.slug}/blobs/${encodeBlobKey(key)}`;
-    const res = await this.client.fetchRaw("GET", path);
-    if (res.status === 404) return null;
-    if (!res.ok) {
-      throw new PerSQLError(res.status, `Blob fetch failed (${res.status})`);
+  /**
+   * Poll until a reviewer decides (or the token expires). Resolves with
+   * the final status — `approved` is your green light for `redeem()`.
+   */
+  async poll(approvalToken, opts = {}) {
+    const intervalMs = Math.max(250, opts.intervalMs ?? 2e3);
+    const deadline = Date.now() + (opts.timeoutMs ?? 10 * 60 * 1e3);
+    while (true) {
+      if (opts.signal?.aborted) {
+        throw new Error("approval poll aborted");
+      }
+      const status = await this.get(approvalToken);
+      if (status.status !== "pending") return status;
+      if (Date.now() > deadline) return status;
+      await new Promise((r) => setTimeout(r, intervalMs));
     }
-    return res;
   }
-  /** Delete a blob. */
-  async delete(key) {
-    const path = `/v1/db/${this.namespace}/${this.slug}/blobs/${encodeBlobKey(key)}`;
-    await this.client.request("DELETE", path);
+  /**
+   * Long-running poll subscription for new approval events on this
+   * database. Returns a `stop()` handle. Webhook delivery is the push
+   * path (events `approval_required` / `approval_resolved`); subscribe
+   * is the pull fallback for clients that can't host a webhook.
+   *
+   * Today this iterates over a known set of tokens supplied by the
+   * caller; an SDK-only client that wants discovery should pair this
+   * with the webhook path. Pass tokens you already hold (e.g. from a
+   * prior `ApprovalRequiredError`).
+   */
+  subscribe(tokens, opts) {
+    const intervalMs = Math.max(1e3, opts.intervalMs ?? 5e3);
+    let cancelled = false;
+    const onAbort = () => {
+      cancelled = true;
+    };
+    opts.signal?.addEventListener("abort", onAbort);
+    const tick = async () => {
+      for (const token of tokens) {
+        if (cancelled) return;
+        try {
+          const status = await this.get(token);
+          const prev = this.seen.get(token);
+          if (status.status !== prev) {
+            this.seen.set(token, status.status);
+            const event = {
+              approvalToken: token,
+              status: status.status,
+              hits: status.hits
+            };
+            if (status.status === "pending") {
+              opts.onApprovalRequired?.(event);
+            } else {
+              opts.onApprovalResolved?.(event);
+            }
+          }
+        } catch (e) {
+          opts.onError?.(e instanceof Error ? e : new Error(String(e)));
+        }
+      }
+    };
+    const id = setInterval(() => {
+      void tick();
+    }, intervalMs);
+    void tick();
+    return {
+      stop: () => {
+        cancelled = true;
+        clearInterval(id);
+        opts.signal?.removeEventListener("abort", onAbort);
+      }
+    };
   }
-  /** List blobs by prefix. */
-  async list(opts = {}) {
-    const params = new URLSearchParams();
-    if (opts.prefix) params.set("prefix", opts.prefix);
-    if (opts.cursor) params.set("cursor", opts.cursor);
-    if (opts.limit) params.set("limit", String(opts.limit));
-    const qs = params.toString();
-    const path = `/v1/db/${this.namespace}/${this.slug}/blobs` + (qs ? `?${qs}` : "");
-    return this.client.request("GET", path);
+  /**
+   * Redeem an approved approvalToken. The bearer must be the same one
+   * that minted it, and the request must target the same database.
+   * Returns the result of the originally-blocked query or batch.
+   */
+  async redeem(approvalToken) {
+    const raw = await this.client.request("POST", `/v1/db/${this.namespace}/${this.slug}/redeem_approval`, {
+      approvalToken
+    });
+    if (Array.isArray(raw)) {
+      return raw.map((r) => ({
+        ...r,
+        data: rowsToObjects(r.columns, r.rows)
+      }));
+    }
+    return { ...raw, data: rowsToObjects(raw.columns, raw.rows) };
   }
 };
-function encodeBlobKey(key) {
-  return key.split("/").map(encodeURIComponent).join("/");
-}
-var PerSQLVectors = class {
+var PerSQLApprovalRules = class {
   constructor(client, namespace, slug) {
     this.client = client;
     this.namespace = namespace;
     this.slug = slug;
   }
-  /** Embed and upsert up to 100 items in one call. */
-  async upsert(items) {
+  async list() {
     return this.client.request(
-      "POST",
-      `/v1/db/${this.namespace}/${this.slug}/vectors`,
-      { items }
+      "GET",
+      `/v1/db/${this.namespace}/${this.slug}/approval-rules`
     );
   }
-  /** Top-K nearest neighbours by free-text query. */
-  async query(text, opts = {}) {
+  /** Requires an admin-role bearer token. */
+  async create(input) {
     return this.client.request(
       "POST",
-      `/v1/db/${this.namespace}/${this.slug}/vectors/query`,
-      { query: text, topK: opts.topK, filter: opts.filter }
+      `/v1/db/${this.namespace}/${this.slug}/approval-rules`,
+      input
     );
   }
-  /** Delete vectors by id. Up to 1000 ids per call. */
-  async delete(ids) {
+  /** Requires an admin-role bearer token. */
+  async delete(ruleId) {
     return this.client.request(
       "DELETE",
-      `/v1/db/${this.namespace}/${this.slug}/vectors`,
-      { ids }
+      `/v1/db/${this.namespace}/${this.slug}/approval-rules/${encodeURIComponent(
+        ruleId
+      )}`
     );
   }
 };
-var PerSQLApprovals = class {
-  constructor(client, namespace, slug) {
-    this.client = client;
-    this.namespace = namespace;
-    this.slug = slug;
-  }
-  /**
-   * Redeem an approved approvalToken. The bearer must be the same one
-   * that minted it, and the request must target the same database.
-   * Returns the result of the originally-blocked query or batch.
-   */
-  async redeem(approvalToken) {
-    const raw = await this.client.request("POST", `/v1/db/${this.namespace}/${this.slug}/redeem_approval`, {
-      approvalToken
-    });
-    if (Array.isArray(raw)) {
-      return raw.map((r) => ({
-        ...r,
-        data: rowsToObjects(r.columns, r.rows)
-      }));
-    }
-    return { ...raw, data: rowsToObjects(raw.columns, raw.rows) };
-  }
-};
 var PerSQLProposals = class {
   constructor(client, namespace, slug) {
     this.client = client;
@@ -1581,6 +1831,11 @@ var PerSQLProposals = class {
    * rows, and returns a single-use `executionToken` valid for 10 min
    * (override with `ttlSec`, max 1 hour). Nothing is mutated until
    * `apply()` is called.
+   *
+   * Local mode keeps the token in-process: single-use still holds, but
+   * `estimatedAffectedRows` is always `null` (no server estimator) and a
+   * stale/unknown token throws a plain `Error` rather than the HTTP
+   * 404/403 of the server path.
    */
   async propose(sql, opts = {}) {
     if (this.client.local) {