orez 0.4.24 → 0.4.26

package/dist/worker/cf-do-shim.d.ts

@@ -0,0 +1,55 @@
+/**
+ * namespace routing primitives for the Cloudflare Durable Object deploy.
+ *
+ * a multi-tenant CF/orez deploy shards data into one DO instance per tenant
+ * namespace (`ns:<scope>-<id>`) plus a control-plane `singleton`. the worker
+ * tiers carry the chosen namespace in a header (and re-stamp it so an inbound
+ * value is never trusted) and must validate its shape before routing — an
+ * unvalidated namespace would let a client mint unbounded DO instances.
+ *
+ * the deployed worker entry classes are bundled strings in the consumer's
+ * deploy integration (awkward to unit-test), so the routing decision and the
+ * security-relevant shape validation live here as pure functions, tested in
+ * cf-do-shim.test.ts. consumers import these into their worker shims instead of
+ * copy-pasting the validation regex at every routing site.
+ */
+export interface NamespaceRoutingOptions {
+    /** allowed namespace scope prefixes. default `['proj', 'test']`. */
+    scopes?: readonly string[];
+    /**
+     * namespace values that resolve to the control-plane `singleton` instance,
+     * in addition to the empty string (which is always the singleton).
+     */
+    controlPlaneNamespaces?: readonly string[];
+    /** request header the worker tiers carry the namespace in. default `x-orez-ns`. */
+    nsHeader?: string;
+}
+/**
+ * true when `ns` is a structurally valid tenant namespace: a configured scope
+ * prefix followed by a 1-64 char `[A-Za-z0-9_-]` id. this is the gate that
+ * keeps a stray header from minting an unbounded DO instance, so every routing
+ * site that forwards a namespace should run it.
+ */
+export declare function isValidNamespace(ns: string, opts?: NamespaceRoutingOptions): boolean;
+/**
+ * resolve a raw namespace string to a DO instance name:
+ *   - `''` or a control-plane alias -> `'singleton'`
+ *   - a valid tenant namespace      -> `'ns:<ns>'`
+ *   - anything else                 -> `null` (caller should reject the request)
+ */
+export declare function doInstanceName(ns: string, opts?: NamespaceRoutingOptions): string | null;
+interface HeaderReader {
+    get(name: string): string | null;
+}
+/**
+ * read the namespace from a request (the configured header, falling back to the
+ * `?ns=` query param) and resolve it to a DO instance name. returns `null` for a
+ * structurally invalid namespace so the worker can reply 400 instead of routing.
+ */
+export declare function doInstanceNameForRequest(request: {
+    headers: HeaderReader;
+}, url: {
+    searchParams: HeaderReader;
+}, opts?: NamespaceRoutingOptions): string | null;
+export {};
+//# sourceMappingURL=cf-do-shim.d.ts.map

package/dist/worker/cf-do-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-do-shim.d.ts","sourceRoot":"","sources":["../../src/worker/cf-do-shim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,uBAA4B,GACjC,MAAM,GAAG,IAAI,CAKf;AAED,UAAU,YAAY;IACpB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CACjC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE;IAAE,OAAO,EAAE,YAAY,CAAA;CAAE,EAClC,GAAG,EAAE;IAAE,YAAY,EAAE,YAAY,CAAA;CAAE,EACnC,IAAI,GAAE,uBAA4B,GACjC,MAAM,GAAG,IAAI,CAIf"}

package/dist/worker/cf-do-shim.js

@@ -0,0 +1,58 @@
+/**
+ * namespace routing primitives for the Cloudflare Durable Object deploy.
+ *
+ * a multi-tenant CF/orez deploy shards data into one DO instance per tenant
+ * namespace (`ns:<scope>-<id>`) plus a control-plane `singleton`. the worker
+ * tiers carry the chosen namespace in a header (and re-stamp it so an inbound
+ * value is never trusted) and must validate its shape before routing — an
+ * unvalidated namespace would let a client mint unbounded DO instances.
+ *
+ * the deployed worker entry classes are bundled strings in the consumer's
+ * deploy integration (awkward to unit-test), so the routing decision and the
+ * security-relevant shape validation live here as pure functions, tested in
+ * cf-do-shim.test.ts. consumers import these into their worker shims instead of
+ * copy-pasting the validation regex at every routing site.
+ */
+/** default namespace scope prefixes (`proj-<id>`, `test-<id>`). */
+const DEFAULT_SCOPES = ['proj', 'test'];
+function escapeForRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function namespacePattern(scopes) {
+    const group = scopes.map(escapeForRegExp).join('|');
+    return new RegExp(`^(?:${group})-[A-Za-z0-9_-]{1,64}$`);
+}
+/**
+ * true when `ns` is a structurally valid tenant namespace: a configured scope
+ * prefix followed by a 1-64 char `[A-Za-z0-9_-]` id. this is the gate that
+ * keeps a stray header from minting an unbounded DO instance, so every routing
+ * site that forwards a namespace should run it.
+ */
+export function isValidNamespace(ns, opts = {}) {
+    return namespacePattern(opts.scopes ?? DEFAULT_SCOPES).test(ns);
+}
+/**
+ * resolve a raw namespace string to a DO instance name:
+ *   - `''` or a control-plane alias -> `'singleton'`
+ *   - a valid tenant namespace      -> `'ns:<ns>'`
+ *   - anything else                 -> `null` (caller should reject the request)
+ */
+export function doInstanceName(ns, opts = {}) {
+    if (!ns)
+        return 'singleton';
+    if ((opts.controlPlaneNamespaces ?? []).includes(ns))
+        return 'singleton';
+    if (!isValidNamespace(ns, opts))
+        return null;
+    return 'ns:' + ns;
+}
+/**
+ * read the namespace from a request (the configured header, falling back to the
+ * `?ns=` query param) and resolve it to a DO instance name. returns `null` for a
+ * structurally invalid namespace so the worker can reply 400 instead of routing.
+ */
+export function doInstanceNameForRequest(request, url, opts = {}) {
+    const ns = request.headers.get(opts.nsHeader ?? 'x-orez-ns') || url.searchParams.get('ns') || '';
+    return doInstanceName(ns, opts);
+}
+//# sourceMappingURL=cf-do-shim.js.map

