@kybernesis/brain-contracts 0.12.0 → 0.14.0

package/dist/brain-provider.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Layer-2 `BrainProvider` seam (ADR-0016).
+ *
+ * A coarse-grained, consumer-facing facade over brain *operations* —
+ * `remember` / `addNote` / `query` / `timeline` / entity ops / `stats` /
+ * `sleep`. It sits one level ABOVE the Layer-3 `StorageProvider` (persistence)
+ * and is the seam a consumer swaps to point a brain at a local engine
+ * (`LocalBrainProvider`, shipped from `brain-core`) or — in a later, Ian-gated
+ * phase — a remote cloud service (`RemoteBrainProvider` → Arcana).
+ *
+ * Bound-tenant model: a provider instance is bound to ONE tenant at
+ * construction (e.g. `createLocalBrainProvider(t)`); methods do NOT take a
+ * `TenantContext` parameter. "A BrainProvider is one brain." This mirrors KAD's
+ * `new LocalBrainProvider(entry)` and maps 1:1 onto Arcana's
+ * `/brain/:workspace/*` endpoints (the workspace is fixed per instance).
+ *
+ * Interface invariants:
+ *   - Every method is async (uniform over local + HTTP-remote).
+ *   - Returned object fields are snake_case (the canonical brain-row shape —
+ *     see the header note in `entity.ts`).
+ *   - It never exposes a `Database` handle or a Layer-3 provider — only domain
+ *     operations cross this seam.
+ *   - Coarse-grained ("chunky, not chatty") so remote latency stays acceptable.
+ *
+ * WRITE-CONSISTENCY CAVEAT (the one genuine semantic leak, per ADR-0016):
+ *   A `LocalBrainProvider` write is *immediately* readable — write-then-read
+ *   sees the write. A future `RemoteBrainProvider` may queue writes for
+ *   outbound delivery, so its writes are *eventually* consistent: a read
+ *   immediately after a write may not yet observe it. Callers MUST NOT assume
+ *   write-then-immediately-read works identically against a remote brain. The
+ *   write methods (`remember`, `addNote`, `upsertEntity`, `pinEntity`) carry
+ *   this caveat in their own JSDoc.
+ */
+import type { TenantContext } from './tenant.js';
+import type { ConversationInput } from './conversation.js';
+import type { HybridSearchResult, HybridSearchOptions } from './search.js';
+import type { TimelineEvent } from './timeline.js';
+import type { TimelineQuery, EntityRelatedHit } from './storage.js';
+import type { Entity, EntityMention } from './entity.js';
+import type { EntityType, RelationshipType } from './constants.js';
+/** Options common to all write operations. */
+export interface WriteOpts {
+    /**
+     * Stable identifier for idempotent retries. RESERVED for the future
+     * `RemoteBrainProvider`, which sends it as the `Idempotency-Key` HTTP header
+     * (24h dedup, cached-response replay) so a partial migration can resume
+     * cleanly. `LocalBrainProvider` IGNORES it — local writes are already
+     * idempotent via the single-writer queue + UNIQUE constraints. Chat-turn
+     * callers can omit it.
+     */
+    idempotencyKey?: string;
+}
+/** Input for {@link BrainProvider.addNote}. Long-form note ingestion. */
+export interface NoteInput {
+    content: string;
+    title?: string;
+    type?: 'conversation' | 'idea' | 'file' | 'transcript' | 'note' | 'intake';
+    source_path?: string;
+}
+/** Result of {@link BrainProvider.addNote}. */
+export interface NoteResult {
+    ok: true;
+    title: string;
+    type: string;
+    /**
+     * ESTIMATED segment count (`ceil(content.length / 250)`), NOT the number of
+     * vector chunks actually indexed. A CLI-feedback figure for parity with KAD;
+     * do not treat it as an embedding count.
+     */
+    segments: number;
+    /**
+     * BEST-EFFORT count of entities touched by this note, derived from a global
+     * entity-count delta taken before/after the write. It is NOT exact per-note
+     * attribution and SKEWS under concurrent writes to the same brain (another
+     * write landing between the snapshots is counted here). A CLI-feedback
+     * figure, not an audit number.
+     */
+    entities_touched: number;
+}
+/** Result of {@link BrainProvider.pinEntity}; `null` when the entity isn't found. */
+export interface PinResult {
+    ok: true;
+    id: number;
+    name: string;
+    pinned: boolean;
+}
+/** A pinned entity, as returned by {@link BrainProvider.getPinnedEntities}. */
+export interface PinnedEntity {
+    id: number;
+    name: string;
+    type: string;
+    mention_count: number;
+    last_seen: string;
+}
+/** Result of {@link BrainProvider.recallEntity}; the full entity context. */
+export interface EntityRecall {
+    entity: Entity;
+    mentions: EntityMention[];
+    related_entities: EntityRelatedHit[];
+}
+/**
+ * A single entity↔entity edge in the renderable entity graph
+ * ({@link BrainProvider.graph}). Endpoints are entity ids (the `nodes` array
+ * carries the full {@link Entity} rows). Field names mirror KAD's
+ * `GET /brain/graph` entity-relation edge sub-shape (`relationship` /
+ * `confidence`) minus its UI-only id namespacing, so a KAD/Arcana renderer maps
+ * `source_id`→`e:<id>` without reshaping.
+ */
+export interface BrainGraphEdge {
+    source_id: number;
+    target_id: number;
+    relationship: RelationshipType;
+    confidence: number;
+    rationale?: string;
+}
+/**
+ * A renderable slice of the **entity** graph — entity nodes + typed entity↔entity
+ * edges, drawn from `entity-graph.db` ONLY.
+ *
+ * SCOPE (deliberate): this is the entity-graph primitive, NOT KAD's full
+ * `GET /brain/graph` assembly. KAD's route is a HOST-level unified graph that
+ * also folds in timeline-event nodes, sleep `memory_edges`, temporal-fact nodes
+ * and disk-scanned notes — work that crosses three DBs and walks the filesystem,
+ * which the kernel must not do (the kernel never touches the fs). A host that
+ * wants the full canvas composes this entity slice with `timeline()` + its own
+ * sleep/disk sources; the library owns only the entity graph.
+ */
+export interface BrainGraph {
+    /** Entity nodes, most-mentioned (most-connected) first — the graph anchors. */
+    nodes: Entity[];
+    /** Typed entity↔entity edges among `nodes` (closed: both endpoints are nodes). */
+    edges: BrainGraphEdge[];
+}
+/** Brain-wide counts, as returned by {@link BrainProvider.stats}. */
+export interface BrainStats {
+    timeline_rows: number;
+    fact_rows: number;
+    entity_rows: number;
+    vector_rows: number;
+    vector_backend: string;
+}
+/**
+ * Per-tenant brain operations. Bound to ONE tenant at construction; methods do
+ * NOT take a `TenantContext`. Obtain a local instance via
+ * `createLocalBrainProvider(t)` (from `@kybernesis/brain-core`).
+ */
+export interface BrainProvider {
+    /**
+     * Full store-conversation pipeline (timeline + entities + facts + embeddings).
+     *
+     * Write-consistency: local writes are immediately readable; a future remote
+     * provider may queue this write (eventually consistent — see the interface
+     * note). `opts.idempotencyKey` is reserved for the remote provider;
+     * `LocalBrainProvider` ignores it.
+     */
+    remember(input: ConversationInput, opts?: WriteOpts): Promise<void>;
+    /**
+     * Long-form note ingestion. Defaults `type='note'`, `channel='note'`.
+     *
+     * Write-consistency: same caveat as {@link remember} — local is immediate,
+     * remote may be eventually consistent. `opts.idempotencyKey` reserved for the
+     * remote provider; ignored locally.
+     */
+    addNote(input: NoteInput, opts?: WriteOpts): Promise<NoteResult>;
+    /**
+     * Idempotent entity upsert, keyed on (normalized_name, type) — the SAME name
+     * under a DIFFERENT type is a distinct entity (so `created` can be `true` for
+     * a name that already exists under another type). `type` defaults to `'topic'`.
+     * Returns the entity id and whether this call inserted a new row.
+     *
+     * `created` is best-effort: when several same-name entities exist across
+     * different types, a re-upsert of an existing one may report a false
+     * `created: true` (the pre-check resolves by name only). Exact tracking would
+     * need a storage-level created signal — treat `created` as a hint, not a gate.
+     *
+     * `type` is constrained to `EntityType` at compile time; the adapter also
+     * validates it at the seam and throws a clean error (naming the bad value +
+     * the allowed set) rather than surfacing a storage-layer CHECK violation.
+     *
+     * Write-consistency: local is immediate; remote may be eventually consistent.
+     */
+    upsertEntity(body: {
+        name: string;
+        type?: EntityType;
+    }, opts?: WriteOpts): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    /**
+     * Toggle `is_pinned` on an entity. Resolves a numeric id or a (case-
+     * insensitive) name. Returns `null` if no entity matches.
+     *
+     * Write-consistency: local is immediate; remote may be eventually consistent.
+     */
+    pinEntity(nameOrId: string, pinned: boolean, opts?: WriteOpts): Promise<PinResult | null>;
+    /**
+     * Hybrid retrieval (semantic + keyword + temporal + graph, RRF-fused).
+     *
+     * REMOTE-PHASE RISK: `HybridSearchOptions.after`/`before` are `Date` objects,
+     * which do not JSON-serialize faithfully over the wire. A future
+     * `RemoteBrainProvider` MUST marshal these Date↔ISO (and back) at the
+     * transport boundary. The `Date` type is intentional and stays (KAD depends
+     * on it); this is a transport concern for the remote adapter, not an
+     * interface change.
+     */
+    query(query: string, opts?: HybridSearchOptions): Promise<HybridSearchResult[]>;
+    /** Timeline events, newest-first, with optional filters. */
+    timeline(opts?: TimelineQuery): Promise<TimelineEvent[]>;
+    /** Full entity context (entity + recent mentions + related entities), or `null`. */
+    recallEntity(name: string): Promise<EntityRecall | null>;
+    /** Pinned entities, most-mentioned first. */
+    getPinnedEntities(): Promise<PinnedEntity[]>;
+    /**
+     * Renderable slice of the entity graph — nodes (most-mentioned first) + the
+     * typed edges among them. Coarse-grained: ONE call returns the whole
+     * renderable graph (chunky, not chatty). `opts.limit` caps the node count
+     * (default 50); edges are restricted to pairs where both endpoints are nodes,
+     * so the returned graph is always closed/drawable. Entity-graph.db only — see
+     * {@link BrainGraph} for why this is the entity slice, not KAD's full assembly.
+     */
+    graph(opts?: {
+        limit?: number;
+    }): Promise<BrainGraph>;
+    /**
+     * Flat entity list for an entities table/browser, most-mentioned (most-
+     * relevant) first, optionally filtered by `type`. `opts.limit` defaults to 50.
+     */
+    listEntities(opts?: {
+        limit?: number;
+        type?: EntityType;
+    }): Promise<Entity[]>;
+    /** Brain-wide counts (timeline / facts / entities / vectors). */
+    stats(): Promise<BrainStats>;
+    /**
+     * Run a full sleep cycle synchronously and return its metrics. `cfg` is an
+     * optional partial config override. Bound-tenant — no `TenantContext` param.
+     */
+    sleep(cfg?: SleepCycleConfig): Promise<SleepCycleMetrics>;
+}
+/**
+ * Sleep config override for {@link BrainProvider.sleep}.
+ *
+ * Opaque at the contract level so `brain-contracts` stays decoupled from the
+ * sleep tuning knobs (which live in `brain-core`). The concrete
+ * `LocalBrainProvider` accepts the real `Partial<SleepConfig>`; callers that
+ * want the typed config import `SleepConfig` from `@kybernesis/brain-core` and
+ * pass it here (assignable, since this is `unknown`).
+ */
+export type SleepCycleConfig = unknown;
+/**
+ * Sleep metrics returned by {@link BrainProvider.sleep}.
+ *
+ * Opaque at the contract level (the full per-step `RunMetrics` shape lives in
+ * `brain-core`, which is one level below `brain-contracts`). The concrete
+ * `LocalBrainProvider.sleep` returns the real `SleepRunMetrics`; callers that
+ * want the typed metrics import `SleepRunMetrics` from `@kybernesis/brain-core`
+ * and narrow this `unknown` to it. Keeping it opaque is what lets one interface
+ * serve both the local provider and a future remote one without pulling sleep
+ * internals into the shared contract.
+ */
+export type SleepCycleMetrics = unknown;
+/** Re-export for adapters that build a provider bound to a tenant. */
+export type { TenantContext };
+//# sourceMappingURL=brain-provider.d.ts.map

