@ponraaj/dimple-sdk 0.0.0-alpha.1

package/dist/internal/store/graph/retrieval-post-pass.d.ts

@@ -0,0 +1,58 @@
+import type { ScoredMemory } from "../models.ts";
+/**
+ * Retrieval post-pass — the deterministic, pure-JS augmentation of search
+ * results with graph context. No Effect, no DB: the store fetches the result set's edges via
+ * the Drizzle builder and this module transforms. Retrieval without edges is
+ * identical to today — the pass is a no-op on an empty graph.
+ *
+ * Rules applied (all deterministic — edges are sorted first, results keep
+ * their input rank order):
+ * - `memory_supersedes` (confirmed): a result that IS the OLD endpoint
+ *   (`fromMemoryId`, the old → new direction) is demoted — `score ×
+ *   supersedeDemotion` — and gets `supersededBy = successor id` (the first
+ *   successor in sorted edge order wins when several supersede edges target
+ *   the same result). Pending supersede candidates never demote.
+ * - `memory_contradicts` (pending OR confirmed): EITHER endpoint in the
+ *   results surfaces `conflicts = [other endpoint id]` on BOTH sides;
+ *   nothing is silently dropped (pending conflicts are visible).
+ * - `memory_supports` (confirmed): the result at the `toMemoryId` endpoint
+ *   gains `supportedBy = [source ids]` — the "why this result" provenance.
+ *
+ * `conceptEdges` is accepted per the documented signature but attaches
+ * nothing in this pass — the concept filter consumes it later.
+ */
+/** A search result augmented with graph context. The base `ScoredMemory`
+ * fields are untouched unless a rule applies; un-affected results are
+ * returned by reference (bit-identical). */
+export interface AugmentedMemory extends ScoredMemory {
+    /** Other endpoints of pending/confirmed `memory_contradicts` edges (both sides surface). */
+    readonly conflicts?: readonly string[];
+    /** Sources of confirmed `memory_supports` edges ("why this result" provenance). */
+    readonly supportedBy?: readonly string[];
+    /** Successor of a confirmed `memory_supersedes` edge — this result is the
+     * OLD endpoint, so its score was multiplied by `supersedeDemotion`. */
+    readonly supersededBy?: string;
+}
+/** One `artifact_edges` row as fetched by the store's post-pass query
+ * (non-rejected, non-expired — pending rows included so conflicts surface). */
+export interface ResultEdge {
+    readonly fromMemoryId: string;
+    readonly toMemoryId: string;
+    readonly edgeKind: string;
+    readonly status: string;
+}
+/** One `memory_concepts` row (concept filter's input — accepted now,
+ * attached later). */
+export interface ConceptEdge {
+    readonly memoryId: string;
+    readonly conceptId: string;
+}
+export interface AugmentResultsOptions {
+    /** Score multiplier applied to superseded results. */
+    readonly supersedeDemotion: number;
+}
+/**
+ * The deterministic graph post-pass over one search result set. Empty inputs
+ * ⇒ results mapped unchanged (the same array, bit-identical scores).
+ */
+export declare const augmentResults: (results: readonly ScoredMemory[], memoryEdges: readonly ResultEdge[], _conceptEdges: readonly ConceptEdge[], opts: AugmentResultsOptions) => readonly AugmentedMemory[];

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