package/dist/worker/cf-do-shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-do-shim.js","sourceRoot":"","sources":["../../src/worker/cf-do-shim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,mEAAmE;AACnE,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,CAAU,CAAA;AAchD,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAA;AACrD,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAyB;IACjD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACnD,OAAO,IAAI,MAAM,CAAC,OAAO,KAAK,wBAAwB,CAAC,CAAA;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,EAAU,EACV,OAAgC,EAAE;IAElC,OAAO,gBAAgB,CAAC,IAAI,CAAC,MAAM,IAAI,cAAc,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,EAAU,EACV,OAAgC,EAAE;IAElC,IAAI,CAAC,EAAE;QAAE,OAAO,WAAW,CAAA;IAC3B,IAAI,CAAC,IAAI,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,WAAW,CAAA;IACxE,IAAI,CAAC,gBAAgB,CAAC,EAAE,EAAE,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAC5C,OAAO,KAAK,GAAG,EAAE,CAAA;AACnB,CAAC;AAMD;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAkC,EAClC,GAAmC,EACnC,OAAgC,EAAE;IAElC,MAAM,EAAE,GACN,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,WAAW,CAAC,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IACvF,OAAO,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;AACjC,CAAC"}

package/dist/worker/zero-cache-do-sqlite.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cloudflare DO-SQLite compatibility for a zero-cache embed.
+ *
+ * zero-cache's embedded SQLite issues storage-engine statements (VACUUM, ATTACH,
+ * journal/checkpoint PRAGMAs) that a Durable Object's `ctx.storage.sql` does NOT
+ * own — the DO manages journaling + checkpointing itself and rejects them with
+ * SQLITE_AUTH, which aborts `/sync`. these helpers make those statements no-op so
+ * the embed boots unmodified, while every real read/write passes straight
+ * through. pure over the minimal `exec` shape (no `@cloudflare/...` types),
+ * tested in zero-cache-do-sqlite.test.ts.
+ */
+interface DoExecSql {
+    exec(sql: string, ...params: unknown[]): unknown;
+    [key: string]: unknown;
+}
+interface DoStorageCtx {
+    storage: {
+        sql: DoExecSql;
+        transactionSync?: (...args: unknown[]) => unknown;
+    };
+}
+export declare const DO_FORBIDDEN_SQLITE: RegExp;
+export declare function isDoForbiddenSqlite(sql: unknown): boolean;
+/**
+ * patch `sql.exec` in place so EVERY caller (the embed, its sqlite shim,
+ * transactionSync callbacks) skips DO-forbidden statements instead of throwing
+ * SQLITE_AUTH. idempotent per handle.
+ */
+export declare function installDoForbiddenSqliteGuard(sql: DoExecSql): void;
+/**
+ * wrap a DO's `storage.sql` for the zero-cache embed: DO-forbidden statements
+ * no-op, and `transactionSync` is bound through when the platform exposes it.
+ */
+export declare function doSqliteStorage(ctx: DoStorageCtx): {
+    exec: (sql: string, ...params: unknown[]) => unknown;
+    transactionSync: ((...args: unknown[]) => unknown) | undefined;
+};
+export {};
+//# sourceMappingURL=zero-cache-do-sqlite.d.ts.map

package/dist/worker/zero-cache-do-sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero-cache-do-sqlite.d.ts","sourceRoot":"","sources":["../../src/worker/zero-cache-do-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,UAAU,SAAS;IACjB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IAChD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,UAAU,YAAY;IACpB,OAAO,EAAE;QACP,GAAG,EAAE,SAAS,CAAA;QACd,eAAe,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;KAClD,CAAA;CACF;AAGD,eAAO,MAAM,mBAAmB,QAC+H,CAAA;AAE/J,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEzD;AAID;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAgBlE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG;IAClD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;IACpD,eAAe,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,CAAA;CAC/D,CAqBA"}

