@ryanstark24/sfgraph-core 1.2.0 → 1.6.0

package/dist/embedding/pool.js

@@ -1,10 +1,160 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+export const EMBED_DIM = 384;
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * The compiled worker entry next to this module, or null when it is not there
+ * (running from TypeScript sources, e.g. under vitest) or when
+ * `SFGRAPH_EMBED_WORKER=0`. Callers fall back to in-process embedding.
+ */
+export function defaultEmbeddingWorkerUrl() {
+    if (process.env.SFGRAPH_EMBED_WORKER === "0")
+        return null;
+    const url = new URL("./worker.js", import.meta.url);
+    try {
+        return existsSync(fileURLToPath(url)) ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * Placeholder for a future piscina-backed embedding pool.
+ * Embedding inference in a worker_thread, so ONNX, tokenisation and pooling run
+ * alongside the ingest fan-out instead of on the main thread.
  *
- * For Commit C we ship an in-process queue (see `./queue.ts`) since
- * worker-thread loading of transformers.js has its own bootstrapping cost
- * that exceeds the budget for a single-batch run. A worker-thread pool is
- * a v1.1 optimization.
+ * One worker: onnxruntime already parallelises each run across cores, so more
+ * workers would only oversubscribe the CPU. Requests are answered in FIFO order.
+ * The worker is spawned on the first call (a warm-cache run never pays the
+ * model load) and is unref'd while idle so it never holds the process open.
+ *
+ * A crash (uncaught error, non-zero exit) or a hang (no reply within
+ * `requestTimeoutMs` while requests are outstanding) rejects every outstanding
+ * request and every later one with that error — callers see an error, never
+ * a hang.
  */
-export const EMBED_DIM = 384;
+export class EmbeddingPool {
+    opts;
+    worker = null;
+    nextId = 1;
+    pending = new Map();
+    crash = null;
+    closed = false;
+    stallTimer = null;
+    timeoutMs;
+    constructor(opts = {}) {
+        this.opts = opts;
+        const env = Number.parseInt(process.env.SFGRAPH_EMBED_TIMEOUT_MS ?? "", 10);
+        this.timeoutMs = opts.requestTimeoutMs ?? (env > 0 ? env : DEFAULT_TIMEOUT_MS);
+    }
+    /** Requests posted and not yet answered. */
+    get inFlight() {
+        return this.pending.size;
+    }
+    embed(texts) {
+        if (this.closed)
+            return Promise.reject(new Error("embedding pool closed"));
+        if (this.crash)
+            return Promise.reject(this.crash);
+        if (texts.length === 0)
+            return Promise.resolve([]);
+        let worker;
+        try {
+            worker = this.ensureWorker();
+        }
+        catch (e) {
+            this.crash = new Error(`embedding worker failed to start: ${e.message}`);
+            return Promise.reject(this.crash);
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            if (!this.stallTimer)
+                this.armStallTimer();
+            worker.ref();
+            worker.postMessage({ id, texts });
+        });
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.clearStallTimer();
+        this.failAll(new Error("embedding pool closed"));
+        const w = this.worker;
+        this.worker = null;
+        if (w)
+            await w.terminate();
+    }
+    ensureWorker() {
+        if (this.worker)
+            return this.worker;
+        const url = this.opts.workerUrl ?? defaultEmbeddingWorkerUrl();
+        if (!url)
+            throw new Error("no compiled embedding worker (worker.js) found");
+        const w = new Worker(url, { workerData: this.opts.workerData });
+        w.unref();
+        w.on("message", (msg) => this.onReply(msg));
+        w.on("error", (err) => {
+            this.onCrash(new Error(`embedding worker crashed: ${err.message}`));
+        });
+        w.on("messageerror", (err) => {
+            this.onCrash(new Error(`embedding worker message error: ${err.message}`));
+        });
+        w.on("exit", (code) => {
+            if (this.worker === w)
+                this.worker = null;
+            if (!this.closed)
+                this.onCrash(new Error(`embedding worker exited with code ${code}`));
+        });
+        this.worker = w;
+        return w;
+    }
+    onReply(msg) {
+        const p = this.pending.get(msg.id);
+        if (!p)
+            return;
+        this.pending.delete(msg.id);
+        // Progress: restart the liveness window (or stop it when idle).
+        this.clearStallTimer();
+        if (this.pending.size === 0)
+            this.worker?.unref();
+        else
+            this.armStallTimer();
+        if ("error" in msg)
+            p.reject(new Error(msg.error));
+        else
+            p.resolve(msg.vectors);
+    }
+    onCrash(err) {
+        // Keep the first cause (an 'error' event is followed by 'exit').
+        if (!this.crash)
+            this.crash = err;
+        this.clearStallTimer();
+        this.failAll(this.crash);
+    }
+    armStallTimer() {
+        this.stallTimer = setTimeout(() => {
+            this.stallTimer = null;
+            if (this.pending.size === 0)
+                return;
+            const w = this.worker;
+            this.onCrash(new Error(`embedding worker unresponsive: no reply in ${Math.round(this.timeoutMs / 1000)}s`));
+            this.worker = null;
+            void w?.terminate();
+        }, this.timeoutMs);
+        this.stallTimer.unref();
+    }
+    clearStallTimer() {
+        if (this.stallTimer)
+            clearTimeout(this.stallTimer);
+        this.stallTimer = null;
+    }
+    failAll(err) {
+        const ps = [...this.pending.values()];
+        this.pending.clear();
+        for (const p of ps)
+            p.reject(err);
+    }
+}
 //# sourceMappingURL=pool.js.map

package/dist/embedding/pool.js.map

@@ -1 +1 @@
-{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/embedding/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC"}
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/embedding/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC;AA0B7B,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAO1C;;;;GAIG;AACH,MAAM,UAAU,yBAAyB;IACvC,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC1D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,aAAa;IASK;IARrB,MAAM,GAAkB,IAAI,CAAC;IAC7B,MAAM,GAAG,CAAC,CAAC;IACF,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC9C,KAAK,GAAiB,IAAI,CAAC;IAC3B,MAAM,GAAG,KAAK,CAAC;IACf,UAAU,GAAyC,IAAI,CAAC;IAC/C,SAAS,CAAS;IAEnC,YAA6B,OAA0B,EAAE;QAA5B,SAAI,GAAJ,IAAI,CAAwB;QACvD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAC5E,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,gBAAgB,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;IACjF,CAAC;IAED,4CAA4C;IAC5C,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,KAAe;QACnB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAAC;QAC3E,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACnD,IAAI,MAAc,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAC/B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,qCAAsC,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;YACpF,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,OAAO,IAAI,OAAO,CAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,UAAU;gBAAE,IAAI,CAAC,aAAa,EAAE,CAAC;YAC3C,MAAM,CAAC,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,KAAK,EAAyB,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAAC;QACjD,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC;YAAE,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC;IAC7B,CAAC;IAEO,YAAY;QAClB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,yBAAyB,EAAE,CAAC;QAC/D,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QAC5E,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAChE,CAAC,CAAC,KAAK,EAAE,CAAC;QACV,CAAC,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAe,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACxD,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,6BAA6B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACtE,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC,cAAc,EAAE,CAAC,GAAU,EAAE,EAAE;YAClC,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,mCAAmC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC5E,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACpB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,MAAM;gBAAE,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,qCAAqC,IAAI,EAAE,CAAC,CAAC,CAAC;QACzF,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAChB,OAAO,CAAC,CAAC;IACX,CAAC;IAEO,OAAO,CAAC,GAAe;QAC7B,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,CAAC;YAAE,OAAO;QACf,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5B,gEAAgE;QAChE,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;;YAC7C,IAAI,CAAC,aAAa,EAAE,CAAC;QAC1B,IAAI,OAAO,IAAI,GAAG;YAAE,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;;YAC9C,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAEO,OAAO,CAAC,GAAU;QACxB,iEAAiE;QACjE,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC;QAClC,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAEO,aAAa;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;gBAAE,OAAO;YACpC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YACtB,IAAI,CAAC,OAAO,CACV,IAAI,KAAK,CACP,8CAA8C,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CACnF,CACF,CAAC;YACF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;QACtB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;IAEO,eAAe;QACrB,IAAI,IAAI,CAAC,UAAU;YAAE,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAEO,OAAO,CAAC,GAAU;QACxB,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,KAAK,MAAM,CAAC,IAAI,EAAE;YAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/embedding/queue.d.ts

@@ -1,4 +1,12 @@
 import type { OrgId, QualifiedName, Sha256 } from "@ryanstark24/sfgraph-shared";
+import type { EmbeddingCacheLike } from "./cache.js";
+/** Real SHA-256 of the embedded text. The vector store dedups on this hash
+ *  (skips re-embedding when it matches), so it MUST reflect the actual text —
+ *  otherwise re-ingest never refreshes a vector. Previously this was
+ *  `asSha256("rule:" + qname)`, but asSha256 is a branded-type CAST, not a
+ *  hash, so the value was constant per node and every vector was write-once
+ *  (config-value enrichment, description changes, etc. never re-embedded). */
+export declare function hashEmbedText(text: string): Sha256;
 export interface EmbeddingItem {
     qname: string;
     text: string;
@@ -7,33 +15,182 @@ export interface EmbeddingItem {
 }
 export interface VectorSink {
     upsertNodeVector(orgId: OrgId, qname: QualifiedName, label: string, vector: Float32Array, contentHash: Sha256): unknown;
+    /**
+     * Remove a node's stored vector (+ meta) when the node is deleted, so it
+     * stops surfacing as a phantom find_similar hit. Optional: lightweight test
+     * sinks may omit it; callers must feature-detect before invoking.
+     */
+    deleteNodeVector?(orgId: OrgId, qname: QualifiedName): unknown;
+    /**
+     * The content_hash of the node's stored vector, or null if none. Used to skip
+     * the (expensive) embedding model entirely when the text is unchanged — not
+     * just the DB write. Optional: sinks that don't implement it fall back to
+     * always embedding.
+     */
+    getContentHash?(orgId: OrgId, qname: QualifiedName): Sha256 | null;
+    /**
+     * Run `fn` in one transaction. When present, each batch's vectors are
+     * written in one commit instead of one per vector. Optional.
+     */
+    transaction?<T>(fn: () => T): T;
+    /** A transaction is open on the sink's connection. Optional. */
+    readonly inTransaction?: boolean;
 }
 export interface EmbeddingQueueOpts {
     vectorStore: VectorSink;
     batchSize?: number;
     onError?: (err: Error) => void;
-    /** Override embedding function — primarily for tests. */
+    /** Override embedding function — primarily for tests, and how ingest plugs
+     *  in the worker-thread pool. */
     embed?: (texts: string[]) => Promise<Float32Array[]>;
+    /** Persistent text → vector cache consulted before the model. */
+    cache?: EmbeddingCacheLike;
+    /** Vector dimension expected from the cache (default SFGRAPH_EMBED_MODEL_DIM or 384). */
+    dim?: number;
+    /**
+     * Batches dispatched to `embed` but not yet written. Default 1, which keeps
+     * the in-process embedder strictly serial (concurrent calls into the
+     * transformers runtime are unsafe/slow). The worker pool runs batches one
+     * at a time in its own thread, so ingest raises this to keep it fed while the
+     * main thread is busy.
+     */
+    maxInFlight?: number;
+    /**
+     * Backpressure bound on queued text (buffered + in flight), in UTF-16 code
+     * units. Above it, partial batches are dispatched and `waitForCapacity()`
+     * blocks the producer. Default 64M (at most ~128 MB of text).
+     */
+    maxPendingChars?: number;
+    /**
+     * Start held: buffer pushes and run no model calls (not even full batches)
+     * until `release()`, except what backpressure forces out. Ingest holds the
+     * queue until "graph ready" so inference never competes for CPU with the
+     * graph build.
+     */
+    hold?: boolean;
+    /**
+     * Called once, the first time the queue has real vector work: an item that
+     * survives the unchanged check at dispatch, or live items dropped by
+     * abandon(). Ingest uses it to set the org's embeddings_pending flag
+     * lazily, so a re-sync with nothing to embed never turns off the
+     * find_similar vector leg.
+     */
+    onWork?: () => void;
+    /**
+     * Persistent-cache write failures (SQLITE_BUSY, disk full, ...). These are
+     * not embedding failures: the graph's vectors were written. Default: a
+     * console warning.
+     */
+    onCacheError?: (err: Error) => void;
+}
+export interface EmbeddingQueueStats {
+    /** Vectors served from the persistent cache (no model call). */
+    cached: number;
+    /** Texts sent to the model successfully. */
+    computed: number;
+    /** Items skipped because the stored vector already matches the text. */
+    unchanged: number;
+    /** Texts whose model call failed (left unembedded). */
+    failed: number;
+    /** Emissions dropped because a later emission of the same (org, qname)
+     *  replaced them before they were written. */
+    superseded: number;
 }
 /**
- * In-process batched embedding queue. push() accumulates; once buffer reaches
- * batchSize, flushBatch() is scheduled. drain() awaits the queue to empty.
+ * Batched embedding queue. push() accumulates; each full batch (or any partial
+ * batch once draining / over capacity) is dispatched to `embed`, up to
+ * `maxInFlight` at a time. drain() awaits the queue to empty.
+ *
+ * Last-writer-wins: every push of an (org, qname) gets a sequence number and
+ * supersedes all earlier pushes of that key. A superseded emission is never
+ * embedded if it is still buffered, and never written (to the vector store or
+ * the cache) if it is already in flight. The "unchanged" check (stored hash
+ * equals the text hash) runs at dispatch and only for the latest emission;
+ * skipping it settles the key, so an earlier, different text still in flight
+ * is discarded rather than written over it. The vector store therefore ends
+ * with the last emission's vector and hash, whatever the batching or
+ * completion order.
  *
- * When the underlying embedder fails to load (e.g. transformers missing), the
- * queue logs via onError and silently skips vector upserts — ingest must not
- * crash because embeddings are unavailable.
+ * When the underlying embedder fails (e.g. transformers missing, worker
+ * crash), the queue reports via onError and skips those vector upserts —
+ * ingest must not crash because embeddings are unavailable.
  */
 export declare class EmbeddingQueue {
     private readonly opts;
     private buffer;
-    private flushing;
+    /** Latest sequence number per outstanding (org, qname). An entry is removed
+     *  once that latest emission is written, skipped or dropped, so a missing
+     *  key means every queued emission of it is superseded. */
+    private latestSeq;
+    private seq;
+    private workSignalled;
+    private bufferChars;
+    private inFlight;
+    private inFlightItems;
+    private inFlightChars;
+    private writeTail;
+    private draining;
+    private held;
+    private generation;
+    private capacityWaiters;
     private readonly batchSize;
+    private readonly maxInFlight;
+    private readonly maxPendingChars;
+    private readonly dim;
     private readonly embedFn;
+    readonly stats: EmbeddingQueueStats;
     constructor(opts: EmbeddingQueueOpts);
+    /** Lift `hold`: dispatch everything buffered (subject to maxInFlight). */
+    release(): void;
     push(item: EmbeddingItem): void;
+    private signalWork;
+    private isLatest;
+    /** The latest emission of its key is done (written, failed or dropped). */
+    private settle;
+    /**
+     * Settle every buffered item that needs no model call: drop superseded and
+     * unchanged ones, and write those whose vector is in the persistent cache.
+     * Only items that need inference stay buffered. Lets a no-wait run persist
+     * the cheap part of its work before abandoning the rest. Returns the number
+     * of vectors written.
+     */
+    flushCached(): number;
+    /** Flush everything (including a partial batch) in the background. */
+    startDrain(): void;
     drain(): Promise<void>;
-    /** Test introspection. */
+    /** Drop all buffered and in-flight work (their results are discarded).
+     *  Returns the number of items dropped. */
+    abandon(): number;
+    /** True when queued text exceeds the backpressure bound. */
+    get overCapacity(): boolean;
+    /** Resolves once queued text is back under the backpressure bound. */
+    waitForCapacity(): Promise<void>;
+    /** Test introspection: buffered (not yet dispatched) items. */
     get pending(): number;
-    private flushBatch;
+    /** Buffered plus in-flight items. */
+    get outstanding(): number;
+    /**
+     * Task 11c N-1: true when some outstanding item will still write a vector
+     * (in flight, or a latest buffered emission whose stored vector differs).
+     * Stops at the first one; hashes buffered texts, so call it once, off the
+     * per-member path.
+     */
+    hasVectorWork(): boolean;
+    private notifyCapacity;
+    private pump;
+    private dispatch;
+    private prepare;
+    /** Upsert one vector. Returns false (and writes nothing) for an all-zero
+     *  vector, the embedder's failure fallback: a zero vector sits at a fixed
+     *  mid-range similarity and outranks genuine weak matches in find_similar,
+     *  so no vector is better than a misleading one. */
+    /**
+     * Write a batch of vectors in one transaction when the sink supports it.
+     * If the transaction fails, the batch is retried row by row (upserts are
+     * idempotent), so a failure behaves as it did before batching: rows before
+     * the bad one are kept and the error propagates.
+     */
+    private writeMany;
+    private writeOne;
 }
 //# sourceMappingURL=queue.d.ts.map

package/dist/embedding/queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/embedding/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAGhF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,gBAAgB,CACd,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IAC/B,yDAAyD;IACzD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACtD;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IAMb,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+C;gBAE1C,IAAI,EAAE,kBAAkB;IAKrD,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IASzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,0BAA0B;IAC1B,IAAI,OAAO,IAAI,MAAM,CAEpB;YAEa,UAAU;CAqBzB"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/embedding/queue.ts"],"names":[],"mappings":"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"}