@@ -0,0 +1,39 @@
+import { Schema } from "effect";
+/**
+ * Traversal row shapes + the ONE sanctioned boundary cast for graph
+ * traversal (raw SQL results carry no type info — `DbBackend.
+ * graphNeighbors` returns `Record<string, unknown>[]`; this module validates
+ * and maps them into the canonical camelCase shape once, at the store
+ * boundary — the mirror of the `ftsSearch`/`vectorSearch` casts).
+ */
+/**
+ * Canonical traversal row — the camelCase shape declared on the backend
+ * (`DbBackend.GraphNeighborRow`). One row = one edge of the neighborhood:
+ * the edge that reached this row's `to` endpoint (the seed query matches
+ * rows touching a frontier node on EITHER endpoint, so `from` may also be
+ * the frontier — `Store.explain` resolves reached nodes from both).
+ */
+export declare const GraphNeighborRow: Schema.Struct<{
+    /** The edge's `from` endpoint id. */
+    readonly fromId: Schema.String;
+    readonly fromKind: Schema.String;
+    /** The edge's `to` endpoint id. */
+    readonly toId: Schema.String;
+    readonly toKind: Schema.String;
+    readonly edgeKind: Schema.String;
+    readonly edgeStatus: Schema.String;
+    readonly weight: Schema.Number;
+    readonly edgeSource: Schema.String;
+    readonly depth: Schema.Number;
+}>;
+/** Decoded `GraphNeighborRow` — the canonical traversal row shape. */
+export interface GraphNeighborRow extends Schema.Schema.Type<typeof GraphNeighborRow> {
+}
+/**
+ * The sanctioned boundary cast for `DbBackend.graphNeighbors` rows:
+ * validates each raw row against the view's fixed shape and maps it to the
+ * canonical camelCase `GraphNeighborRow`. Throws (defect) on a row that
+ * does not match — the backend owns the query, so a mismatch is a real bug,
+ * not a runtime condition.
+ */
+export declare const fromNeighborRows: (rows: readonly Record<string, unknown>[]) => readonly GraphNeighborRow[];

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

@@ -0,0 +1,38 @@
+import { Config } from "effect";
+export { StoreError, NotFound, DuplicateActiveKey } from "./error.ts";
+import * as topics from "./topics/index.ts";
+export { topics };
+export { auditWriteHandler, type AuditWriteHandler } from "./audit.ts";
+export { TopicConfig } from "./schema/topics.ts";
+export type { AddEdgeInput, ExplainResult } from "./service.ts";
+export type { TopicHealth } from "./topics/observability.ts";
+export type { TopicConfig as TopicConfigType } from "./schema/topics.ts";
+export type { RetrievalAuditRow } from "./models.ts";
+import * as graph from "./graph/index.ts";
+export { graph };
+export { augmentResults } from "./graph/retrieval-post-pass.ts";
+export type { AugmentedMemory, ResultEdge, ConceptEdge, AugmentResultsOptions, } from "./graph/retrieval-post-pass.ts";
+export { leafLocalCandidates } from "./graph/candidates.ts";
+export type { CandidateMember, CandidateKind, EdgeCandidate, EdgeCandidateInfo, IsolatedMemory, GraphCandidatesOptions, GraphCandidatesResult, } from "./graph/candidates.ts";
+export { farthestPointSeeds, kGroupLloyd, clusterMembers, clusterConceptId, conceptConfidence, clusterLeaf, clusterCorpus, conceptClusterHandler, } from "./graph/concepts.ts";
+export type { ClusterResult, ClusterWriteResult, ConceptClusterHandler, ConceptClusterHandlerDeps, } from "./graph/concepts.ts";
+export { graphDreamHandler, dreamStateDefaults } from "./graph/dream.ts";
+export type { DreamPair, DreamRelation, DreamDerived, DreamClassification, DreamClassifier, DreamOutcome, DreamHandler, DreamHandlerDeps, } from "./graph/dream.ts";
+export { graphCoverage } from "./graph/observability.ts";
+export type { GraphCoverage } from "./graph/observability.ts";
+export { graphRepairHandler } from "./graph/repair.ts";
+export type { RepairResult, GraphRepairHandler, GraphRepairHandlerDeps } from "./graph/repair.ts";
+export { parseMetadata, encodeMetadata, mergeMetadataBlob } from "./schema/metadata.ts";
+export { Service as DbBackend, type DrizzleDB } from "./db-backend.ts";
+export { Service as Store } from "./service.ts";
+export * from "./models.ts";
+export { layer as dbBackendLayer, layerConfig as dbBackendLayerConfig, layerFromConfig as dbBackendLayerFromConfig, } from "./libsql-backend.ts";
+export { layer as storeLayer, layerConfig as storeLayerConfig, layerFromConfig as storeLayerFromConfig, } from "./store.ts";
+export declare const layer: (url: string, options?: {
+    migrationFolder?: string;
+}) => import("effect/Layer").Layer<import("./internal/logger/index.js").Logging | import("./db-backend.ts").Service | import("./service.ts").Service, import("./error.ts").StoreError, import("effect/Scope").Scope>;
+export declare const layerConfig: (config: Config.Wrap<{
+    url: string;
+}>, options?: {
+    migrationFolder?: string;
+}) => import("effect/Layer").Layer<import("./internal/logger/index.js").Logging | import("./db-backend.ts").Service | import("./service.ts").Service, Config.ConfigError | import("./error.ts").StoreError, import("effect/Scope").Scope>;

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

