@ponraaj/dimple-sdk 0.0.0-alpha.1

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

@@ -0,0 +1,110 @@
+/**
+ * Topic-tree maintenance jobs — underflow (merge/borrow) and sibling
+ * rebalance, the structural counterparts of `jobs.ts` splitting.
+ *
+ * ## mergeOrBorrow
+ *
+ * B-Tree deletion semantics applied to vector space: when a leaf drops
+ * below `minLeafItems`, **borrow first** (cheap, never cascades — the
+ * classic B-tree rotation: move the closest movable member from the
+ * nearest larger sibling, repeat until valid or no movable members), then
+ * **merge** (consumes the sibling; only when `mergedCount ≤ maxLeafItems`
+ * so a merge cannot immediately re-overflow into a split — the classic
+ * merge→split thrash). If neither is possible, the
+ * leaf stays underfilled (logged, status untouched) — lazy-underflow
+ * default policy, same as PostgreSQL's no-op on underflow.
+ *
+ * ## rebalanceSiblings
+ *
+ * Uneven siblings: when the largest sibling has more than `2×` the
+ * smallest, move borderline members (closer to the small centroid than
+ * the large one, `manual_lock = 0`, move preserves/improves both radii)
+ * from large to small. Gated by the growth-state cooldown
+ * (`cooldownUntil` + `rebalanceCooldownMs`) so repeated runs cannot churn.
+ *
+ * ## Determinism
+ *
+ * Same DB state + same config ⇒ identical moves: siblings sorted by
+ * `topic_key`, centroid scores tie-break lexicographically, candidate
+ * members sorted by `memory_id`, all CF math via the O(1) `cfInsert` /
+ * `cfRemove` exact updates. Audit timestamps come from the injectable
+ * Effect Clock (captured outside the tx closure) — observability only.
+ */
+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";
+/** Result of {@link mergeOrBorrow}: what the maintenance pass did. */
+export type MaintenanceOutcome = {
+    readonly action: "none";
+} | {
+    readonly action: "borrowed";
+    readonly moves: number;
+    readonly donor: string;
+} | {
+    readonly action: "merged";
+    readonly mergedInto: string;
+    readonly absorbed: string;
+} | {
+    readonly action: "underfilled";
+    readonly reason: "no-borrowable" | "merge-would-overflow" | "merge-locked";
+};
+/** Result of {@link rebalanceSiblings}. */
+export type RebalanceOutcome = {
+    readonly action: "none";
+    readonly reason: "balanced" | "cooldown" | "no-candidates";
+} | {
+    readonly action: "rebalanced";
+    readonly moves: number;
+};
+/**
+ * Underflow maintenance for one leaf: borrow from the nearest larger
+ * sibling first, else merge with the nearest sibling (only when the merge
+ * stays within `maxLeafItems`), else leave the leaf underfilled (logged).
+ * Idempotent: a leaf at or above `minLeafItems` is a no-op.
+ *
+ * Deterministic: siblings sorted by `topic_key`, nearest by centroid score
+ * (lexicographic tie-break), borrowed members chosen closest to the
+ * underfilled centroid (tie → smaller `memory_id`), `manual_lock = 1`
+ * memberships never auto-move.
+ */
+export declare const mergeOrBorrow: (topicKey: string, model: EmbeddingModelConfig, config: TopicConfig) => Effect.Effect<MaintenanceOutcome, TopicError | StoreError, DbBackend>;
+/**
+ * Rebalance uneven siblings under one parent: when the largest sibling has
+ * more than `2×` the smallest, move borderline members (closer to the small
+ * centroid, `manual_lock = 0`, move preserves/improves both weighted radii)
+ * from large to small. Cooldown-gated via growth-state `cooldownUntil`.
+ */
+export declare const rebalanceSiblings: (topicKey: string, model: EmbeddingModelConfig, config: TopicConfig) => Effect.Effect<RebalanceOutcome, TopicError | StoreError, DbBackend>;
+/** Dependencies for {@link topicMergeHandler} / {@link topicRebalanceHandler}. */
+export interface TopicMaintenanceHandlerDeps {
+    /** Resolves a model key to its config (the model registry). */
+    readonly getModelConfig: (modelKey: string) => EmbeddingModelConfig | undefined;
+    /** Tree-shape config for the maintenance decisions. */
+    readonly config: TopicConfig;
+    /** Backend captured at registration (see {@link topicSplitHandler}). */
+    readonly backend?: DbBackendInterface;
+}
+/** The `topic.merge` / `topic.rebalance` handler shape (see jobs.ts). */
+export type TopicMaintenanceHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+/**
+ * Factory for the `topic.merge` job handler: resolves the model, runs
+ * {@link mergeOrBorrow}, returns `undefined` (the definition's success
+ * schema is `Schema.Void` — the outcome lives in the DB).
+ */
+export declare function topicMergeHandler(deps: TopicMaintenanceHandlerDeps & {
+    readonly backend: DbBackendInterface;
+}): Handler;
+export declare function topicMergeHandler(deps: TopicMaintenanceHandlerDeps): TopicMaintenanceHandler;
+/**
+ * Factory for the `topic.rebalance` job handler: resolves the model, runs
+ * {@link rebalanceSiblings}, returns `undefined`.
+ */
+export declare function topicRebalanceHandler(deps: TopicMaintenanceHandlerDeps & {
+    readonly backend: DbBackendInterface;
+}): Handler;
+export declare function topicRebalanceHandler(deps: TopicMaintenanceHandlerDeps): TopicMaintenanceHandler;

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