package/dist/brain-provider.d.ts.map

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

package/dist/brain-provider.js

@@ -0,0 +1,35 @@
+/**
+ * Layer-2 `BrainProvider` seam (ADR-0016).
+ *
+ * A coarse-grained, consumer-facing facade over brain *operations* —
+ * `remember` / `addNote` / `query` / `timeline` / entity ops / `stats` /
+ * `sleep`. It sits one level ABOVE the Layer-3 `StorageProvider` (persistence)
+ * and is the seam a consumer swaps to point a brain at a local engine
+ * (`LocalBrainProvider`, shipped from `brain-core`) or — in a later, Ian-gated
+ * phase — a remote cloud service (`RemoteBrainProvider` → Arcana).
+ *
+ * Bound-tenant model: a provider instance is bound to ONE tenant at
+ * construction (e.g. `createLocalBrainProvider(t)`); methods do NOT take a
+ * `TenantContext` parameter. "A BrainProvider is one brain." This mirrors KAD's
+ * `new LocalBrainProvider(entry)` and maps 1:1 onto Arcana's
+ * `/brain/:workspace/*` endpoints (the workspace is fixed per instance).
+ *
+ * Interface invariants:
+ *   - Every method is async (uniform over local + HTTP-remote).
+ *   - Returned object fields are snake_case (the canonical brain-row shape —
+ *     see the header note in `entity.ts`).
+ *   - It never exposes a `Database` handle or a Layer-3 provider — only domain
+ *     operations cross this seam.
+ *   - Coarse-grained ("chunky, not chatty") so remote latency stays acceptable.
+ *
+ * WRITE-CONSISTENCY CAVEAT (the one genuine semantic leak, per ADR-0016):
+ *   A `LocalBrainProvider` write is *immediately* readable — write-then-read
+ *   sees the write. A future `RemoteBrainProvider` may queue writes for
+ *   outbound delivery, so its writes are *eventually* consistent: a read
+ *   immediately after a write may not yet observe it. Callers MUST NOT assume
+ *   write-then-immediately-read works identically against a remote brain. The
+ *   write methods (`remember`, `addNote`, `upsertEntity`, `pinEntity`) carry
+ *   this caveat in their own JSDoc.
+ */
+export {};
+//# sourceMappingURL=brain-provider.js.map