package/dist/worker/zero-cache-do-sqlite.js

@@ -0,0 +1,64 @@
+/**
+ * Cloudflare DO-SQLite compatibility for a zero-cache embed.
+ *
+ * zero-cache's embedded SQLite issues storage-engine statements (VACUUM, ATTACH,
+ * journal/checkpoint PRAGMAs) that a Durable Object's `ctx.storage.sql` does NOT
+ * own — the DO manages journaling + checkpointing itself and rejects them with
+ * SQLITE_AUTH, which aborts `/sync`. these helpers make those statements no-op so
+ * the embed boots unmodified, while every real read/write passes straight
+ * through. pure over the minimal `exec` shape (no `@cloudflare/...` types),
+ * tested in zero-cache-do-sqlite.test.ts.
+ */
+// storage-engine statements the DO rejects (it owns journaling/checkpointing).
+export const DO_FORBIDDEN_SQLITE = /^\s*(?:VACUUM\b|ATTACH\b|PRAGMA\s+(?:journal_mode|synchronous|page_size|mmap_size|wal_checkpoint|wal_autocheckpoint|locking_mode|temp_store|cache_size)\b)/i;
+export function isDoForbiddenSqlite(sql) {
+    return typeof sql === 'string' && DO_FORBIDDEN_SQLITE.test(sql);
+}
+const GUARD_MARK = '__orezDoSqliteGuarded';
+/**
+ * patch `sql.exec` in place so EVERY caller (the embed, its sqlite shim,
+ * transactionSync callbacks) skips DO-forbidden statements instead of throwing
+ * SQLITE_AUTH. idempotent per handle.
+ */
+export function installDoForbiddenSqliteGuard(sql) {
+    if (!sql || sql[GUARD_MARK])
+        return;
+    const rawExec = sql.exec.bind(sql);
+    sql.exec = (statement, ...params) => {
+        if (isDoForbiddenSqlite(statement)) {
+            return {
+                toArray: () => [],
+                rowsRead: 0,
+                rowsWritten: 0,
+                columnNames: [],
+                [Symbol.iterator]: () => [][Symbol.iterator](),
+            };
+        }
+        return rawExec(statement, ...params);
+    };
+    sql[GUARD_MARK] = true;
+}
+/**
+ * wrap a DO's `storage.sql` for the zero-cache embed: DO-forbidden statements
+ * no-op, and `transactionSync` is bound through when the platform exposes it.
+ */
+export function doSqliteStorage(ctx) {
+    const rawExec = ctx.storage.sql.exec.bind(ctx.storage.sql);
+    const exec = (sql, ...params) => {
+        if (isDoForbiddenSqlite(sql)) {
+            return {
+                toArray: () => [],
+                rowsRead: 0,
+                [Symbol.iterator]: () => [][Symbol.iterator](),
+            };
+        }
+        return rawExec(sql, ...params);
+    };
+    return {
+        exec,
+        transactionSync: typeof ctx.storage.transactionSync === 'function'
+            ? ctx.storage.transactionSync.bind(ctx.storage)
+            : undefined,
+    };
+}
+//# sourceMappingURL=zero-cache-do-sqlite.js.map

package/dist/worker/zero-cache-do-sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero-cache-do-sqlite.js","sourceRoot":"","sources":["../../src/worker/zero-cache-do-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAC9B,6JAA6J,CAAA;AAE/J,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjE,CAAC;AAED,MAAM,UAAU,GAAG,uBAAuB,CAAA;AAE1C;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,GAAc;IAC1D,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC;QAAE,OAAM;IACnC,MAAM,OAAO,GAAI,GAAG,CAAC,IAAuD,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACtF,GAAG,CAAC,IAAI,GAAG,CAAC,SAAiB,EAAE,GAAG,MAAiB,EAAE,EAAE;QACrD,IAAI,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,OAAO;gBACL,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE;gBACjB,QAAQ,EAAE,CAAC;gBACX,WAAW,EAAE,CAAC;gBACd,WAAW,EAAE,EAAE;gBACf,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE;aAC/C,CAAA;QACH,CAAC;QACD,OAAO,OAAO,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,CAAA;IACtC,CAAC,CAAA;IACD,GAAG,CAAC,UAAU,CAAC,GAAG,IAAI,CAAA;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAiB;IAI/C,MAAM,OAAO,GACX,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IACjB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACvB,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,GAAG,MAAiB,EAAE,EAAE;QACjD,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE;gBACjB,QAAQ,EAAE,CAAC;gBACX,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE;aAC/C,CAAA;QACH,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,CAAA;IAChC,CAAC,CAAA;IACD,OAAO;QACL,IAAI;QACJ,eAAe,EACb,OAAO,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,UAAU;YAC/C,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YAC/C,CAAC,CAAC,SAAS;KAChB,CAAA;AACH,CAAC"}

