@ponraaj/dimple-sdk 0.0.0-alpha.1

package/dist/internal/store/generated-migrations.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GENERATED — do not edit by hand. Run `bun run scripts/generate-migrations.ts`
+ * after changing packages/store/drizzle. The migration SQL is compiled into
+ * the bundle (opencode's migrations-as-code pattern): runtime migrations
+ * never read a folder from disk.
+ */
+export interface EmbeddedMigration {
+    readonly name: string;
+    /** sha256 of the SQL — identical to drizzle-kit's journal hashes, so
+     * databases migrated by the folder-based runner skip already-applied
+     * entries and new inserts stay journal-compatible. */
+    readonly hash: string;
+    readonly sql: string;
+}
+export declare const EMBEDDED_MIGRATIONS: readonly EmbeddedMigration[];

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

@@ -0,0 +1,93 @@
+/**
+ * Write-path edge candidates — the pure, deterministic rules that scan a
+ * routed topic leaf after a memory's embedding lands and propose
+ * `artifact_edges` rows.
+ *
+ * No Effect, no DB: the store loads the leaf members and this module
+ * decides. Every rule is a pure function of the inputs (plus the conflict
+ * bands), and the output is deterministic — members are sorted by memory
+ * id and each member yields at MOST ONE candidate (the strongest
+ * applicable rule wins).
+ *
+ * ## Rules (per leaf member, evaluated in priority order)
+ *
+ * 1. Identity — the member has the same logical key as the new memory:
+ *    CONFIRMED `memory_supersedes` (confidence 0.5). Same-key memories are
+ *    the same logical artifact, so the newer one wins immediately; the
+ *    store flips the old memory to `superseded` in the same transaction as
+ *    the edge insert. Pending candidates never mutate state — this rule is
+ *    the one exception because the key match is exact, not a similarity
+ *    guess.
+ * 2. Near-duplicate — cosine similarity above the `nearDuplicate` band
+ *    edge: PENDING `memory_supersedes` (confidence = raw cosine). Waits
+ *    for confirmation; a false positive is rejected, never harmful.
+ * 3. Conflict band — cosine inside `(conflictLow, nearDuplicate]` AND the
+ *    two memories are related (same logical-key family — version-suffixed
+ *    variants of one key — or a shared metadata `topics` tag): PENDING
+ *    `memory_contradicts` (confidence = raw cosine). The metadata blob is
+ *    parsed defensively — a malformed blob matches nothing.
+ *
+ * Direction is canonical: the OLDER memory (by `createdAt`; a timestamp
+ * tie keeps the existing member, so the just-written memory never flips
+ * itself) is `fromMemoryId` — the endpoint confirmation supersedes — and
+ * the newer one is `toMemoryId`.
+ */
+import type { EdgeKind, EdgeSource } from "../schema/graph.ts";
+/** One leaf member as seen by the candidate rules. */
+export interface CandidateMember {
+    readonly id: string;
+    readonly vector: Float32Array;
+    readonly createdAt: number;
+    readonly logicalKey?: string;
+    readonly metadata?: string | null;
+}
+/** Which rule produced a candidate (the provenance on `EdgeCandidate`). */
+export type CandidateKind = "near-duplicate" | "conflict-band" | "identity";
+/** One rule-derived edge proposal from `leafLocalCandidates`. */
+export interface EdgeCandidate {
+    readonly fromMemoryId: string;
+    readonly toMemoryId: string;
+    readonly edgeKind: "memory_supersedes" | "memory_contradicts";
+    readonly source: "rule";
+    readonly status: "pending" | "confirmed";
+    readonly confidence: number;
+    readonly reason: CandidateKind;
+}
+/** One pending candidate surfaced by `Store.graphCandidates` (an
+ * `artifact_edges` row — the status is `pending` by construction). */
+export interface EdgeCandidateInfo {
+    readonly id: string;
+    readonly fromMemoryId: string;
+    readonly toMemoryId: string;
+    readonly edgeKind: EdgeKind;
+    readonly source: EdgeSource;
+    readonly confidence: number | null;
+    readonly createdAt: number;
+}
+/** One isolated memory (no live incident edge on either endpoint). */
+export interface IsolatedMemory {
+    readonly id: string;
+    readonly createdAt: number;
+}
+/** `Store.graphCandidates` result: the newest pending candidates plus the
+ * isolated-memory survey (count + oldest examples). */
+export interface GraphCandidatesResult {
+    readonly pending: readonly EdgeCandidateInfo[];
+    readonly isolatedCount: number;
+    readonly oldestIsolated: readonly IsolatedMemory[];
+}
+/** Options for `Store.graphCandidates`. */
+export interface GraphCandidatesOptions {
+    /** Max pending candidates returned (clamped to [1, 200]; default 50). */
+    readonly limit?: number;
+}
+/**
+ * The leaf-local candidate scan: compare the new memory against its
+ * leaf-mates (per the module rules) and return at most one candidate per
+ * member, in member-id order (deterministic — the input order is
+ * irrelevant). The new memory itself is never a candidate target.
+ */
+export declare const leafLocalCandidates: (newId: string, newVector: Float32Array, newCreatedAt: number, newLogicalKey: string | undefined, newMetadata: string | null | undefined, members: readonly CandidateMember[], bands: {
+    readonly nearDuplicate: number;
+    readonly conflictLow: number;
+}) => readonly EdgeCandidate[];

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

@@ -0,0 +1,169 @@
+/**
+ * Inductive concept clustering — k-means over memory embeddings, plus the
+ * `concept.cluster` job handler that materializes concepts + annotations.
+ *
+ * ## The clustering pipeline
+ *
+ * The pure core is a deterministic k-means (>2 groups) over L2-normalized
+ * vectors, built from the same primitives as the topic-tree splitter
+ * (`topics/tree.ts` — never modified):
+ *
+ *   1. `farthestPointSeeds` — farthest-first seeding: the first two seeds
+ *      are the farthest pair, each next seed is the vector farthest from
+ *      its nearest existing seed.
+ *   2. `kGroupLloyd` — nearest-centroid assignment + centroid recomputation,
+ *      iterated for a fixed number of passes or until a fixpoint.
+ *   3. `clusterMembers` — the full pipeline on the content-canonical order
+ *      (see `canonicalOrder`), so the result is a function of the vector
+ *      SET, never of the caller's array order. Group assignments are
+ *      un-permuted back to the caller's index space.
+ *
+ * A surviving cluster (≥ `clusterMinSize` members) becomes one concept row:
+ * content-addressed id `concept_<fnv1a32 of the centroid's floats>`, null
+ * name (inductive clusters are anonymous — the name column is nullable), the
+ * centroid as embedding, and one `memory_concepts` row per member with
+ * confidence = cosine similarity to the centroid.
+ *
+ * ## Determinism
+ *
+ * Same DB state + same config ⇒ identical clusters: canonical ordering,
+ * index tie-breaks (smaller wins) everywhere, float32 accumulation in
+ * canonical order, ids hashed from centroid floats only. Audit timestamps
+ * come from the injectable Effect Clock (observability only).
+ *
+ * ## Dimension assumption
+ *
+ * The prototype assumes the ACTIVE model is 384-dimensional: the
+ * `concepts.embedding` column is a fixed `F32_BLOB(384)`, so centroids from
+ * any other dimension cannot be stored. Cluster jobs are only safe while
+ * the active model stays 384-dim.
+ */
+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 { GraphConfig } from "../schema/graph.ts";
+/**
+ * Deterministic farthest-first seeding for k groups.
+ *
+ * The first two seeds are `farthestPair`'s result (its contract: `a = 0` is
+ * the first vector — callers must pass the CONTENT-CANONICAL order, exactly
+ * as `splitPlan` does). Each next seed is the unchosen vector whose minimum
+ * dot product against the existing seeds is smallest — the vector farthest
+ * from its nearest seed under the normalized-vector invariant. Ties break to
+ * the smaller index; already-chosen indices are never re-picked (a seed is
+ * distance 0 from itself, so without the exclusion the tie-break could
+ * return a seed).
+ *
+ * `k` clamps to the vector count (an empty input yields `[]`); fewer than 2
+ * vectors yield the degenerate `[0]` / `[a, b]` forms of `farthestPair`.
+ * Never mutates inputs.
+ */
+export declare const farthestPointSeeds: (vectors: readonly Float32Array[], k: number) => readonly number[];
+/**
+ * Deterministic k-group Lloyd refinement: assign every vector to the group
+ * with the highest dot product against the group's centroid (initial seeds,
+ * then recomputed means), iterating for `passes` iterations. Ties go to the
+ * smaller GROUP index (position in `seeds`). Stops early at a fixpoint —
+ * further passes are no-ops, so the result is identical either way.
+ *
+ * Centroid math follows `tree.ts`'s `lloydRefine`: group CF-triplets via
+ * `cfFromVectors`, float64 `dot(x, ls) / count` scoring for reassignment,
+ * float32 `centroidOf` for the reported centroids. Empty groups score 0 and
+ * stay empty (their centroid is the zero vector).
+ *
+ * Never mutates inputs. `seeds` holds indices into `vectors` (the seed
+ * vectors themselves — the initial assignment is nearest-seed, not
+ * seed-region).
+ */
+export declare const kGroupLloyd: (vectors: readonly Float32Array[], seeds: readonly number[], passes: number) => {
+    groups: Uint32Array;
+    centroids: readonly Float32Array[];
+};
+/** Result of {@link clusterMembers}: per-vector group assignment + centroids. */
+export interface ClusterResult {
+    /** `groups[i]` = the group of `vectors[i]` (caller index space). */
+    readonly groups: Uint32Array;
+    /** One centroid per group, in group-index order. */
+    readonly centroids: readonly Float32Array[];
+}
+/**
+ * Deterministic k-means over one vector set. Runs the whole pipeline on the
+ * content-canonical order (mirroring `splitPlan`'s v3 determinism): canonical
+ * permutation → farthest-first seeds → k-group Lloyd → un-permute the
+ * assignment back to the caller's index space. `k` clamps to the vector
+ * count. The result is a function of the vector SET — never of the caller's
+ * array order. Never mutates inputs.
+ */
+export declare const clusterMembers: (vectors: readonly Float32Array[], k: number, passes: number) => ClusterResult;
+/**
+ * Content-addressed concept id: `concept_` + FNV-1a 32-bit hex over the
+ * JSON of the centroid's float32 values. The centroid is computed on the
+ * canonical order, so identical embeddings yield identical ids across runs
+ * and DBs (a hash collision merges two clusters into one concept row — the
+ * same 32-bit collision odds as the topic child keys).
+ */
+export declare const clusterConceptId: (centroid: Float32Array) => string;
+/**
+ * Cosine similarity of a member vector to its cluster centroid. Vectors are
+ * L2-normalized (the tree.ts invariant), so the cosine is
+ * `dot(x, c) / |c|`; a zero centroid yields 0. Clamped to [0, 1] — a
+ * negative cosine means "opposite direction", not a confident membership.
+ */
+export declare const conceptConfidence: (vector: Float32Array, centroid: Float32Array) => number;
+/** Result of one cluster pass: how many concepts + annotations were written. */
+export interface ClusterWriteResult {
+    /** Concepts upserted (clusters that met `clusterMinSize`). */
+    readonly concepts: number;
+    /** `memory_concepts` rows inserted/refreshed. */
+    readonly annotated: number;
+}
+/**
+ * Cluster ONE topic leaf's members into concepts: load the model-scoped
+ * memberships, fetch the members' vectors from the model's per-model vector
+ * table, cluster, and write the surviving clusters. A topic with no
+ * memberships (or no vector rows) writes nothing — the idempotent no-op
+ * that makes stale job re-offers harmless.
+ */
+export declare const clusterLeaf: (topicKey: string, model: EmbeddingModelConfig, config: GraphConfig) => Effect.Effect<ClusterWriteResult, StoreError, DbBackend>;
+/**
+ * The CORPUS pass: cluster a deterministic sample of the memory store and
+ * annotate the sampled memories. The sample is every Nth memory ordered by
+ * `memory_id` (N chosen to reach ~5000 samples; N = 1 when the store is
+ * smaller), active memories with an embedding only. Embeddings come from the
+ * `memories.embedding` column — the ACTIVE model's embeddings, written by
+ * the write hook (see the module doc's dimension assumption).
+ */
+export declare const clusterCorpus: (model: EmbeddingModelConfig, config: GraphConfig) => Effect.Effect<ClusterWriteResult, StoreError, DbBackend>;
+/** Dependencies for {@link conceptClusterHandler}. */
+export interface ConceptClusterHandlerDeps {
+    /** Resolves a model key to its config (the model registry). */
+    readonly getModelConfig: (modelKey: string) => EmbeddingModelConfig | undefined;
+    /** Graph config — `clusterK` / `clusterMinSize` drive the clustering. */
+    readonly config: GraphConfig;
+    /** Backend captured at registration (see {@link topicSplitHandler}). */
+    readonly backend?: DbBackendInterface;
+}
+/** The `concept.cluster` handler shape (see jobs.ts). */
+export type ConceptClusterHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+/**
+ * Factory for the `concept.cluster` job handler. Two modes, selected by the
+ * payload:
+ *
+ * - `{ modelKey, topicKey }` — cluster ONE topic leaf's members (per-tree
+ *   inductive pass).
+ * - `{ modelKey }` — the CORPUS pass: cluster a deterministic sample of the
+ *   memory store.
+ *
+ * The success schema is `Schema.Void` — the outcome lives in the DB
+ * (concepts + `memory_concepts` rows), not the job result. A pass that
+ * writes nothing (no members, no clusters meeting `clusterMinSize`) is a
+ * success, never an error — the idempotent no-op that makes stale re-offers
+ * harmless.
+ */
+export declare function conceptClusterHandler(deps: ConceptClusterHandlerDeps & {
+    readonly backend: DbBackendInterface;
+}): Handler;
+export declare function conceptClusterHandler(deps: ConceptClusterHandlerDeps): ConceptClusterHandler;

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

@@ -0,0 +1,171 @@
+/**
+ * The consolidation dream job — `memory.dream`. One run per model key:
+ * gather candidate memory pairs (rule-derived pending edges + a fresh
+ * near-duplicate scan over memories created since the watermark), ask the
+ * injected LLM classifier to judge them, then persist its relations and
+ * derived memories.
+ *
+ * The store never imports an AI SDK: {@link DreamClassifier} is the injected
+ * contract — the app root composes the real implementation from the llm
+ * package. The handler fails the job on unknown-model, persistence, AND
+ * classifier errors (a silent "success" would hide a classifier outage
+ * from the caller; the watermark never advances past an unjudged batch).
+ *
+ * ## Run flow
+ *
+ * The run proceeds in stages. It first loads the model's `dream_state`
+ * row (the watermark) and counts memories created since it; the gates
+ * (`minHours` elapsed since the last dream AND `minNewMemories` new
+ * memories) must both pass, else the run returns early with
+ * `skipped: true` and a reason. Next it gathers candidate pairs from two
+ * sources, deduplicated and bounded by `maxPairs` in deterministic order:
+ * pending `artifact_edges` rows written by the write-path rules (status
+ * `pending`, source `rule`), and a fresh near-duplicate scan
+ * (`leafLocalCandidates`) of each new memory against its topic-leaf
+ * mates. Both memories' contents are loaded for every pair. Then it calls
+ * `classify(pairs, { maxDerived })` — any classifier error FAILS the job
+ * (the watermark stays untouched, so the retried run judges the batch
+ * again). Finally it persists
+ * relations and derived memories (see below) and advances the watermark
+ * in ONE upsert, only after every write succeeded. A persistence error
+ * propagates as a job failure — the watermark stays put, so the retried
+ * run redoes the writes, which are all check-first idempotent.
+ *
+ * ## Persistence rules
+ *
+ * - Relations: an edge is skipped when either endpoint memory is pinned
+ *   (`MemoryMetadata.pinned`) or no longer exists. `memory_supersedes`
+ *   with confidence ≥ 0.8 is written CONFIRMED and flips the older
+ *   (`from`) memory to `superseded` in the same transaction (the shared
+ *   active→superseded flip + `superseded` event, mirroring the edge API);
+ *   everything else (`memory_supersedes` below the bar,
+ *   `memory_contradicts`, `memory_supports`) stays pending. All dream edges
+ *   carry source `llm`. Source memories are NEVER modified except that
+ *   supersede flip.
+ * - Derived memories: provenance enforcement — at least one declared source
+ *   must still exist, else the derived memory is skipped. The memory is
+ *   written content-addressed (`derived:<fnv1a32(content)>`, active-key
+ *   dedupe makes re-derivation idempotent), its metadata blob records the
+ *   surviving source ids, and one pending `memory_supports` edge is written
+ *   from each surviving source.
+ *
+ * ## Determinism
+ *
+ * Every iteration derives from persisted state: pending edges by
+ * `created_at` then `id`, new memories by `memory_id`, the combined pair
+ * set sorted lexicographically, relations/derived processed in the
+ * classifier's output order. Audit timestamps come from the injectable
+ * Effect Clock (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";
+/** One memory pair judged by the classifier (older first — the direction
+ * the graph edge API expects: the older memory is the supersede target). */
+export interface DreamPair {
+    readonly olderId: string;
+    readonly newerId: string;
+    readonly olderContent: string;
+    readonly newerContent: string;
+}
+/** One judged relation between two existing memories. */
+export interface DreamRelation {
+    readonly fromMemoryId: string;
+    readonly toMemoryId: string;
+    readonly edgeKind: "memory_supersedes" | "memory_contradicts" | "memory_supports";
+    readonly confidence: number;
+}
+/** One new memory to synthesize from the judged sources. */
+export interface DreamDerived {
+    readonly content: string;
+    readonly sources: readonly string[];
+}
+/** The classifier's judgement of one pair batch. */
+export interface DreamClassification {
+    readonly relations: readonly DreamRelation[];
+    readonly derived: readonly DreamDerived[];
+}
+/**
+ * The injected classifier contract. The store never imports an AI SDK —
+ * the app root provides an implementation that calls the model with the
+ * pair contents and returns relations + derived memories. Errors are
+ * swallowed by the handler (logged, watermark untouched); the channel is
+ * `unknown` precisely because the store cannot name the implementation's
+ * error type.
+ */
+export interface DreamClassifier {
+    readonly classify: (pairs: readonly DreamPair[], opts: {
+        readonly maxDerived: number;
+    }) => Effect.Effect<DreamClassification, unknown>;
+}
+/**
+ * Dream settings used when the graph config carries none (the config schema
+ * has no dream fields — these local defaults are the source of truth):
+ * at least `minHours` between dream runs, at least `minNewMemories` new
+ * memories to bother the classifier, at most `maxPairs` judged per run, and
+ * at most `maxDerived` synthesized memories per run.
+ */
+export declare const dreamStateDefaults: {
+    readonly minHours: 24;
+    readonly minNewMemories: 20;
+    readonly maxPairs: 200;
+    readonly maxDerived: 10;
+};
+/** Outcome of one dream run. The handler returns this value even though the
+ * job's success schema is void — the result is for direct callers/tests;
+ * the persisted job result stays void (the watermark row is the durable
+ * state). */
+export interface DreamOutcome {
+    /** True when the gates rejected the run before any work. */
+    readonly skipped: boolean;
+    /** Skip explanation (gates). */
+    readonly reason?: string;
+    /** Pairs sent to the classifier. */
+    readonly classified: number;
+    /** Derived memories actually inserted. */
+    readonly created: number;
+    /** Memories flipped active → superseded by confirmed supersede edges. */
+    readonly superseded: number;
+}
+/** Dependencies for {@link graphDreamHandler}. */
+export interface DreamHandlerDeps {
+    /** Resolves a model key to its config (the model registry). */
+    readonly getModelConfig: (modelKey: string) => EmbeddingModelConfig | undefined;
+    /**
+     * The injected classifier that judges candidate pairs. The app root
+     * implements it over any LLM (for example `makeDreamClassifier` from
+     * `@dimple/llm`); the store never imports an AI SDK. The classifier
+     * receives the gathered pairs plus a `maxDerived` budget and must return
+     * relations (canonical direction: supersede/contradict edges point
+     * old → new) and optional derived memories with provenance sources.
+     */
+    readonly classify: DreamClassifier;
+    /** Backend captured at registration (see {@link topicSplitHandler}). */
+    readonly backend?: DbBackendInterface;
+}
+/** The `memory.dream` handler shape (see jobs.ts). */
+export type DreamHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+/**
+ * Factory for the `memory.dream` job handler. Payload: `{ modelKey }`.
+ * Runs the four phases (orient → gather → consolidate → prune) for that
+ * model's tree, then advances the model's `dream_state` watermark in ONE
+ * upsert — only after every write succeeded.
+ *
+ * Gates (from `dreamStateDefaults`): the run skips unless at least
+ * `minHours` passed since the last dream AND at least `minNewMemories`
+ * memories were created since the watermark. A fresh model (no state row)
+ * passes both gates trivially.
+ *
+ * The success schema is `Schema.Void` — the durable outcome lives in the
+ * `dream_state` row + the written edges/memories; the returned
+ * {@link DreamOutcome} is for direct callers. Skipped and
+ * classifier-failed runs are successes, never errors (a skipped run is
+ * normal cadence; a failed classifier must not crash the worker or retry
+ * forever — the watermark stays put so the batch is judged again next run).
+ */
+export declare function graphDreamHandler(deps: DreamHandlerDeps & {
+    readonly backend: DbBackendInterface;
+}): Handler;
+export declare function graphDreamHandler(deps: DreamHandlerDeps): DreamHandler;

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

@@ -0,0 +1,25 @@
+import { Schema } from "effect";
+declare const EdgeNotFound_base: Schema.Class<EdgeNotFound, Schema.TaggedStruct<"graph.EdgeNotFound", {
+    readonly id: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Graph error types (mirror of `topics/errors.ts`). Each distinct failure
+ * mode gets its own `Schema.TaggedErrorClass` so callers can `catchTag`
+ * precisely; they ride the public `Store` error channel alongside
+ * `StoreError`.
+ */
+/** A status/soft-delete transition targeted an edge id that does not exist. */
+export declare class EdgeNotFound extends EdgeNotFound_base {
+}
+declare const EdgeExists_base: Schema.Class<EdgeExists, Schema.TaggedStruct<"graph.EdgeExists", {
+    readonly fromMemoryId: Schema.String;
+    readonly toMemoryId: Schema.String;
+    readonly edgeKind: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `Store.addEdge` hit the `(from_memory_id, to_memory_id, edge_kind)`
+ * unique constraint (the composite PK) — the edge already exists.
+ */
+export declare class EdgeExists extends EdgeExists_base {
+}
+export {};

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

@@ -0,0 +1,15 @@
+/**
+ * Graph barrel. The artifact graph's store-level surface: canonical errors
+ * (`EdgeNotFound` / `EdgeExists`), the traversal row schema + the sanctioned
+ * boundary cast (`fromNeighborRows`), and the graph schema (`artifact_edges`
+ * table, the typed `graph_edges` view handle, `GraphConfig`).
+ */
+export * from "./errors.ts";
+export * from "./traversal.ts";
+export * from "./retrieval-post-pass.ts";
+export * from "./concepts.ts";
+export * from "./dream.ts";
+export * from "./candidates.ts";
+export * from "./observability.ts";
+export * from "./repair.ts";
+export * from "../schema/graph.ts";

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

@@ -0,0 +1,37 @@
+/**
+ * Graph coverage — the observability snapshot of the artifact graph's
+ * reach over one model's memory population.
+ *
+ * The memory counts are scoped to the model: "the model's memories" are
+ * the active `memories` rows whose `embedding_model` column names the
+ * model (set by `Store.updateEmbedding` — the moment a memory joins a
+ * model's vector space). Edges and concepts are global tables, so the
+ * incident-edge survey and the pending-candidate count are computed over
+ * the whole graph, but the denominators (total / covered / isolated) are
+ * model-scoped.
+ *
+ * All reads are plain Drizzle builder queries (one id-column scan per
+ * count) plus a single `count(*)` aggregate for the pending-candidate
+ * backlog — no raw SQL, no backend methods.
+ */
+import { Effect } from "effect";
+import { Service as DbBackend } from "../db-backend.ts";
+import { StoreError } from "../error.ts";
+/** One coverage snapshot for a model's memory population. */
+export interface GraphCoverage {
+    /** Active memories embedded by the model. */
+    readonly totalMemories: number;
+    /** Of those, with at least one live incident edge (confirmed or pending, not expired). */
+    readonly coveredMemories: number;
+    /** `coveredMemories / totalMemories` as a percentage, rounded to one decimal (0 when empty). */
+    readonly coveragePercent: number;
+    /** Pending, non-expired `artifact_edges` rows — the write-path candidate backlog. */
+    readonly pendingCandidates: number;
+    /** Total concept rows (concepts are global, not per-model). */
+    readonly conceptCount: number;
+    /** Distinct memories with at least one concept annotation. */
+    readonly annotatedMemories: number;
+    /** Model memories with no live incident edge (the `graphCandidates` survey mirror). */
+    readonly isolatedMemories: number;
+}
+export declare const graphCoverage: (modelKey: string) => Effect.Effect<GraphCoverage, StoreError, DbBackend>;

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

@@ -0,0 +1,85 @@
+/**
+ * The graph repair job — `graph.repair`. One pass per model key that
+ * sweeps the graph tables for rows that should not exist and removes them.
+ *
+ * The scan is global (edges, concepts and annotations are not per-model
+ * tables); the payload's model key is validated against the model registry
+ * so the job's idempotency token (`repair:<modelKey>`) always refers to a
+ * real model, exactly like the other graph jobs.
+ *
+ * ## What the pass fixes
+ *
+ * 1. ORPHANED EDGES — `artifact_edges` rows whose `from` or `to` memory
+ *    row is gone. Normally impossible (the schema declares cascade
+ *    deletes), but a crash window or a foreign-key-disabled database can
+ *    leave them behind; they are dead weight for traversal and the
+ *    candidates review. Detected with a double left join against
+ *    `memories`; deleted outright.
+ * 2. STALE CONCEPT ANNOTATIONS — `memory_concepts` rows whose concept row
+ *    or memory row is gone (the same crash-window class). Deleted by
+ *    their composite key.
+ * 3. EXPIRED EDGES (OPTIONAL) — soft-deleted edges (`expired_at` set)
+ *    older than a grace window. The soft-delete keeps history around for
+ *    review; the purge makes it a hard delete. Gated by the handler
+ *    option `includePurgeExpired` (default false) — the conservative
+ *    default keeps the pass read-only on edge history.
+ *
+ * ## Logging and idempotence
+ *
+ * Every fix is recorded as a `memory_events` row with event type
+ * `graph_repair` and a JSON `reason` describing the action — attached to
+ * a surviving endpoint memory where one exists. An orphan whose BOTH
+ * endpoints are gone has no surviving memory to attach an event to (the
+ * events table's memory id is a foreign key to `memories`), so those
+ * deletions are the one case that is not logged — the row itself was the
+ * only trace. All reads and writes run in ONE transaction, so a
+ * mid-pass failure rolls back every fix and the counts; a re-run then
+ * finds the same state and repeats cleanly (idempotent — the second run
+ * simply finds nothing to fix).
+ */
+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";
+/** How many rows of each class one repair pass fixed. */
+export interface RepairResult {
+    /** `artifact_edges` rows whose endpoint memory was gone. */
+    readonly orphanedEdges: number;
+    /** `memory_concepts` rows whose concept or memory was gone. */
+    readonly staleAnnotations: number;
+    /** Soft-deleted edges hard-purged past the grace window (only when enabled). */
+    readonly expiredEdges: number;
+}
+/** Dependencies for {@link graphRepairHandler}. */
+export interface GraphRepairHandlerDeps {
+    /** Resolves a model key to its config (the model registry). */
+    readonly getModelConfig: (modelKey: string) => EmbeddingModelConfig | undefined;
+    /** Backend captured at registration (see {@link topicSplitHandler}). */
+    readonly backend?: DbBackendInterface;
+    /** When true, hard-purge soft-deleted edges older than `expiredGraceMs`.
+     * Default false — the expired sweep is skipped entirely. */
+    readonly includePurgeExpired?: boolean;
+    /** Grace window for the expired purge in ms (default one week). */
+    readonly expiredGraceMs?: number;
+}
+/** The `graph.repair` handler shape (see jobs.ts). */
+export type GraphRepairHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+/**
+ * Factory for the `graph.repair` job handler. Payload: `{ modelKey }`.
+ * Validates the model key, then runs the repair transaction: orphaned
+ * `artifact_edges` (endpoints missing — normally impossible via FK
+ * cascade, the backstop for crash windows), stale `memory_concepts`
+ * annotations, and — only when `includePurgeExpired` is set — hard-purge
+ * of soft-deleted edges older than `expiredGraceMs`. Every fix is logged
+ * to `memory_events` (`event_type = "graph_repair"`). Idempotent: a
+ * second pass finds nothing and writes nothing.
+ *
+ * The success schema is `Schema.Void` — the durable outcome is the
+ * deleted rows + the `graph_repair` event log; the returned
+ * {@link RepairResult} is for direct callers/tests.
+ */
+export declare function graphRepairHandler(deps: GraphRepairHandlerDeps & {
+    readonly backend: DbBackendInterface;
+}): Handler;
+export declare function graphRepairHandler(deps: GraphRepairHandlerDeps): GraphRepairHandler;