package/dist/brain-provider.js.map

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

package/dist/conversation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Conversation-ingest DTO — lifted from `brain-core/src/store-conversation.ts`
+ * so the Layer-2 `BrainProvider` interface (which lives here in brain-contracts)
+ * can reference `remember`'s input shape without contracts depending on
+ * brain-core.
+ *
+ * Plain, self-contained shape (no runtime behaviour). `brain-core` imports it
+ * back and re-exports it unchanged, so existing `@kybernesis/brain-core`
+ * consumers (KAD) import `ConversationInput` from the same place as before —
+ * this move is additive and non-breaking.
+ */
+export interface ConversationInput {
+    prompt: string;
+    response: string;
+    channel: string;
+    timestamp?: string;
+    metadata?: Record<string, unknown>;
+    eventType?: 'conversation' | 'idea' | 'file' | 'transcript' | 'note' | 'intake';
+}
+//# sourceMappingURL=conversation.d.ts.map

package/dist/conversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;CACjF"}

package/dist/conversation.js

@@ -0,0 +1,13 @@
+/**
+ * Conversation-ingest DTO — lifted from `brain-core/src/store-conversation.ts`
+ * so the Layer-2 `BrainProvider` interface (which lives here in brain-contracts)
+ * can reference `remember`'s input shape without contracts depending on
+ * brain-core.
+ *
+ * Plain, self-contained shape (no runtime behaviour). `brain-core` imports it
+ * back and re-exports it unchanged, so existing `@kybernesis/brain-core`
+ * consumers (KAD) import `ConversationInput` from the same place as before —
+ * this move is additive and non-breaking.
+ */
+export {};
+//# sourceMappingURL=conversation.js.map