package/dist/worker/zero-cache-replica-repair.d.ts

@@ -0,0 +1,66 @@
+/**
+ * self-heal for a zero-cache embed's DO-SQLite replica.
+ *
+ * zero-cache snapshots its publication into a replica (here, the Durable
+ * Object's `ctx.storage.sql`, `ZERO_REPLICA_FILE=':do-sqlite:'`). on a real
+ * Postgres that replica lives in a normal file with normal transaction
+ * semantics; inside a DO the sqlite shim makes BEGIN/COMMIT/ROLLBACK no-ops
+ * (the object auto-commits per I/O turn) and any boot can be killed across an
+ * await (the 120s ready-timeout, an eviction, an OOM). that combination leaves
+ * three distinct corrupt-replica states that each wedge `/sync` permanently
+ * until healed. these functions detect and repair each one; every one of them
+ * fixed a specific production incident (see the per-function comments).
+ *
+ * the replica is *derived* data — the upstream rows live in the SQL DO and are
+ * untouched by any wipe here, so dropping the replica only forces zero-cache to
+ * re-run initial sync. pure logic over minimal `exec`/`get`/`put` shapes (no
+ * `@cloudflare/...` types); the decision logic is unit-tested in
+ * zero-cache-replica-repair.test.ts against simulated replica states. consumers
+ * call these from their ZeroCacheDO boot sequence with their own storage key +
+ * log prefix.
+ */
+export interface ReplicaSqlResult {
+    toArray(): Array<Record<string, unknown>>;
+}
+export interface ReplicaSqlStorage {
+    exec(sql: string, ...params: unknown[]): ReplicaSqlResult;
+}
+export interface ReplicaKvStorage {
+    get(key: string): Promise<unknown>;
+    put(key: string, value: unknown): Promise<unknown>;
+}
+/**
+ * run a SQL statement against the SQL-DO backend (pg-over-DO `/exec`), returning
+ * its `{ rows, error }` body. consumers wrap their backend fetch in this shape;
+ * an `{ error }` is surfaced (never treated as "no rows", which would silently
+ * disable the guards).
+ */
+export type BackendExec = (sql: string, params?: unknown[]) => Promise<{
+    rows?: Array<Record<string, unknown>>;
+    error?: string;
+}>;
+/**
+ * drop every non-internal table from the replica SQLite. SQLite internals
+ * (`sqlite_*`) and Cloudflare's DO tables (`_cf_*`) are skipped: the DO storage
+ * authorizer rejects DROP on `_cf_*` with SQLITE_AUTH, which would abort the
+ * whole reset. returns the number of tables dropped.
+ */
+export declare function dropReplicaTables(sql: ReplicaSqlStorage): number;
+export declare function resetReplicaIfTableSetChanged(sql: ReplicaSqlStorage, storage: ReplicaKvStorage, opts: {
+    schemaVersion: string;
+    tables?: Iterable<string>;
+    /** durable storage key the last-applied tag is persisted under. */
+    tagKey: string;
+}): Promise<void>;
+export declare function repairPartialReplicaInit(sql: ReplicaSqlStorage, opts?: {
+    logPrefix?: string;
+}): void;
+export declare function resetReplicaIfChangeLogPoisoned(sql: ReplicaSqlStorage, backendExec: BackendExec, opts: {
+    appId: string;
+    logPrefix?: string;
+}): Promise<void>;
+export declare function clearChangeStreamerStateIfReplicaUninitialized(sql: ReplicaSqlStorage, backendExec: BackendExec, opts: {
+    appId: string;
+    logPrefix?: string;
+}): Promise<void>;
+//# sourceMappingURL=zero-cache-replica-repair.d.ts.map

package/dist/worker/zero-cache-replica-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero-cache-replica-repair.d.ts","sourceRoot":"","sources":["../../src/worker/zero-cache-replica-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAC1C;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAA;CAC1D;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACnD;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,KACf,OAAO,CAAC;IAAE,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAEvE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAUhE;AAWD,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,iBAAiB,EACtB,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE;IACJ,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACzB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAA;CACf,GACA,OAAO,CAAC,IAAI,CAAC,CAWf;AAeD,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,iBAAiB,EACtB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,IAAI,CA8BN;AASD,wBAAsB,+BAA+B,CACnD,GAAG,EAAE,iBAAiB,EACtB,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAoDf;AASD,wBAAsB,8CAA8C,CAClE,GAAG,EAAE,iBAAiB,EACtB,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CA8Bf"}

package/dist/worker/zero-cache-replica-repair.js

