@kybernesis/brain-contracts 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export * from './timeline.js';
 export * from './entity.js';
 export * from './fact.js';
 export * from './sleep.js';
+export * from './storage.js';
 export * from './logger.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -4,5 +4,6 @@ export * from './timeline.js';
 export * from './entity.js';
 export * from './fact.js';
 export * from './sleep.js';
+export * from './storage.js';
 export * from './logger.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/storage.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Storage provider interfaces — the swappable seam (Stage 1).
+ *
+ * `brain-core` business logic depends ONLY on these interfaces, obtained via
+ * the `setStorageProvider`/`getStorage` seam in brain-core (which mirrors
+ * `setLLMProvider`). Each backend package (brain-storage-sqlite today; a
+ * libsql impl in Stage 3) implements them with its own dialect.
+ *
+ * DESIGN RULES (load-bearing — see docs/specs/storage-provider-di-spec.md):
+ *  - Every method is async. Inserts return `Promise<number>` (the new id), so
+ *    the impl owns `RETURNING` vs `lastInsertRowid` internally.
+ *  - No method ever exposes a driver handle (`better-sqlite3.Database`, a libsql
+ *    client, …). The seam speaks domain operations, never SQL.
+ *  - Returned object fields are snake_case, matching the v0.2.0 realignment and
+ *    guarded by schema-naming.test.ts.
+ *  - The 3 within-kind transactions (mergeEntities, deleteEntity, the vector
+ *    chunk insert) are IMPL-INTERNAL to their methods — no public transaction
+ *    primitive is exposed in Stage 1 (decision ①: keep per-kind best-effort
+ *    semantics; cross-kind unit-of-work is a reserved Stage-3 addition).
+ *  - Param names stay camelCase at the input edge (unchanged public surface);
+ *    only RETURNED fields are snake_case.
+ *
+ * NOTE: this interface establishes the 5-store decomposition + shape. Methods
+ * are added as each brain-core module migrates (G1–G6); the surface is complete
+ * by the time the conformance suite (G7) runs against it.
+ */
+import type { TenantContext } from './tenant.js';
+import type { TimelineEvent, TimelineEventInput } from './timeline.js';
+import type { Entity, EntityMention, Contradiction, EntityInsight } from './entity.js';
+import type { Fact } from './fact.js';
+import type { EntityType, RelationshipType, InsightType, EventType, FactCategory } from './constants.js';
+export interface TimelineQuery {
+    start?: string;
+    end?: string;
+    type?: EventType;
+    search?: string;
+    entities?: string[];
+    topics?: string[];
+    limit?: number;
+    offset?: number;
+}
+export interface TimelineStats {
+    totalEvents: number;
+    byType: Record<EventType, number>;
+    dateRange: {
+        earliest: string | null;
+        latest: string | null;
+    };
+}
+export interface VectorChunkInput {
+    /** Embedding vector; impl marshals to its own binding format. */
+    embedding: number[];
+    ts: string;
+    source?: string;
+    content: string;
+    origin_id?: string;
+}
+export interface VectorSearchRow {
+    ts: string;
+    source: string | null;
+    content: string;
+    origin_id: string | null;
+    distance: number;
+}
+export interface TimelineStore {
+    ensureSchema(t: TenantContext): Promise<void>;
+    addEvent(t: TenantContext, event: TimelineEventInput): Promise<number>;
+    removeEventByPath(t: TenantContext, sourcePath: string): Promise<boolean>;
+    updateEvent(t: TenantContext, id: number, updates: Partial<Omit<TimelineEventInput, 'source_path'>>): Promise<void>;
+    deleteEventById(t: TenantContext, id: number): Promise<boolean>;
+    getEventById(t: TenantContext, id: number): Promise<TimelineEvent | null>;
+    getEventByPath(t: TenantContext, sourcePath: string): Promise<TimelineEvent | null>;
+    query(t: TenantContext, query: TimelineQuery): Promise<TimelineEvent[]>;
+    findRecentDuplicate(t: TenantContext, title: string, withinHours: number): Promise<{
+        id: number;
+        title: string;
+    } | null>;
+    incrementEventCount(t: TenantContext, eventId: number): Promise<void>;
+    stats(t: TenantContext): Promise<TimelineStats>;
+    /** DISTINCT source_paths whose title/tags/entities LIKE the (lowercased) term. (ops.ts recall) */
+    findSourcePathsMatching(t: TenantContext, termLower: string, limit: number): Promise<string[]>;
+}
+export interface EntityRelatedHit {
+    entity: Entity;
+    relationship: string;
+    strength: number;
+}
+export interface TypedRelationship {
+    entity: Entity;
+    relationship: RelationshipType;
+    direction: 'outgoing' | 'incoming';
+    confidence: number;
+    rationale?: string;
+}
+export interface EntityGraphStats {
+    totalEntities: number;
+    totalMentions: number;
+    totalRelations: number;
+    byType: Record<EntityType, number>;
+}
+export interface EntityGraphStore {
+    ensureSchema(t: TenantContext): Promise<void>;
+    findOrCreateEntity(t: TenantContext, name: string, type: EntityType, timestamp: string): Promise<Entity>;
+    addEntityAlias(t: TenantContext, entityId: number, alias: string): Promise<void>;
+    addEntityMention(t: TenantContext, entityId: number, conversationId: string, sourcePath: string, context: string, timestamp: string, sourceType?: string, confidence?: number): Promise<void>;
+    linkEntities(t: TenantContext, sourceId: number, targetId: number, relationship?: RelationshipType): Promise<void>;
+    linkEntitiesWithType(t: TenantContext, sourceId: number, targetId: number, options: {
+        relationship: RelationshipType;
+        confidence?: number;
+        rationale?: string;
+        method?: string;
+    }): Promise<void>;
+    getTypedRelationships(t: TenantContext, entityId: number): Promise<TypedRelationship[]>;
+    getEntityContext(t: TenantContext, nameOrId: string | number): Promise<{
+        entity: Entity;
+        mentions: EntityMention[];
+        relatedEntities: EntityRelatedHit[];
+    } | null>;
+    searchEntities(t: TenantContext, query: string, options?: {
+        type?: EntityType;
+        limit?: number;
+    }): Promise<Entity[]>;
+    getRecentEntities(t: TenantContext, limit?: number): Promise<Entity[]>;
+    getMostMentionedEntities(t: TenantContext, options?: {
+        type?: EntityType;
+        limit?: number;
+    }): Promise<Entity[]>;
+    stats(t: TenantContext): Promise<EntityGraphStats>;
+    detectEntitiesInQuery(t: TenantContext, query: string): Promise<{
+        entities: string[];
+        remainingQuery: string;
+    }>;
+    mergeEntities(t: TenantContext, keepId: number, removeId: number, reason: string, confidence?: number, aiRationale?: string, mergedBy?: string): Promise<{
+        mentions_moved: number;
+        relations_moved: number;
+    }>;
+    deleteEntity(t: TenantContext, entityId: number, reason: string, mergedBy?: string): Promise<void>;
+    getEntityProfile(t: TenantContext, entityId: number): Promise<{
+        profile: string;
+        generated_at: string;
+        fact_count: number;
+    } | null>;
+    saveEntityProfile(t: TenantContext, entityId: number, profile: string, factCount: number): Promise<void>;
+    createContradiction(t: TenantContext, entityId: number, factAId: number, factBId: number, factA: string, factB: string, description: string): Promise<number>;
+    getOpenContradictions(t: TenantContext, entityId: number): Promise<Contradiction[]>;
+    resolveContradiction(t: TenantContext, contradictionId: number, resolvedBy: string): Promise<void>;
+    applyContradictions(t: TenantContext, entityId: number, factIds: number[]): Promise<void>;
+    saveEntityInsight(t: TenantContext, entityId: number, insightType: InsightType, insight: string, reasoning: string, confidence: number, sourceEntityIds?: number[], expiresAt?: string): Promise<number>;
+    getEntityInsights(t: TenantContext, entityId: number, minConfidence?: number): Promise<EntityInsight[]>;
+    markInsightsStale(t: TenantContext, entityId: number): Promise<void>;
+    getEntitiesForReasoning(t: TenantContext, limit?: number, staleDays?: number, recencyDays?: number): Promise<Array<{
+        id: number;
+        name: string;
+        type: string;
+    }>>;
+    markEntityReasoned(t: TenantContext, entityId: number): Promise<void>;
+    pinEntity(t: TenantContext, entityId: number, pinned?: boolean): Promise<void>;
+    listPinned(t: TenantContext, type?: EntityType): Promise<Entity[]>;
+    /** Bump access_count + last_accessed for an entity. (ops.ts recall tracking) */
+    trackAccess(t: TenantContext, entityId: number): Promise<void>;
+}
+/** Insert shape for storeFact — server fills id/created_at/is_latest/access_count/is_retracted. */
+export type StoreFactInput = Omit<Fact, 'id' | 'created_at' | 'is_latest' | 'access_count' | 'is_retracted'>;
+export interface FactStore {
+    ensureFactsTable(t: TenantContext): Promise<void>;
+    storeFact(t: TenantContext, fact: StoreFactInput): Promise<number>;
+    retractFact(t: TenantContext, factId: number, retractedBy?: string): Promise<void>;
+    reinforceFact(t: TenantContext, factId: number): Promise<void>;
+    getFactById(t: TenantContext, factId: number): Promise<Fact | null>;
+    getFactsForEntity(t: TenantContext, entity: string, options?: {
+        latestOnly?: boolean;
+        limit?: number;
+        category?: FactCategory;
+    }): Promise<Fact[]>;
+    markFactSuperseded(t: TenantContext, oldFactId: number, newFactId: number): Promise<void>;
+    factsCount(t: TenantContext): Promise<number>;
+    listFacts(t: TenantContext, options?: {
+        limit?: number;
+        offset?: number;
+        latestOnly?: boolean;
+        category?: FactCategory;
+    }): Promise<Fact[]>;
+    listTemporalFacts(t: TenantContext, options?: {
+        includeExpired?: boolean;
+        limit?: number;
+    }): Promise<Fact[]>;
+    searchFactsFts(t: TenantContext, query: string, limit?: number): Promise<Fact[]>;
+    /**
+     * Active (latest, non-expired) fact CONTENTS for a category. (user-profile.ts)
+     * order 'frecency' = confidence DESC, access_count DESC (fallback confidence-only
+     * if access_count column is absent); 'recent' = timestamp DESC.
+     */
+    getFactContentsByCategory(t: TenantContext, category: string, limit: number, order: 'frecency' | 'recent'): Promise<string[]>;
+}
+export interface MemoryEdgeHit {
+    related_path: string;
+    confidence: number;
+    shared_tags: string;
+}
+export interface SleepStore {
+    /** memory_edges neighbours of a source path. Returns [] if the table doesn't exist yet. */
+    getRelatedEdges(t: TenantContext, sourcePath: string, limit: number): Promise<MemoryEdgeHit[]>;
+}
+export interface VectorStore {
+    /** Can the vector backend be opened for this tenant? (loads sqlite-vec) */
+    available(t: TenantContext): Promise<boolean>;
+    hasOrigin(t: TenantContext, originId: string): Promise<boolean>;
+    insertChunk(t: TenantContext, chunk: VectorChunkInput): Promise<number>;
+    search(t: TenantContext, embedding: number[], limit: number): Promise<VectorSearchRow[]>;
+    stats(t: TenantContext): Promise<{
+        count: number;
+        available: boolean;
+    }>;
+}
+export interface StorageProvider {
+    timeline: TimelineStore;
+    entities: EntityGraphStore;
+    facts: FactStore;
+    sleep: SleepStore;
+    vectors: VectorStore;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/storage.js

@@ -0,0 +1,28 @@
+/**
+ * Storage provider interfaces — the swappable seam (Stage 1).
+ *
+ * `brain-core` business logic depends ONLY on these interfaces, obtained via
+ * the `setStorageProvider`/`getStorage` seam in brain-core (which mirrors
+ * `setLLMProvider`). Each backend package (brain-storage-sqlite today; a
+ * libsql impl in Stage 3) implements them with its own dialect.
+ *
+ * DESIGN RULES (load-bearing — see docs/specs/storage-provider-di-spec.md):
+ *  - Every method is async. Inserts return `Promise<number>` (the new id), so
+ *    the impl owns `RETURNING` vs `lastInsertRowid` internally.
+ *  - No method ever exposes a driver handle (`better-sqlite3.Database`, a libsql
+ *    client, …). The seam speaks domain operations, never SQL.
+ *  - Returned object fields are snake_case, matching the v0.2.0 realignment and
+ *    guarded by schema-naming.test.ts.
+ *  - The 3 within-kind transactions (mergeEntities, deleteEntity, the vector
+ *    chunk insert) are IMPL-INTERNAL to their methods — no public transaction
+ *    primitive is exposed in Stage 1 (decision ①: keep per-kind best-effort
+ *    semantics; cross-kind unit-of-work is a reserved Stage-3 addition).
+ *  - Param names stay camelCase at the input edge (unchanged public surface);
+ *    only RETURNED fields are snake_case.
+ *
+ * NOTE: this interface establishes the 5-store decomposition + shape. Methods
+ * are added as each brain-core module migrates (G1–G6); the surface is complete
+ * by the time the conformance suite (G7) runs against it.
+ */
+export {};
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/brain-contracts",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Zod schemas, provider interfaces, and shared types for the Kybernesis brain library",
   "license": "MIT",
   "author": "David Cruwys (AppyDave)",