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

package/dist/internal/embedder/auto-install.d.ts

@@ -1,35 +1,10 @@
-/**
- * First-use auto-install of the OPTIONAL `@huggingface/transformers` peer.
- *
- * `@huggingface/transformers` is an optional peer (its tree pulls the
- * `sharp` + `onnxruntime-node` postinstall scripts that abort npm 11
- * installs). When the config declares a `transformers` provider model,
- * the intent is explicit — so the FIRST local-embed use installs the
- * package automatically with the project's own package manager, instead
- * of failing with a manual step.
- *
- * Safety notes:
- * - The install is scoped to the detected project root (the manifest's
- *   directory) and uses the manager the project already uses.
- * - EVERY install runs `--ignore-scripts` (npm/pnpm/yarn) or bun's
- *   default script-blocking — verified harmless: the onnxruntime-node
- *   binaries ship in the package; its postinstall is not required for
- *   embedding, and sharp is never loaded for text embeddings.
- * - Failure (offline, restricted env) is a typed EmbeddingError with the
- *   manual command — never a crash.
- */
-export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
-export interface InstallTarget {
-    readonly pm: PackageManager;
-    readonly root: string;
-}
-/** Detect the project's package manager by walking UP from `cwd` for a
- * lockfile (bun.lock/bun.lockb → bun, package-lock.json → npm,
- * pnpm-lock.yaml → pnpm, yarn.lock → yarn). Falls back to bun + cwd. */
-export declare const detectPackageManager: (cwd: string) => InstallTarget;
-/** The install argv for a manager. `--ignore-scripts` on npm/pnpm/yarn:
- * the blocked postinstalls are proven unnecessary for embedding (bun
- * blocks them by default already). */
+import { type PackageManager } from "./internal/installer/index.js";
+export type { InstallTarget, PackageManager } from "./internal/installer/index.js";
+export { detectPackageManager } from "./internal/installer/index.js";
+/** The install argv for a manager with the transformers package (kept for
+ * callers/tests that assert the shape). */
 export declare const installCommand: (pm: PackageManager) => readonly [string, ...string[]];
-/** Run the install for the project at `cwd`; rejects on non-zero exit. */
+/** Install transformers at the project root detected from `cwd`. The
+ * shared installer kills the child on timeout and dedups concurrent
+ * first-use installs; failures reject with the manual command. */
 export declare const installTransformers: (cwd: string) => Promise<void>;

package/dist/internal/installer/index.d.ts

@@ -0,0 +1,26 @@
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+export interface InstallTarget {
+    readonly pm: PackageManager;
+    readonly root: string;
+}
+export declare class InstallerError extends Error {
+    constructor(message: string);
+}
+/** Detect the project's package manager by walking UP from `cwd` for a
+ * lockfile. NO lockfile → npm (the most universal — a bun fallback broke
+ * Node-only machines with ENOENT). */
+export declare const detectPackageManager: (cwd: string) => InstallTarget;
+/** The executable name for a manager. win32 ships `.cmd` shims for
+ * npm/pnpm/yarn — the bare names fail with ENOENT. */
+export declare const resolveExecutable: (pm: PackageManager, platform?: NodeJS.Platform) => string;
+/** The base install argv for a manager. Scripts are skipped everywhere;
+ * pnpm at a workspace root additionally gets `-w`. */
+export declare const installArgs: (pm: PackageManager, packages: readonly string[], root: string) => string[];
+export interface InstallOptions {
+    readonly cwd?: string;
+    /** Hard deadline; the child is SIGKILLed when it trips (default 5 min). */
+    readonly timeoutMs?: number;
+    /** Injectable for tests (defaults to process.platform). */
+    readonly platform?: NodeJS.Platform;
+}
+export declare const installOptionalPeers: (packages: readonly string[], opts?: InstallOptions) => Promise<void>;

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";
@@ -65,6 +65,11 @@ export interface ExplainResult {
 }
 export interface Interface {
     readonly write: (input: WriteMemoryInput) => Effect.Effect<MemoryUnit, StoreError | DuplicateActiveKey>;
+    /** Bulk write: batch insert in ONE transaction (all-or-nothing; a
+     * duplicate logical key fails the whole batch with DuplicateActiveKey).
+     * The per-write graph candidate scan is NOT part of this — pair with
+     * `updateEmbedding(..., { scanCandidates: false })` for bulk ingest. */
+    readonly writeMany: (inputs: readonly WriteMemoryInput[]) => Effect.Effect<readonly MemoryUnit[], StoreError | DuplicateActiveKey>;
     /** Upsert for the index path — the identity rule (same logical key ⇒
      * confirmed `memory_supersedes`) made reachable for ACTIVE keys: demote
      * the active holder of the key (if any), write the new unit, and link
@@ -105,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>;
@@ -115,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;
@@ -139,7 +157,23 @@ export interface Interface {
     readonly forget: (id: string) => Effect.Effect<void, NotFound | StoreError>;
     readonly sweep: (namespace: string) => Effect.Effect<SweepResult, StoreError>;
     readonly events: (memoryId: string) => Effect.Effect<readonly MemoryEvent[], StoreError>;
-    readonly updateEmbedding: (id: string, embedding: ReadonlyArray<number>, model: string) => Effect.Effect<void, NotFound | StoreError>;
+    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.7",
+  "version": "0.0.0-alpha.9",
   "private": false,
   "files": [
     "dist"