@@ -0,0 +1,185 @@
+/**
+ * self-heal for a zero-cache embed's DO-SQLite replica.
+ *
+ * zero-cache snapshots its publication into a replica (here, the Durable
+ * Object's `ctx.storage.sql`, `ZERO_REPLICA_FILE=':do-sqlite:'`). on a real
+ * Postgres that replica lives in a normal file with normal transaction
+ * semantics; inside a DO the sqlite shim makes BEGIN/COMMIT/ROLLBACK no-ops
+ * (the object auto-commits per I/O turn) and any boot can be killed across an
+ * await (the 120s ready-timeout, an eviction, an OOM). that combination leaves
+ * three distinct corrupt-replica states that each wedge `/sync` permanently
+ * until healed. these functions detect and repair each one; every one of them
+ * fixed a specific production incident (see the per-function comments).
+ *
+ * the replica is *derived* data — the upstream rows live in the SQL DO and are
+ * untouched by any wipe here, so dropping the replica only forces zero-cache to
+ * re-run initial sync. pure logic over minimal `exec`/`get`/`put` shapes (no
+ * `@cloudflare/...` types); the decision logic is unit-tested in
+ * zero-cache-replica-repair.test.ts against simulated replica states. consumers
+ * call these from their ZeroCacheDO boot sequence with their own storage key +
+ * log prefix.
+ */
+/**
+ * drop every non-internal table from the replica SQLite. SQLite internals
+ * (`sqlite_*`) and Cloudflare's DO tables (`_cf_*`) are skipped: the DO storage
+ * authorizer rejects DROP on `_cf_*` with SQLITE_AUTH, which would abort the
+ * whole reset. returns the number of tables dropped.
+ */
+export function dropReplicaTables(sql) {
+    const rows = sql.exec("SELECT name FROM sqlite_master WHERE type='table'").toArray();
+    let dropped = 0;
+    for (const row of rows) {
+        const name = String(row.name);
+        if (name.startsWith('sqlite_') || name.startsWith('_cf_'))
+            continue;
+        sql.exec('DROP TABLE IF EXISTS "' + name.replaceAll('"', '""') + '"');
+        dropped++;
+    }
+    return dropped;
+}
+// zero-cache snapshots the publication's tables into its replica ONCE during
+// initial sync and never picks up a table OR COLUMN added afterward — ALTER only
+// feeds the change stream, not the existing snapshot. so a redeploy that evolves
+// the schema leaves the persisted replica stuck on the old shape and every
+// client fails SchemaVersionNotSupported (2026-06-10: file.title/description
+// columns — table set unchanged, so a tables-only tag never reset). key the tag
+// on schemaVersion (a hash of the full deploy-time DDL batch — any
+// table/column/type change) plus the table set, and wipe the replica on change
+// so zero-cache re-runs initial sync over the full publication.
+export async function resetReplicaIfTableSetChanged(sql, storage, opts) {
+    const tag = JSON.stringify([opts.schemaVersion, [...(opts.tables || [])].sort()]);
+    const lastTag = await storage.get(opts.tagKey);
+    // reset whenever the tag differs — including the no-baseline case (lastTag
+    // undefined), which covers a DO whose replica was initialized by a deploy that
+    // predates this tracking. on a brand-new DO the replica is empty so the drop
+    // loop is a no-op; on a stale one it forces a full re-sync.
+    if (lastTag !== tag) {
+        dropReplicaTables(sql);
+    }
+    await storage.put(opts.tagKey, tag);
+}
+// repair a PARTIALLY-INITIALIZED replica left by an interrupted embed boot.
+// zero-cache's runSchemaMigrations wraps initial-sync (createReplicationStateTables
+// + the versionHistory row write) in one BEGIN EXCLUSIVE/COMMIT, expecting it to
+// be atomic. but on a CF DO the sqlite shim makes BEGIN/COMMIT/ROLLBACK NO-OPS
+// (the DO auto-commits per I/O turn), and the setup migration is async (it awaits
+// initialSync, which yields across turns). so if the boot is killed mid-migration
+// — the 120s ready-timeout, a DO eviction, an OOM — the _zero.* tables auto-commit
+// but the closing versionHistory INSERT never runs. next boot: getVersionHistory
+// reads an empty table => dataVersion 0 => it re-runs the setup migration =>
+// CREATE TABLE "_zero.replicationConfig" => "already exists" SQLITE_ERROR, and
+// /sync never reaches ready (editor stuck on "loading files"). detect that exact
+// inconsistency (replica data tables present but no versionHistory row) and wipe
+// the _zero.* replica so the embed re-runs initial sync cleanly.
+export function repairPartialReplicaInit(sql, opts = {}) {
+    const logPrefix = opts.logPrefix ?? '[orez]';
+    const hasConfig = sql
+        .exec("SELECT 1 FROM sqlite_master WHERE type='table' AND name='_zero.replicationConfig'")
+        .toArray().length;
+    if (!hasConfig)
+        return;
+    let versionRows = 0;
+    try {
+        versionRows = sql
+            .exec('SELECT 1 FROM "_zero.versionHistory" LIMIT 1')
+            .toArray().length;
+    }
+    catch {
+        // versionHistory table missing entirely is also an inconsistent state
+        versionRows = 0;
+    }
+    if (versionRows > 0)
+        return;
+    // inconsistent: the replica's _zero.* control tables exist but version tracking
+    // is empty. the ENTIRE replica is half-initialized — initial-sync creates the
+    // _zero.* control tables AND the published app tables in the same interrupted
+    // run, so re-running setup also fails on a duplicate app table. drop every
+    // replica table so the next boot initial-syncs the whole set from scratch.
+    const dropped = dropReplicaTables(sql);
+    console.log(logPrefix +
+        ' repaired partial replica init: dropped ' +
+        dropped +
+        ' replica tables (no versionHistory row) so initial sync re-runs');
+}
+// a changeLog transaction group without a commit entry is an interrupted storer
+// write (zero stores each replicated tx inside one pg transaction; real pg rolls
+// a crashed tx back, but the DO sqlite shim auto-commits per turn, so a kill
+// persists the partial group). catchup replays it as begin->data->begin and the
+// replicator dies on "Already in a transaction" on every boot. wiping the replica
+// here makes the uninitialized-replica guard clear cdc state, forcing a clean
+// initial sync.
+export async function resetReplicaIfChangeLogPoisoned(sql, backendExec, opts) {
+    const logPrefix = opts.logPrefix ?? '[orez]';
+    const initialized = sql
+        .exec("SELECT 1 FROM sqlite_master WHERE type='table' AND name='_zero.replicationConfig'")
+        .toArray().length;
+    if (!initialized)
+        return;
+    // /exec parses pg SQL: placeholders are $1-style, never '?'. an {error}
+    // response must be surfaced — treating it as "no rows" silently disables the
+    // guard (the exact failure mode this guard exists to prevent).
+    const listBody = await backendExec("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE $1", [opts.appId + '_%/cdc_changeLog']);
+    if (listBody.error) {
+        console.error(logPrefix + ' changeLog poison check failed (list): ' + listBody.error);
+        return;
+    }
+    const names = (listBody.rows || []).map((row) => String(row.name));
+    for (const name of names) {
+        const checkBody = await backendExec('SELECT watermark FROM "' +
+            name.replaceAll('"', '""') +
+            "\" GROUP BY watermark HAVING SUM(CASE WHEN json_extract(change, '$.tag') = 'commit' THEN 1 ELSE 0 END) = 0 LIMIT 1");
+        if (checkBody.error) {
+            console.error(logPrefix + ' changeLog poison check failed (scan): ' + checkBody.error);
+            return;
+        }
+        const rows = checkBody.rows || [];
+        console.log(logPrefix +
+            ' changeLog poison scan: ' +
+            name +
+            ' -> ' +
+            (rows.length ? 'POISONED at ' + rows[0].watermark : 'clean'));
+        if (!rows.length)
+            continue;
+        const dropped = dropReplicaTables(sql);
+        console.log(logPrefix +
+            ' cdc changeLog has a partial transaction at watermark ' +
+            rows[0].watermark +
+            ' (interrupted storer write): dropped ' +
+            dropped +
+            ' replica tables so cdc state clears and initial sync re-runs');
+        return;
+    }
+}
+// a replica without its init marker must not reuse the cdc subscription state,
+// or initial sync never re-runs. the change-streamer's subscription state lives
+// in the SQL DO and SURVIVES a replica wipe (the resets above, or an OOM
+// eviction); a wiped replica + surviving subscription state makes zero-cache
+// skip initial sync ("already synced") and serve an EMPTY replica that only ever
+// receives catchup changes. when the replica has no init marker, clear the cdc
+// state so the embed re-runs initial sync from scratch.
+export async function clearChangeStreamerStateIfReplicaUninitialized(sql, backendExec, opts) {
+    const logPrefix = opts.logPrefix ?? '[orez]';
+    const initialized = sql
+        .exec("SELECT 1 FROM sqlite_master WHERE type='table' AND name='_zero.replicationConfig'")
+        .toArray().length;
+    if (initialized)
+        return;
+    // /exec parses pg SQL: $1-style placeholders, never '?' (a '?' is a parse
+    // error whose {error} body silently disabled this guard).
+    const body = await backendExec("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE $1", [opts.appId + '_%/cdc_%']);
+    if (body.error) {
+        console.error(logPrefix + ' cdc state clear failed (list): ' + body.error);
+        return;
+    }
+    const names = (body.rows || []).map((row) => String(row.name));
+    for (const name of names) {
+        await backendExec('DROP TABLE IF EXISTS "' + name.replaceAll('"', '""') + '"');
+    }
+    if (names.length) {
+        console.log(logPrefix +
+            ' replica uninitialized: cleared ' +
+            names.length +
+            ' cdc state tables so initial sync re-runs');
+    }
+}
+//# sourceMappingURL=zero-cache-replica-repair.js.map