@@ -0,0 +1,102 @@
+/**
+ * Topic-tree observability: metrics, change-log queries, and health checks.
+ *
+ * All three functions are read-only, Effect-based, take `DbBackend` from the
+ * environment, and produce deterministically ordered output (never
+ * wall-clock, never randomness):
+ *
+ * - `topicMetrics` — one-shot aggregate snapshot of a model's tree
+ *   (size, shape, overflow/deferral pressure, rejection total, last op).
+ * - `topicChangeLog` — newest-first audit trail (the append-only log is the
+ *   replay/repair source).
+ * - `topicHealth` — structural invariant sweep; violations are human-readable
+ *   strings, `warnCount` = violation count.
+ *
+ * ## Scope note
+ *
+ * `topic_change_log` has no `model_key` column (schema/topics.ts), so
+ * change-log queries scope through the model's topic keys via a subquery —
+ * the same pattern as `Store.deleteTree`.
+ *
+ * ## Complexity (current scale)
+ *
+ * - `topicMetrics`: one `topics` scan (`O(T)` rows, T = O(N/L)) + one
+ *   `topic_growth_state` aggregate + one change-log head read.
+ * - `topicHealth`: one `topics` scan + ONE grouped `topic_memberships` count
+ *   query (the current-scale equivalent of COUNT-per-topic; a production
+ *   index would maintain per-topic counts instead).
+ *
+ * ## Determinism
+ *
+ * Ordering derives from persisted state only: `leafMemberCounts` is sorted
+ * ascending, change-log rows by `id` DESC (PK order, ties impossible). No
+ * wall-clock in any ordering decision.
+ */
+import { Effect } from "effect";
+import { Service as DbBackend } from "../db-backend.ts";
+import type { TopicConfig, TopicChangeLog } from "../schema/topics.ts";
+import type { TopicError } from "./errors.ts";
+import type { StoreError } from "../error.ts";
+/** One-shot aggregate snapshot of a model's tree (see {@link topicMetrics}). */
+export interface TopicMetrics {
+    readonly totalTopics: number;
+    readonly leaves: number;
+    readonly internal: number;
+    /** Maximum `depth` over all topic rows (0 = root only). */
+    readonly depth: number;
+    /** Member counts of every leaf, sorted ascending (regardless of status). */
+    readonly leafMemberCounts: ReadonlyArray<number>;
+    /** Leaves with `memberCount > config.maxLeafItems` (split-job pressure). */
+    readonly overflowCandidates: number;
+    /** Topics with status `split_deferred` (gate rejected, awaiting backstop). */
+    readonly deferredLeaves: number;
+    /** Sum of `split_rejected_count` over the model's growth-state rows. */
+    readonly splitRejectedTotal: number;
+    /** Newest change-log entry (by id), or null when the log is empty. */
+    readonly lastOperation: {
+        readonly operation: string;
+        readonly createdAt: number;
+    } | null;
+}
+/** Options for {@link topicChangeLog}. */
+export interface TopicChangeLogOptions {
+    /** Only rows with this operation (e.g. `"split"`, `"create"`). */
+    readonly operation?: string;
+    /** Maximum rows returned, newest first (default 50). */
+    readonly limit?: number;
+}
+/** Structural health of a model's tree (see {@link topicHealth}). */
+export interface TopicHealth {
+    /** Human-readable invariant violations; empty = healthy. */
+    readonly invariantViolations: ReadonlyArray<string>;
+    /** `invariantViolations.length`. */
+    readonly warnCount: number;
+}
+/**
+ * Aggregate metrics for one model's tree. Read-only; the caller decides what
+ * to act on (repair tooling, dashboards, overflow autoscaling).
+ */
+export declare const topicMetrics: (modelKey: string, config: TopicConfig) => Effect.Effect<TopicMetrics, TopicError | StoreError, DbBackend>;
+/**
+ * Newest-first audit trail for a model's tree. Rows are ordered by `id` DESC
+ * (PK order — the append-only log's natural recency), limited to
+ * `opts.limit` (default 50), optionally filtered by `opts.operation`
+ * (exact match on the `operation` column).
+ */
+export declare const topicChangeLog: (modelKey: string, opts?: TopicChangeLogOptions) => Effect.Effect<ReadonlyArray<TopicChangeLog>, TopicError | StoreError, DbBackend>;
+/**
+ * Structural invariant sweep for one model's tree. Reports every violation as
+ * a human-readable string; an empty `invariantViolations` means healthy.
+ *
+ * Checks:
+ * 1. Every leaf `memberCount <= maxLeafItems + slack`, where
+ *    `slack = max(2, ceil(splitDeferredHardLimit / 2) − maxLeafItems)` — the
+ *    same allowance the split acceptance gate grants a forced split's child.
+ * 2. Every internal topic has `childCount >= 2`. The reserved `__root__`
+ *    anchor is exempt: it is seeded with `childCount 0` and routing/split
+ *    never maintain it (the root's child set lives in `topic_relations`).
+ * 3. Leaf `memberCount` agrees with the actual `topic_memberships` row count
+ *    (one grouped COUNT query — the current-scale stand-in for a
+ *    maintained per-topic counter).
+ */
+export declare const topicHealth: (modelKey: string, config: TopicConfig) => Effect.Effect<TopicHealth, TopicError | StoreError, DbBackend>;

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

