@ryanstark24/sfgraph-core 1.4.0 → 1.6.0

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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"}