orez 0.4.30 → 0.4.31

package/dist/config.js

@@ -6,9 +6,9 @@ export function defineConfig(config) {
 export function getConfig(overrides = {}) {
     return {
         dataDir: overrides.dataDir || '.orez',
-        pgPort: overrides.pgPort || 6434,
-        zeroPort: overrides.zeroPort || 5849,
-        adminPort: overrides.adminPort || 0,
+        pgPort: overrides.pgPort ?? 6434,
+        zeroPort: overrides.zeroPort ?? 5849,
+        adminPort: overrides.adminPort ?? 0,
         pgUser: overrides.pgUser || 'user',
         pgPassword: overrides.pgPassword || 'password',
         migrationsDir: overrides.migrationsDir || '',

package/dist/fk-cascade.d.ts

@@ -0,0 +1,102 @@
+/**
+ * fk-cascade — pg→sqlite compat for ON DELETE actions.
+ *
+ * orez's backends drop every FOREIGN KEY constraint when translating PG DDL to
+ * their store (the PGlite shim regex-strips them; the DO backend filters the
+ * CONSTR_FOREIGN AST nodes). that leaves the store with no FK enforcement and,
+ * crucially, no `ON DELETE CASCADE` / `ON DELETE SET NULL` — so a plain
+ * `DELETE FROM parent` orphans every child row instead of cascading.
+ *
+ * native engine cascade is not an option here: change capture is trigger-based
+ * (`_zero_change_trigger` / `_zero_track_change`), and SQLite does NOT fire
+ * triggers for native foreign-key cascade actions unless `recursive_triggers`
+ * is on. an engine-level cascade would delete child rows invisibly, so zero
+ * clients would never learn the rows are gone — strictly worse than orphaning.
+ *
+ * instead we restore faithful PG semantics by EXPANSION: capture the FK edges
+ * the backends were about to drop, and rewrite each `DELETE FROM parent` into
+ * an ordered set of explicit, set-based child statements (leaves-first) plus
+ * the original parent delete. every emitted statement is a real DELETE/UPDATE,
+ * so it goes through the same change-tracking trigger and replicates to zero
+ * clients exactly like any other write. one implementation, both backends.
+ *
+ * this module is pure: it operates on already-parsed libpg_query CREATE TABLE
+ * AST nodes (for edge capture) and plain SQL strings (for expansion). the
+ * caller owns naming — it passes a `resolveTable` that produces the canonical
+ * SQL identifier for a table (schema-qualified PG name). that identifier doubles
+ * as the registry key, so capture and expansion stay consistent. the expansion
+ * emits PG SQL under those names; the DO backend re-runs each child through its
+ * normal rewrite (flatten + change-track), while PGlite runs them directly.
+ */
+/** the ON DELETE actions we can faithfully expand. restrict/no-action/set-default are left alone (no enforcement, matching today). */
+export type FkDeleteAction = 'cascade' | 'set-null';
+export interface FkChild {
+    /** canonical SQL identifier of the child (referencing) table; also its registry key. */
+    table: string;
+    /** child FK column identifiers (already quoted), in FK order. */
+    columns: string[];
+    /** referenced parent column identifiers (already quoted), aligned with `columns`. */
+    refColumns: string[];
+    onDelete: FkDeleteAction;
+}
+/**
+ * parent-table → children that reference it. built once from DDL, consulted on
+ * every DELETE. keyed by the canonical table identifier `resolveTable` produces.
+ */
+export declare class FkCascadeRegistry {
+    private byParent;
+    add(parentKey: string, child: FkChild): void;
+    childrenOf(parentKey: string): readonly FkChild[];
+    /** every (parentKey, child) edge — for persisting the registry to durable storage. */
+    entries(): IterableIterator<readonly [string, FkChild]>;
+    /** true once any cascade/set-null edge has been captured — lets backends skip the DELETE parse on FK-free schemas. */
+    get hasEdges(): boolean;
+    clear(): void;
+}
+export interface TableRef {
+    schemaname?: string;
+    relname: string;
+}
+export type ResolveTable = (ref: TableRef) => string;
+export declare function quoteIdent(name: string): string;
+/**
+ * capture every cascade/set-null FK edge declared by a CREATE TABLE statement
+ * into `registry`. handles both inline column FKs (`col … REFERENCES parent(c)`)
+ * and table-level FKs (`FOREIGN KEY (col) REFERENCES parent(c)`). call this at
+ * the exact site each backend drops the constraint, BEFORE it is discarded.
+ */
+export declare function recordCreateTableForeignKeys(createStmt: {
+    relation?: TableRef;
+    tableElts?: unknown[];
+} | undefined, registry: FkCascadeRegistry, resolveTable: ResolveTable): number;
+/**
+ * capture cascade/set-null FK edges from an `ALTER TABLE … ADD CONSTRAINT …
+ * FOREIGN KEY …` statement (drizzle's standard FK form — it emits FKs as a
+ * separate ALTER, not inline in CREATE TABLE). call at the site the backend
+ * drops the constraint. returns the number of edges recorded.
+ */
+export declare function recordAlterTableForeignKeys(alterStmt: {
+    relation?: TableRef;
+    cmds?: unknown[];
+} | undefined, registry: FkCascadeRegistry, resolveTable: ResolveTable): number;
+export interface ExpandOptions {
+    /** guard against pathological / cyclic graphs. */
+    maxDepth?: number;
+}
+/**
+ * expand a `DELETE FROM target [WHERE wherePredicate]` into the ordered list of
+ * statements that reproduces PG's ON DELETE semantics. children are emitted
+ * leaves-first (grandchildren before children) so every delete runs before the
+ * rows it depends on disappear; the returned list does NOT include the original
+ * parent delete — the caller still runs that, after these.
+ *
+ * each statement embeds the full original predicate via nested subqueries, so
+ * for a parameterized DELETE the SAME bound params apply unchanged to every
+ * emitted statement.
+ *
+ * cascade → `DELETE FROM child WHERE childCols IN (SELECT … )`
+ * set-null → `UPDATE child SET childCols = NULL WHERE childCols IN (SELECT … )`
+ *            (SET NULL does not delete the child, so its subtree is not recursed)
+ */
+export declare function expandDelete(target: string, wherePredicate: string | null, registry: FkCascadeRegistry, options?: ExpandOptions): string[];
+//# sourceMappingURL=fk-cascade.d.ts.map

package/dist/fk-cascade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fk-cascade.d.ts","sourceRoot":"","sources":["../src/fk-cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,sIAAsI;AACtI,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,CAAA;AAEnD,MAAM,WAAW,OAAO;IACtB,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAA;IACb,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,qFAAqF;IACrF,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,QAAQ,EAAE,cAAc,CAAA;CACzB;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAA+B;IAE/C,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAY5C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE;IAIjD,sFAAsF;IACrF,OAAO,IAAI,gBAAgB,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAMxD,sHAAsH;IACtH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,KAAK,IAAI,IAAI;CAGd;AAcD,MAAM,WAAW,QAAQ;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAA;AASpD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAaD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,GAAG,SAAS,EACtE,QAAQ,EAAE,iBAAiB,EAC3B,YAAY,EAAE,YAAY,GACzB,MAAM,CAyCR;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,GAAG,SAAS,EAChE,QAAQ,EAAE,iBAAiB,EAC3B,YAAY,EAAE,YAAY,GACzB,MAAM,CAwBR;AAqDD,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,GAAG,IAAI,EAC7B,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,aAAkB,GAC1B,MAAM,EAAE,CA6BV"}

package/dist/fk-cascade.js

@@ -0,0 +1,233 @@
+/**
+ * fk-cascade — pg→sqlite compat for ON DELETE actions.
+ *
+ * orez's backends drop every FOREIGN KEY constraint when translating PG DDL to
+ * their store (the PGlite shim regex-strips them; the DO backend filters the
+ * CONSTR_FOREIGN AST nodes). that leaves the store with no FK enforcement and,
+ * crucially, no `ON DELETE CASCADE` / `ON DELETE SET NULL` — so a plain
+ * `DELETE FROM parent` orphans every child row instead of cascading.
+ *
+ * native engine cascade is not an option here: change capture is trigger-based
+ * (`_zero_change_trigger` / `_zero_track_change`), and SQLite does NOT fire
+ * triggers for native foreign-key cascade actions unless `recursive_triggers`
+ * is on. an engine-level cascade would delete child rows invisibly, so zero
+ * clients would never learn the rows are gone — strictly worse than orphaning.
+ *
+ * instead we restore faithful PG semantics by EXPANSION: capture the FK edges
+ * the backends were about to drop, and rewrite each `DELETE FROM parent` into
+ * an ordered set of explicit, set-based child statements (leaves-first) plus
+ * the original parent delete. every emitted statement is a real DELETE/UPDATE,
+ * so it goes through the same change-tracking trigger and replicates to zero
+ * clients exactly like any other write. one implementation, both backends.
+ *
+ * this module is pure: it operates on already-parsed libpg_query CREATE TABLE
+ * AST nodes (for edge capture) and plain SQL strings (for expansion). the
+ * caller owns naming — it passes a `resolveTable` that produces the canonical
+ * SQL identifier for a table (schema-qualified PG name). that identifier doubles
+ * as the registry key, so capture and expansion stay consistent. the expansion
+ * emits PG SQL under those names; the DO backend re-runs each child through its
+ * normal rewrite (flatten + change-track), while PGlite runs them directly.
+ */
+/**
+ * parent-table → children that reference it. built once from DDL, consulted on
+ * every DELETE. keyed by the canonical table identifier `resolveTable` produces.
+ */
+export class FkCascadeRegistry {
+    byParent = new Map();
+    add(parentKey, child) {
+        const list = this.byParent.get(parentKey);
+        if (!list) {
+            this.byParent.set(parentKey, [child]);
+            return;
+        }
+        // dedupe: the same DDL can be re-applied (CREATE TABLE IF NOT EXISTS, a boot
+        // load followed by a re-sent migration) — a duplicate edge doubles the cascade.
+        if (list.some((existing) => sameEdge(existing, child)))
+            return;
+        list.push(child);
+    }
+    childrenOf(parentKey) {
+        return this.byParent.get(parentKey) ?? EMPTY;
+    }
+    /** every (parentKey, child) edge — for persisting the registry to durable storage. */
+    *entries() {
+        for (const [parentKey, children] of this.byParent) {
+            for (const child of children)
+                yield [parentKey, child];
+        }
+    }
+    /** true once any cascade/set-null edge has been captured — lets backends skip the DELETE parse on FK-free schemas. */
+    get hasEdges() {
+        return this.byParent.size > 0;
+    }
+    clear() {
+        this.byParent.clear();
+    }
+}
+const EMPTY = Object.freeze([]);
+function sameEdge(a, b) {
+    return (a.table === b.table &&
+        a.onDelete === b.onDelete &&
+        a.columns.length === b.columns.length &&
+        a.columns.every((c, i) => c === b.columns[i]) &&
+        a.refColumns.every((c, i) => c === b.refColumns[i]));
+}
+/** libpg_query fk_del_action codes → the action we expand (others: no enforcement, skip). */
+const DELETE_ACTION = {
+    c: 'cascade', // CASCADE
+    n: 'set-null', // SET NULL
+    // a: NO ACTION, r: RESTRICT, d: SET DEFAULT — no faithful expansion, leave unenforced
+};
+export function quoteIdent(name) {
+    return '"' + name.replace(/"/g, '""') + '"';
+}
+function stringValues(nodes) {
+    if (!Array.isArray(nodes))
+        return [];
+    const out = [];
+    for (const node of nodes) {
+        const sval = node?.String;
+        const value = sval?.sval ?? sval?.str;
+        if (typeof value === 'string')
+            out.push(value);
+    }
+    return out;
+}
+/**
+ * capture every cascade/set-null FK edge declared by a CREATE TABLE statement
+ * into `registry`. handles both inline column FKs (`col … REFERENCES parent(c)`)
+ * and table-level FKs (`FOREIGN KEY (col) REFERENCES parent(c)`). call this at
+ * the exact site each backend drops the constraint, BEFORE it is discarded.
+ */
+export function recordCreateTableForeignKeys(createStmt, registry, resolveTable) {
+    const relation = createStmt?.relation;
+    if (!relation?.relname)
+        return 0;
+    const childTable = resolveTable(relation);
+    let recorded = 0;
+    for (const elt of createStmt?.tableElts ?? []) {
+        const node = elt;
+        // table-level: FOREIGN KEY (a, b) REFERENCES parent (x, y)
+        if (node.Constraint?.contype === 'CONSTR_FOREIGN') {
+            if (addForeignKey(registry, childTable, node.Constraint, stringValues(node.Constraint.fk_attrs), resolveTable)) {
+                recorded++;
+            }
+            continue;
+        }
+        // inline column: col … REFERENCES parent (x)
+        const col = node.ColumnDef;
+        if (col?.colname && Array.isArray(col.constraints)) {
+            for (const c of col.constraints) {
+                const constraint = c.Constraint;
+                if (constraint?.contype === 'CONSTR_FOREIGN') {
+                    if (addForeignKey(registry, childTable, constraint, [col.colname], resolveTable)) {
+                        recorded++;
+                    }
+                }
+            }
+        }
+    }
+    return recorded;
+}
+/**
+ * capture cascade/set-null FK edges from an `ALTER TABLE … ADD CONSTRAINT …
+ * FOREIGN KEY …` statement (drizzle's standard FK form — it emits FKs as a
+ * separate ALTER, not inline in CREATE TABLE). call at the site the backend
+ * drops the constraint. returns the number of edges recorded.
+ */
+export function recordAlterTableForeignKeys(alterStmt, registry, resolveTable) {
+    const relation = alterStmt?.relation;
+    if (!relation?.relname)
+        return 0;
+    const childTable = resolveTable(relation);
+    let recorded = 0;
+    for (const cmd of alterStmt?.cmds ?? []) {
+        const command = cmd
+            ?.AlterTableCmd;
+        if (command?.subtype !== 'AT_AddConstraint')
+            continue;
+        const constraint = command.def?.Constraint;
+        if (constraint?.contype !== 'CONSTR_FOREIGN')
+            continue;
+        if (addForeignKey(registry, childTable, constraint, stringValues(constraint.fk_attrs), resolveTable)) {
+            recorded++;
+        }
+    }
+    return recorded;
+}
+function addForeignKey(registry, childTable, constraint, childColumns, resolveTable) {
+    const onDelete = DELETE_ACTION[constraint.fk_del_action ?? 'a'];
+    if (!onDelete)
+        return false; // restrict / no-action / set-default: nothing to expand
+    const parent = constraint.pktable;
+    if (!parent?.relname)
+        return false;
+    const refColumns = stringValues(constraint.pk_attrs);
+    // need an explicit referenced column to build the IN-subquery; drizzle always
+    // emits one. without it we can't faithfully expand, so skip rather than guess.
+    if (childColumns.length === 0 || refColumns.length !== childColumns.length)
+        return false;
+    registry.add(resolveTable(parent), {
+        table: childTable,
+        columns: childColumns.map(quoteIdent),
+        refColumns: refColumns.map(quoteIdent),
+        onDelete,
+    });
+    return true;
+}
+function columnTuple(columns) {
+    return columns.length === 1 ? columns[0] : `(${columns.join(', ')})`;
+}
+/**
+ * build the set-based predicate selecting child rows whose FK points at the
+ * parent rows matched by `parentPredicate`:
+ *   childCols IN (SELECT refCols FROM parentTable WHERE parentPredicate)
+ */
+function childMatchPredicate(child, parentTable, parentPredicate) {
+    const where = parentPredicate ? ` WHERE ${parentPredicate}` : '';
+    const select = `SELECT ${child.refColumns.join(', ')} FROM ${parentTable}${where}`;
+    return `${columnTuple(child.columns)} IN (${select})`;
+}
+/**
+ * expand a `DELETE FROM target [WHERE wherePredicate]` into the ordered list of
+ * statements that reproduces PG's ON DELETE semantics. children are emitted
+ * leaves-first (grandchildren before children) so every delete runs before the
+ * rows it depends on disappear; the returned list does NOT include the original
+ * parent delete — the caller still runs that, after these.
+ *
+ * each statement embeds the full original predicate via nested subqueries, so
+ * for a parameterized DELETE the SAME bound params apply unchanged to every
+ * emitted statement.
+ *
+ * cascade → `DELETE FROM child WHERE childCols IN (SELECT … )`
+ * set-null → `UPDATE child SET childCols = NULL WHERE childCols IN (SELECT … )`
+ *            (SET NULL does not delete the child, so its subtree is not recursed)
+ */
+export function expandDelete(target, wherePredicate, registry, options = {}) {
+    if (!registry.hasEdges)
+        return [];
+    const maxDepth = options.maxDepth ?? 32;
+    const out = [];
+    const visit = (table, predicate, depth, path) => {
+        if (depth > maxDepth)
+            return;
+        for (const child of registry.childrenOf(table)) {
+            if (path.has(child.table))
+                continue; // cycle guard — self-ref / mutual FK
+            const match = childMatchPredicate(child, table, predicate);
+            if (child.onDelete === 'cascade') {
+                // delete grandchildren first, keyed off the rows this child is about to lose
+                visit(child.table, match, depth + 1, new Set(path).add(child.table));
+                out.push(`DELETE FROM ${child.table} WHERE ${match}`);
+            }
+            else {
+                // set-null: null the link, leave the child row (and its subtree) intact
+                const assignments = child.columns.map((c) => `${c} = NULL`).join(', ');
+                out.push(`UPDATE ${child.table} SET ${assignments} WHERE ${match}`);
+            }
+        }
+    };
+    visit(target, wherePredicate, 0, new Set([target]));
+    return out;
+}
+//# sourceMappingURL=fk-cascade.js.map

package/dist/fk-cascade.js.map

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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAoDpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AA0DjD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC1E,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAA;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAoEvE,wBAAsB,aAAa,CAAC,SAAS,GAAE,OAAO,CAAC,cAAc,CAAM;;;;;;;;;;;;;;GAu9B1E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAsDpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AA0DjD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC1E,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAA;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAoEvE,wBAAsB,aAAa,CAAC,SAAS,GAAE,OAAO,CAAC,cAAc,CAAM;;;;;;;;;;;;;;GA0+B1E"}

package/dist/index.js

@@ -17,7 +17,7 @@ import { getConfig, getConnectionString } from './config.js';
 import { log, port, setLogLevel, setLogStore } from './log.js';
 import { DoBackend } from './pg-proxy-do-backend.js';
 import { startPgProxy } from './pg-proxy.js';
-import { createPGliteInstances, createPGliteWorkerInstances, createSinglePGliteInstance, createSinglePGliteWorkerInstance, createPGliteWorker, runMigrations, startPeriodicCheckpoint, startPeriodicVacuum, } from './pglite-manager.js';
+import { createPGliteInstances, createPGliteWorkerInstances, createSinglePGliteInstance, createSinglePGliteWorkerInstance, createPGliteWorker, runMigrations, startPeriodicCheckpoint, startPeriodicVacuum, vacuumPGliteChurnTables, } from './pglite-manager.js';
 import { findPort } from './port.js';
 import { orezTitle } from './process-title.js';
 import { ensurePublicationHasTables, syncManagedPublications } from './publications.js';
@@ -25,6 +25,7 @@ import { classifyZeroCrashRecovery, classifyZeroStartupRecovery, hasRecoverableZ
 import { installChangeTracking } from './replication/change-tracker.js';
 import { resetReplicationState } from './replication/handler.js';
 import { applySqliteMode, cleanupShim, formatNativeBootstrapInstructions, hasMissingNativeBinarySignature, inspectNativeSqliteBinary, resolveSqliteMode, resolveSqliteModeConfig, } from './sqlite-mode/index.js';
+import { enableZeroChangeLogCleanupRetry } from './zero-changelog-cleanup-patch.js';
 import { enableZeroReplicaCheckpoint } from './zero-checkpoint-patch.js';
 import { probeZeroCacheHttp } from './zero-health.js';
 import { disableZeroLitestreamRestore } from './zero-litestream-patch.js';
@@ -240,6 +241,19 @@ export async function startZeroLite(overrides = {}) {
     let instances, db, stopCheckpoint, stopVacuum = () => { };
     let migrationsApplied = 0;
     let isDoBackend = false;
+    let pgliteVacuumMs = 0;
+    let delayedVacuumTimer;
+    const queuePgliteVacuum = (delayMs = 15_000) => {
+        if (isDoBackend || pgliteVacuumMs <= 0)
+            return;
+        if (delayedVacuumTimer)
+            clearTimeout(delayedVacuumTimer);
+        delayedVacuumTimer = setTimeout(() => {
+            delayedVacuumTimer = undefined;
+            void vacuumPGliteChurnTables(instances);
+        }, delayMs);
+        delayedVacuumTimer.unref?.();
+    };
     if (config.doBackendUrl) {
         isDoBackend = true;
         log.orez(`using DO backend: ${config.doBackendUrl}`);
@@ -275,12 +289,6 @@ export async function startZeroLite(overrides = {}) {
             config.checkpointIntervalMs > 0
                 ? startPeriodicCheckpoint(instances, config.checkpointIntervalMs)
                 : () => { };
-        // periodic VACUUM of the change-tracking churn tables — PGlite has no
-        // effective autovacuum, so without this the change buffer bloats until the
-        // change-streamer scan times out and Zero stops sending live updates. Interval
-        // via OREZ_VACUUM_MS (default 10min, 0 disables).
-        const vacuumMs = Number(process.env.OREZ_VACUUM_MS ?? 10 * 60 * 1000);
-        stopVacuum = vacuumMs > 0 ? startPeriodicVacuum(instances, vacuumMs) : () => { };
         // config-based publications
         if (config.zeroPublications && !process.env.ZERO_APP_PUBLICATIONS) {
             process.env.ZERO_APP_PUBLICATIONS = config.zeroPublications;
@@ -289,6 +297,16 @@ export async function startZeroLite(overrides = {}) {
         migrationsApplied = await runMigrations(db, config);
         log.debug.orez('installing change tracking');
         await installChangeTracking(db);
+        // periodic VACUUM of the change-tracking churn tables — PGlite has no
+        // effective autovacuum, so without this the change buffers bloat until the
+        // change-streamer scan times out and Zero stops sending live updates. Start it
+        // only after Orez's own tracking tables exist; zero-cache's CDB changeLog is
+        // vacuumed once more after zero-cache has started.
+        pgliteVacuumMs = Number(process.env.OREZ_VACUUM_MS ?? 60 * 1000);
+        if (pgliteVacuumMs > 0) {
+            await vacuumPGliteChurnTables(instances);
+            stopVacuum = startPeriodicVacuum(instances, pgliteVacuumMs);
+        }
     }
     // shared: publications config
     if (config.zeroPublications && !process.env.ZERO_APP_PUBLICATIONS) {
@@ -325,6 +343,9 @@ export async function startZeroLite(overrides = {}) {
         await ensurePublicationHasTables(db, managedPub.names);
         log.debug.orez('re-installing change tracking after on-db-ready');
         await installChangeTracking(db);
+        if (!isDoBackend && pgliteVacuumMs > 0) {
+            await vacuumPGliteChurnTables(instances);
+        }
     }
     if (isDoBackend) {
         await installChangeTracking(db);
@@ -343,26 +364,22 @@ export async function startZeroLite(overrides = {}) {
         instances.postgresReplicas = await createReadReplicas(db, config.readReplicas, config);
     }
     // clean up stale lock files from previous crash. if lock files were present,
-    // the previous shutdown was unclean and the replica, change DB, and CVR DB can
-    // disagree about the same client/version history, so rebuild all zero state.
+    // the previous shutdown was unclean and the replica file may not be safe to
+    // reuse, but wiping CVR/CDB here evicts every persisted client with
+    // ClientNotFound. rebuild only the replica; true CDC/CVR corruption is handled
+    // by the crash classifiers below.
     const hadStaleLocks = cleanupStaleLockFiles(config);
     if (hadStaleLocks) {
-        log.debug.orez('unclean shutdown detected, resetting zero state');
-        await recoverZeroState({
-            config,
-            instances,
-            zeroCacheProcess: null,
-        });
+        log.debug.orez('unclean shutdown detected, rebuilding replica (CVR preserved)');
+        cleanupStaleReplica(config);
+        resetReplicationState();
     }
     if (!config.skipZeroCache) {
         const replicaResetReason = getZeroReplicaStartupResetReason(getReplicaDir(config));
         if (replicaResetReason) {
-            log.orez(`detected invalid zero replica (${replicaResetReason}), resetting zero state`);
-            await recoverZeroState({
-                config,
-                instances,
-                zeroCacheProcess: null,
-            });
+            log.orez(`detected invalid zero replica (${replicaResetReason}), rebuilding replica (CVR preserved)`);
+            cleanupStaleReplica(config);
+            resetReplicationState();
         }
     }
     // when admin is enabled, zero-cache runs on internal port with http proxy in front
@@ -394,6 +411,10 @@ export async function startZeroLite(overrides = {}) {
                 const details = tail?.length ? tail.slice(-20).join('\n') : '';
                 throw new Error(`zero-cache crashed during startup stability check\n${details}`);
             }
+            if (!isDoBackend && pgliteVacuumMs > 0) {
+                await vacuumPGliteChurnTables(instances);
+                queuePgliteVacuum();
+            }
         };
         // zero-cache can die during startup for a few distinct reasons; the policy
         // for each lives in classifyZeroStartupRecovery (pure + unit-tested) and
@@ -410,7 +431,7 @@ export async function startZeroLite(overrides = {}) {
             plainRestarts: 0,
             maxRestarts: 3,
             didRecoverState: false,
-            didFullReset: false,
+            didCacheReset: false,
             canWasmFallback: sqliteMode === 'native' && !config.disableWasmSqlite,
             didWasmFallback: false,
             nativeBinaryMissing: false,
@@ -456,10 +477,11 @@ export async function startZeroLite(overrides = {}) {
                     sqliteModeConfig = resolveSqliteModeConfig(false, true); // force wasm
                     continue;
                 }
-                if (action === 'full-reset') {
-                    startupRetry.didFullReset = true;
-                    log.orez('zero-cache still crashing after restarts — resetting zero state and retrying once more...');
-                    await recoverZeroState({ config, instances, zeroCacheProcess });
+                if (action === 'cache-reset') {
+                    startupRetry.didCacheReset = true;
+                    log.orez('zero-cache still crashing after restarts — rebuilding replica and retrying once more (CVR preserved)...');
+                    cleanupStaleReplica(config);
+                    resetReplicationState();
                     continue;
                 }
                 // action === 'restart': transient / unexpected crash, plain relaunch.
@@ -471,7 +493,7 @@ export async function startZeroLite(overrides = {}) {
         // visible in logs rather than silently swallowed.
         if (startupRetry.plainRestarts > 0 ||
             startupRetry.didRecoverState ||
-            startupRetry.didFullReset ||
+            startupRetry.didCacheReset ||
             startupRetry.didWasmFallback) {
             log.orez('zero-cache started after recovery');
         }
@@ -820,16 +842,14 @@ export async function startZeroLite(overrides = {}) {
                 installCrashWatcher();
             })
                 .catch((err) => {
-                // if a plain restart can't bring it back, the local state may be
-                // worse than the tail suggested — fall back to a full reset once.
-                log.orez(`zero-cache restart recovery failed (${err?.message || err}) — falling back to full reset`);
-                resetZeroState('full')
+                log.orez(`zero-cache restart recovery failed (${err?.message || err}) — rebuilding replica (CVR preserved)`);
+                resetZeroState('cache-only')
                     .then(() => {
-                    log.orez('zero-cache full-reset recovery successful');
+                    log.orez('zero-cache replica rebuild recovery successful');
                     installCrashWatcher();
                 })
                     .catch((resetErr) => {
-                    log.orez(`zero-cache full-reset recovery failed: ${resetErr?.message || resetErr}`);
+                    log.orez(`zero-cache replica rebuild recovery failed: ${resetErr?.message || resetErr}`);
                 });
             });
         });
@@ -894,14 +914,14 @@ export async function startZeroLite(overrides = {}) {
                 installCrashWatcher();
             }
             catch (err) {
-                log.orez(`zero-cache HTTP liveness restart failed (${err?.message || err}) — falling back to full reset`);
+                log.orez(`zero-cache HTTP liveness restart failed (${err?.message || err}) — rebuilding replica (CVR preserved)`);
                 try {
-                    await resetZeroState('full');
-                    log.orez('zero-cache HTTP liveness full-reset recovery successful');
+                    await resetZeroState('cache-only');
+                    log.orez('zero-cache HTTP liveness replica rebuild recovery successful');
                     installCrashWatcher();
                 }
                 catch (resetErr) {
-                    log.orez(`zero-cache HTTP liveness full-reset recovery failed: ${resetErr?.message || resetErr}`);
+                    log.orez(`zero-cache HTTP liveness replica rebuild recovery failed: ${resetErr?.message || resetErr}`);
                 }
             }
             finally {
@@ -923,6 +943,8 @@ export async function startZeroLite(overrides = {}) {
         shuttingDown = true;
         if (zeroHttpHealthTimer)
             clearInterval(zeroHttpHealthTimer);
+        if (delayedVacuumTimer)
+            clearTimeout(delayedVacuumTimer);
         stopCheckpoint();
         stopVacuum();
         httpProxyServer?.close();
@@ -1067,6 +1089,10 @@ async function startZeroCache(config, logStore, sqliteMode = resolveSqliteMode(c
     // orez owns the replica on disk and has no litestream backup; stop zero 1.5's
     // change-streamer from erroring + resyncing on every restart (see the patch).
     disableZeroLitestreamRestore();
+    // zero-cache's changeLog cleanup can strand pending cleanup watermarks when
+    // it runs before any subscriber is connected. Keep the cleanup timer alive so
+    // local/ephemeral Orez instances do not accumulate a huge CDB catchup log.
+    enableZeroChangeLogCleanupRetry();
     // litestream also checkpointed the replica WAL in stock zero-cache; with it gone,
     // nothing reclaims the wal2 (PASSIVE autocheckpoint can't pass the view-syncer's
     // held readers), so it grows unbounded and reads slow down. Inject a periodic