@@ -0,0 +1,43 @@
+/**
+ * Deterministic query routing: leaf selection for topic-scoped retrieval.
+ *
+ * Beam descent from `__root__`: at each level score the children of the
+ * current frontier, keep the top-`k` (`k = opts.beamWidth ?? config.beamWidth`,
+ * default 3), descend. Stops when the whole frontier is leaves. An empty
+ * result means the tree has no leaves (immature or corrupt) — the caller
+ * falls back to an unscoped search.
+ *
+ * ## Determinism
+ *
+ * - Topic rows are ordered by `topic_key` asc; children are sorted by
+ *   `topic_key` asc; topic vectors come from `fetchTopicVectors` (ordered by
+ *   `topic_key` asc).
+ * - `scoreChildren` breaks score ties to the smaller index, which IS the
+ *   lexicographic tie-break (same argument as `routing.ts`).
+ * - No randomness, no wall-clock timestamps, no unordered iteration. Same DB
+ *   state + same query ⇒ identical leaf keys.
+ *
+ * ## Complexity
+ *
+ * `O(D·B·C·d)` (D = maxDepth, B = beamWidth, C = children per node) plus one
+ * bounded read of the model's topics rows, relations and centroids. Final
+ * ranking still runs in libSQL (`vectorSearch` with `topic_key IN (...)`).
+ */
+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 type { StoreError } from "../error.ts";
+/** Options for {@link resolveTopics}. */
+export interface ResolveTopicsOptions {
+    /** Number of children kept per level (default: `config.beamWidth`). */
+    readonly beamWidth?: number;
+}
+/**
+ * Resolve the leaf topics a query should search: `readonly string[]` of
+ * `topic_key`s, ordered by score (descending; ties lexicographic). An empty
+ * array means the tree has no leaves — the caller falls back to an unscoped
+ * search.
+ */
+export declare const resolveTopics: (queryVector: ReadonlyArray<number>, model: EmbeddingModelConfig, config: TopicConfig, opts?: ResolveTopicsOptions) => Effect.Effect<ReadonlyArray<string>, TopicError | StoreError, DbBackend>;

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