package/dist/worker/zero-cache-replica-repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero-cache-replica-repair.js","sourceRoot":"","sources":["../../src/worker/zero-cache-replica-repair.ts"],"names":[],"mappings":"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"}

package/dist/worker/zero-sql-write-circuit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * runaway-write circuit breaker for a Durable Object's SQLite storage.
+ *
+ * a ZeroSqlDO (orez `ZeroDO`) runs the pg-over-DO backend in-instance, so a
+ * buggy or malicious mutation flow can write unbounded rows into the DO's
+ * SQLite and blow past the platform's per-object storage + billing limits
+ * before anything notices. this wraps `sql.exec` to meter rows written per
+ * rolling window and trip — refusing further writes — once the rate stays over
+ * a soft threshold for a sustained period, or instantly past a hard threshold.
+ *
+ * the meter state lives in a single-row table in the same SQLite, so a tripped
+ * breaker survives DO eviction (the object stays bricked-for-writes until an
+ * operator clears the row). reads are never gated. the wrap is idempotent per
+ * `sql` handle.
+ *
+ * pure logic over the minimal `DurableSqlStorage` shape (no `@cloudflare/...`
+ * types), unit-tested in zero-sql-write-circuit.test.ts. consumers install it
+ * from their ZeroSqlDO constructor with their own table/log prefix.
+ */
+export interface DurableSqlCursor {
+    one(): Record<string, unknown> | undefined;
+    rowsWritten?: number;
+}
+export interface DurableSqlStorage {
+    exec(sql: string, ...params: unknown[]): DurableSqlCursor;
+}
+export interface WriteCircuitOptions {
+    /** single-row meter table name. default `_orez_write_circuit`. */
+    table?: string;
+    /** soft cap: rows/window above which the sustained timer starts. default 2,000,000. */
+    rowsPerWindow?: number;
+    /** hard cap: rows/window that trips instantly. default 10,000,000. */
+    hardRowsPerWindow?: number;
+    /** rolling window length in ms. default 60,000. */
+    windowMs?: number;
+    /** how long the rate must stay over the soft cap before tripping, in ms. default 180,000. */
+    sustainedMs?: number;
+    /** log prefix for the trip diagnostics. default `[orez]`. */
+    logPrefix?: string;
+}
+/**
+ * wrap `sql.exec` with the runaway-write circuit breaker. idempotent: a second
+ * call on the same `sql` handle is a no-op.
+ */
+export declare function installZeroSqlWriteCircuitBreaker(sql: DurableSqlStorage, opts?: WriteCircuitOptions): void;
+//# sourceMappingURL=zero-sql-write-circuit.d.ts.map

