@ponraaj/dimple-sdk 0.0.0-alpha.8 → 0.0.0-alpha.9

package/dist/internal/store/db-backend.d.ts

@@ -84,8 +84,12 @@ export interface Interface {
     readonly listIsolatedMemories: (limit: number, modelKey?: string) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
     readonly db: DrizzleDB;
     readonly tables: StoreTables;
-    readonly ftsSearch: (query: string, namespace: string, limit: number, topicKeys?: ReadonlyArray<string>, modelKey?: string, contentType?: string | ReadonlyArray<string>) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
-    readonly vectorSearch: (query: ReadonlyArray<number>, namespace: string, limit: number, model: EmbeddingModelConfig, topicKeys?: ReadonlyArray<string>, contentType?: string | ReadonlyArray<string>) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
+    readonly ftsSearch: (query: string, namespace: string, limit: number, topicKeys?: ReadonlyArray<string>, modelKey?: string, contentType?: string | ReadonlyArray<string>, 
+    /** Include the 384-float `embedding` blob per row (default false —
+     * search results never need vectors; write paths read them via
+     * fetchMemoryVectors). */
+    includeEmbedding?: boolean) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
+    readonly vectorSearch: (query: ReadonlyArray<number>, namespace: string, limit: number, model: EmbeddingModelConfig, topicKeys?: ReadonlyArray<string>, contentType?: string | ReadonlyArray<string>, includeEmbedding?: boolean) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
     readonly sweep: (namespace: string) => Effect.Effect<SweepResult, StoreError>;
     /** The DB's tables + columns (`dimple db-schema` surface). */
     readonly listSchema: () => Effect.Effect<ReadonlyArray<{
@@ -109,11 +113,26 @@ export interface Interface {
     readonly graphNeighbors: (kind: "memory" | "topic" | "concept", id: string, opts?: GraphNeighborsOptions) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
     readonly ensureVectorTable: (model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly insertVector: (memoryId: string, vector: ReadonlyArray<number>, model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
+    /** Batch variant of `insertVector` — one multi-row statement (bulk
+     * ingest: per-memory statements dominate the write path). */
+    readonly insertVectors: (entries: ReadonlyArray<{
+        readonly memoryId: string;
+        readonly vector: ReadonlyArray<number>;
+    }>, model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly deleteVector: (memoryId: string, dimensions: number) => Effect.Effect<void, StoreError>;
     readonly ensureTopicVectorTable: (model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly upsertTopicVector: (topicKey: string, sumVector: ReadonlyArray<number>, model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
+    /** Batch variant of `upsertTopicVector` — one multi-row statement (the
+     * bulk-routing path: sequential per-key upserts dominate batch ingest). */
+    readonly upsertTopicVectors: (entries: ReadonlyArray<{
+        readonly topicKey: string;
+        readonly sumVector: ReadonlyArray<number>;
+    }>, model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly deleteTopicVectors: (model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly fetchTopicVectors: (model: EmbeddingModelConfig) => Effect.Effect<ReadonlyArray<TopicVectorRow>, StoreError>;
+    /** Single-row variant — the forget path's per-ancestor maintenance
+     * re-read the WHOLE table per level before (O(depth × N) decodes). */
+    readonly fetchTopicVector: (topicKey: string, model: EmbeddingModelConfig) => Effect.Effect<TopicVectorRow | undefined, StoreError>;
     readonly fetchMemoryVectors: (memoryIds: ReadonlyArray<string>, model: EmbeddingModelConfig) => Effect.Effect<ReadonlyArray<MemoryVectorRow>, StoreError>;
     readonly listMemoryIds: (model: EmbeddingModelConfig) => Effect.Effect<ReadonlyArray<string>, StoreError>;
 }

package/dist/internal/store/service.d.ts

@@ -1,5 +1,5 @@
 import { Context, Effect } from "effect";
-import type { MemoryUnit, MemoryEvent, WriteMemoryInput, SweepResult, Concept } from "./models.ts";
+import type { MemoryUnit, MemoryEvent, WriteMemoryInput, SweepResult, Concept, ScoredMemory } from "./models.ts";
 import type { StoreError, NotFound, DuplicateActiveKey } from "./error.ts";
 import type { TopicError } from "./topics/errors.ts";
 import type { MaintenanceOutcome, RebalanceOutcome } from "./topics/maintenance.ts";
@@ -110,6 +110,10 @@ export interface Interface {
         readonly contentType?: string | ReadonlyArray<string>;
         /** `false` suppresses the per-leg audit row (fused-row callers). */
         readonly audit?: boolean;
+        /** Include the 384-float embedding on results (default false). */
+        readonly includeEmbedding?: boolean;
+        /** `false` skips the per-leg graph augmentation (fused-row callers). */
+        readonly augment?: boolean;
     }) => Effect.Effect<ReadonlyArray<AugmentedMemory>, StoreError>;
     readonly searchVector: (query: ReadonlyArray<number>, namespace: string, limit: number, opts?: {
         readonly topicKeys?: ReadonlyArray<string>;
@@ -120,7 +124,16 @@ export interface Interface {
         readonly contentType?: string | ReadonlyArray<string>;
         /** `false` suppresses the per-leg audit row (fused-row callers). */
         readonly audit?: boolean;
+        /** Include the 384-float embedding on results (default false). */
+        readonly includeEmbedding?: boolean;
+        /** `false` skips the per-leg graph augmentation (fused-row callers). */
+        readonly augment?: boolean;
     }) => Effect.Effect<ReadonlyArray<AugmentedMemory>, StoreError>;
+    /** One-pass graph augmentation over an already-ranked result set (the
+     * hybrid path: the per-leg augment passes are skipped and the FUSED set
+     * gets one edge fetch + one concept fetch instead of two of each over
+     * 2× the rows). */
+    readonly augmentSearchResults: (results: ReadonlyArray<ScoredMemory>) => Effect.Effect<ReadonlyArray<AugmentedMemory>, StoreError>;
     /** The DB's tables + columns (`dimple db-schema` surface). */
     readonly listSchema: () => Effect.Effect<ReadonlyArray<{
         readonly table: string;
@@ -147,6 +160,20 @@ export interface Interface {
     readonly updateEmbedding: (id: string, embedding: ReadonlyArray<number>, model: string, options?: {
         readonly scanCandidates?: boolean;
     }) => Effect.Effect<void, NotFound | StoreError>;
+    /** Bulk variant of `updateEmbedding` — the writeMany path. One
+     * transaction for all memory updates + events, batch vector insert,
+     * and `routeInsertMany` (tree read once, all insertions computed in
+     * memory, one transaction). For NEW memories: the idempotent re-embed
+     * decrement is deliberately NOT part of the batch (use
+     * `updateEmbedding` for re-embedding existing routed memories).
+     * `scanCandidates` defaults to false-ish via the config: it runs only
+     * when explicitly requested AND `graph.enabled` is not false. */
+    readonly updateEmbeddingMany: (entries: ReadonlyArray<{
+        readonly id: string;
+        readonly embedding: ReadonlyArray<number>;
+    }>, model: string, options?: {
+        readonly scanCandidates?: boolean;
+    }) => Effect.Effect<void, StoreError>;
     readonly findStale: (model: string) => Effect.Effect<readonly string[], StoreError>;
     readonly createConcept: (name: string, embedding: ReadonlyArray<number>) => Effect.Effect<Concept, StoreError>;
     readonly getConcept: (id: string) => Effect.Effect<Concept, NotFound | StoreError>;

package/dist/internal/store/topics/routing.d.ts

@@ -88,3 +88,36 @@ export declare const routeInsert: (memoryId: string, vector: ReadonlyArray<numbe
     topicKey: string;
     overflow: boolean;
 }, TopicError | StoreError, DbBackend>;
+/**
+ * Batch routing — the bulk-ingest path (`Store.updateEmbeddingMany`).
+ *
+ * Sequential `routeInsert` re-reads the WHOLE tree (all topics, all
+ * relations, all centroid sum-vectors) and commits its own transaction
+ * PER UNIT — measured ~42 ms/unit under bulk ingest, dominating the
+ * write path. This variant:
+ *
+ * 1. Reads the tree structure + sum-vectors ONCE.
+ * 2. Routes every entry against an IN-MEMORY mirror of the tree state,
+ *    applying each unit's CF updates locally before the next descent —
+ *    so the descents are bit-identical to sequential routeInsert calls
+ *    against the DB (same reads, same writes, same order).
+ * 3. Applies ALL membership inserts + topic CF updates in ONE
+ *    transaction (per-topic deltas accumulated in memory).
+ * 4. Writes the derived sum vectors in ONE batched upsert (backend
+ *    `upsertTopicVectors`), still after commit (backend not
+ *    transaction-aware — see module docs).
+ *
+ * Contract differences vs sequential: all-or-nothing (a validation
+ * failure or structural corruption rejects the whole batch), and the
+ * batch does NOT handle re-embedding (no membership decrement path) —
+ * it is for NEW memories; re-embedding existing ones goes through
+ * `routeInsert`/`Store.updateEmbedding`.
+ */
+export declare const routeInsertMany: (entries: readonly {
+    readonly memoryId: string;
+    readonly vector: ReadonlyArray<number>;
+}[], model: EmbeddingModelConfig, config: TopicConfig) => Effect.Effect<readonly {
+    readonly memoryId: string;
+    readonly topicKey: string;
+    readonly overflow: boolean;
+}[], TopicError | StoreError, DbBackend>;

package/dist/internal/workflow/signals.d.ts

@@ -0,0 +1,20 @@
+/**
+ * In-process execution-completion signals — the event side of `Runtime.wait`.
+ *
+ * `wait` used to poll the persisted `${jobId}/result` key every 250ms. The
+ * engine knows the exact completion moment, so it now notifies a per-
+ * executionId set of Deferreds; `wait` races the signal against its poll
+ * interval (the poll stays as the fallback for cross-process waits, where
+ * the completing engine lives in another process).
+ *
+ * Plain module-level Map — no Effect service: the signal is a fire-and-
+ * forget wakeup, and the subscribers are runtime-layer Deferreds. Cleanup
+ * on unsubscribe keeps the map from leaking job ids.
+ */
+import { Deferred } from "effect";
+/** Subscribe to one execution's completion. */
+export declare const onExecutionDone: (executionId: string, deferred: Deferred.Deferred<void>) => void;
+/** Unsubscribe (wait's finally — the poll fallback may still be running). */
+export declare const offExecutionDone: (executionId: string, deferred: Deferred.Deferred<void>) => void;
+/** Fire every subscriber's deferred (the engine's completion tap). */
+export declare const notifyExecutionDone: (executionId: string) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponraaj/dimple-sdk",
-  "version": "0.0.0-alpha.8",
+  "version": "0.0.0-alpha.9",
   "private": false,
   "files": [
     "dist"