@catalyst-cloud/sdk 0.14.0 → 0.14.2

package/dist/node.js

@@ -7305,7 +7305,8 @@ function searchIndexesOver(db, tables) {
   );
   const pairs = JSON.parse(String(row?.["j"] ?? "[]"));
   return pairs.filter(([, ddl]) => {
-    const content = /content\s*=\s*'([^']*)'/i.exec(ddl)?.[1];
+    const m = /content\s*=\s*(?:'([^']*)'|"([^"]*)"|([A-Za-z_]\w*))/i.exec(ddl);
+    const content = m?.[1] ?? m?.[2] ?? m?.[3];
     return content !== void 0 && tables.has(content);
   }).map(([name]) => name);
 }
@@ -7619,6 +7620,9 @@ var CatalystReplica = class _CatalystReplica {
   fetchImpl;
   log;
   engine = null;
+  /** The dynamic engine open is owned until it settles; closeAndWait must not release the lock first. */
+  engineOpening = null;
+  shutdownTask = null;
   writeDb = null;
   sqlExecutor = null;
   client = null;
@@ -7632,11 +7636,9 @@ var CatalystReplica = class _CatalystReplica {
   readonlyMode = false;
   /** The claimed single-writer lock (writers only; null for readers / `:memory:` / disabled). */
   writerLock = null;
-  /** The in-flight seed's AbortController (CTC-281), or null when no seed is running. close() aborts
-   *  it SYNCHRONOUSLY so the pending /snapshot fetch + body read release their connection instead of
-   *  keeping the event loop referenced after close() resolved — the "close() succeeded but the
-   *  process can't exit" hostage mechanism from the incident chain. Also the seed idle-timeout's
-   *  abort seam. One controller per seed RUN (a retried seed gets a fresh one). */
+  /** The in-flight seed's AbortController (CTC-281), synchronously aborted by closeAndWait before it
+   *  joins the fetch/body-reader unwind. Also the seed idle-timeout's abort seam. One controller per
+   *  seed RUN (a retried seed gets a fresh one). */
   seedAbort = null;
   /** Resolved on the first 'live' status (start() = caught-up + ready to read); rejected on close /
    *  an initial seed failure. */
@@ -7728,7 +7730,18 @@ var CatalystReplica = class _CatalystReplica {
     if (this.started) throw new Error("CatalystReplica: start() already called");
     this.started = true;
     this.writerLock = claimWriterLock(this.opts.dbPath, this.opts.writerGuard ?? {}, this.log);
-    const engine = await this.resolveEngine();
+    const engineOpening = this.resolveEngine();
+    this.engineOpening = engineOpening;
+    let engine;
+    try {
+      engine = await engineOpening;
+    } finally {
+      if (this.engineOpening === engineOpening) this.engineOpening = null;
+    }
+    if (this.closed) {
+      this.engine = engine;
+      throw new Error("CatalystReplica: start cancelled by close()");
+    }
     this.engine = engine;
     const stored = readAccountStamp(engine);
     const mySource = this.opts.accountSource ?? DEFAULT_ACCOUNT_SOURCE;
@@ -7827,13 +7840,14 @@ var CatalystReplica = class _CatalystReplica {
       tracerName: DEFAULT_SCOPE_NAME,
       meterName: DEFAULT_SCOPE_NAME
     });
+    if (this.closed) throw new Error("CatalystReplica: start cancelled by close()");
     this.registerMetrics();
     this.client = new LiveSyncClient({
       baseUrl: this.baseUrl,
       accountId: this.opts.account,
       connectPath: this.opts.connectPath,
       auth: this.opts.auth,
-      reseed: () => this.seedFromSnapshot(),
+      reseed: (signal) => this.seedFromSnapshot(signal),
       getCursor: () => getCursor(this.writeDb),
       connectParams: () => this.workflowRevParams(),
       onChange: (frame) => this.applyFrame(frame),
@@ -7868,13 +7882,11 @@ var CatalystReplica = class _CatalystReplica {
       const timer = setTimeout(() => {
         if (settled) return;
         settled = true;
-        void this.close().finally(() => {
-          reject(
-            new Error(
-              `CatalystReplica.start() did not reach 'live' within ${timeoutMs}ms (account=${this.opts.account}, dbPath=${this.opts.dbPath})`
-            )
-          );
-        });
+        const timeoutMessage = `CatalystReplica.start() did not reach 'live' within ${timeoutMs}ms (account=${this.opts.account}, dbPath=${this.opts.dbPath})`;
+        void this.close().then(
+          () => reject(new Error(timeoutMessage)),
+          (cleanupError) => reject(new Error(timeoutMessage, { cause: cleanupError }))
+        );
       }, timeoutMs);
       timer.unref?.();
       livePromise.then(
@@ -7906,14 +7918,23 @@ var CatalystReplica = class _CatalystReplica {
     if (!this.client) throw new Error("CatalystReplica: resume() before start()");
     this.client.resume();
   }
-  /** Stop the socket, release the writer lock, close the DB. Idempotent. Rejects a still-pending
-   *  start(). On a reader: no socket/lock to release — just closes the read-only handle. */
-  async close() {
-    if (this.closed) return;
+  /**
+   * Compatibility shutdown entrypoint. It now acknowledges actual seed/engine settlement before
+   * releasing the writer guard or closing SQLite; callers that need an explicit lifecycle name can
+   * use closeAndWait().
+   */
+  close() {
+    return this.closeAndWait();
+  }
+  /** Stop the socket and join engine-open and transport seed/reseed work before releasing ownership. */
+  async closeAndWait() {
+    if (this.shutdownTask) return this.shutdownTask;
     this.closed = true;
     this.client?.stop();
     try {
-      this.seedAbort?.abort(new Error("CatalystReplica closed"));
+      const abortError = new Error("CatalystReplica closed");
+      abortError.name = "AbortError";
+      this.seedAbort?.abort(abortError);
     } catch (err) {
       this.log("warn", "seed abort threw", err);
     }
@@ -7921,25 +7942,45 @@ var CatalystReplica = class _CatalystReplica {
     const rej = this.liveReject;
     this.clearLiveDeferred();
     rej?.(new Error("CatalystReplica: closed before first 'live'"));
-    try {
-      this.writerLock?.release();
-    } catch (err) {
-      this.log("warn", "writer-lock release threw", err);
-    }
-    this.writerLock = null;
-    for (const reg of this.metricRegs) {
+    const client = this.client;
+    const shutdown = async () => {
+      const failures = [];
+      if (this.engineOpening) await this.engineOpening.catch(() => void 0);
+      let seedIoAcknowledged = false;
       try {
-        reg.remove();
+        await client?.stopAndWait();
+        seedIoAcknowledged = true;
       } catch (err) {
-        this.log("warn", "metric unregister threw", err);
+        failures.push(err);
       }
-    }
-    this.metricRegs = [];
-    try {
-      this.engine?.close();
-    } catch (err) {
-      this.log("warn", "engine close threw", err);
-    }
+      for (const reg of this.metricRegs) {
+        try {
+          reg.remove();
+        } catch (err) {
+          failures.push(err);
+        }
+      }
+      this.metricRegs = [];
+      let engineClosed = this.engine == null;
+      try {
+        this.engine?.close();
+        engineClosed = true;
+        this.engine = null;
+      } catch (err) {
+        failures.push(err);
+      }
+      if (engineClosed && seedIoAcknowledged) {
+        try {
+          this.writerLock?.release();
+          this.writerLock = null;
+        } catch (err) {
+          failures.push(err);
+        }
+      }
+      if (failures.length) throw new AggregateError(failures, "CatalystReplica shutdown failed");
+    };
+    this.shutdownTask = shutdown();
+    return this.shutdownTask;
   }
   // ── Reads ───────────────────────────────────────────────────────────────────────────────────────
   /** The read-model SqlExecutor over the replica. `buildIssuesView(replica.sql, …)` is unchanged. */
@@ -8258,16 +8299,19 @@ var CatalystReplica = class _CatalystReplica {
    * interrupted seed self-heals (getCursor → null → re-seed on the next start), preserving host-sync's
    * atomic truncate+apply+setCursor safety without holding one giant transaction.
    */
-  async seedFromSnapshot() {
+  async seedFromSnapshot(attemptSignal) {
     return this.telemetry.withActiveSpan(
       REPLICA_SPAN.seed,
       { [CATALYST_ATTR.tenant]: this.opts.account },
       async (span) => {
         const engine = this.engine;
         const writeDb = this.writeDb;
+        if (attemptSignal?.aborted) throw attemptSignal.reason;
         if (this.closed) throw new Error("CatalystReplica: seed aborted (already closed)");
         const abort = new AbortController();
         this.seedAbort = abort;
+        const onAttemptAbort = () => abort.abort(attemptSignal?.reason);
+        attemptSignal?.addEventListener("abort", onAttemptAbort, { once: true });
         const idleMs = this.opts.snapshotIdleTimeoutMs ?? 3e4;
         let idleTimer = null;
         const clearIdle = () => {
@@ -8377,6 +8421,7 @@ var CatalystReplica = class _CatalystReplica {
           throw err;
         } finally {
           clearIdle();
+          attemptSignal?.removeEventListener("abort", onAttemptAbort);
           if (this.seedAbort === abort) this.seedAbort = null;
         }
       }

package/dist/replica/catalyst-replica.d.ts

@@ -177,6 +177,9 @@ export declare class CatalystReplica {
     private readonly fetchImpl;
     private readonly log;
     private engine;
+    /** The dynamic engine open is owned until it settles; closeAndWait must not release the lock first. */
+    private engineOpening;
+    private shutdownTask;
     private writeDb;
     private sqlExecutor;
     private client;
@@ -190,11 +193,9 @@ export declare class CatalystReplica {
     private readonlyMode;
     /** The claimed single-writer lock (writers only; null for readers / `:memory:` / disabled). */
     private writerLock;
-    /** The in-flight seed's AbortController (CTC-281), or null when no seed is running. close() aborts
-     *  it SYNCHRONOUSLY so the pending /snapshot fetch + body read release their connection instead of
-     *  keeping the event loop referenced after close() resolved — the "close() succeeded but the
-     *  process can't exit" hostage mechanism from the incident chain. Also the seed idle-timeout's
-     *  abort seam. One controller per seed RUN (a retried seed gets a fresh one). */
+    /** The in-flight seed's AbortController (CTC-281), synchronously aborted by closeAndWait before it
+     *  joins the fetch/body-reader unwind. Also the seed idle-timeout's abort seam. One controller per
+     *  seed RUN (a retried seed gets a fresh one). */
     private seedAbort;
     /** Resolved on the first 'live' status (start() = caught-up + ready to read); rejected on close /
      *  an initial seed failure. */
@@ -263,9 +264,14 @@ export declare class CatalystReplica {
      * after `close()`.
      */
     resume(): void;
-    /** Stop the socket, release the writer lock, close the DB. Idempotent. Rejects a still-pending
-     *  start(). On a reader: no socket/lock to release — just closes the read-only handle. */
+    /**
+     * Compatibility shutdown entrypoint. It now acknowledges actual seed/engine settlement before
+     * releasing the writer guard or closing SQLite; callers that need an explicit lifecycle name can
+     * use closeAndWait().
+     */
     close(): Promise<void>;
+    /** Stop the socket and join engine-open and transport seed/reseed work before releasing ownership. */
+    closeAndWait(): Promise<void>;
     /** The read-model SqlExecutor over the replica. `buildIssuesView(replica.sql, …)` is unchanged. */
     get sql(): SqlExecutor;
     issues(opts?: {

package/dist/replica/catalyst-replica.d.ts.map

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

package/dist/replica/catalyst-replica.js

@@ -132,6 +132,9 @@ export class CatalystReplica {
     fetchImpl;
     log;
     engine = null;
+    /** The dynamic engine open is owned until it settles; closeAndWait must not release the lock first. */
+    engineOpening = null;
+    shutdownTask = null;
     writeDb = null;
     sqlExecutor = null;
     client = null;
@@ -145,11 +148,9 @@ export class CatalystReplica {
     readonlyMode = false;
     /** The claimed single-writer lock (writers only; null for readers / `:memory:` / disabled). */
     writerLock = null;
-    /** The in-flight seed's AbortController (CTC-281), or null when no seed is running. close() aborts
-     *  it SYNCHRONOUSLY so the pending /snapshot fetch + body read release their connection instead of
-     *  keeping the event loop referenced after close() resolved — the "close() succeeded but the
-     *  process can't exit" hostage mechanism from the incident chain. Also the seed idle-timeout's
-     *  abort seam. One controller per seed RUN (a retried seed gets a fresh one). */
+    /** The in-flight seed's AbortController (CTC-281), synchronously aborted by closeAndWait before it
+     *  joins the fetch/body-reader unwind. Also the seed idle-timeout's abort seam. One controller per
+     *  seed RUN (a retried seed gets a fresh one). */
     seedAbort = null;
     /** Resolved on the first 'live' status (start() = caught-up + ready to read); rejected on close /
      *  an initial seed failure. */
@@ -250,7 +251,22 @@ export class CatalystReplica {
         // Single-writer guard: claim sole ownership of the file BEFORE opening it, so a second concurrent
         // writer rejects here instead of racing the cursor/seed. A no-op for ':memory:' or when disabled.
         this.writerLock = claimWriterLock(this.opts.dbPath, this.opts.writerGuard ?? {}, this.log);
-        const engine = await this.resolveEngine();
+        const engineOpening = this.resolveEngine();
+        this.engineOpening = engineOpening;
+        let engine;
+        try {
+            engine = await engineOpening;
+        }
+        finally {
+            if (this.engineOpening === engineOpening)
+                this.engineOpening = null;
+        }
+        // close() may have been requested while the sqlite driver was opening. The lock stays held until
+        // that opener settles, and a late opener is closed before migrations or any other writes begin.
+        if (this.closed) {
+            this.engine = engine;
+            throw new Error("CatalystReplica: start cancelled by close()");
+        }
         this.engine = engine;
         // ── CTC-582: THE ACCOUNT FENCE ────────────────────────────────────────────────────────────────
         //
@@ -446,13 +462,15 @@ export class CatalystReplica {
             tracerName: DEFAULT_SCOPE_NAME,
             meterName: DEFAULT_SCOPE_NAME,
         });
+        if (this.closed)
+            throw new Error("CatalystReplica: start cancelled by close()");
         this.registerMetrics();
         this.client = new LiveSyncClient({
             baseUrl: this.baseUrl,
             accountId: this.opts.account,
             connectPath: this.opts.connectPath,
             auth: this.opts.auth,
-            reseed: () => this.seedFromSnapshot(),
+            reseed: (signal) => this.seedFromSnapshot(signal),
             getCursor: () => getCursor(this.writeDb),
             connectParams: () => this.workflowRevParams(),
             onChange: (frame) => this.applyFrame(frame),
@@ -496,10 +514,11 @@ export class CatalystReplica {
                 if (settled)
                     return;
                 settled = true;
-                void this.close().finally(() => {
-                    reject(new Error(`CatalystReplica.start() did not reach 'live' within ${timeoutMs}ms ` +
-                        `(account=${this.opts.account}, dbPath=${this.opts.dbPath})`));
-                });
+                const timeoutMessage = `CatalystReplica.start() did not reach 'live' within ${timeoutMs}ms ` +
+                    `(account=${this.opts.account}, dbPath=${this.opts.dbPath})`;
+                // Consume both shutdown outcomes. An ignored finally() promise would reject independently
+                // when cleanup fails, leaving the caller with only the timeout and an unhandled rejection.
+                void this.close().then(() => reject(new Error(timeoutMessage)), (cleanupError) => reject(new Error(timeoutMessage, { cause: cleanupError })));
             }, timeoutMs);
             timer.unref?.();
             livePromise.then(() => {
@@ -532,19 +551,25 @@ export class CatalystReplica {
             throw new Error("CatalystReplica: resume() before start()");
         this.client.resume();
     }
-    /** Stop the socket, release the writer lock, close the DB. Idempotent. Rejects a still-pending
-     *  start(). On a reader: no socket/lock to release — just closes the read-only handle. */
-    async close() {
-        if (this.closed)
-            return;
+    /**
+     * Compatibility shutdown entrypoint. It now acknowledges actual seed/engine settlement before
+     * releasing the writer guard or closing SQLite; callers that need an explicit lifecycle name can
+     * use closeAndWait().
+     */
+    close() {
+        return this.closeAndWait();
+    }
+    /** Stop the socket and join engine-open and transport seed/reseed work before releasing ownership. */
+    async closeAndWait() {
+        if (this.shutdownTask)
+            return this.shutdownTask;
         this.closed = true;
         this.client?.stop();
-        // Abort any in-flight seed SYNCHRONOUSLY (CTC-281) — never await its settlement (close() must
-        // stay one-tick). Without this, the pending /snapshot fetch + un-cancelled body reader kept the
-        // TCP connection referenced after close() resolved, holding a supervised process's exit hostage.
-        // stop() ran first, so the seed's rejection lands in paths that already refuse to reopen.
+        // Abort any in-flight seed synchronously, then join its actual I/O in LiveSyncClient.stopAndWait.
         try {
-            this.seedAbort?.abort(new Error("CatalystReplica closed"));
+            const abortError = new Error("CatalystReplica closed");
+            abortError.name = "AbortError";
+            this.seedAbort?.abort(abortError);
         }
         catch (err) {
             this.log("warn", "seed abort threw", err);
@@ -553,29 +578,55 @@ export class CatalystReplica {
         const rej = this.liveReject;
         this.clearLiveDeferred();
         rej?.(new Error("CatalystReplica: closed before first 'live'"));
-        try {
-            this.writerLock?.release();
-        }
-        catch (err) {
-            this.log("warn", "writer-lock release threw", err);
-        }
-        this.writerLock = null;
-        // Unregister the observable-gauge callbacks so a closed replica stops being scraped + can be GC'd.
-        for (const reg of this.metricRegs) {
+        const client = this.client;
+        const shutdown = async () => {
+            const failures = [];
+            // The replica lock remains held while either an engine opener or client-owned seed can still
+            // write. Startup checks `closed` immediately after the opener and before client construction.
+            if (this.engineOpening)
+                await this.engineOpening.catch(() => undefined);
+            let seedIoAcknowledged = false;
             try {
-                reg.remove();
+                await client?.stopAndWait();
+                seedIoAcknowledged = true;
             }
             catch (err) {
-                this.log("warn", "metric unregister threw", err);
+                failures.push(err);
             }
-        }
-        this.metricRegs = [];
-        try {
-            this.engine?.close();
-        }
-        catch (err) {
-            this.log("warn", "engine close threw", err);
-        }
+            for (const reg of this.metricRegs) {
+                try {
+                    reg.remove();
+                }
+                catch (err) {
+                    failures.push(err);
+                }
+            }
+            this.metricRegs = [];
+            let engineClosed = this.engine == null;
+            try {
+                this.engine?.close();
+                engineClosed = true;
+                this.engine = null;
+            }
+            catch (err) {
+                failures.push(err);
+            }
+            // Do not admit a successor while the old handle may still be live. Keep the sidecar on an
+            // engine-close or seed-I/O acknowledgement failure so ownership remains conservatively held.
+            if (engineClosed && seedIoAcknowledged) {
+                try {
+                    this.writerLock?.release();
+                    this.writerLock = null;
+                }
+                catch (err) {
+                    failures.push(err);
+                }
+            }
+            if (failures.length)
+                throw new AggregateError(failures, "CatalystReplica shutdown failed");
+        };
+        this.shutdownTask = shutdown();
+        return this.shutdownTask;
     }
     // ── Reads ───────────────────────────────────────────────────────────────────────────────────────
     /** The read-model SqlExecutor over the replica. `buildIssuesView(replica.sql, …)` is unchanged. */
@@ -919,7 +970,7 @@ export class CatalystReplica {
      * interrupted seed self-heals (getCursor → null → re-seed on the next start), preserving host-sync's
      * atomic truncate+apply+setCursor safety without holding one giant transaction.
      */
-    async seedFromSnapshot() {
+    async seedFromSnapshot(attemptSignal) {
         // The whole seed (fetch + truncate + batched apply + setCursor) runs inside ONE active span so it
         // nests under the resync span when triggered by a {type:"resync"} frame, and stands alone on a cold
         // start. Active so the per-batch apply spans auto-parent under it.
@@ -930,10 +981,16 @@ export class CatalystReplica {
             // it synchronously. Every await below (fetch, each body chunk) is bounded by it — a hung
             // /snapshot can no longer wedge the transport in "resyncing" (no socket, no timers) or keep
             // the event loop referenced after close().
+            if (attemptSignal?.aborted)
+                throw attemptSignal.reason;
             if (this.closed)
                 throw new Error("CatalystReplica: seed aborted (already closed)");
             const abort = new AbortController();
             this.seedAbort = abort;
+            // Carry the transport's exact owned cancellation into fetch/body reads. A distinct cleanup
+            // error, even one named AbortError, must remain distinguishable at stopAndWait().
+            const onAttemptAbort = () => abort.abort(attemptSignal?.reason);
+            attemptSignal?.addEventListener("abort", onAttemptAbort, { once: true });
             // The idle (NO-PROGRESS) deadline: (re)armed before the fetch and on every body chunk, so a
             // big-but-flowing seed never trips it while a silent half-open connection always does.
             // Unref'd — the timer must never itself hold the process open.
@@ -1085,6 +1142,7 @@ export class CatalystReplica {
             }
             finally {
                 clearIdle();
+                attemptSignal?.removeEventListener("abort", onAttemptAbort);
                 if (this.seedAbort === abort)
                     this.seedAbort = null;
             }