package/dist/worker/zero-sql-write-circuit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero-sql-write-circuit.d.ts","sourceRoot":"","sources":["../../src/worker/zero-sql-write-circuit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAA;CAC1D;AAED,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAQD;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,iBAAiB,EACtB,IAAI,GAAE,mBAAwB,GAC7B,IAAI,CA+HN"}

package/dist/worker/zero-sql-write-circuit.js

@@ -0,0 +1,128 @@
+/**
+ * runaway-write circuit breaker for a Durable Object's SQLite storage.
+ *
+ * a ZeroSqlDO (orez `ZeroDO`) runs the pg-over-DO backend in-instance, so a
+ * buggy or malicious mutation flow can write unbounded rows into the DO's
+ * SQLite and blow past the platform's per-object storage + billing limits
+ * before anything notices. this wraps `sql.exec` to meter rows written per
+ * rolling window and trip — refusing further writes — once the rate stays over
+ * a soft threshold for a sustained period, or instantly past a hard threshold.
+ *
+ * the meter state lives in a single-row table in the same SQLite, so a tripped
+ * breaker survives DO eviction (the object stays bricked-for-writes until an
+ * operator clears the row). reads are never gated. the wrap is idempotent per
+ * `sql` handle.
+ *
+ * pure logic over the minimal `DurableSqlStorage` shape (no `@cloudflare/...`
+ * types), unit-tested in zero-sql-write-circuit.test.ts. consumers install it
+ * from their ZeroSqlDO constructor with their own table/log prefix.
+ */
+// any statement that can write rows (so reads never pay the meter cost).
+const MUTATION_RE = /^\s*(?:insert|update|delete|replace|create|alter|drop|truncate|vacuum|reindex|with)\b/i;
+const INSTALLED = new WeakSet();
+/**
+ * wrap `sql.exec` with the runaway-write circuit breaker. idempotent: a second
+ * call on the same `sql` handle is a no-op.
+ */
+export function installZeroSqlWriteCircuitBreaker(sql, opts = {}) {
+    if (!sql || INSTALLED.has(sql))
+        return;
+    const table = opts.table ?? '_orez_write_circuit';
+    const rowsPerWindow = opts.rowsPerWindow ?? 2_000_000;
+    const hardRowsPerWindow = opts.hardRowsPerWindow ?? 10_000_000;
+    const windowMs = opts.windowMs ?? 60 * 1000;
+    const sustainedMs = opts.sustainedMs ?? 3 * 60 * 1000;
+    const logPrefix = opts.logPrefix ?? '[orez]';
+    const rawExec = sql.exec.bind(sql);
+    let ready = false;
+    const ensureReady = () => {
+        if (ready)
+            return;
+        rawExec('CREATE TABLE IF NOT EXISTS ' +
+            table +
+            ' (id INTEGER PRIMARY KEY CHECK (id = 1), window_start INTEGER NOT NULL DEFAULT 0, rows_in_window INTEGER NOT NULL DEFAULT 0, first_over_at INTEGER NOT NULL DEFAULT 0, tripped_at INTEGER NOT NULL DEFAULT 0, last_statement TEXT)');
+        rawExec('INSERT OR IGNORE INTO ' +
+            table +
+            ' (id, window_start, rows_in_window, first_over_at, tripped_at, last_statement) VALUES (1, 0, 0, 0, 0, ?)', '');
+        ready = true;
+    };
+    const readState = () => {
+        ensureReady();
+        return (rawExec('SELECT window_start, rows_in_window, first_over_at, tripped_at FROM ' +
+            table +
+            ' WHERE id = 1').one() || {});
+    };
+    const clippedStatement = (statement) => String(statement || '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 500);
+    const assertOpen = (statement) => {
+        const state = readState();
+        const trippedAt = Number(state.tripped_at || 0);
+        if (trippedAt > 0) {
+            throw new Error(logPrefix +
+                ' ZeroSqlDO write circuit breaker tripped at ' +
+                new Date(trippedAt).toISOString() +
+                '; refusing SQL write: ' +
+                clippedStatement(statement));
+        }
+    };
+    const recordRowsWritten = (rowsWritten, statement) => {
+        const rows = Number(rowsWritten || 0);
+        if (!Number.isFinite(rows) || rows <= 0)
+            return false;
+        const now = Date.now();
+        const state = readState();
+        let windowStart = Number(state.window_start || 0);
+        let rowsInWindow = Number(state.rows_in_window || 0);
+        let firstOverAt = Number(state.first_over_at || 0);
+        const trippedAt = Number(state.tripped_at || 0);
+        if (trippedAt > 0)
+            return true;
+        const windowAgeMs = windowStart ? now - windowStart : 0;
+        if (!windowStart || windowAgeMs >= windowMs) {
+            const previousWindowWasOver = windowAgeMs < windowMs * 2 && rowsInWindow > rowsPerWindow;
+            windowStart = now;
+            rowsInWindow = 0;
+            if (!previousWindowWasOver)
+                firstOverAt = 0;
+        }
+        rowsInWindow += rows;
+        let nextTrippedAt = 0;
+        if (rowsInWindow > rowsPerWindow) {
+            if (!firstOverAt)
+                firstOverAt = now;
+            if (rowsInWindow > hardRowsPerWindow || now - firstOverAt >= sustainedMs) {
+                nextTrippedAt = now;
+            }
+        }
+        rawExec('UPDATE ' +
+            table +
+            ' SET window_start = ?, rows_in_window = ?, first_over_at = ?, tripped_at = ?, last_statement = ? WHERE id = 1', windowStart, rowsInWindow, firstOverAt, nextTrippedAt, clippedStatement(statement));
+        if (nextTrippedAt) {
+            console.error(logPrefix +
+                ' ZeroSqlDO write circuit breaker tripped: rows_in_window=' +
+                rowsInWindow +
+                ', rows_written=' +
+                rows +
+                ', statement=' +
+                clippedStatement(statement));
+            return true;
+        }
+        return false;
+    };
+    sql.exec = (statement, ...params) => {
+        const text = String(statement || '');
+        const isCircuitStatement = text.includes(table);
+        const isMutation = MUTATION_RE.test(text) && !isCircuitStatement;
+        if (isMutation)
+            assertOpen(text);
+        const cursor = rawExec(statement, ...params);
+        if (isMutation && recordRowsWritten(cursor && cursor.rowsWritten, text)) {
+            assertOpen(text);
+        }
+        return cursor;
+    };
+    INSTALLED.add(sql);
+}
+//# sourceMappingURL=zero-sql-write-circuit.js.map

package/dist/worker/zero-sql-write-circuit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero-sql-write-circuit.js","sourceRoot":"","sources":["../../src/worker/zero-sql-write-circuit.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orez",
-  "version": "0.4.24",
+  "version": "0.4.26",
   "description": "PGlite-powered zero-sync development backend. No Docker required.",
   "type": "module",
   "license": "MIT",
@@ -87,7 +87,7 @@
     "@electric-sql/pglite": "0.4.1",
     "@electric-sql/pglite-tools": "^0.3.1",
     "@pgsql/traverse": "17.2.6",
-    "bedrock-sqlite": "0.4.24",
+    "bedrock-sqlite": "0.4.26",
     "citty": "^0.2.0",
     "pg-gateway": "0.3.0-beta.4",
     "pgsql-parser": "^17.9.11",