@@ -0,0 +1,90 @@
+/**
+ * Deterministic topic-tree seeding + insert routing.
+ *
+ * ## Contracts
+ *
+ * - `ensureTopicTree` is an idempotent seed: creates the two reserved topics
+ *   (`__root__` internal, `__unassigned_active__` leaf), their `parent_child`
+ *   relation, growth-state rows and exactly one `create` change-log entry —
+ *   all in one transaction, scoped by `model_key` (every model's
+ *   tree has its own reserved rows — identity is the `(topic_key, model_key)`
+ *   composite PK). Reserved keys sort before any `t_<hash>` key
+ *   lexicographically (`_` = 0x5F < `t` = 0x74), which the descent relies on
+ *   for stable tie-breaking.
+ * - `routeInsert` runs its Drizzle writes (membership insert, leaf CF, ancestor
+ *   CF) in ONE transaction; the derived sum-vector upserts run immediately
+ *   after commit (the backend is not transaction-aware — see below). It never
+ *   writes change-log entries (only structural operations do).
+ * - Determinism: given the same DB state, the same `(memoryId, vector, model,
+ *   config)` always lands in the same leaf. Children are sorted by
+ *   `topic_key` and score ties break lexicographically (smaller key wins).
+ *   No randomness,
+ *   no insertion-order-dependent structure. Audit
+ *   timestamps (`created_at`/`updated_at`) come from the injectable Effect
+ *   Clock — they are observability data only and never influence routing.
+ *
+ * ## Transactions vs the backend (documented limitation)
+ *
+ * `upsertTopicVector` / `fetchTopicVectors` are DbBackend raw-SQL calls on the
+ * client connection, NOT transaction-aware. Drizzle's libsql transaction runs
+ * on a **separate connection** (`client.transaction()`), so calling them
+ * inside the tx callback fails with `SQLITE_BUSY`. The code therefore
+ * keeps every Drizzle write (membership + `topics` CF rows) in the single
+ * transaction and runs the vector-table upserts immediately AFTER commit.
+ * Consequence: the derived sum vectors are eventually consistent with the
+ * strictly-consistent membership — a crash between commit and upsert
+ * leaves a stale centroid, never an orphaned membership. Single-writer local
+ * file DB, so the pre-tx read set is stable; if the backend grows
+ * transaction-aware vector methods, move the upserts onto the tx.
+ */
+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 type { StoreError } from "../error.ts";
+/** Reserved tree root — internal router, depth 0. */
+export declare const ROOT_TOPIC_KEY = "__root__";
+/** Reserved overflow/seed leaf under the root — depth 1. */
+export declare const UNASSIGNED_ACTIVE_TOPIC_KEY = "__unassigned_active__";
+/**
+ * Idempotent tree seed. If the model's `__root__` exists the tree is already
+ * seeded and this is a no-op (the existence check runs INSIDE the transaction
+ * and is scoped by `model_key` — (multi-model) the reserved keys are the same
+ * strings in every model's tree, and the `(topic_key, model_key)` composite PK
+ * is what separates them; two concurrent seeds of the same model cannot
+ * double-insert). Otherwise one transaction creates:
+ * `__root__` (internal, depth 0), `__unassigned_active__` (leaf, depth 1,
+ * `parent_child` under root), growth-state rows for both, and one `create`
+ * change-log entry.
+ *
+ * Also ensures the per-model topic vector table exists (idempotent
+ * `CREATE TABLE IF NOT EXISTS`) — `routeInsert` upserts into it, so the seed
+ * is the natural lifecycle point.
+ */
+export declare const ensureTopicTree: (model: EmbeddingModelConfig, config: TopicConfig) => Effect.Effect<{
+    rootKey: string;
+    unassignedKey: string;
+}, TopicError | StoreError, DbBackend>;
+/**
+ * Route one memory (its embedding `vector`) into the model's tree and update
+ * the affected CF-triplets:
+ *
+ * 1. Route: greedy descent from `__root__` through the best child centroid,
+ *    capped at `maxDepth` (lexicographic tie-break).
+ * 2. ONE transaction: insert the `topic_memberships` row, update the leaf CF
+ *    (`memberCount + 1`, `sumSquares += x·x`, sum vector `+= x` — O(1) exact
+ *    via `cfInsert`), and walk the ancestors (`memberCount + 1`, sum vector
+ *    `+= x` per level — exact O(depth · d)).
+ * 3. After commit: write the derived sum vectors to the per-model topic vector
+ *    table (backend upserts — see module docs).
+ * 4. `overflow = memberCount > maxLeafItems` after the update (the caller
+ *    decides whether to enqueue a structural job).
+ *
+ * Deterministic given the same DB state (see module docs). Does NOT write
+ * change-log entries — only structural operations do.
+ */
+export declare const routeInsert: (memoryId: string, vector: ReadonlyArray<number>, model: EmbeddingModelConfig, config: TopicConfig) => Effect.Effect<{
+    topicKey: string;
+    overflow: boolean;
+}, TopicError | StoreError, DbBackend>;