@@ -0,0 +1,18 @@
+import { Layer, Config, Scope } from "effect";
+import { StoreError } from "./error.ts";
+import { Service } from "./db-backend.ts";
+import { Service as ConfigService } from "./internal/config/index.js";
+export declare const layer: (url: string, options?: {
+    migrationFolder?: string;
+    releaseClient?: boolean;
+}) => Layer.Layer<Service, StoreError, never>;
+export declare const layerConfig: (config: Config.Wrap<{
+    url: string;
+}>, options?: {
+    migrationFolder?: string;
+    releaseClient?: boolean;
+}) => Layer.Layer<Service, Config.ConfigError | StoreError, Scope.Scope>;
+export declare const layerFromConfig: (options?: {
+    migrationFolder?: string;
+    releaseClient?: boolean;
+}) => Layer.Layer<Service, StoreError, ConfigService | Scope.Scope>;

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

@@ -0,0 +1,122 @@
+import { Schema } from "effect";
+export { MemoryMetadata } from "./schema/metadata.ts";
+export declare const MemoryState: Schema.Literals<readonly ["active", "superseded", "archived", "forgotten"]>;
+export type MemoryState = Schema.Schema.Type<typeof MemoryState>;
+export declare const MemoryEventType: Schema.Literals<readonly ["created", "superseded", "archived", "forgotten", "embedding_updated"]>;
+export type MemoryEventType = Schema.Schema.Type<typeof MemoryEventType>;
+export declare const MemoryUnit: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly logicalKey: Schema.String;
+    readonly content: Schema.String;
+    readonly contentType: Schema.String;
+    readonly state: Schema.Literals<readonly ["active", "superseded", "archived", "forgotten"]>;
+    readonly createdAt: Schema.Number;
+    readonly ttlSecs: Schema.Number;
+    readonly namespace: Schema.String;
+    readonly metadata: Schema.optional<Schema.String>;
+    readonly embedding: Schema.optional<Schema.$Array<Schema.Number>>;
+    readonly embeddingModel: Schema.optional<Schema.String>;
+}>;
+export interface MemoryUnit extends Schema.Schema.Type<typeof MemoryUnit> {
+}
+export declare const WriteMemoryInput: Schema.Struct<{
+    readonly logicalKey: Schema.String;
+    readonly content: Schema.String;
+    readonly contentType: Schema.optional<Schema.String>;
+    readonly namespace: Schema.optional<Schema.String>;
+    readonly ttlSecs: Schema.optional<Schema.Number>;
+    readonly metadata: Schema.optional<Schema.String>;
+    /** Typed overlay merged INTO the raw metadata blob on write (unknown blob
+     * keys preserved. Takes precedence over `metadata`. */
+    readonly typedMetadata: Schema.optional<Schema.Struct<{
+        readonly topics: Schema.$Array<Schema.String>;
+        readonly sourceType: Schema.String;
+        readonly temporalContext: Schema.optional<Schema.Struct<{
+            readonly windowStart: Schema.Number;
+            readonly windowEnd: Schema.Number;
+        }>>;
+        readonly confidence: Schema.Number;
+        readonly affordances: Schema.$Array<Schema.String>;
+        readonly language: Schema.optional<Schema.String>;
+        readonly pinned: Schema.optional<Schema.Boolean>;
+    }>>;
+}>;
+export interface WriteMemoryInput extends Schema.Schema.Type<typeof WriteMemoryInput> {
+}
+export declare const ScoredMemory: Schema.Struct<{
+    readonly memory: Schema.Struct<{
+        readonly id: Schema.String;
+        readonly logicalKey: Schema.String;
+        readonly content: Schema.String;
+        readonly contentType: Schema.String;
+        readonly state: Schema.Literals<readonly ["active", "superseded", "archived", "forgotten"]>;
+        readonly createdAt: Schema.Number;
+        readonly ttlSecs: Schema.Number;
+        readonly namespace: Schema.String;
+        readonly metadata: Schema.optional<Schema.String>;
+        readonly embedding: Schema.optional<Schema.$Array<Schema.Number>>;
+        readonly embeddingModel: Schema.optional<Schema.String>;
+    }>;
+    readonly score: Schema.Number;
+    readonly rank: Schema.Number;
+    readonly source: Schema.String;
+}>;
+/** One `retrieval_log` row as built by the store's audit helper. The
+ * `audit.write` job def in `@dimple/workflow` decodes this shape
+ * structurally. */
+export interface RetrievalAuditRow {
+    readonly id: string;
+    readonly queryHash: string;
+    readonly queryText: string;
+    readonly namespace: string;
+    readonly mode: string;
+    readonly queryProfile?: string | null;
+    readonly sources?: string | null;
+    readonly resultCount?: number | null;
+    readonly latencyMs: number;
+    readonly createdAt: number;
+}
+export interface ScoredMemory extends Schema.Schema.Type<typeof ScoredMemory> {
+}
+export declare const SweepResult: Schema.Struct<{
+    readonly archived: Schema.Number;
+    readonly forgotten: Schema.Number;
+}>;
+export interface SweepResult extends Schema.Schema.Type<typeof SweepResult> {
+}
+export declare const MemoryEvent: Schema.Struct<{
+    readonly id: Schema.Number;
+    readonly memoryId: Schema.String;
+    readonly eventType: Schema.Literals<readonly ["created", "superseded", "archived", "forgotten", "embedding_updated"]>;
+    readonly fromState: Schema.optional<Schema.Literals<readonly ["active", "superseded", "archived", "forgotten"]>>;
+    readonly toState: Schema.optional<Schema.Literals<readonly ["active", "superseded", "archived", "forgotten"]>>;
+    readonly reason: Schema.optional<Schema.String>;
+    readonly createdAt: Schema.Number;
+}>;
+export interface MemoryEvent extends Schema.Schema.Type<typeof MemoryEvent> {
+}
+export declare const Concept: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly name: Schema.String;
+    readonly embedding: Schema.$Array<Schema.Number>;
+    readonly occurrenceCount: Schema.Number;
+    readonly firstSeen: Schema.Number;
+    readonly lastSeen: Schema.Number;
+}>;
+export interface Concept extends Schema.Schema.Type<typeof Concept> {
+}
+export declare const RetrievalLogEntry: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly queryHash: Schema.String;
+    readonly queryText: Schema.String;
+    readonly namespace: Schema.String;
+    readonly mode: Schema.String;
+    readonly queryProfile: Schema.optional<Schema.String>;
+    /** Serialized query profile / result-source ids. */
+    readonly sources: Schema.optional<Schema.String>;
+    readonly resultCount: Schema.Number;
+    readonly latencyMs: Schema.Number;
+    readonly createdAt: Schema.Number;
+}>;
+export interface RetrievalLogEntry extends Schema.Schema.Type<typeof RetrievalLogEntry> {
+}