@ponraaj/dimple-sdk 0.0.0-alpha.1

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

@@ -0,0 +1,162 @@
+import { Context, Effect } from "effect";
+import type { MemoryUnit, MemoryEvent, WriteMemoryInput, SweepResult, Concept } 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";
+import type { EmbeddingModelConfig } from "./internal/config/index.js";
+import type { Topic, TopicChangeLog } from "./schema/topics.ts";
+import type { ArtifactEdge, EdgeKind, EdgeSource } from "./schema/graph.ts";
+import type { AugmentedMemory } from "./graph/retrieval-post-pass.ts";
+import type { TopicMetrics, TopicChangeLogOptions, TopicHealth } from "./topics/observability.ts";
+import type { SetActiveModelResult } from "./topics/lifecycle.ts";
+import type { GraphNeighborsOptions } from "./db-backend.ts";
+import type { EdgeNotFound, EdgeExists } from "./graph/errors.ts";
+import type { MemoryMetadata } from "./schema/metadata.ts";
+import type { GraphCandidatesOptions, GraphCandidatesResult } from "./graph/candidates.ts";
+import type { GraphCoverage } from "./graph/observability.ts";
+/** Shape of one topic-membership reference (topicMembers). */
+export interface TopicMemberRef {
+    readonly memoryId: string;
+}
+/** Aggregate tree shape (topicStats). */
+export interface TopicStats {
+    readonly depth: number;
+    readonly leafCount: number;
+    readonly internalCount: number;
+    readonly totalTopics: number;
+}
+/** Input for `Store.addEdge` — one memory↔memory edge (the only kinds
+ * the lean `artifact_edges` table holds). */
+export interface AddEdgeInput {
+    readonly fromMemoryId: string;
+    readonly toMemoryId: string;
+    readonly edgeKind: EdgeKind;
+    readonly source: EdgeSource;
+    readonly confidence?: number;
+    readonly weight?: number;
+    /** Bypass pending — for the identity rule (same logicalKey) and confirmed API writes. */
+    readonly confirmed?: boolean;
+}
+/** Options for `Store.listEdges`. Expired edges are excluded by default
+ * (soft-delete — history stays queryable via `includeExpired`). */
+export interface ListEdgesOptions {
+    /** Restrict to edges touching this memory (either endpoint). */
+    readonly memoryId?: string;
+    readonly edgeKind?: EdgeKind;
+    readonly status?: ArtifactEdge["status"];
+    readonly includeExpired?: boolean;
+}
+/** One reached node of an `explain` traversal (the other endpoint of a
+ * neighbor edge, deduplicated — first reach wins, so the shallowest depth). */
+export interface ExplainNode {
+    readonly id: string;
+    readonly kind: string;
+    readonly edgeKind: string;
+    readonly depth: number;
+}
+export interface ExplainResult {
+    readonly seed: {
+        readonly kind: string;
+        readonly id: string;
+    };
+    readonly nodes: readonly ExplainNode[];
+    /** Pending conflicts surfaced even though they are not confirmed. */
+    readonly pendingConflicts: readonly string[];
+}
+export interface Interface {
+    readonly write: (input: WriteMemoryInput) => Effect.Effect<MemoryUnit, StoreError | DuplicateActiveKey>;
+    readonly get: (id: string) => Effect.Effect<MemoryUnit, NotFound | StoreError>;
+    readonly getByKey: (key: string, namespace: string) => Effect.Effect<MemoryUnit, NotFound | StoreError>;
+    readonly recency: (namespace: string, limit: number) => Effect.Effect<ReadonlyArray<AugmentedMemory>, StoreError>;
+    readonly searchFts5: (query: string, namespace: string, limit: number, opts?: {
+        readonly topicKeys?: ReadonlyArray<string>;
+        /** `false` suppresses the per-leg audit row (fused-row callers). */
+        readonly audit?: boolean;
+    }) => Effect.Effect<ReadonlyArray<AugmentedMemory>, StoreError>;
+    readonly searchVector: (query: ReadonlyArray<number>, namespace: string, limit: number, opts?: {
+        readonly topicKeys?: ReadonlyArray<string>;
+        /** Restrict to memories annotated with ANY of these concept ids. */
+        readonly conceptIds?: ReadonlyArray<string>;
+        /** `false` suppresses the per-leg audit row (fused-row callers). */
+        readonly audit?: boolean;
+    }) => Effect.Effect<ReadonlyArray<AugmentedMemory>, StoreError>;
+    /** One fused retrieval-audit row (the hybrid path's audit contract). */
+    readonly logAudit: (input: {
+        readonly query: string;
+        readonly namespace: string;
+        readonly mode: string;
+        readonly resultCount: number;
+        readonly startTime: number;
+        readonly queryProfile?: string | null;
+        readonly sources?: string | null;
+        readonly hashSeed?: string;
+    }) => Effect.Effect<void, StoreError>;
+    readonly supersede: (key: string, namespace: string) => Effect.Effect<void, NotFound | StoreError>;
+    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 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>;
+    readonly listConcepts: () => Effect.Effect<readonly Concept[], StoreError>;
+    readonly annotateMemory: (memoryId: string, conceptId: string, confidence?: number) => Effect.Effect<void, NotFound | StoreError>;
+    readonly getMemoryAnnotations: (memoryId: string) => Effect.Effect<readonly string[], StoreError>;
+    readonly queryByMetadata: (filter: Record<string, unknown>) => Effect.Effect<readonly MemoryUnit[], StoreError>;
+    readonly getMemoryMetadata: (id: string) => Effect.Effect<MemoryMetadata | undefined, NotFound | StoreError>;
+    readonly setMemoryMetadata: (id: string, metadata: MemoryMetadata) => Effect.Effect<void, NotFound | StoreError>;
+    readonly ensureTopicTree: (modelKey: string) => Effect.Effect<{
+        rootKey: string;
+        unassignedKey: string;
+    }, TopicError | StoreError>;
+    readonly resolveTopics: (queryVector: ReadonlyArray<number>, opts?: {
+        readonly beamWidth?: number;
+    }) => Effect.Effect<readonly string[], TopicError | StoreError>;
+    readonly topicMembers: (topicKey: string) => Effect.Effect<readonly TopicMemberRef[], StoreError>;
+    readonly listTopics: (modelKey: string) => Effect.Effect<readonly Topic[], StoreError>;
+    readonly topicStats: (modelKey: string) => Effect.Effect<TopicStats, StoreError>;
+    readonly deleteTree: (modelKey: string) => Effect.Effect<void, TopicError | StoreError>;
+    readonly processSplits: (modelKey: string) => Effect.Effect<number, TopicError | StoreError>;
+    readonly mergeOrBorrow: (modelKey: string, topicKey: string) => Effect.Effect<MaintenanceOutcome, TopicError | StoreError>;
+    readonly rebalanceSiblings: (modelKey: string, topicKey: string) => Effect.Effect<RebalanceOutcome, TopicError | StoreError>;
+    readonly setActiveModel: (model: EmbeddingModelConfig) => Effect.Effect<SetActiveModelResult, TopicError | StoreError>;
+    readonly isActive: (modelKey: string) => Effect.Effect<boolean, TopicError | StoreError>;
+    readonly topicMetrics: (modelKey: string) => Effect.Effect<TopicMetrics, TopicError | StoreError>;
+    readonly topicChangeLog: (modelKey: string, opts?: TopicChangeLogOptions) => Effect.Effect<ReadonlyArray<TopicChangeLog>, TopicError | StoreError>;
+    readonly topicHealth: (modelKey: string) => Effect.Effect<TopicHealth, TopicError | StoreError>;
+    /** Insert one memory↔memory edge. A `(from, to, kind)` duplicate fails
+     * with `EdgeExists` (the composite PK). `confirmed` bypasses pending —
+     * the identity rule and explicit API writes. */
+    readonly addEdge: (input: AddEdgeInput) => Effect.Effect<ArtifactEdge, EdgeExists | StoreError | NotFound>;
+    /** Soft-delete (never a hard delete of history): sets `expired_at=now`.
+     * Expired edges are excluded from `listEdges` and traversal by default. */
+    readonly expireEdge: (id: string) => Effect.Effect<void, EdgeNotFound | StoreError>;
+    /** Promote a pending edge to confirmed. For `memory_supersedes` the OLD
+     * memory (the `from` endpoint) flips `active → superseded` in the SAME
+     * transaction (pending candidates never mutate state). */
+    readonly confirmEdge: (id: string) => Effect.Effect<void, EdgeNotFound | StoreError>;
+    readonly rejectEdge: (id: string) => Effect.Effect<void, EdgeNotFound | StoreError>;
+    readonly listEdges: (opts?: ListEdgesOptions) => Effect.Effect<readonly ArtifactEdge[], StoreError>;
+    /** The "what is near this exact artifact" API — per-hop traversal over the
+     * `graph_edges` view with caps + deterministic order, plus the seed's
+     * pending conflicts surfaced. */
+    readonly explain: (node: {
+        readonly kind: "memory" | "topic" | "concept";
+        readonly id: string;
+    }, opts?: GraphNeighborsOptions) => Effect.Effect<ExplainResult, StoreError>;
+    /** Read-only review surface for the write-path candidate rules: the
+     * newest pending `artifact_edges` rows (created_at desc, bounded —
+     * default 50) plus the isolated-memory survey (count + oldest examples:
+     * memories with no live incident edge on either endpoint). */
+    readonly graphCandidates: (opts?: GraphCandidatesOptions) => Effect.Effect<GraphCandidatesResult, StoreError>;
+    /** The artifact graph's reach over one model's memories: total active
+     * memories embedded by the model, how many have at least one live
+     * incident edge (confirmed or pending, not expired), the coverage
+     * percentage, the pending candidate backlog, concept + annotated-memory
+     * counts, and the isolated-memory count. */
+    readonly graphCoverage: (modelKey: string) => Effect.Effect<GraphCoverage, StoreError>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@dimple/store/Store", Interface>;
+export declare class Service extends Service_base {
+}
+export {};

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

@@ -0,0 +1,70 @@
+import { Config, Effect, Layer } from "effect";
+import type { Scope } from "effect/Scope";
+import type { RetrievalAuditRow } from "./models.ts";
+import { Service as DbBackend } from "./db-backend.ts";
+import { Service } from "./service.ts";
+import { StoreError } from "./error.ts";
+import { Service as ConfigService } from "./internal/config/index.js";
+import { type LogConfig, type Logging } from "./internal/logger/index.js";
+import type { EmbeddingModelConfig } from "./internal/config/index.js";
+import type { TopicConfig as TopicConfigType } from "./schema/topics.ts";
+import { GraphConfig } from "./schema/graph.ts";
+/**
+ * Topic-tree layer options. `enabled` gates the write hook only — the
+ * read-side methods (resolveTopics/topicMembers/listTopics/topicStats) are
+ * always available; the write hook routes every embedded memory into the tree
+ * and enqueues splits on overflow.
+ *
+ * `enqueueSplit` is the production-path injection seam:
+ * when set, the write hook delegates overflow to it instead of running splits
+ * inline. It receives the overflowed leaf key and the layer's model key; the
+ * app root wires it to `JobRuntime.enqueue(TopicSplit, ...)` — `@dimple/store`
+ * never imports `@dimple/workflow` (the seam is a plain effect callback). The
+ * hook may fail with any error; the store surfaces it as `StoreError`
+ * (post-commit reporting — the memory write + topic routing already
+ * committed by the time overflow fires). When unset, overflow keeps the
+ * inline `processSplits` fallback (sync convenience; production
+ * wiring always provides the seam).
+ */
+export interface StoreTopicsOptions {
+    readonly enabled?: boolean;
+    readonly config?: TopicConfigType;
+    readonly enqueueSplit?: (topicKey: string, modelKey: string) => Effect.Effect<void, unknown>;
+    /** Production-path seam for underflow maintenance (mirrors `enqueueSplit`):
+     * fires with the underfilled leaf key after a forget drops it below
+     * `minLeafItems`. The app root wires it to
+     * `JobRuntime.enqueue(TopicMerge, ...)`. When unset, the forget path runs
+     * the inline drain instead. */
+    readonly enqueueMerge?: (topicKey: string, modelKey: string) => Effect.Effect<void, unknown>;
+}
+export declare const layer: (url: string, options?: {
+    migrationFolder?: string;
+    /** Close the underlying client when the layer's scope closes (the
+     * app-root/SDK path — dispose releases the fd). Bare-store
+     * compositions leave it open (services may outlive the scope). */
+    releaseClient?: boolean;
+    embeddingModelConfig?: EmbeddingModelConfig;
+    topics?: StoreTopicsOptions;
+    graphConfig?: GraphConfig;
+    /** Retrieval-audit seam: when present, `retrieval_log` rows are
+     * enqueued as `audit.write` jobs instead of fire-and-forget inserts
+     * (the `@dimple/core` default; the query path never blocks). */
+    enqueueAudit?: (row: RetrievalAuditRow) => Effect.Effect<void, unknown>;
+    /** Structured-logging config; when present the Logging service is
+     * installed and Effect's default logger is replaced (all `Effect.log*`
+     * output flows through `@dimple/logger` per this config). */
+    logging?: LogConfig;
+    /** Default TTL for writes that omit `ttlSecs` (the config's
+     * `defaultTtlSecs`; default 604800). */
+    defaultTtlSecs?: number;
+}) => Layer.Layer<Logging | DbBackend | Service, StoreError, Scope>;
+export declare const layerConfig: (config: Config.Wrap<{
+    url: string;
+}>, options?: {
+    migrationFolder?: string;
+    embeddingModelConfig?: EmbeddingModelConfig;
+}) => Layer.Layer<Logging | DbBackend | Service, Config.ConfigError | StoreError, Scope>;
+export declare const layerFromConfig: (options?: {
+    migrationFolder?: string;
+}) => Layer.Layer<Service | DbBackend | Logging, StoreError, ConfigService | Scope>;
+export declare const loggingFromConfig: Layer.Layer<Logging, never, ConfigService | Scope>;

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

@@ -0,0 +1,39 @@
+import { Schema } from "effect";
+declare const TopicNotFound_base: Schema.Class<TopicNotFound, Schema.TaggedStruct<"topics.TopicNotFound", {
+    readonly topicKey: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Topic-tree error types. Each distinct failure mode gets its
+ * own `Schema.TaggedErrorClass` so callers can `catchTag` precisely.
+ * `TopicError` is the tagged union; individual classes are exported for
+ * pattern matching.
+ */
+/** A topic that routing/structural operations needed does not exist. */
+export declare class TopicNotFound extends TopicNotFound_base {
+}
+declare const InvariantViolation_base: Schema.Class<InvariantViolation, Schema.TaggedStruct<"topics.InvariantViolation", {
+    readonly topicKey: Schema.String;
+    readonly violations: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** A `TopicConfig` violates the structural invariants (`validateConfig`). */
+export declare class InvariantViolation extends InvariantViolation_base {
+}
+declare const ModelMismatch_base: Schema.Class<ModelMismatch, Schema.TaggedStruct<"topics.ModelMismatch", {
+    readonly expected: Schema.String;
+    readonly actual: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Two embeddings/models that must agree do not (dimension or model mismatch). */
+export declare class ModelMismatch extends ModelMismatch_base {
+}
+declare const RoutingFailure_base: Schema.Class<RoutingFailure, Schema.TaggedStruct<"topics.RoutingFailure", {
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Unexpected failure inside routing/seed — wraps the underlying cause
+ * (backend `StoreError`, driver exception, ...).
+ */
+export declare class RoutingFailure extends RoutingFailure_base {
+}
+/** Tagged union of all topic-tree errors. */
+export type TopicError = TopicNotFound | InvariantViolation | ModelMismatch | RoutingFailure;
+export {};

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

@@ -0,0 +1,24 @@
+/**
+ * Topic-tree barrel. Re-exports the pure algorithms, seeding/routing, the
+ * split job, query routing, maintenance (merge/rebalance), the multi-model
+ * lifecycle + `memory.embed` backfill handler, observability, canonical
+ * error types, and the `topics` schema tables + `TopicConfig`.
+ *
+ * The canonical error classes live in `topics/errors.ts`; the job handlers
+ * (`topicSplitHandler` / `topicMergeHandler` / `topicRebalanceHandler` /
+ * `memoryEmbedHandler`) take app-root-injected deps (see their module docs).
+ */
+export * from "./tree.ts";
+export * from "./routing.ts";
+export * from "./query.ts";
+export * from "./lifecycle.ts";
+export { memoryEmbedHandler } from "./lifecycle.ts";
+export type { MemoryEmbedHandler, MemoryEmbedHandlerDeps } from "./lifecycle.ts";
+export * from "./errors.ts";
+export { splitTopic, topicSplitHandler, shouldSplit } from "./jobs.ts";
+export type { SplitOutcome, TopicSplitHandler, TopicSplitHandlerDeps } from "./jobs.ts";
+export { mergeOrBorrow, rebalanceSiblings, topicMergeHandler, topicRebalanceHandler, } from "./maintenance.ts";
+export type { MaintenanceOutcome, RebalanceOutcome, TopicMaintenanceHandler, TopicMaintenanceHandlerDeps, } from "./maintenance.ts";
+export { topicMetrics, topicChangeLog, topicHealth } from "./observability.ts";
+export type { TopicMetrics, TopicChangeLogOptions, TopicHealth } from "./observability.ts";
+export * from "../schema/topics.ts";

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

@@ -0,0 +1,149 @@
+/**
+ * Topic-tree split job — the leaf-split store operation and its
+ * `@dimple/workflow` handler.
+ *
+ * `splitTopic` is the pure store operation: load a leaf's members + vectors,
+ * run the deterministic split plan (`tree.ts`), and materialize an accepted
+ * split in ONE transaction (child topics, per-model topic vectors, membership
+ * re-parenting, relations, growth state, change log). A rejected plan defers
+ * the split (`split_deferred` + `splitRejectedCount`); the hard-limit backstop force-
+ * splits a leaf once it exceeds `splitDeferredHardLimit`.
+ *
+ * `topicSplitHandler` wraps the operation for the frozen `topic.split` job
+ * definition (`packages/workflow/src/queue.ts`): payload `{ topicId, modelKey }`,
+ * success `Schema.Void`, error `Schema.String` (the executor maps
+ * `JobFailure.message` into the queue error channel — never wrap in
+ * `JobFailed` here).
+ *
+ * ## Errors (canonical union, topics/errors.ts)
+ *
+ * - `TopicNotFound` — the topic is missing, not a leaf, or retired (inactive).
+ * - `ModelMismatch` — the topic belongs to another model's tree.
+ * - `InvariantViolation` — the plan produced an invalid child shape; the
+ *   transaction rolls back (nothing commits).
+ * - `StoreError` — backend/persistence failures.
+ *
+ * A rejected split is a **logged outcome, not an error**: `splitTopic` returns
+ * `{ accepted: false, reason }` and the handler completes successfully.
+ *
+ * ## Determinism
+ *
+ * Child keys are content-addressable: FNV-1a 32-bit hex over `{ parent,
+ * members }` where `members` is the child's vector fingerprint in
+ * content-canonical order (`childBaseKey` below) — vectors, never memory
+ * ids, so identical embeddings yield identical keys across runs and DBs
+ * (the `-2` suffix disambiguates collisions). No randomness; ties follow
+ * `tree.ts` (smaller index). Audit timestamps come from the injectable
+ * Effect Clock (captured once per transaction, outside the closure) —
+ * observability data only, they never influence the split decision.
+ *
+ * ## Backend dependency note
+ *
+ * The split transaction writes topic-vector rows through the Drizzle `tx`
+ * handle (the backend's `upsertTopicVector` uses the standalone client and
+ * cannot join the transaction), so the per-model topic-vector table name and
+ * the `vector32`-family convert map are mirrored here from `libsql-backend.ts`
+ * (the canonical source — keep both in sync).
+ */
+import { Effect } from "effect";
+import { JobFailure, type Handler, type JobContext } from "./internal/workflow/index.js";
+import type { EmbeddingModelConfig } from "./internal/config/index.js";
+import { Service as DbBackend } from "../db-backend.ts";
+import type { Interface as DbBackendInterface } from "../db-backend.ts";
+import { StoreError } from "../error.ts";
+import type { TopicConfig } from "../schema/topics.ts";
+import type { TopicError } from "./errors.ts";
+/**
+ * Overflow predicate for the insert path (used by routing): a leaf needs a
+ * split job once its member count exceeds `maxLeafItems`.
+ */
+export declare const shouldSplit: (leafMemberCount: number, config: TopicConfig) => boolean;
+/**
+ * Result of {@link splitTopic}: an accepted split returns the two child keys
+ * and their member counts (the counts let callers detect an uneven split —
+ * e.g. the `onUnevenSplit` seam in {@link topicSplitHandler}).
+ */
+export type SplitOutcome = {
+    readonly accepted: true;
+    readonly children: readonly [string, string];
+    readonly childCounts: readonly [number, number];
+} | {
+    readonly accepted: false;
+    readonly reason: "unbalanced" | "no-improvement";
+};
+/**
+ * Deterministic 2-way split of a leaf topic.
+ *
+ * Loads the leaf + its members (sorted by `memory_id`) and their vectors,
+ * runs {@link splitPlan}, and materializes the split in one transaction:
+ * children + topic vectors + membership re-parenting + relations + growth
+ * state + change log. Rejections defer (status `split_deferred`,
+ * `splitRejectedCount` bumped, one change-log row on the 0→1 flip); the
+ * backstop force-splits past `splitDeferredHardLimit` (logged `split_forced`).
+ *
+ * Idempotency: a leaf at or below `maxLeafItems` with no pending deferral
+ * returns `{ accepted: false, reason: "no-improvement" }` without writing
+ * anything (the early no-op that keeps concurrent overflow checks harmless);
+ * an already-split parent is `TopicNotFound` (the workflow handler converts
+ * that into a stale-job success).
+ */
+export declare const splitTopic: (topicKey: string, model: EmbeddingModelConfig, config: TopicConfig) => Effect.Effect<SplitOutcome, TopicError | StoreError, DbBackend>;
+/** Dependencies for {@link topicSplitHandler}. */
+export interface TopicSplitHandlerDeps {
+    /** Resolves a model key to its config (the model registry). */
+    readonly getModelConfig: (modelKey: string) => EmbeddingModelConfig | undefined;
+    /** Tree-shape config for the split decision. */
+    readonly config: TopicConfig;
+    /**
+     * Production-path seam for sibling rebalance (mirrors `enqueueSplit`):
+     * fired after an ACCEPTED split whose two children are uneven
+     * (`max(counts) > 2 × min(counts)` — the rebalanceSiblings criterion). The
+     * app root wires this to `JobRuntime.enqueue(TopicRebalance, …)`; the
+     * rebalance job resolves the parent internally, so the child key is the
+     * right trigger. The store cannot fire this itself: the split runs
+     * asynchronously in the worker, so the post-split imbalance is only
+     * observable here.
+     */
+    readonly onUnevenSplit?: (childKey: string, modelKey: string) => Effect.Effect<void, unknown>;
+    /**
+     * Self-healing seam: fired for every child of an ACCEPTED split that is
+     * STILL over `maxLeafItems`. The app root wires this to another
+     * `topic.split` job, so a worker that lagged behind a write burst splits
+     * the overgrown leaf AND keeps re-enqueuing its over-budget children —
+     * the maintenance chain converges every leaf to the page budget (the
+     * "keep compacting on current state" rule — the write path only enqueues
+     * splits for leaves that CURRENT writes overflow, so children left over
+     * budget by a lagged split would otherwise stall forever).
+     */
+    readonly onChildOverflow?: (childKey: string, modelKey: string) => Effect.Effect<void, unknown>;
+    /**
+     * Store backend captured at registration time. Required for the standard
+     * workflow worker path: worker fibers only see services declared in the
+     * worker layer's requirements, and the JobRegistry handler type erases
+     * requirements — so the backend must be captured in the closure (the
+     * registration site is a `Layer.effect` where `yield* DbBackend` works).
+     * When omitted, the handler effect requires `DbBackend` from its own
+     * environment (direct/in-process use).
+     */
+    readonly backend?: DbBackendInterface;
+}
+/** The `topic.split` handler shape — `unknown` success like `JobRegistry.Handler`. */
+export type TopicSplitHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+/**
+ * Factory for the `topic.split` job handler.
+ *
+ * Resolves the model via `deps.getModelConfig` (missing model → `JobFailure`,
+ * which the executor maps to the queue's `Schema.String` error channel),
+ * runs {@link splitTopic}, and returns `undefined` — the definition's success
+ * schema is `Schema.Void` (the outcome lives in the DB: topics/memberships/
+ * change log, not the job result). A rejected split is a success (the deferral
+ * is the recorded outcome,).
+ *
+ * Pass `deps.backend` (captured at registration) to get a plain
+ * `JobRegistry.Handler` runnable inside the standard worker; without it the
+ * handler requires `DbBackend` from its own environment.
+ */
+export declare function topicSplitHandler(deps: TopicSplitHandlerDeps & {
+    readonly backend: DbBackendInterface;
+}): Handler;
+export declare function topicSplitHandler(deps: TopicSplitHandlerDeps): TopicSplitHandler;

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

@@ -0,0 +1,126 @@
+/**
+ * Multi-model lifecycle: `setActiveModel` + `isActive`, and the
+ * `memory.embed` backfill job handler (`memoryEmbedHandler`) that re-embeds
+ * one memory with a target model — the per-memory production path for the
+ * switch (see the switch description below).
+ *
+ * ## The invariant
+ *
+ * Routing NEVER mixes models: `routeInsert` / `resolveTopics` take an
+ * explicit model and read only that model's topic rows (`model_key` scoped)
+ * and that model's per-model vector tables (`vec_<dims>_<model>` /
+ * `topic_vec_<dims>_<model>`). Since the topic tables carry a
+ * `(topic_key, model_key)` composite PK — every model's tree has its own
+ * reserved rows, so ACTIVE and RETIRED trees coexist. "The active tree" is
+ * simply the tree whose `topics.status = 'active'` rows belong to the
+ * current model; `setActiveModel` flips statuses, nothing else.
+ *
+ * ## The switch
+ *
+ * 1. `ensureTopicTree(model, config)` — seed the new tree if absent
+ *    (idempotent, model-scoped).
+ * 2. `listMemoryIds(model)` — every memory with a vector for the NEW model,
+ *    sorted by `memory_id` (deterministic order — the task's "never iterate
+ *    unordered sets").
+ * 3. For each memory (sorted): already a member of the new model's tree →
+ *    `alreadyInTree`; otherwise fetch its vector and `routeInsert` →
+ *    `routed`. Each `routeInsert` commits in its own transaction: the batch
+ *    is per-memory-committed by design. The durable production path is the
+ *    `memory.embed` job (this module's `memoryEmbedHandler`) — the app root
+ *    enqueues one job per stale memory (via `findStale`) and the worker
+ *    re-embeds + routes each. A future batch re-route JOB with resume could
+ *    amortize the per-memory commits; the per-memory job is correct and
+ *    resumable today.
+ * 4. Deactivate every OTHER model's trees: `status = 'inactive'` where
+ *    `model_key != model.id` and not already inactive. The distinct affected
+ *    model keys are returned as `deactivated`. Growth state is NOT touched:
+ *    it is per-topic audit data (`lastSplitAt`, rejection counters, …) and
+ *    remains valid if the model is ever re-activated.
+ * 5. One change-log entry on the new tree's root (`__root__`),
+ *    operation `"activate"`, reason `{ model, deactivated }`. The entry is
+ *    written only when the activation
+ *    changed observable state (deactivated other trees or routed memories) —
+ *    a pure re-activation of the already-active model writes nothing
+ *    (idempotent, deterministic). Note: `topic_change_log` has no
+ *    `model_key` column, and the reserved root key is the same string in
+ *    every model's tree — the entry is unambiguous in practice because it is
+ *    the ONLY `activate` row for the root written by this switch, but
+ *    key-based log queries (topicChangeLog) can surface it for other models.
+ *    Documented ambiguity.
+ *
+ * ## Determinism
+ *
+ * All iteration derives from persisted state: `listMemoryIds` is ordered by
+ * `memory_id`, topic rows by `topic_key`, and the deactivation query filters
+ * on status. The audit timestamp comes from the injectable Effect Clock
+ * (observability only — never read by routing).
+ */
+import { Effect } from "effect";
+import type { EmbeddingModelConfig } from "./internal/config/index.js";
+import { Service as DbBackend } from "../db-backend.ts";
+import type { TopicConfig } from "../schema/topics.ts";
+import type { TopicError } from "./errors.ts";
+import { NotFound, StoreError } from "../error.ts";
+import { JobFailure, type Handler, type JobContext } from "./internal/workflow/index.js";
+import type { Interface as DbBackendInterface } from "../db-backend.ts";
+/** Result of {@link setActiveModel}. */
+export interface SetActiveModelResult {
+    /** Memories routed into the new model's tree by this call. */
+    readonly routed: number;
+    /** Memories already members of the new model's tree (idempotent no-ops). */
+    readonly alreadyInTree: number;
+    /** Distinct model keys whose trees this call flipped to `inactive`. */
+    readonly deactivated: readonly string[];
+}
+/**
+ * True when the model's tree has at least one active topic row — i.e. the
+ * model is the current default for routing. A model whose tree was never
+ * seeded, or whose every row was deactivated, is not active.
+ */
+export declare const isActive: (modelKey: string) => Effect.Effect<boolean, TopicError | StoreError, DbBackend>;
+/**
+ * Switch the ACTIVE tree to `model`: seed the new
+ * tree, re-route every memory that has a vector for the new model, retire
+ * every other model's trees, and record the activation in the change log.
+ *
+ * Deterministic order everywhere: `listMemoryIds` returns ids sorted by
+ * `memory_id`; the already-in-tree check is per memory, in that order;
+ * deactivation is a single status flip filtered on persisted state.
+ *
+ * Idempotent: re-activating the already-active model routes nothing
+ * (memberships exist → `alreadyInTree`), flips nothing (`deactivated` is
+ * empty), and writes no log entry.
+ */
+export declare const setActiveModel: (model: EmbeddingModelConfig, config: TopicConfig) => Effect.Effect<SetActiveModelResult, TopicError | StoreError, DbBackend>;
+/**
+ * Dependencies for {@link memoryEmbedHandler}: the app root composes the
+ * embedder registry and the store backend (the store package does not
+ * depend on `@dimple/embedder` — the handler is the wiring seam).
+ */
+export interface MemoryEmbedHandlerDeps {
+    /** Resolves a model key to its config (the model registry). */
+    readonly getModelConfig: (modelKey: string) => EmbeddingModelConfig | undefined;
+    /** Embeds one text with the TARGET model (the app root's embedder). */
+    readonly embedOne: (text: string, model: EmbeddingModelConfig) => Effect.Effect<Float32Array, unknown>;
+    /** Loads one memory's content by id (the store backend's read path).
+     * `undefined` = stale re-offer (memory gone) — the handler treats it as a
+     * success no-op. The error channel mirrors `Store.get` (`NotFound |
+     * StoreError`) so the handler can `catchTag("Store.NotFound")` cleanly. */
+    readonly getMemoryContent: (memoryId: string) => Effect.Effect<string | undefined, NotFound | StoreError>;
+    /** Tree-shape config for the routing decision. */
+    readonly config: TopicConfig;
+    /** Backend captured at registration (see {@link topicSplitHandler}). */
+    readonly backend?: DbBackendInterface;
+}
+/** The `memory.embed` handler shape (see jobs.ts). */
+export type MemoryEmbedHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+/**
+ * Factory for the `memory.embed` job handler: re-embeds one memory with the
+ * target model and routes it into that model's tree. The success schema is
+ * `Schema.Void` — the outcome lives in the DB (vector row + membership).
+ * A memory with no content is a stale re-offer → success no-op.
+ */
+export declare function memoryEmbedHandler(deps: MemoryEmbedHandlerDeps & {
+    readonly backend: DbBackendInterface;
+}): Handler;
+export declare function memoryEmbedHandler(deps: MemoryEmbedHandlerDeps): MemoryEmbedHandler;