package/dist/internal/store/topics/topic-vectors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared topic-vector-table helpers for the structural jobs (split, merge,
+ * borrow, rebalance). The per-model `topic_vec_<dims>_<model>` tables are
+ * dynamic (not Drizzle tables), so every writer goes through this raw-SQL
+ * helper — one canonical place for the table name + conversion function.
+ */
+import type { EmbeddingModelConfig } from "./internal/config/index.js";
+import { type SQLWrapper } from "drizzle-orm";
+/** Per-model topic vector table name (mirrors libsql-backend.ts — canonical). */
+export declare const topicVectorTableName: (model: EmbeddingModelConfig) => string;
+/** vectorType → libSQL conversion function for the sum-vector column. */
+export declare const VECTOR_CONVERT_FNS: Readonly<Record<string, string>>;
+/** Anything with a `.run(sql)` — a Drizzle tx or the db handle. */
+export interface SqlRunner {
+    readonly run: (query: string | SQLWrapper<unknown>) => unknown;
+}
+/** Delete one topic's sum-vector row (merge absorbs the sibling's row). */
+export declare const deleteTopicVectorRow: (runner: SqlRunner, model: EmbeddingModelConfig, topicKey: string) => Promise<void>;
+/**
+ * Upsert one topic's sum vector. `ls` is the CF-triplet LS (sum of member
+ * vectors) as a plain Float32Array. Works inside a transaction (structural
+ * ops) or directly on the db handle (repair paths).
+ */
+export declare const writeTopicVector: (runner: SqlRunner, model: EmbeddingModelConfig, topicKey: string, ls: Float32Array) => Promise<void>;

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

