@lostgradient/weft 0.2.1 → 0.4.0

package/dist/storage/neon-value-mapping.js

@@ -0,0 +1,23 @@
+export function affectedRowCount(result) {
+  return result.rowCount ?? result.affectedRows ?? result.rows.length;
+}
+export function toStorageValue(raw) {
+  if (raw instanceof Uint8Array)
+    return new Uint8Array(raw);
+  return new Uint8Array(raw);
+}
+export function toBytea(value) {
+  return Buffer.from(value);
+}
+export function resolveBatchNetEffect(operations) {
+  const puts = new Map, deletes = new Set;
+  for (const operation of operations)
+    if (operation.type === "put") {
+      deletes.delete(operation.key);
+      puts.set(operation.key, operation.value);
+    } else {
+      puts.delete(operation.key);
+      deletes.add(operation.key);
+    }
+  return { puts, deletes };
+}

package/dist/storage/neon.d.ts

@@ -0,0 +1,124 @@
+import { type DeleteRangeOptions } from './delete-range.ts';
+import { type BatchOperation, type ConditionalBatchCondition, type ScanOptions, type Storage, type StorageCapabilities } from './interface.ts';
+import { type NeonQueryResult } from './neon-value-mapping.ts';
+/**
+ * A connection that can run a single interactive transaction. Obtained from
+ * {@link NeonPool.connect}; `release()` returns it to the pool. Both
+ * `batch()` and `conditionalBatch()` drive `BEGIN`/`COMMIT`/`ROLLBACK` over one
+ * of these so every statement in a transaction lands on the same connection —
+ * `pool.query()` alone may scatter statements across pooled connections, which
+ * would make a multi-statement batch non-atomic.
+ */
+export type NeonPoolClient = {
+    query(sql: string, parameters?: unknown[]): Promise<NeonQueryResult>;
+    release(): void;
+};
+/**
+ * Minimal structural view of a node-postgres `Pool`. The real Neon serverless
+ * `Pool` satisfies this; the PGlite test backend is wrapped to satisfy it too.
+ * `query()` runs a single statement on a pooled connection (used for the
+ * single-statement hot paths); `connect()` pins a connection for an interactive
+ * transaction; `end()` tears the pool down.
+ */
+export type NeonPool = {
+    query(sql: string, parameters?: unknown[]): Promise<NeonQueryResult>;
+    connect(): Promise<NeonPoolClient>;
+    end(): Promise<void>;
+};
+/**
+ * Configuration for connecting to a Neon (or any Postgres) database.
+ *
+ * @example
+ * ```ts
+ * import { NeonStorage, type NeonStorageOptions } from '@lostgradient/weft/storage/neon';
+ *
+ * const options: NeonStorageOptions = {
+ *   url: 'postgresql://user:password@ep-cool-name.us-east-2.aws.neon.tech/weft?sslmode=require',
+ * };
+ * await using storage = new NeonStorage(options);
+ * ```
+ */
+export type NeonStorageOptions = {
+    /** Postgres connection string for the primary endpoint. */
+    url: string;
+    /**
+     * Optional pre-built pool. Pass this to reuse a pool you manage (for example a
+     * test backend such as PGlite, or a shared application pool), instead of having
+     * the adapter construct its own from `url`. When supplied, `url` is ignored and
+     * **ownership stays with the caller**: disposing the `NeonStorage` does NOT
+     * close an injected pool, so it can be shared across adapters and the caller
+     * remains responsible for ending it. A pool the adapter constructs itself (from
+     * `url`) IS closed on disposal.
+     */
+    pool?: NeonPool;
+    /**
+     * Postgres schema to contain the kv table. Default: unqualified — the table
+     * resolves through `search_path` (in practice `public`). When set, the adapter
+     * creates the schema if absent (`CREATE SCHEMA IF NOT EXISTS`) and qualifies
+     * every statement as `"schema"."table"`. Lets Weft live in its own schema
+     * alongside the application's tables in one database — one PITR line, no Drizzle
+     * drift/drop risk. Validated as a strict Postgres identifier at construction.
+     */
+    schema?: string;
+    /**
+     * Table name. Default: `'kv'`. Validated as a strict Postgres identifier at
+     * construction. With neither `schema` nor `table` set, the adapter emits
+     * byte-identical SQL against the unqualified `kv` table (existing deployments
+     * are unaffected).
+     */
+    table?: string;
+};
+/**
+ * Storage adapter backed by Neon serverless Postgres for durable, remote
+ * deployments. Implements the same `Storage` interface as the SQLite adapters
+ * over a single `kv(key TEXT COLLATE "C", value BYTEA)` table, so switching from
+ * a local SQLite store to Neon is a configuration change, not a code change.
+ *
+ * **Endpoint assumption.** `capabilities()` reports `readAfterWrite:
+ * 'linearizable'`, which holds for the **primary** Neon endpoint. A read-replica
+ * connection string would violate that guarantee — point this adapter at the
+ * primary.
+ *
+ * **WebSocket runtime.** The Neon serverless driver connects over WebSocket. Bun
+ * and Node 22+ provide a global `WebSocket`, so no extra wiring is needed there.
+ * On Node ≤21 the driver needs `neonConfig.webSocketConstructor` set to the `ws`
+ * package before first use; install `ws` and configure it in that runtime.
+ *
+ * @example
+ * ```ts
+ * import { NeonStorage } from '@lostgradient/weft/storage/neon';
+ * import { Engine } from '@lostgradient/weft';
+ *
+ * await using storage = new NeonStorage({
+ *   url: process.env['NEON_DATABASE_URL']!,
+ * });
+ * await using engine = new Engine({ storage });
+ * ```
+ */
+export declare class NeonStorage implements Storage {
+    #private;
+    /**
+     * @param options Connection configuration ({@link NeonStorageOptions}).
+     * @param poolFactory Internal seam for constructing the owned pool from `url`.
+     *   Defaults to the real driver `Pool`; tests inject a fake (for example one
+     *   whose `end()` rejects) to exercise owned-pool teardown without a network.
+     *   Used only when no `pool` is supplied; an injected `pool` stays caller-owned.
+     */
+    constructor(options: NeonStorageOptions, poolFactory?: (url: string) => NeonPool);
+    capabilities(): StorageCapabilities;
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    deletePrefix(prefix: string): Promise<number>;
+    deleteRange(prefix: string, options: DeleteRangeOptions): Promise<number>;
+    scan(prefix: string, options?: ScanOptions): AsyncIterable<[string, Uint8Array]>;
+    keys(prefix: string, options?: ScanOptions): AsyncIterable<string>;
+    count(prefix: string): Promise<number>;
+    scoped(prefix: string): Storage;
+    batch(operations: BatchOperation[]): Promise<void>;
+    conditionalBatch(conditions: ConditionalBatchCondition[], operations: BatchOperation[]): Promise<boolean>;
+    query<T>(sql: string, parameters?: unknown[]): Promise<T[]>;
+    [Symbol.dispose](): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/storage/neon.js

@@ -0,0 +1,15 @@
+// @bun
+var U_=Object.defineProperty;var Z_=(_)=>_;function G_(_,E){this[_]=Z_.bind(null,E)}var z_=(_,E)=>{for(var F in E)U_(_,F,{get:E[F],enumerable:!0,configurable:!0,set:G_.bind(E,F)})};var M=(_,E)=>()=>(_&&(E=_(_=0)),E);var v_=(_,E,F)=>{if(E!=null){if(typeof E!=="object"&&typeof E!=="function")throw TypeError('Object expected to be assigned to "using" declaration');let W;if(F)W=E[Symbol.asyncDispose];if(W===void 0)W=E[Symbol.dispose];if(typeof W!=="function")throw TypeError("Object not disposable");_.push([F,W,E])}else if(F)_.push([F]);return E},P_=(_,E,F)=>{let W=(Y)=>E=F?new SuppressedError(Y,E,"An error was suppressed during disposal"):(F=!0,Y),J=(Y)=>{while(Y=_.pop())try{var Q=Y[1]&&Y[1].call(Y[2]);if(Y[0])return Promise.resolve(Q).then(J,(U)=>(W(U),J()))}catch(U){W(U)}if(F)throw E};return J()};function N(_,E,F){if(!_.capabilities()[E])throw Error(`Feature "${F}" requires storage capability "${E}", but this storage backend does not provide it.`)}function M_(_){let E=_.capabilities(),F=[];if(E.persistence!=="local"&&E.persistence!=="remote")F.push(`persistence must be "local" or "remote" (got "${E.persistence}")`);if(E.readAfterWrite!=="linearizable")F.push(`readAfterWrite must be "linearizable" (got "${E.readAfterWrite}")`);if(E.scanConsistency!=="snapshot")F.push(`scanConsistency must be "snapshot" (got "${E.scanConsistency}")`);if(!E.atomicBatch)F.push("atomicBatch must be true");if(!E.conditionalBatch)F.push("conditionalBatch must be true");if(F.length>0)throw Error(`Storage is not durable enough for recovery: ${F.join("; ")}.`)}var C="default";async function q(_,E){return await _.get(E)!==null}async function*H(_,E,F){for await(let[W]of _.scan(E,F))yield W}async function h(_,E){let F=0;for await(let W of H(_,E))F++;return F}async function b(_,E){let F=[];for await(let W of H(_,E))F.push({type:"delete",key:W});if(F.length===0)return 0;return await _.batch(F),F.length}async function x(_,E,F){let W=[];for await(let J of H(_,E,F))W.push({type:"delete",key:J});if(W.length===0)return 0;return await _.batch(W),W.length}var $_;var y=M(()=>{$_=["actrec:","archive:","async-act:","attr:","audit:bulk:","blob:","budget:","budget-charged:","ev:","fleet-event-by-workflow:","fleet-event:","fleet-event-tail","idx:","lease:","liveness:","offload:","op:","review:","schedule:","schedule-due:","schedule-run:","sig:","sigres:","sigseq:","start-idem:","state:","tag:","tool-effect:","upd:","upk:","upr:","wf:","wf-cleanup:","wf-cleanup-needed:","wf-concurrency:","wf-concurrency-holder:","wf-deadline:","wf-delayed:","wf-finalizer-state:","wf-has-services:","wf-headers:","wf-idx-","wf-teardown:","wf-teardown-deadletter:","wf-teardown-needed:","wf-terminal:"]});function G(_,E){if(E>A)throw new m(_,E)}function g(_){return _.length>0?_.slice(0,-1)+String.fromCharCode(_.charCodeAt(_.length-1)+1):"\xFF"}function u_(_,E={}){if(E.gt!==void 0&&_<=E.gt)return!1;if(E.gte!==void 0&&_<E.gte)return!1;if(E.lt!==void 0&&_>=E.lt)return!1;if(E.lte!==void 0&&_>E.lte)return!1;return!0}function u(_,E){if(_===null||E===null)return _===E;if(_.byteLength!==E.byteLength)return!1;for(let F=0;F<_.byteLength;F++)if(_[F]!==E[F])return!1;return!0}async function c(_,E){if(_.has)return _.has(E);return q(_,E)}function k(_,E,F){if(_.keys)return _.keys(E,F);return H(_,E,F)}async function w(_,E){if(_.count)return _.count(E);return h(_,E)}async function f(_,E){if(_.deletePrefix)return _.deletePrefix(E);return b(_,E)}async function c_(_,E){G("batch operations",E.length),await _.batch(E)}async function d(_,E,F){if(G("conditionalBatch conditions",E.length),G("conditionalBatch operations",F.length),N(_,"conditionalBatch","storageConditionalBatch"),!_.conditionalBatch)throw Error("This storage backend reports conditionalBatch capability but does not implement the conditionalBatch() method.");return _.conditionalBatch(E,F)}function X(_){return encodeURIComponent(_)}function k_(_){return decodeURIComponent(_)}function w_(_){try{return decodeURIComponent(_)}catch{return null}}var A=1e4,g_=1e4,m,Z=(_)=>String(_).padStart(16,"0"),H_="0",V_="1",I=(_,E,F,W)=>`sig:${X(_)}:${X(E)}:${W}:${X(F)}`,f_;var V=M(()=>{y();m=class m extends Error{code="StorageBatchOperationLimitExceededError";cap=A;count;target;constructor(_,E){super(`${_} count ${E} exceeds MAX_BATCH_OPERATIONS (${A}).`);this.name="StorageBatchOperationLimitExceededError",this.target=_,this.count=E}};f_={workflow:(_)=>`wf:${X(_)}`,checkpoint:(_)=>`wf:${X(_)}:ckpt`,checkpointHistory:(_,E)=>`wf:${X(_)}:ckpt:${String(E).padStart(10,"0")}`,timelinePrefix:(_)=>`wf:${X(_)}:timeline:`,timeline:(_,E)=>`wf:${X(_)}:timeline:${String(E).padStart(10,"0")}`,schedule:(_)=>`schedule:${X(_)}`,scheduleTick:(_,E)=>`schedule-due:${String(_).padStart(16,"0")}:${X(E)}`,scheduleRun:(_)=>`schedule-run:${X(_)}`,operation:(_,E,F)=>`op:${_}:${Z(E)}:${F}`,operationInflight:(_)=>`op:inflight:${_}`,operationQueued:(_)=>`op:queued:${_}`,operationResolved:(_)=>`op:resolved:${_}`,operationDeadLetterPrefix:()=>"op:dead-letter:",operationDeadLetter:(_)=>`op:dead-letter:${_}`,bulkOperationAuditPrefix:()=>"audit:bulk:",bulkOperationAudit:(_,E,F)=>`audit:bulk:${Z(_)}:${X(E)}:${X(F)}`,operationResolvedByTimePrefix:()=>"op:resolved-by-time:",operationResolvedByTime:(_,E)=>`op:resolved-by-time:${Z(_)}:${X(E)}`,asyncActivity:(_,E)=>`async-act:v1:${X(_)}:${X(E)}`,activityReconciliationPrefix:(_)=>`actrec:v1:${X(_)}:`,activityReconciliation:(_,E,F)=>`actrec:v1:${X(_)}:${X(E)}:${F}`,eventPrefix:(_)=>`ev:${X(_)}:`,event:(_,E)=>`ev:${X(_)}:${String(E).padStart(10,"0")}`,eventHead:(_)=>`ev:${X(_)}:head`,eventWatermark:(_)=>`ev:${X(_)}:watermark`,fleetEventPrefix:()=>"fleet-event:",fleetEvent:(_)=>`fleet-event:${String(_).padStart(10,"0")}`,fleetEventTail:()=>"fleet-event-tail",fleetEventByWorkflowPrefix:(_)=>`fleet-event-by-workflow:${X(_)}:`,fleetEventByWorkflow:(_,E)=>`fleet-event-by-workflow:${X(_)}:${String(E).padStart(10,"0")}`,signal:(_,E,F)=>I(_,E,F,V_),startSignal:(_,E,F)=>I(_,E,F,H_),signalSequence:(_)=>`sigseq:v1:${X(_)}`,signalAcceptedResponsePrefix:(_)=>`sigres:v1:${X(_)}:`,signalAcceptedResponse:(_,E,F)=>`sigres:v1:${X(_)}:${X(E)}:${X(F)}`,deadline:(_,E)=>`wf-deadline:${Z(_)}:${X(E)}`,terminalCleanup:(_,E)=>`wf-cleanup:${Z(_)}:${X(E)}`,teardownTimer:(_,E)=>`wf-teardown:${Z(_)}:${X(E)}`,delayedStart:(_,E)=>`wf-delayed:${Z(_)}:${X(E)}`,terminalWorkflowPrefix:()=>"wf-terminal:",terminalWorkflow:(_,E)=>`wf-terminal:${Z(_)}:${X(E)}`,attribute:(_)=>`attr:${X(_)}`,attributeIndex:(_,E,F)=>`idx:${_}:${E}:${X(F)}`,tagIndex:(_,E)=>`tag:${X(_)}:${X(E)}`,updatePrefix:(_)=>`upd:${X(_)}:`,update:(_,E)=>`upd:${X(_)}:${E}`,updateResponse:(_)=>`upr:${_}`,updateIdempotency:(_,E)=>`upk:${X(_)}:${E}`,startIdempotency:(_)=>`start-idem:${X(_)}`,startIdempotencySignalId:(_)=>`start-idem:${_}`,livenessPrefix:()=>"liveness:",liveness:(_)=>`liveness:${X(_)}`,leasePrefix:()=>"lease:",leaseEpoch:()=>"lease:epoch",leaseHolder:()=>"lease:holder",budget:(_,E,F)=>`budget:${_}:${E}:${F}`,review:(_,E)=>`review:${X(_)}:${E}`,workflowHeaders:(_)=>`wf-headers:${X(_)}`,childCancellationPrefix:(_)=>`child-cancel:${X(_)}:`,childCancellation:(_,E)=>`child-cancel:${X(_)}:${X(E)}`,terminalCleanupNeeded:(_)=>`wf-cleanup-needed:${X(_)}`,workflowConcurrency:(_,E)=>`wf-concurrency:${X(_)}:${X(E)}`,workflowConcurrencyHolder:(_)=>`wf-concurrency-holder:${X(_)}`,workflowHasServices:(_)=>`wf-has-services:${X(_)}`,finalizerState:(_)=>`wf-finalizer-state:${X(_)}`,teardownOwed:(_)=>`wf-teardown-needed:${X(_)}`,teardownDeadLetter:(_)=>`wf-teardown-deadletter:${X(_)}`,offload:(_,E)=>`offload:${X(_)}:${E}`,archive:(_,E)=>`archive:${X(_)}:${E}`,stateExecution:(_,E)=>`state:execution:${X(_)}:${X(E)}`,stateWorkflow:(_,E)=>`state:workflow-scope:${C}:${X(_)}:${X(E)}`,streamChunkPrefix:(_,E)=>`blob:${X(_)}:${E}:chunk:`,streamChunk:(_,E,F)=>`blob:${X(_)}:${E}:chunk:${String(F).padStart(10,"0")}`,streamTail:(_,E)=>`blob:${X(_)}:${E}:tail`,streamMetadata:(_,E)=>`blob:${X(_)}:${E}:meta`,budgetCharged:(_)=>`budget-charged:${_}`,toolEffect:(_,E,F)=>`tool-effect:${X(_)}:${E}:${F}`,workflowVisibilityStatus:(_,E)=>`wf-idx-status:${X(_)}:${X(E)}`,workflowVisibilityType:(_,E)=>`wf-idx-type:${X(_)}:${X(E)}`,workflowVisibilityCreated:(_,E)=>`wf-idx-created:${Z(_)}:${X(E)}`,workflowVisibilityUpdated:(_,E)=>`wf-idx-updated:${Z(_)}:${X(E)}`,workflowVisibilityDeadline:(_,E)=>`wf-idx-deadline:${Z(_)}:${X(E)}`,workflowVisibilityManifest:(_)=>`wf-idx-manifest:${X(_)}`,workflowVisibilityMetaVersion:()=>"wf-idx-meta:version",workflowVisibilityMetaBuiltAt:()=>"wf-idx-meta:built-at",workflowVisibilityMetaCursor:()=>"wf-idx-meta:cursor"}});function j_(_){if(_===void 0)return;if(typeof _!=="number"||!Number.isInteger(_)||_<0)throw Error("deleteRange limit must be a finite non-negative integer");return _===0?0:_}function j(_){let E={},F=!1;for(let J of["gt","gte","lt","lte"]){let Y=_[J];if(Y===void 0)continue;if(typeof Y!=="string")throw Error("deleteRange bounds must be strings");E[J]=Y,F=!0}if(!F)throw Error("deleteRange requires at least one of gt/gte/lt/lte; use deletePrefix to delete a whole prefix");let W=j_(_.limit);if(W!==void 0)E.limit=W;return E}async function l(_,E,F){let W=j(F);if(_.deleteRange)return _.deleteRange(E,W);return x(_,E,W)}var S=()=>{};function T(_){return _.replaceAll(/:+$/g,"")}function L_(_,E){let F=T(_),W=T(E);if(F.length===0)return W;if(W.length===0)return F;return`${F}:${W}`}function p(_,E){return new K(_,E)}var K;var a=M(()=>{S();V();K=class K{#_;#E;constructor(_,E){this.#_=_,this.#E=T(E)}#F(_){if(this.#E.length===0)return _;return _.length===0?`${this.#E}:`:`${this.#E}:${_}`}#X(_){if(this.#E.length===0)return _;return _.slice(this.#E.length+1)}#Y(_={}){let E={};if(_.limit!==void 0)E.limit=_.limit;if(_.reverse!==void 0)E.reverse=_.reverse;if(_.gt!==void 0)E.gt=this.#F(_.gt);if(_.gte!==void 0)E.gte=this.#F(_.gte);if(_.lt!==void 0)E.lt=this.#F(_.lt);if(_.lte!==void 0)E.lte=this.#F(_.lte);return E}#J(_){let E={};if(_.limit!==void 0)E.limit=_.limit;if(_.gt!==void 0)E.gt=this.#F(_.gt);if(_.gte!==void 0)E.gte=this.#F(_.gte);if(_.lt!==void 0)E.lt=this.#F(_.lt);if(_.lte!==void 0)E.lte=this.#F(_.lte);return E}capabilities(){return this.#_.capabilities()}scoped(_){return new K(this.#_,L_(this.#E,_))}async get(_){return this.#_.get(this.#F(_))}async put(_,E){await this.#_.put(this.#F(_),E)}async delete(_){await this.#_.delete(this.#F(_))}async*scan(_,E){for await(let[F,W]of this.#_.scan(this.#F(_),this.#Y(E)))yield[this.#X(F),W]}async batch(_){G("batch operations",_.length),await this.#_.batch(_.map((E)=>{if(E.type==="put")return{type:"put",key:this.#F(E.key),value:E.value};return{type:"delete",key:this.#F(E.key)}}))}async conditionalBatch(_,E){return d(this.#_,_.map((F)=>({key:this.#F(F.key),expectedValue:F.expectedValue})),E.map((F)=>{if(F.type==="put")return{type:"put",key:this.#F(F.key),value:F.value};return{type:"delete",key:this.#F(F.key)}}))}async has(_){return c(this.#_,this.#F(_))}async deletePrefix(_){return f(this.#_,this.#F(_))}async deleteRange(_,E){let F=this.#J(j(E));return l(this.#_,this.#F(_),F)}async*keys(_,E){for await(let F of k(this.#_,this.#F(_),this.#Y(E)))yield this.#X(F)}async count(_){return w(this.#_,this.#F(_))}[Symbol.dispose](){this.#_[Symbol.dispose]()}}});function C_(_){return _.trim().replace(/;+\s*$/u,"").trim()}function A_(_){return B_.test(_)}function Y_(_){let E=C_(_);if(E.length===0)throw Error("Storage query must not be empty.");if(E.includes(";"))throw Error("Storage query must contain exactly one read-only statement.");if(N_.test(E))return;if(D_.test(E)&&A_(E))return;throw Error("Storage query only supports read-only SELECT and PRAGMA statements.")}var D_,B_,N_;var J_=M(()=>{D_=/^PRAGMA\b/iu,B_=/^PRAGMA\s+(?:[A-Z_][A-Z0-9_]*\.)?[A-Z_][A-Z0-9_]*\s*$/iu,N_=/^SELECT\b/iu});S();V();import{Pool as S_}from"@neondatabase/serverless";V();function O(_){return _.rowCount??_.affectedRows??_.rows.length}function L(_){if(_ instanceof Uint8Array)return new Uint8Array(_);return new Uint8Array(_)}function D(_){return Buffer.from(_)}function z(_){let E=new Map,F=new Set;for(let W of _)if(W.type==="put")F.delete(W.key),E.set(W.key,W.value);else E.delete(W.key),F.add(W.key);return{puts:E,deletes:F}}async function s(_,E,F){if(F.length===0)return!0;let W=F.map((Q)=>Q.key),J=await _.query(E.selectValuesByKeys,[W]),Y=new Map;for(let Q of J.rows){let U=Q.value;if(U!==null&&U!==void 0)Y.set(Q.key,L(U))}for(let Q of F){let U=Y.get(Q.key)??null;if(!u(U,Q.expectedValue))return!1}return!0}async function v(_,E,F){if(F.puts.size>0){let W=[],J=[];for(let[Y,Q]of F.puts)W.push(Y),J.push(D(Q));await _.query(E.upsertValuesByKeys,[W,J])}if(F.deletes.size>0)await _.query(E.deleteValuesByKeys,[[...F.deletes]])}V();var n="kv",i=/^[a-z_][a-z0-9_]*$/i;function P(_,E){if(!i.test(_))throw Error(`NeonStorage ${E} name "${_}" is not a valid Postgres identifier. Use only letters, digits, and underscores, starting with a letter or underscore (matching ${i.source}).`)}function t(_){let{schema:E,table:F}=_;if(E===void 0&&F===void 0)return n;let W=F??n;if(P(W,"table"),E===void 0)return`"${W}"`;return P(E,"schema"),`"${E}"."${W}"`}function B(_){return[_,g(_)]}function o(_,E){let{gt:F,gte:W,lt:J,lte:Y}=E,Q=B(_),U=["key >= $1 AND key < $2"];if(F!==void 0)Q.push(F),U.push(`key > $${Q.length}`);if(W!==void 0)Q.push(W),U.push(`key >= $${Q.length}`);if(J!==void 0)Q.push(J),U.push(`key < $${Q.length}`);if(Y!==void 0)Q.push(Y),U.push(`key <= $${Q.length}`);return{conditions:U,parameters:Q}}function r(_,E={}){let{limit:F,reverse:W}=E,{conditions:J,parameters:Y}=o(_,E),Q=W?"DESC":"ASC",U="";if(F!==void 0)Y.push(F),U=` LIMIT $${Y.length}`;return{parameters:Y,whereOrderLimit:`WHERE ${J.join(" AND ")} ORDER BY key ${Q}${U}`}}function e(_){let E=`CREATE TABLE IF NOT EXISTS ${_} (
+  key TEXT COLLATE "C" PRIMARY KEY,
+  value BYTEA NOT NULL
+)`,F=`
+  SELECT COALESCE(co.collname, 'default') AS collation
+  FROM pg_attribute a
+  LEFT JOIN pg_collation co ON co.oid = a.attcollation
+  WHERE a.attrelid = to_regclass($1) AND a.attname = 'key' AND a.attnum > 0
+`;return{tableReference:_,createTable:E,selectKeyCollation:`
+  SELECT COALESCE(co.collname, 'default') AS collation
+  FROM pg_attribute a
+  LEFT JOIN pg_collation co ON co.oid = a.attcollation
+  WHERE a.attrelid = to_regclass($1) AND a.attname = 'key' AND a.attnum > 0
+`,selectValueByKey:`SELECT value FROM ${_} WHERE key = $1`,upsertValueByKey:`INSERT INTO ${_} (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value`,deleteValueByKey:`DELETE FROM ${_} WHERE key = $1`,selectKeyPresence:`SELECT 1 AS present FROM ${_} WHERE key = $1 LIMIT 1`,countKeysByPrefix:`SELECT COUNT(*) AS count FROM ${_} WHERE key >= $1 AND key < $2`,deleteKeysByPrefix:`DELETE FROM ${_} WHERE key >= $1 AND key < $2`,selectValuesByKeys:`SELECT key, value FROM ${_} WHERE key = ANY($1)`,upsertValuesByKeys:`INSERT INTO ${_} (key, value) SELECT * FROM unnest($1::text[], $2::bytea[]) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value`,deleteValuesByKeys:`DELETE FROM ${_} WHERE key = ANY($1)`,keyValueRangeSelect(W,J={}){let{parameters:Y,whereOrderLimit:Q}=r(W,J);return{parameters:Y,sql:`SELECT key, value FROM ${_} ${Q}`}},keyRangeSelect(W,J={}){let{parameters:Y,whereOrderLimit:Q}=r(W,J);return{parameters:Y,sql:`SELECT key FROM ${_} ${Q}`}},keyRangeDelete(W,J){let{conditions:Y,parameters:Q}=o(W,J),U=Y.join(" AND ");if(J.limit===void 0)return{parameters:Q,sql:`DELETE FROM ${_} WHERE ${U}`};return Q.push(J.limit),{parameters:Q,sql:`DELETE FROM ${_} WHERE key IN (SELECT key FROM ${_} WHERE ${U} ORDER BY key ASC LIMIT $${Q.length})`}}}}var __="BEGIN ISOLATION LEVEL SERIALIZABLE",E_="BEGIN ISOLATION LEVEL READ COMMITTED",F_="BEGIN READ ONLY",W_="COMMIT",R="ROLLBACK";function X_(_){return P(_,"schema"),`CREATE SCHEMA IF NOT EXISTS "${_}"`}J_();a();var T_=new Set(["40001","40P01"]),Q_=5;function K_(_){if(typeof _!=="object"||_===null||!("code"in _))return!1;let E=_.code;return typeof E==="string"&&T_.has(E)}class O_{#_;#E;#F;#X;#Y;#J;constructor(_,E=(F)=>new S_({connectionString:F})){this.#Y=_.pool===void 0,this.#_=_.pool??E(_.url),this.#F=_.schema;let F=t({schema:_.schema,table:_.table});this.#E=e(F)}capabilities(){return{persistence:"remote",readAfterWrite:"linearizable",scanConsistency:"snapshot",atomicBatch:!0,conditionalBatch:!0,boundedRangeDelete:!0}}#W(){return this.#X??=this.#Z().catch((_)=>{throw this.#X=void 0,_}),this.#X}async#Z(){if(this.#F!==void 0)await this.#_.query(X_(this.#F));await this.#_.query(this.#E.createTable),await this.#G()}async#G(){let E=(await this.#_.query(this.#E.selectKeyCollation,[this.#E.tableReference])).rows[0]?.collation;if(E==="C")return;let F=E===void 0?"no such table":typeof E==="string"?`"${E}"`:"an unexpected collation value";throw Error(`NeonStorage requires the ${this.#E.tableReference} table's "key" column to use COLLATE "C" (found ${F}). A table created without COLLATE "C" sorts keys by the database locale, which breaks Weft's lexicographic prefix scans. Use a fresh table, or recreate it as: CREATE TABLE ${this.#E.tableReference} (key TEXT COLLATE "C" PRIMARY KEY, value BYTEA NOT NULL).`)}async get(_){await this.#W();let F=(await this.#_.query(this.#E.selectValueByKey,[_])).rows[0];if(F===void 0)return null;let W=F.value;if(W===null||W===void 0)return null;return L(W)}async put(_,E){await this.#W(),await this.#_.query(this.#E.upsertValueByKey,[_,D(E)])}async delete(_){await this.#W(),await this.#_.query(this.#E.deleteValueByKey,[_])}async has(_){return await this.#W(),(await this.#_.query(this.#E.selectKeyPresence,[_])).rows.length>0}async deletePrefix(_){await this.#W();let[E,F]=B(_),W=await this.#_.query(this.#E.deleteKeysByPrefix,[E,F]);return O(W)}async deleteRange(_,E){await this.#W();let F=j(E),{parameters:W,sql:J}=this.#E.keyRangeDelete(_,F),Y=await this.#_.query(J,W);return O(Y)}async*scan(_,E={}){await this.#W();let{parameters:F,sql:W}=this.#E.keyValueRangeSelect(_,E),J=await this.#_.query(W,F);for(let Y of J.rows)yield[Y.key,L(Y.value)]}async*keys(_,E={}){await this.#W();let{parameters:F,sql:W}=this.#E.keyRangeSelect(_,E),J=await this.#_.query(W,F);for(let Y of J.rows)yield Y.key}async count(_){await this.#W();let[E,F]=B(_),W=await this.#_.query(this.#E.countKeysByPrefix,[E,F]);return Number(W.rows[0]?.count??0)}scoped(_){return p(this,_)}async#Q(_,E,F=()=>!0){let W=await this.#_.connect();try{await W.query(_);try{let J=await E(W);return await W.query(F(J)?W_:R),J}catch(J){throw await W.query(R).catch(()=>{}),J}}finally{W.release()}}async batch(_){if(G("batch operations",_.length),_.length===0)return;await this.#W(),await this.#Q(E_,async(E)=>{await v(E,this.#E,z(_))})}async conditionalBatch(_,E){G("conditionalBatch conditions",_.length),G("conditionalBatch operations",E.length),await this.#W();let F=z(E),W;for(let J=0;J<Q_;J+=1)try{return await this.#Q(__,async(Y)=>{if(!await s(Y,this.#E,_))return!1;return await v(Y,this.#E,F),!0},(Y)=>Y)}catch(Y){if(!K_(Y))throw Y;W=Y}throw Error(`conditionalBatch exhausted ${Q_} attempts after retryable transaction failures`,{cause:W})}async query(_,E){return await this.#W(),Y_(_),this.#Q(F_,async(F)=>{return(await F.query(_,E??[])).rows})}#U(){if(!this.#Y)return Promise.resolve();return this.#J??=this.#_.end(),this.#J}[Symbol.dispose](){this.#U().catch(()=>{})}async[Symbol.asyncDispose](){await this.#U()}}export{O_ as NeonStorage};

package/dist/storage/node-sqlite-loader.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Lazy loader for the optional `better-sqlite3` peer dependency used by
+ * {@link NodeSQLiteStorage}. Kept in its own module — and deliberately NOT in the
+ * package `exports` map — so the test-only injection seam
+ * ({@link loadBetterSqlite3ForTest}) never becomes part of the documented public
+ * surface. `node-sqlite.ts` imports `loadBetterSqlite3` (production path);
+ * `node-sqlite.test.ts` imports the test entry directly from here.
+ *
+ * @module storage/node-sqlite-loader
+ */
+/**
+ * Minimal `better-sqlite3` `Database` surface this adapter uses. Defined here so
+ * both the loader and the storage module compile without the package installed.
+ */
+export type BetterSqliteStatement = {
+    run(...parameters: unknown[]): unknown;
+    get(...parameters: unknown[]): Record<string, unknown> | undefined;
+    all(...parameters: unknown[]): Record<string, unknown>[];
+};
+export type BetterSqliteTransaction = (...args: unknown[]) => unknown;
+export type BetterSqliteDatabase = {
+    pragma(source: string): unknown;
+    exec(source: string): void;
+    prepare(source: string): BetterSqliteStatement;
+    transaction(fn: (...args: unknown[]) => unknown): BetterSqliteTransaction;
+    close(): void;
+};
+export type BetterSqliteConstructor = new (path: string) => BetterSqliteDatabase;
+/**
+ * Build the actionable error thrown when `better-sqlite3` cannot be loaded —
+ * either because the optional dependency is absent or its native binding fails
+ * to dlopen.
+ */
+export declare function createMissingBetterSqlite3Error(cause: unknown): Error;
+/**
+ * Whether `error` is a recognizable `better-sqlite3` load failure (missing
+ * package or native-binding dlopen failure) worth reshaping into the actionable
+ * peer-dependency error rather than re-throwing raw.
+ */
+export declare function isBetterSqlite3LoadFailure(error: unknown): boolean;
+/**
+ * Resolve the `better-sqlite3` module via a CommonJS require. This package is
+ * ESM (`type: module`), so the global `require` is not defined — `createRequire`
+ * from `node:module` builds a CommonJS require for loading the native binding.
+ *
+ * Extracted as a standalone function so tests can inject a throwing resolver
+ * (see {@link loadBetterSqlite3ForTest}) to exercise the missing/failed-dependency
+ * paths WITHOUT `mock.module('node:module', ...)`. That mock is irreversible in
+ * Bun: it patches the CJS loader process-wide and `mock.restore()` does not undo
+ * it, which poisons `require()` for every later test in the same process
+ * (notably any WASM module that requires a core module during boot).
+ */
+declare function resolveBetterSqlite3Module(): {
+    default?: BetterSqliteConstructor;
+} & BetterSqliteConstructor;
+/** Resolver for the `better-sqlite3` module. Injectable for tests. */
+type BetterSqlite3ModuleResolver = typeof resolveBetterSqlite3Module;
+/**
+ * Load (and cache) the `better-sqlite3` constructor. Reshapes a recognized load
+ * failure into the actionable peer-dependency error.
+ */
+export declare function loadBetterSqlite3(resolveModule?: BetterSqlite3ModuleResolver): BetterSqliteConstructor;
+/**
+ * Test-only entry that exercises {@link loadBetterSqlite3}'s module-resolution
+ * and error-shaping with an injected resolver, bypassing the cached constructor
+ * so the missing/failed-dependency paths run every call. This lets those paths be
+ * tested without mocking the global `node:module` loader. Lives in this
+ * non-exported module so it never reaches the public package surface.
+ */
+export declare function loadBetterSqlite3ForTest(resolveModule: BetterSqlite3ModuleResolver): BetterSqliteConstructor;
+export {};

package/dist/storage/node-sqlite-loader.js

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+let DatabaseConstructor;
+export function createMissingBetterSqlite3Error(cause) {
+  return Error('NodeSQLiteStorage requires the optional peer dependency "better-sqlite3". Install it in your application with: bun add better-sqlite3 (or npm install better-sqlite3).', { cause });
+}
+export function isBetterSqlite3LoadFailure(error) {
+  if (!(error instanceof Error))
+    return !1;
+  const errorCode = error.code;
+  if (errorCode === "MODULE_NOT_FOUND")
+    return error.message.includes("'better-sqlite3'") || error.message.includes('"better-sqlite3"') || error.message.includes("'bindings'") || error.message.includes('"bindings"');
+  if (errorCode === "ERR_DLOPEN_FAILED")
+    return error.message.includes("better-sqlite3");
+  return !1;
+}
+function resolveBetterSqlite3Module() {
+  return createRequire(import.meta.url)("better-sqlite3");
+}
+export function loadBetterSqlite3(resolveModule = resolveBetterSqlite3Module) {
+  if (DatabaseConstructor)
+    return DatabaseConstructor;
+  let mod;
+  try {
+    mod = resolveModule();
+  } catch (error) {
+    if (isBetterSqlite3LoadFailure(error))
+      throw createMissingBetterSqlite3Error(error);
+    throw error;
+  }
+  DatabaseConstructor = typeof mod.default === "function" ? mod.default : mod;
+  return DatabaseConstructor;
+}
+export function loadBetterSqlite3ForTest(resolveModule) {
+  const previous = DatabaseConstructor;
+  DatabaseConstructor = void 0;
+  try {
+    return loadBetterSqlite3(resolveModule);
+  } finally {
+    DatabaseConstructor = previous;
+  }
+}

package/dist/storage/node-sqlite.d.ts

@@ -11,25 +11,7 @@
  * @module storage/node-sqlite
  */
 import type { BatchOperation, ConditionalBatchCondition, ScanOptions, Storage, StorageCapabilities } from './interface.ts';
-/**
- * Minimal subset of the `better-sqlite3` API surface that this adapter uses.
- * Defined here so the module compiles without the package installed — the
- * actual dependency is resolved lazily at construction time.
- */
-type BetterSqliteStatement = {
-    run(...parameters: unknown[]): unknown;
-    get(...parameters: unknown[]): Record<string, unknown> | undefined;
-    all(...parameters: unknown[]): Record<string, unknown>[];
-};
-type BetterSqliteTransaction = (...args: unknown[]) => unknown;
-type BetterSqliteDatabase = {
-    pragma(source: string): unknown;
-    exec(source: string): void;
-    prepare(source: string): BetterSqliteStatement;
-    transaction(fn: (...args: unknown[]) => unknown): BetterSqliteTransaction;
-    close(): void;
-};
-type BetterSqliteConstructor = new (path: string) => BetterSqliteDatabase;
+import { type BetterSqliteConstructor } from './node-sqlite-loader.ts';
 /**
  * Runtime-neutral alias for the Node SQLite adapter. Consumers that import
  * from `@lostgradient/weft/storage/sqlite` get this class under Node.

package/dist/storage/node-sqlite.js

@@ -1,7 +1,4 @@
 // @bun
-// src/storage/node-sqlite.ts
-import { createRequire } from "module";
-
 // src/storage/capabilities.ts
 function requireStorageCapability(storage, capability, featureName) {
   if (!storage.capabilities()[capability]) {
@@ -49,6 +46,24 @@ async function storageDeleteRangeCore(storage, prefix, options) {
 }
 
 // src/storage/interface.ts
+var MAX_BATCH_OPERATIONS = 1e4;
+class StorageBatchOperationLimitExceededError extends Error {
+  code = "StorageBatchOperationLimitExceededError";
+  cap = MAX_BATCH_OPERATIONS;
+  count;
+  target;
+  constructor(target, count) {
+    super(`${target} count ${count} exceeds MAX_BATCH_OPERATIONS (${MAX_BATCH_OPERATIONS}).`);
+    this.name = "StorageBatchOperationLimitExceededError";
+    this.target = target;
+    this.count = count;
+  }
+}
+function assertStorageBatchOperationCount(target, count) {
+  if (count > MAX_BATCH_OPERATIONS) {
+    throw new StorageBatchOperationLimitExceededError(target, count);
+  }
+}
 function resolvePrefixRangeEnd(prefix) {
   return prefix.length > 0 ? prefix.slice(0, -1) + String.fromCharCode(prefix.charCodeAt(prefix.length - 1) + 1) : "\xFF";
 }
@@ -91,6 +106,8 @@ async function storageDeletePrefix(storage, prefix) {
   return storageDeletePrefixCore(storage, prefix);
 }
 async function storageConditionalBatch(storage, conditions, operations) {
+  assertStorageBatchOperationCount("conditionalBatch conditions", conditions.length);
+  assertStorageBatchOperationCount("conditionalBatch operations", operations.length);
   requireStorageCapability(storage, "conditionalBatch", "storageConditionalBatch");
   if (!storage.conditionalBatch) {
     throw new Error("This storage backend reports conditionalBatch capability but does not implement the conditionalBatch() method.");
@@ -98,6 +115,44 @@ async function storageConditionalBatch(storage, conditions, operations) {
   return storage.conditionalBatch(conditions, operations);
 }
 
+// src/storage/node-sqlite-loader.ts
+import { createRequire } from "module";
+var DatabaseConstructor;
+function createMissingBetterSqlite3Error(cause) {
+  return new Error('NodeSQLiteStorage requires the optional peer dependency "better-sqlite3". ' + "Install it in your application with: bun add better-sqlite3 (or npm install better-sqlite3).", { cause });
+}
+function isBetterSqlite3LoadFailure(error) {
+  if (!(error instanceof Error))
+    return false;
+  const errorCode = error.code;
+  if (errorCode === "MODULE_NOT_FOUND") {
+    return error.message.includes("'better-sqlite3'") || error.message.includes('"better-sqlite3"') || error.message.includes("'bindings'") || error.message.includes('"bindings"');
+  }
+  if (errorCode === "ERR_DLOPEN_FAILED") {
+    return error.message.includes("better-sqlite3");
+  }
+  return false;
+}
+function resolveBetterSqlite3Module() {
+  const requireFromHere = createRequire(import.meta.url);
+  return requireFromHere("better-sqlite3");
+}
+function loadBetterSqlite3(resolveModule = resolveBetterSqlite3Module) {
+  if (DatabaseConstructor)
+    return DatabaseConstructor;
+  let mod;
+  try {
+    mod = resolveModule();
+  } catch (error) {
+    if (isBetterSqlite3LoadFailure(error)) {
+      throw createMissingBetterSqlite3Error(error);
+    }
+    throw error;
+  }
+  DatabaseConstructor = typeof mod.default === "function" ? mod.default : mod;
+  return DatabaseConstructor;
+}
+
 // src/storage/sqlite-key-value-queries.ts
 var SQLITE_CREATE_KEY_VALUE_TABLE = `CREATE TABLE IF NOT EXISTS kv (
   key TEXT PRIMARY KEY,
@@ -178,35 +233,6 @@ function buildSqliteKeyRangeSelect(prefix, options = {}) {
 }
 
 // src/storage/node-sqlite.ts
-var DatabaseConstructor;
-function createMissingBetterSqlite3Error(cause) {
-  return new Error('NodeSQLiteStorage requires the optional peer dependency "better-sqlite3". ' + "Install it in your application with: bun add better-sqlite3 (or npm install better-sqlite3).", { cause });
-}
-function isBetterSqlite3LoadFailure(error) {
-  if (!(error instanceof Error))
-    return false;
-  const errorCode = error.code;
-  if (errorCode === "MODULE_NOT_FOUND") {
-    return error.message.includes("'better-sqlite3'") || error.message.includes('"better-sqlite3"') || error.message.includes("'bindings'") || error.message.includes('"bindings"');
-  }
-  if (errorCode === "ERR_DLOPEN_FAILED") {
-    return error.message.includes("better-sqlite3");
-  }
-  return false;
-}
-function loadBetterSqlite3() {
-  if (DatabaseConstructor)
-    return DatabaseConstructor;
-  const requireFromHere = createRequire(import.meta.url);
-  let mod;
-  try {
-    mod = requireFromHere("better-sqlite3");
-  } catch (error) {
-    throw createMissingBetterSqlite3Error(error);
-  }
-  DatabaseConstructor = typeof mod.default === "function" ? mod.default : mod;
-  return DatabaseConstructor;
-}
 class NodeSQLiteStorage {
   #database;
   #persistence;
@@ -286,11 +312,14 @@ class NodeSQLiteStorage {
     }
   }
   async batch(operations) {
+    assertStorageBatchOperationCount("batch operations", operations.length);
     if (operations.length === 0)
       return;
     this.#batchTransaction(operations);
   }
   async conditionalBatch(conditions, operations) {
+    assertStorageBatchOperationCount("conditionalBatch conditions", conditions.length);
+    assertStorageBatchOperationCount("conditionalBatch operations", operations.length);
     const conditionalTransaction = this.#database.transaction((...arguments_) => {
       const pendingConditions = arguments_[0];
       const pendingOperations = arguments_[1];

package/dist/storage/postgres-key-value-queries.d.ts

@@ -0,0 +1,104 @@
+import type { NormalizedDeleteRangeOptions } from './delete-range.ts';
+import { type ScanOptions } from './interface.ts';
+/**
+ * The Postgres counterpart of `sqlite-key-value-queries.ts`. The schema is the
+ * same single `kv(key, value)` table, but two Postgres specifics differ from the
+ * SQLite builders and force a separate module:
+ *
+ * - **Numbered placeholders.** Postgres binds parameters as `$1`, `$2`, … in
+ *   statement order, not the positional `?` SQLite uses. A builder that appends
+ *   bounds dynamically must therefore track the next placeholder index.
+ * - **`COLLATE "C"` on the key.** Postgres `TEXT` sorts by the database locale,
+ *   which reorders punctuation and would silently corrupt every prefix-range
+ *   scan and `ORDER BY key` the engine relies on. Pinning the primary-key column
+ *   to the `C` collation restores byte-wise (codepoint) ordering, matching
+ *   SQLite's default `BINARY` collation and the engine's key-layout assumptions.
+ *
+ * Every query is parameterized by a **table reference** so the adapter can point
+ * at a configured `"schema"."table"` instead of the default unqualified `kv`
+ * (see {@link buildPostgresKeyValueQueries}). The reference is interpolated once
+ * at construction, not per query.
+ *
+ * @module storage/postgres-key-value-queries
+ */
+/** The default unqualified table reference (resolves through `search_path`). */
+export declare const DEFAULT_POSTGRES_TABLE_REFERENCE = "kv";
+/**
+ * Validate a Postgres identifier (schema or table name) against a strict
+ * `[a-z_][a-z0-9_]*` pattern. Identifiers cannot be bound as `$n` parameters, so
+ * they must be interpolated into the SQL text — this validation, run once at
+ * construction, is the injection guard that makes interpolation safe. The strict
+ * pattern excludes the `"` quote character, so no quote-doubling is required.
+ */
+export declare function assertPostgresIdentifier(value: string, role: 'schema' | 'table'): void;
+/**
+ * Resolve the SQL table reference from optional schema/table names. With neither
+ * set, returns the bare unqualified `kv` so existing deployments emit
+ * byte-identical SQL (the default search-path-resolved table). With either set,
+ * returns a fully quoted `"schema"."table"` reference; both names are validated
+ * as strict identifiers first so the interpolation is injection-safe.
+ */
+export declare function resolvePostgresTableReference(options: {
+    schema?: string | undefined;
+    table?: string | undefined;
+}): string;
+export type PostgresKeyRangeQueryParameter = string | number;
+/** A fully-built SQL statement and its bound parameters (SELECT or DELETE). */
+export type PostgresBuiltQuery = {
+    parameters: PostgresKeyRangeQueryParameter[];
+    sql: string;
+};
+export declare function buildPostgresPrefixRangeParameters(prefix: string): [string, string];
+/**
+ * The complete set of SQL statements an adapter instance runs, all bound to one
+ * `tableReference`. Built once per {@link NeonStorage} via
+ * {@link buildPostgresKeyValueQueries}; the range builders close over the
+ * reference so callers never re-pass it.
+ */
+export type PostgresKeyValueQueries = {
+    readonly tableReference: string;
+    readonly createTable: string;
+    readonly selectKeyCollation: string;
+    readonly selectValueByKey: string;
+    readonly upsertValueByKey: string;
+    readonly deleteValueByKey: string;
+    readonly selectKeyPresence: string;
+    readonly countKeysByPrefix: string;
+    readonly deleteKeysByPrefix: string;
+    /** One-statement condition read for `conditionalBatch`: `key = ANY($1)`. */
+    readonly selectValuesByKeys: string;
+    /** One-statement multi-row upsert for `batch`: `unnest($1::text[], $2::bytea[])`. */
+    readonly upsertValuesByKeys: string;
+    /** One-statement delete for `batch`: `key = ANY($1)`. */
+    readonly deleteValuesByKeys: string;
+    keyValueRangeSelect(prefix: string, options?: ScanOptions): PostgresBuiltQuery;
+    keyRangeSelect(prefix: string, options?: ScanOptions): PostgresBuiltQuery;
+    keyRangeDelete(prefix: string, options: NormalizedDeleteRangeOptions): PostgresBuiltQuery;
+};
+/**
+ * Build the full query set for a `kv`-shaped table at `tableReference` (either
+ * the bare unqualified `kv` or a quoted `"schema"."table"`). The reference is
+ * already validated/quoted by {@link resolvePostgresTableReference}; this only
+ * interpolates it into statement text.
+ *
+ * The collation check uses `to_regclass($1)` with the resolved reference so it
+ * is scoped to the configured table — a `kv` table elsewhere on the search path
+ * can never be inspected by mistake.
+ */
+export declare function buildPostgresKeyValueQueries(tableReference: string): PostgresKeyValueQueries;
+/** Begin a transaction at SERIALIZABLE isolation (conditionalBatch's CAS path). */
+export declare const PG_BEGIN_SERIALIZABLE = "BEGIN ISOLATION LEVEL SERIALIZABLE";
+/** Begin a transaction at READ COMMITTED isolation (the atomic batch() path). */
+export declare const PG_BEGIN_READ_COMMITTED = "BEGIN ISOLATION LEVEL READ COMMITTED";
+/**
+ * Begin a READ ONLY transaction for the `query()` passthrough. Postgres enforces
+ * this at the database level — a writing statement (including a data-modifying
+ * CTE that a textual SELECT check would miss) errors instead of mutating.
+ */
+export declare const PG_BEGIN_READ_ONLY = "BEGIN READ ONLY";
+/** Commit the current transaction. */
+export declare const PG_COMMIT = "COMMIT";
+/** Roll back the current transaction. */
+export declare const PG_ROLLBACK = "ROLLBACK";
+/** Create the configured schema if it is absent (only when a schema is set). */
+export declare function buildPostgresCreateSchema(schema: string): string;