package/dist/conversation.js.map

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

package/dist/index.d.ts

@@ -7,4 +7,7 @@ export * from './sleep.js';
 export * from './storage.js';
 export * from './logger.js';
 export * from './reconcile-diff.js';
+export * from './conversation.js';
+export * from './search.js';
+export * from './brain-provider.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,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,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;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -7,4 +7,7 @@ export * from './sleep.js';
 export * from './storage.js';
 export * from './logger.js';
 export * from './reconcile-diff.js';
+export * from './conversation.js';
+export * from './search.js';
+export * from './brain-provider.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,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,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;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC"}

package/dist/search.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Hybrid-search DTOs — lifted from `brain-core/src/hybrid-search.ts` so the
+ * Layer-2 `BrainProvider` interface (which lives here in brain-contracts) can
+ * reference them without contracts depending on brain-core.
+ *
+ * These are plain, self-contained shapes (no runtime behaviour). `brain-core`
+ * imports them back and re-exports them unchanged, so existing
+ * `@kybernesis/brain-core` consumers (KAD) import them from the same place as
+ * before — this move is additive and non-breaking.
+ *
+ * Field names are snake_case where they mirror DB-derived rows (the load-bearing
+ * convention — see the header note in `entity.ts`); the camelCase fields here
+ * (`semanticScore`, `hybridScore`, …) are pre-existing computed scores carried
+ * over verbatim from KAD's hybrid-search result, NOT new additions.
+ */
+export interface HybridSearchResult {
+    id: string;
+    title: string;
+    content: string;
+    source_path: string;
+    timestamp: string;
+    type: string;
+    tier?: string;
+    priority?: number;
+    tags?: string[];
+    semanticScore: number;
+    metadataScore: number;
+    hybridScore: number;
+    matchType: 'semantic' | 'keyword' | 'both';
+    relatedMemories?: string[];
+    /** Raw vector distance from the semantic arm (lower = closer), BEFORE RRF
+     *  rank-collapse — exposed so callers can judge match strength (RRF otherwise
+     *  discards it). NOTE: this is the raw store distance (L2 via vec_distance_l2);
+     *  its scale depends on the injected embedder (unbounded; ~[0,2] only for
+     *  unit-normalized vectors). NOT a calibrated 0–1 similarity — callers must
+     *  calibrate to their embedder. Undefined if not a semantic hit. Additive. */
+    rawSemanticDistance?: number;
+    /** Raw keyword-arm relevance score (higher = better), pre-RRF. Undefined if
+     *  not a keyword hit. */
+    rawKeywordScore?: number;
+}
+export interface HybridSearchOptions {
+    limit?: number;
+    tier?: 'hot' | 'warm' | 'archive' | 'all';
+    minPriority?: number;
+    includeRelated?: boolean;
+    semanticWeight?: number;
+    metadataWeight?: number;
+    type?: 'conversation' | 'idea' | 'file' | 'transcript' | 'note';
+    entity?: string;
+    entityMatch?: 'all' | 'any';
+    after?: Date;
+    before?: Date;
+    expandQuery?: boolean;
+    factFirst?: boolean;
+    rerank?: boolean;
+    /** Run the relational graph arm (Channel 5) when the query parses as a
+     *  relationship question. Default ON — but the parser gate means it only
+     *  fires for relational queries, so non-relational retrieval is unaffected.
+     *  Set false to disable entirely (kill switch). */
+    useRelational?: boolean;
+    /** Run the entity-LOOKUP archetype ("what is X / who is X") within the
+     *  relational arm. Default OFF — measured break-even on knowledge brains
+     *  (+entity, −recall, net +1 probe; gap-analysis #8). Opt in for entity/
+     *  lookup-heavy corpora (e.g. Arcana). Requires useRelational. */
+    useLookup?: boolean;
+    /** KYB-80: weight fact scores by read-time decayed confidence in the
+     *  factFirst path. Default OFF — gated on brain-bench. No effect unless
+     *  factFirst is also set. */
+    useDecay?: boolean;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAC3C,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;kFAK8E;IAC9E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;6BACyB;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,CAAC;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAC5B,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;uDAGmD;IACnD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;sEAGkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;iCAE6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/search.js

@@ -0,0 +1,17 @@
+/**
+ * Hybrid-search DTOs — lifted from `brain-core/src/hybrid-search.ts` so the
+ * Layer-2 `BrainProvider` interface (which lives here in brain-contracts) can
+ * reference them without contracts depending on brain-core.
+ *
+ * These are plain, self-contained shapes (no runtime behaviour). `brain-core`
+ * imports them back and re-exports them unchanged, so existing
+ * `@kybernesis/brain-core` consumers (KAD) import them from the same place as
+ * before — this move is additive and non-breaking.
+ *
+ * Field names are snake_case where they mirror DB-derived rows (the load-bearing
+ * convention — see the header note in `entity.ts`); the camelCase fields here
+ * (`semanticScore`, `hybridScore`, …) are pre-existing computed scores carried
+ * over verbatim from KAD's hybrid-search result, NOT new additions.
+ */
+export {};
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

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

package/package.json

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