@@ -0,0 +1,181 @@
+/**
+ * Pure, deterministic topic-tree algorithms.
+ *
+ * All functions in this module are synchronous, side-effect free, and never
+ * mutate their inputs. They operate on plain `Float32Array` vectors.
+ *
+ * ## Invariant: vectors are L2-normalized
+ *
+ * The embedder normalizes every vector (`transformers.js`, `normalize: true`),
+ * so for every stored vector `||x|| = 1` (or the zero vector, in degenerate
+ * cases). Consequently **cosine similarity equals the dot product**, and all
+ * similarity comparisons in this module are plain dot products. A zero vector
+ * behaves as a "neutral" item: its dot product with anything is `0`.
+ *
+ * ## Determinism contract
+ *
+ * - No randomness, no wall-clock timestamps, no insertion-order-dependent
+ *   structure.
+ * - Ties always break to the SMALLER index (farthest-pair candidate, group
+ *   assignment, child ranking).
+ * - Same input + same config ⇒ bit-identical output.
+ *
+ * ## Complexity
+ *
+ * `n` = vectors in a leaf (bounded by `maxLeafItems` / split-deferred hard
+ * limit), `d` = embedding dimensions. Split machinery is `O(passes · n · d)`
+ * with `n ≤ 512`.
+ */
+import type { TopicConfig } from "../schema/topics.ts";
+/**
+ * BIRCH CF-triplet: sufficient statistics of a vector set.
+ * `count` = N, `ls` = sum vector, `ss` = sum of squared norms.
+ * Supports O(1) exact insert/remove and closed-form centroid/radius — no
+ * vector scans for aggregates.
+ */
+export interface CfTriplet {
+    readonly count: number;
+    readonly ls: Float32Array;
+    readonly ss: number;
+}
+/**
+ * Build the CF-triplet of a vector set. All vectors must share one length;
+ * an empty input yields a zero-dimension triplet (`count = 0`).
+ */
+export declare const cfFromVectors: (vectors: readonly Float32Array[]) => CfTriplet;
+/**
+ * O(1) exact insert of vector `x` into a CF-triplet. Returns a new triplet;
+ * neither input is mutated.
+ */
+export declare const cfInsert: (cf: CfTriplet, x: Float32Array) => CfTriplet;
+/**
+ * O(1) exact removal of vector `x` from a CF-triplet. `count` clamps at 0 and
+ * `ss` clamps at 0 (float subtraction can round slightly below). Returns a
+ * new triplet; neither input is mutated.
+ */
+export declare const cfRemove: (cf: CfTriplet, x: Float32Array) => CfTriplet;
+/**
+ * Centroid (mean vector) of a CF-triplet: `ls / count`. An empty triplet
+ * (`count = 0`) yields the zero vector of the same dimension.
+ */
+export declare const centroidOf: (cf: CfTriplet) => Float32Array;
+/**
+ * RMS radius of a CF-triplet: `sqrt(max(ss/count - |mean|^2, 0))` — the
+ * exact root-mean-square deviation of members from the centroid, computed
+ * from the CF alone (no vector scan). Empty triplet ⇒ `0`.
+ */
+export declare const radiusOf: (cf: CfTriplet) => number;
+/**
+ * BIRCH-style weighted radius of a CF-triplet: `ss - |ls|^2 / count`, the
+ * sum of squared deviations from the centroid, exact from the CF alone.
+ * By the variance decomposition this equals the parent's weighted radius
+ * minus the between-group term for any two-group partition — the quantity
+ * Lloyd refinement monotonically decreases (exact arithmetic; float32
+ * accumulation noise is < 1e-3 relative). Empty triplet ⇒ `0`.
+ */
+export declare const weightedRadiusOf: (cf: CfTriplet) => number;
+/**
+ * Content-canonical permutation of `vectors`: indices sorted by
+ * lexicographic coordinate order (stable — equal vectors keep input order).
+ * `sorted[i] = vectors[order[i]!]`. The whole split pipeline runs on the
+ * canonical order so its output is a function of the vector SET, not of the
+ * caller's array order (random UUID-ordered memberships must not change the
+ * tree shape — the benchmark flake root cause).
+ */
+export declare const canonicalOrder: (vectors: readonly Float32Array[]) => readonly number[];
+/**
+ * Deterministic farthest-first seed pair: `a = 0` (first vector of the
+ * CANONICAL order — callers must sort via {@link canonicalOrder} first),
+ * then `b` = the vector with the lowest dot product against `a` (farthest
+ * under the normalized-vector invariant). Ties break to the smaller index.
+ * For fewer than 2 vectors returns `{ a: 0, b: 0 }` (degenerate — callers
+ * guard on counts before splitting). Never mutates input.
+ */
+export declare const farthestPair: (vectors: readonly Float32Array[]) => {
+    a: number;
+    b: number;
+};
+/**
+ * Assign every vector to group 0 or 1 by higher dot product against the
+ * seed vectors at `seedA` / `seedB`; ties go to group 0 (smaller index).
+ * Returns a fresh `Uint8Array` (`0` = closer to `seedA`, `1` = closer to
+ * `seedB`). Never mutates inputs.
+ */
+export declare const assignNearest: (vectors: readonly Float32Array[], seedA: number, seedB: number) => Uint8Array;
+/**
+ * Deterministic Lloyd refinement: recompute each group's centroid, reassign
+ * every vector to the group with the higher dot product (tie ⇒ smaller group
+ * index, i.e. 0), repeat for `passes` iterations. Stops early at a fixpoint —
+ * further passes are no-ops, so the result is identical either way. Returns
+ * the final groups plus both group CF-triplets.
+ *
+ * Monotone: the sum of weighted radii never increases in exact arithmetic.
+ * Comparisons use the float64 division of the float32-accumulated sum
+ * `ls / count` (not the float32-rounded {@link centroidOf}) so that each
+ * reassignment is a true SSE minimization — the classic Lloyd chain
+ * `WR(new) ≤ WR(new, μ_old) ≤ WR(old)` holds in float64. The contract-mandated
+ * float32 `ls` accumulation perturbs the *measured* WR by < 1e-3 relative
+ * (empirically ≤ 5e-4 over 2000 seeds).
+ *
+ * Never mutates inputs.
+ */
+export declare const lloydRefine: (vectors: readonly Float32Array[], groups: Uint8Array, passes: number) => {
+    groups: Uint8Array;
+    leftCf: CfTriplet;
+    rightCf: CfTriplet;
+};
+/** Outcome of {@link splitPlan} — accepted splits plus the acceptance gate diagnostics. */
+export interface SplitPlanResult {
+    readonly accepted: boolean;
+    readonly reason: "ok" | "unbalanced" | "no-improvement";
+    readonly groups: Uint8Array;
+    readonly leftCount: number;
+    readonly rightCount: number;
+    readonly leftWeightedRadius: number;
+    readonly rightWeightedRadius: number;
+    readonly parentWeightedRadius: number;
+}
+/**
+ * Deterministic 2-way split plan for one leaf: content-canonical ordering →
+ * farthest-pair seeds → nearest-seed assignment → Lloyd refinement
+ * (`config.lloydPasses` passes). Accepted iff both child counts reach
+ * `config.minLeafItems` AND the summed child weighted radii are strictly
+ * below the parent's (a non-degenerate split strictly reduces weighted
+ * radius by the between-group term `(n₁n₂/n)·|μ₁−μ₂|²`; equality —
+ * "no-improvement" — means the centroids coincide). Reason precedence:
+ * `"unbalanced"` (count gate) before `"no-improvement"` (radius gate).
+ *
+ * ## Determinism (v3)
+ *
+ * The pipeline first reorders the input via {@link canonicalOrder}, so the
+ * returned plan is a function of the vector SET only — never of the
+ * caller's array order. `groups` is un-permuted back to the CALLER's index
+ * space before returning (index `i` corresponds to `vectors[i]`), so
+ * callers map group assignments straight onto their own member ids.
+ *
+ * Remaining order-dependence: bit-identical vectors keep their input
+ * relative order (stable sort) and always score equally, so they land in
+ * the same group; only the float32 accumulation inside `cfOfGroup` can
+ * round differently for them (≤ 1 ulp on `ls`) — it cannot flip a distinct
+ * vector's assignment unless that vector is itself within 1 ulp of a tie.
+ *
+ * Never mutates inputs.
+ */
+export declare const splitPlan: (vectors: readonly Float32Array[], config: TopicConfig) => SplitPlanResult;
+/**
+ * Score child centroids against a query vector: dot products, sorted
+ * descending; ties break to the smaller index. Returns a fresh array of
+ * `{ index, score }` pairs (index = position in `centroids`). Never mutates
+ * inputs.
+ */
+export declare const scoreChildren: (centroids: readonly Float32Array[], query: Float32Array) => Array<{
+    index: number;
+    score: number;
+}>;
+/**
+ * Validate a `TopicConfig` against the structural invariants of the tree.
+ * Returns an array of violation strings (empty when valid). Warnings — such
+ * as `minLeafItems * 2 > maxLeafItems`, which makes splits unsatisfiable at
+ * a full leaf — are included so callers can log them without failing.
+ */
+export declare const validateConfig: (config: TopicConfig) => ReadonlyArray<string>;

package/dist/internal/wasm/grammar-store.d.ts

@@ -0,0 +1,14 @@
+import { Context, Effect, Layer } from "effect";
+import { GrammarProvisionError } from "@dimple/shared/errors";
+import { Service as TreeSitterRegistry } from "./wasm-registry";
+import { Service as WasmDownloader } from "./wasm-downloader";
+import { Service as WasmCache } from "./wasm-cache";
+export interface Interface {
+    readonly ensure: (lang: string) => Effect.Effect<string, GrammarProvisionError>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@dimple/wasm/GrammarStore", Interface>;
+export declare class Service extends Service_base {
+}
+export declare const layer: Layer.Layer<Service, never, TreeSitterRegistry | WasmDownloader | WasmCache>;
+export declare const allLive: Layer.Layer<TreeSitterRegistry | WasmDownloader | WasmCache | Service, never, never>;
+export {};

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

@@ -0,0 +1,5 @@
+export { Service as TreeSitterRegistry } from "./wasm-registry";
+export type { GrammarMetaData } from "./wasm-registry";
+export { Service as WasmDownloader } from "./wasm-downloader";
+export { Service as WasmCache, layer as wasmCacheLayer } from "./wasm-cache";
+export { Service as GrammarStore, layer as grammarStoreLayer, allLive as GrammarStoreAllLive, } from "./grammar-store";

package/dist/internal/wasm/wasm-cache.d.ts

@@ -0,0 +1,17 @@
+import { Context, Effect, Layer } from "effect";
+import { WasmCacheError } from "@dimple/shared/errors";
+/**
+ * Grammar WASM cache — downloads are staged to a temp file and renamed
+ * into place (an interrupted download never leaves a corrupt parser).
+ * Plain `node:fs` (NOT @effect/platform-bun): the bundled SDK runs on
+ * Node too (the CLI's shebang spawns node), so Bun-specific filesystem
+ * layers are off the table.
+ */
+export interface Interface {
+    readonly ensure: (lang: string, version: string, download: Effect.Effect<Uint8Array>) => Effect.Effect<string, WasmCacheError>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@dimple/wasm/WasmCache", Interface>;
+export declare class Service extends Service_base {
+}
+export declare const layer: Layer.Layer<Service, never, never>;
+export {};

package/dist/internal/wasm/wasm-downloader.d.ts

@@ -0,0 +1,10 @@
+import { Context, Effect, Layer } from "effect";
+import { WasmDownloadError } from "@dimple/shared/errors";
+export interface Interface {
+    readonly download: (url: string) => Effect.Effect<Uint8Array, WasmDownloadError>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@dimple/wasm/WasmDownloader", Interface>;
+export declare class Service extends Service_base {
+    static readonly layer: Layer.Layer<Service, never, never>;
+}
+export {};

package/dist/internal/wasm/wasm-registry.d.ts

@@ -0,0 +1,16 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import { RegistryError } from "@dimple/shared/errors";
+declare const GrammarMetaDataSchema: Schema.Struct<{
+    readonly lang: Schema.String;
+    readonly version: Schema.String;
+    readonly url: Schema.String;
+}>;
+export type GrammarMetaData = typeof GrammarMetaDataSchema.Type;
+export interface Interface {
+    readonly resolve: (lang: string) => Effect.Effect<GrammarMetaData, RegistryError>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@dimple/wasm/TreeSitterRegistry", Interface>;
+export declare class Service extends Service_base {
+    static readonly layer: Layer.Layer<Service, never, never>;
+}
+export {};

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

@@ -0,0 +1,39 @@
+/**
+ * Job runtime configuration — the `jobs` section of `dimple.jsonc`.
+ *
+ * All fields optional; `resolveJobsConfig` fills the documented defaults.
+ * Consumed by the deployment wiring (executor mode selection, worker
+ * concurrency, queue lease/attempt tuning) — the facade itself reads its
+ * options from the layer composition, not from this schema.
+ */
+import { Schema } from "effect";
+export declare const JobsConfig: Schema.Struct<{
+    /** libSQL URL for the dedicated jobs database. */
+    readonly dbUrl: Schema.optional<Schema.String>;
+    /** `background` (worker layers) | `inline` (submit-scope worker) | `external` (cron drain).
+     * RESERVED: the core composition currently installs background workers
+     * only (the config package parses it but nothing switches on it yet). */
+    readonly execution: Schema.optional<Schema.Literals<readonly ["background", "inline", "external"]>>;
+    /** Worker concurrency per queue. */
+    readonly concurrency: Schema.optional<Schema.Number>;
+    /** Queue item lease duration in ms (→ `PersistedQueue` `lockExpiration`).
+     * RESERVED: not yet wired to the executor. */
+    readonly leaseTimeoutMs: Schema.optional<Schema.Number>;
+    /** Max attempts per queue item before it is dropped (→ `take maxAttempts`). */
+    readonly maxAttempts: Schema.optional<Schema.refine<number, Schema.Number>>;
+    /** External-drain poll window hint in ms. RESERVED: not yet wired. */
+    readonly pollIntervalMs: Schema.optional<Schema.Number>;
+}>;
+export interface JobsConfig extends Schema.Schema.Type<typeof JobsConfig> {
+}
+/** Documented defaults — the source of truth for `resolveJobsConfig`. */
+export declare const JobsConfigDefaults: {
+    dbUrl: string;
+    execution: "background";
+    concurrency: number;
+    leaseTimeoutMs: number;
+    maxAttempts: number;
+    pollIntervalMs: number;
+};
+/** Fills every optional field with its documented default. */
+export declare const resolveJobsConfig: (config: JobsConfig) => Required<JobsConfig>;