@pellux/goodvibes-sdk 0.38.0 → 1.1.0

package/dist/platform/state/code-index-reindex.js

@@ -0,0 +1,156 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * CodeIndexReindexScheduler — Stage B tool-site reindex hooks.
+ *
+ * After a successful file-writing tool call (write / edit, including the edit
+ * tool's notebook operations), the touched path(s) are scheduled for an
+ * incremental `CodeIndexStore.reindexFile()`. Three properties the brief asks
+ * for, all enforced here rather than at the (two) tool-execution call sites:
+ *
+ *  1. NEVER BLOCKS THE TURN. `onToolExecuted` only records paths and arms a
+ *     timer; the reindex runs later, off the tool-result path. Nothing here is
+ *     awaited by the caller.
+ *
+ *  2. DEBOUNCED + COALESCED, per path. Each touched path gets its own timer;
+ *     re-touching the same path before its quiet window elapses resets that
+ *     path's timer, so a phased edit or several edits to one file in a turn
+ *     collapse to a SINGLE reindex. Distinct paths reindex independently, each
+ *     after its own quiet window. Timers are `unref()`'d so a pending reindex
+ *     never keeps the process alive.
+ *
+ *  3. NO-OP WHEN THERE IS NOTHING TO MAINTAIN, and CONTAINED FAILURE. At fire
+ *     time the scheduler re-checks (live, so a runtime toggle is respected)
+ *     that the code index is enabled AND already built (available &&
+ *     indexedChunks > 0) — reindexing a single file into an index that was
+ *     never built would fabricate a misleading one-file index, so that case is
+ *     a silent no-op. `reindexFile` is cheap when the file is unchanged
+ *     (hash-gated). Any error is caught, logged, and recorded as the last
+ *     activity — it never rethrows into the turn.
+ *
+ * The most-recent completed reindex is exposed via `lastActivity()` for honest
+ * surfacing (e.g. TUI `/codebase status`).
+ */
+import { resolve as resolvePathAbsolute } from 'node:path';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+/** Default per-path debounce window: long enough to coalesce a burst of edits to one file, short enough that the index trails the working tree by well under a second. */
+export const DEFAULT_REINDEX_DEBOUNCE_MS = 300;
+/**
+ * Tool names whose successful execution touches files worth reindexing, and the
+ * argument shapes that carry the touched path(s). `write` carries `files[].path`;
+ * `edit` carries `edits[].path` plus an optional `notebook_operations.path`. A
+ * top-level `path`/`file_path` is also honored for robustness against tool
+ * variants. Anything else yields no paths (no-op).
+ */
+export function extractReindexPaths(toolName, args) {
+    if (toolName !== 'write' && toolName !== 'edit')
+        return [];
+    const paths = new Set();
+    const addIfString = (value) => {
+        if (typeof value === 'string' && value.trim().length > 0)
+            paths.add(value);
+    };
+    addIfString(args['path']);
+    addIfString(args['file_path']);
+    const files = args['files'];
+    if (Array.isArray(files)) {
+        for (const file of files) {
+            if (file && typeof file === 'object')
+                addIfString(file['path']);
+        }
+    }
+    const edits = args['edits'];
+    if (Array.isArray(edits)) {
+        for (const edit of edits) {
+            if (edit && typeof edit === 'object')
+                addIfString(edit['path']);
+        }
+    }
+    const notebookOps = args['notebook_operations'];
+    if (notebookOps && typeof notebookOps === 'object') {
+        addIfString(notebookOps['path']);
+    }
+    return [...paths];
+}
+export class CodeIndexReindexScheduler {
+    deps;
+    timers = new Map();
+    inFlight = new Set();
+    last = null;
+    debounceMs;
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.debounceMs = deps.debounceMs ?? DEFAULT_REINDEX_DEBOUNCE_MS;
+        this.now = deps.now ?? Date.now;
+    }
+    /**
+     * Entry point wired into both tool-execution loops. A no-op for a failed call
+     * or a non-file tool. Extracts touched paths and schedules each (debounced).
+     * Returns immediately — never awaits a reindex.
+     */
+    onToolExecuted(toolName, args, success) {
+        if (!success)
+            return;
+        for (const p of extractReindexPaths(toolName, args)) {
+            this.schedule(resolvePathAbsolute(this.deps.workingDirectory, p));
+        }
+    }
+    /** Arm (or reset) the per-path debounce timer for one absolute path. */
+    schedule(absPath) {
+        const existing = this.timers.get(absPath);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.timers.delete(absPath);
+            this.track(this.runReindex(absPath));
+        }, this.debounceMs);
+        timer.unref?.();
+        this.timers.set(absPath, timer);
+    }
+    /** The most recent reindex the scheduler actually ran, or null if none has completed. */
+    lastActivity() {
+        return this.last;
+    }
+    /** Count of paths with a pending (debouncing) reindex. */
+    pendingCount() {
+        return this.timers.size;
+    }
+    /** Test/shutdown helper: fire every pending debounce timer now and await all in-flight reindexes. */
+    async flush() {
+        for (const [path, timer] of [...this.timers]) {
+            clearTimeout(timer);
+            this.timers.delete(path);
+            this.track(this.runReindex(path));
+        }
+        await Promise.allSettled([...this.inFlight]);
+    }
+    /** Cancel every pending timer (does not touch in-flight reindexes). */
+    dispose() {
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+    }
+    track(promise) {
+        this.inFlight.add(promise);
+        void promise.finally(() => this.inFlight.delete(promise));
+    }
+    async runReindex(absPath) {
+        // Live gates — respect a runtime toggle of the setting and never fabricate a
+        // one-file index when nothing was ever built.
+        if (this.deps.isEnabled && !this.deps.isEnabled())
+            return;
+        const stats = this.deps.target.stats();
+        if (!stats.available || stats.indexedChunks === 0)
+            return;
+        try {
+            const { indexed, mode } = await this.deps.target.reindexFile(absPath);
+            this.last = { path: absPath, at: this.now(), status: indexed ? 'indexed' : 'skipped', mode };
+        }
+        catch (err) {
+            const error = summarizeError(err);
+            logger.warn('Code index incremental reindex failed', { path: absPath, error });
+            this.last = { path: absPath, at: this.now(), status: 'error', error };
+        }
+    }
+}

package/dist/platform/state/code-index-store.d.ts.map

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

package/dist/platform/state/code-index-store.js

@@ -1,7 +1,7 @@
 /** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
 /**
  * CodeIndexStore — an incremental, tree-sitter-chunked, embedding-backed index
- * of a repo's source tree (Wave-5, W5.3, Stage A).
+ * of a repo's source tree (Stage A; see CHANGELOG 0.38.0).
  *
  * Deliberately MIRRORS MemoryStore + SqliteVecMemoryIndex (state/memory-store.ts,
  * state/memory-vector-store.ts) rather than reusing them: those classes are
@@ -54,7 +54,7 @@
  */
 import { dirname, join, relative, sep } from 'node:path';
 import { mkdirSync, statSync } from 'node:fs';
-import { Database } from 'bun:sqlite';
+import { createRequire } from 'node:module';
 import { loadSqliteVecExtension } from './sqlite-vec-loader.js';
 import { HASHED_MEMORY_EMBEDDING_PROVIDER, MemoryEmbeddingProviderRegistry, normalizeMemoryEmbeddingVector, } from './memory-embeddings.js';
 import { MEMORY_VECTOR_DIMS } from './memory-vector-store.js';
@@ -64,6 +64,14 @@ import { CHUNK_ROW_COLUMNS, EMBEDDING_PROVIDER_META_KEY, createCodeIndexSchema,
 import { buildGitignoreMatcher, collectGlobFiles, createFindDiagnostics, findNestedGitignoreFiles, isBinary, readTextFile, } from '../tools/find/shared.js';
 import { logger } from '../utils/logger.js';
 import { summarizeError } from '../utils/error-display.js';
+// bun:sqlite is a Bun-only builtin; a static import makes this module unloadable
+// under Node (breaks the release install-smoke check). Lazily require the ctor so
+// the `bun:` specifier stays off the static graph — only pulled on the Bun-only
+// path that opens a database.
+let bunDatabaseCtor = null;
+function bunSqliteDatabase() {
+    return (bunDatabaseCtor ??= createRequire(import.meta.url)('bun:sqlite').Database);
+}
 const DEFAULT_MAX_FILES = 5000;
 const DEFAULT_MAX_FILE_BYTES = 512 * 1024;
 const DEFAULT_MAX_TOTAL_BYTES = 256 * 1024 * 1024;
@@ -122,7 +130,7 @@ export class CodeIndexStore {
             if (this.dbPath !== ':memory:') {
                 mkdirSync(dirname(this.dbPath), { recursive: true });
             }
-            this.db = new Database(this.dbPath);
+            this.db = new (bunSqliteDatabase())(this.dbPath);
             loadSqliteVecExtension(this.db);
             this.available = true;
             createCodeIndexSchema(this.db);

package/dist/platform/state/index.d.ts

@@ -19,6 +19,12 @@ export { MemoryStore } from './memory-store.js';
 export { MemoryRegistry } from './memory-registry.js';
 export type { MemoryBundle, MemoryClass, MemoryRecord, MemoryLink, MemoryAddOptions, MemorySearchFilter, MemorySemanticSearchResult, MemoryStoreOptions, MemoryDoctorReport, MemoryScope, MemoryReviewState, ProvenanceLink, ProvenanceLinkKind, } from './memory-store.js';
 export { buildIncidentMemoryAddOptions, buildMcpSecurityMemoryAddOptions, buildPluginSecurityMemoryAddOptions, buildPolicyPreflightMemoryAddOptions, } from './memory-ingest.js';
+export { resolveCanonicalMemoryDbPath, foldMemoryStores, formatMemoryFoldReport, } from './canonical-memory.js';
+export type { LegacyMemorySource, MemoryFoldSourceReport, MemoryFoldReport, FoldMemoryStoresOptions, } from './canonical-memory.js';
+export { MIN_PROMPT_MEMORY_CONFIDENCE, describeMemoryPromptEligibility, isPromptActiveMemory, describeMemoryIndexUnavailable, describeMemoryIndexCaveat, runHonestMemorySearch, } from './memory-recall-contract.js';
+export type { MemoryPromptEligibility, HonestSearchStore, HonestMemorySearchOptions, HonestMemorySearchResult, } from './memory-recall-contract.js';
+export { VIBE_PERSONA_TAG, VIBE_PROJECTION_HEADING, VIBE_PROJECTION_CAVEAT, selectVibeRecords, renderVibeProjection, vibeBodyToConstraintOptions, } from './vibe-projection.js';
+export type { VibeProjectionOptions, VibeImportOptions } from './vibe-projection.js';
 export { MEMORY_VECTOR_DIMS, embedMemoryText, resolveMemoryVectorDbPath, SqliteVecMemoryIndex, } from './memory-vector-store.js';
 export type { MemoryVectorCandidate, MemoryVectorStats } from './memory-vector-store.js';
 export { DEFAULT_MEMORY_EMBEDDING_DIMS, HASHED_MEMORY_EMBEDDING_PROVIDER, MemoryEmbeddingProviderRegistry, normalizeMemoryEmbeddingVector, } from './memory-embeddings.js';
@@ -28,4 +34,6 @@ export type { KnowledgeInjection, ScoredKnowledgeInjection } from './knowledge-i
 export { selectKnowledgeForTask, selectKnowledgeForTaskScored, buildKnowledgeInjectionPrompt } from './knowledge-injection.js';
 export { CodeIndexStore } from './code-index-store.js';
 export type { CodeChunk, CodeChunkMode, CodeContextResult, CodeIndexBuildProgress, CodeIndexBuildStats, CodeIndexOptions, CodeIndexSkipReport, CodeIndexStats, } from './code-index-store.js';
+export { CodeIndexReindexScheduler, extractReindexPaths, DEFAULT_REINDEX_DEBOUNCE_MS, } from './code-index-reindex.js';
+export type { CodeIndexReindexActivity, CodeIndexReindexTarget, CodeIndexReindexSchedulerDeps, } from './code-index-reindex.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/platform/state/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,6BAA6B,EAC7B,gCAAgC,EAChC,mCAAmC,EACnC,oCAAoC,GACrC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACzF,OAAO,EACL,6BAA6B,EAC7B,gCAAgC,EAChC,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qCAAqC,EAAE,MAAM,4BAA4B,CAAC;AACnF,YAAY,EACV,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,6BAA6B,EAC7B,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAC/H,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,GACf,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/state/index.ts"],"names":[],"mappings":"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"}

package/dist/platform/state/index.js

@@ -12,8 +12,12 @@ export { FileUndoManager } from './file-undo.js';
 export { MemoryStore } from './memory-store.js';
 export { MemoryRegistry } from './memory-registry.js';
 export { buildIncidentMemoryAddOptions, buildMcpSecurityMemoryAddOptions, buildPluginSecurityMemoryAddOptions, buildPolicyPreflightMemoryAddOptions, } from './memory-ingest.js';
+export { resolveCanonicalMemoryDbPath, foldMemoryStores, formatMemoryFoldReport, } from './canonical-memory.js';
+export { MIN_PROMPT_MEMORY_CONFIDENCE, describeMemoryPromptEligibility, isPromptActiveMemory, describeMemoryIndexUnavailable, describeMemoryIndexCaveat, runHonestMemorySearch, } from './memory-recall-contract.js';
+export { VIBE_PERSONA_TAG, VIBE_PROJECTION_HEADING, VIBE_PROJECTION_CAVEAT, selectVibeRecords, renderVibeProjection, vibeBodyToConstraintOptions, } from './vibe-projection.js';
 export { MEMORY_VECTOR_DIMS, embedMemoryText, resolveMemoryVectorDbPath, SqliteVecMemoryIndex, } from './memory-vector-store.js';
 export { DEFAULT_MEMORY_EMBEDDING_DIMS, HASHED_MEMORY_EMBEDDING_PROVIDER, MemoryEmbeddingProviderRegistry, normalizeMemoryEmbeddingVector, } from './memory-embeddings.js';
 export { createBuiltinMemoryEmbeddingProviders } from './memory-embedding-http.js';
 export { selectKnowledgeForTask, selectKnowledgeForTaskScored, buildKnowledgeInjectionPrompt } from './knowledge-injection.js';
 export { CodeIndexStore } from './code-index-store.js';
+export { CodeIndexReindexScheduler, extractReindexPaths, DEFAULT_REINDEX_DEBOUNCE_MS, } from './code-index-reindex.js';

package/dist/platform/state/memory-recall-contract.d.ts

@@ -0,0 +1,118 @@
+/**
+ * memory-recall-contract.ts — the CROSS-SURFACE recall-honesty contract (see CHANGELOG 1.0.0).
+ *
+ * PROVENANCE. This is the agent's memory-honesty discipline, promoted
+ * verbatim from a single surface (the agent's memory-prompt.ts) into the SDK so it
+ * is ONE shared contract, not a discipline re-derived (and re-weakened) per surface.
+ * Under memory unification the store is unified and cross-surface, which multiplies the cost of a
+ * dishonest recall — so this discipline becomes MORE load-bearing, not less. A
+ * unified store must not be able to lie more loudly than the siloed one did.
+ *
+ * The contract is three rules:
+ *   1. INJECTION FLOOR = the store's own declared baseline trust (60), never higher.
+ *      MemoryStore.add() stamps every new record at confidence 60 unless the caller
+ *      says otherwise. A floor above 60 would starve every honestly-stored fact — a
+ *      freshly-learned fact could never clear recall on its own. The floor trusts a
+ *      record exactly as much as the store already vouches for it; anything stored
+ *      BELOW 60 (explicitly marked less certain) still does not qualify.
+ *   2. FLAGGED RECORDS ARE NEVER INJECTED. stale/contradicted records are excluded
+ *      outright, regardless of confidence — the surface already knows they are wrong
+ *      or superseded, so no confidence number buys them back into a prompt.
+ *   3. DEGRADED STATES ARE HONEST, NOT SILENT. an unavailable semantic index yields
+ *      a STATED reason and a literal fallback — never a silent empty result that
+ *      reads as "nothing was ever stored." 'no match' and 'index unavailable' are
+ *      distinct and both said out loud.
+ */
+import type { MemoryRecord, MemorySearchFilter, MemorySemanticSearchResult } from './memory-store.js';
+import type { MemoryVectorStats } from './memory-vector-store.js';
+/**
+ * Recall-prompt confidence floor. Tied to the store's own baseline: MemoryStore.add
+ * stamps new records at confidence 60. This is NOT a number chosen to make things
+ * pass — it is the store's own definition of "a real, usable fact."
+ */
+export declare const MIN_PROMPT_MEMORY_CONFIDENCE = 60;
+export interface MemoryPromptEligibility {
+    readonly eligible: boolean;
+    /** Why this record did or did not clear the recall floor — confidence, review state, and provenance, never silent. */
+    readonly reason: string;
+}
+/**
+ * Recall-eligibility decision for one record, with an honest human-readable reason
+ * attached (never a silent yes/no). This is the receipt every surface surfaces.
+ *
+ * Flagged records (stale/contradicted) are excluded outright regardless of
+ * confidence. Everything else is judged on its own stored confidence against
+ * MIN_PROMPT_MEMORY_CONFIDENCE — the store's own baseline. Nothing is blanket-boosted.
+ */
+export declare function describeMemoryPromptEligibility(record: MemoryRecord): MemoryPromptEligibility;
+export declare function isPromptActiveMemory(record: MemoryRecord): boolean;
+/**
+ * A HARD unavailable reason: the semantic index cannot be consulted at all, so a
+ * search must fall back to a literal scan and SAY SO — never a silent empty result
+ * that reads as "no memory matches" when the index was never asked. Returns null
+ * when the index is available and can be consulted.
+ */
+export declare function describeMemoryIndexUnavailable(stats: MemoryVectorStats): string | null;
+/**
+ * A SOFT caveat: the index is up and consulted, but running on the built-in
+ * hashed-only fallback embedding provider rather than a modeled semantic provider.
+ * Still ranks real matches better than a literal scan, but say so rather than
+ * presenting it as equivalent. Returns null when a real provider is configured.
+ */
+export declare function describeMemoryIndexCaveat(stats: MemoryVectorStats): string | null;
+/**
+ * The minimal read surface a honest search needs. MemoryStore (and MemoryRegistry)
+ * satisfy this structurally — the function stays decoupled from either concrete
+ * class so it can run over any store that exposes the three read paths.
+ */
+export interface HonestSearchStore {
+    search(filter: MemorySearchFilter): MemoryRecord[];
+    searchSemantic(filter: MemorySearchFilter): MemorySemanticSearchResult[];
+    vectorStats(): MemoryVectorStats;
+}
+export interface HonestMemorySearchOptions {
+    /**
+     * Apply the recall-INJECTION contract to the result set: exclude flagged
+     * (stale/contradicted) records outright and drop records below the confidence
+     * floor, counting each exclusion honestly. Off by default — a review/browse
+     * caller wants to SEE flagged and low-confidence records; only a prompt-recall
+     * caller filters them out.
+     */
+    readonly recall?: boolean | undefined;
+}
+/**
+ * The honest search envelope. `records` is what a caller should use; the rest is
+ * the receipt: which path actually ran, and — when a degraded path was taken —
+ * WHY, out loud. A wire client and a local surface serialize the SAME envelope, so
+ * the honesty contract cannot be re-weakened per surface.
+ */
+export interface HonestMemorySearchResult {
+    readonly records: readonly MemoryRecord[];
+    /** The path that actually ran. `'literal'` even when semantic was requested but the index could not be consulted. */
+    readonly mode: 'literal' | 'semantic';
+    readonly requestedSemantic: boolean;
+    /** Non-null ONLY when semantic was requested and the index could not be consulted, forcing the literal fallback. The stated reason — never a silent empty. */
+    readonly indexUnavailableReason: string | null;
+    /** Soft caveat when the semantic path ran on the hashed-only fallback provider. */
+    readonly caveat: string | null;
+    /** Whether the recall-injection contract filtered the set (options.recall). */
+    readonly recallFiltered: boolean;
+    readonly excludedFlaggedCount: number;
+    readonly excludedBelowFloorCount: number;
+    /** Result count BEFORE any recall-injection filtering — so a caller can tell "index empty" from "everything filtered out". */
+    readonly totalBeforeRecallFilter: number;
+}
+/**
+ * Run a search that HONORS the recall-honesty contract end to end:
+ *  - semantic requested + index consultable → semantic ranking (+ soft caveat when
+ *    on the hashed fallback provider);
+ *  - semantic requested + index NOT consultable → literal scan WITH the stated
+ *    `indexUnavailableReason`, never a silent empty that reads as "nothing stored";
+ *  - `recall: true` → flagged records excluded outright and sub-floor records
+ *    dropped, each exclusion counted rather than silently vanished.
+ *
+ * This is the ONE composition every surface (daemon route, wire client, offline
+ * local store) calls, so the contract is applied identically everywhere.
+ */
+export declare function runHonestMemorySearch(store: HonestSearchStore, filter?: MemorySearchFilter, options?: HonestMemorySearchOptions): HonestMemorySearchResult;
+//# sourceMappingURL=memory-recall-contract.d.ts.map

package/dist/platform/state/memory-recall-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-recall-contract.d.ts","sourceRoot":"","sources":["../../../src/platform/state/memory-recall-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AACtG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAE/C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,sHAAsH;IACtH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAOD;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,YAAY,GAAG,uBAAuB,CAkB7F;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAKtF;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAKjF;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,EAAE,CAAC;IACnD,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,0BAA0B,EAAE,CAAC;IACzE,WAAW,IAAI,iBAAiB,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,qHAAqH;IACrH,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,8JAA8J;IAC9J,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,8HAA8H;IAC9H,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,iBAAiB,EACxB,MAAM,GAAE,kBAAuB,EAC/B,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CA+D1B"}

package/dist/platform/state/memory-recall-contract.js

@@ -0,0 +1,170 @@
+/**
+ * memory-recall-contract.ts — the CROSS-SURFACE recall-honesty contract (see CHANGELOG 1.0.0).
+ *
+ * PROVENANCE. This is the agent's memory-honesty discipline, promoted
+ * verbatim from a single surface (the agent's memory-prompt.ts) into the SDK so it
+ * is ONE shared contract, not a discipline re-derived (and re-weakened) per surface.
+ * Under memory unification the store is unified and cross-surface, which multiplies the cost of a
+ * dishonest recall — so this discipline becomes MORE load-bearing, not less. A
+ * unified store must not be able to lie more loudly than the siloed one did.
+ *
+ * The contract is three rules:
+ *   1. INJECTION FLOOR = the store's own declared baseline trust (60), never higher.
+ *      MemoryStore.add() stamps every new record at confidence 60 unless the caller
+ *      says otherwise. A floor above 60 would starve every honestly-stored fact — a
+ *      freshly-learned fact could never clear recall on its own. The floor trusts a
+ *      record exactly as much as the store already vouches for it; anything stored
+ *      BELOW 60 (explicitly marked less certain) still does not qualify.
+ *   2. FLAGGED RECORDS ARE NEVER INJECTED. stale/contradicted records are excluded
+ *      outright, regardless of confidence — the surface already knows they are wrong
+ *      or superseded, so no confidence number buys them back into a prompt.
+ *   3. DEGRADED STATES ARE HONEST, NOT SILENT. an unavailable semantic index yields
+ *      a STATED reason and a literal fallback — never a silent empty result that
+ *      reads as "nothing was ever stored." 'no match' and 'index unavailable' are
+ *      distinct and both said out loud.
+ */
+import { HASHED_MEMORY_EMBEDDING_PROVIDER } from './memory-embeddings.js';
+/**
+ * Recall-prompt confidence floor. Tied to the store's own baseline: MemoryStore.add
+ * stamps new records at confidence 60. This is NOT a number chosen to make things
+ * pass — it is the store's own definition of "a real, usable fact."
+ */
+export const MIN_PROMPT_MEMORY_CONFIDENCE = 60;
+function provenanceSummary(record) {
+    if (record.provenance.length === 0)
+        return 'no provenance recorded';
+    return `provenance ${record.provenance.slice(0, 2).map((entry) => `${entry.kind}:${entry.ref}`).join(', ')}`;
+}
+/**
+ * Recall-eligibility decision for one record, with an honest human-readable reason
+ * attached (never a silent yes/no). This is the receipt every surface surfaces.
+ *
+ * Flagged records (stale/contradicted) are excluded outright regardless of
+ * confidence. Everything else is judged on its own stored confidence against
+ * MIN_PROMPT_MEMORY_CONFIDENCE — the store's own baseline. Nothing is blanket-boosted.
+ */
+export function describeMemoryPromptEligibility(record) {
+    const provenance = provenanceSummary(record);
+    if (record.reviewState === 'stale' || record.reviewState === 'contradicted') {
+        return {
+            eligible: false,
+            reason: `reviewState is ${record.reviewState} — flagged memory is never injected regardless of confidence (${provenance})`,
+        };
+    }
+    if (record.confidence < MIN_PROMPT_MEMORY_CONFIDENCE) {
+        return {
+            eligible: false,
+            reason: `confidence ${record.confidence}% is below the ${MIN_PROMPT_MEMORY_CONFIDENCE}% recall floor (${provenance})`,
+        };
+    }
+    return {
+        eligible: true,
+        reason: `confidence ${record.confidence}% clears the ${MIN_PROMPT_MEMORY_CONFIDENCE}% recall floor, reviewState ${record.reviewState} (${provenance})`,
+    };
+}
+export function isPromptActiveMemory(record) {
+    return describeMemoryPromptEligibility(record).eligible;
+}
+/**
+ * A HARD unavailable reason: the semantic index cannot be consulted at all, so a
+ * search must fall back to a literal scan and SAY SO — never a silent empty result
+ * that reads as "no memory matches" when the index was never asked. Returns null
+ * when the index is available and can be consulted.
+ */
+export function describeMemoryIndexUnavailable(stats) {
+    if (!stats.enabled)
+        return 'the semantic memory index is disabled for this store';
+    if (!stats.available)
+        return `the semantic memory index is unavailable${stats.error ? `: ${stats.error}` : ''}`;
+    if (stats.indexedRecords === 0)
+        return 'the semantic memory index has no indexed records yet';
+    return null;
+}
+/**
+ * A SOFT caveat: the index is up and consulted, but running on the built-in
+ * hashed-only fallback embedding provider rather than a modeled semantic provider.
+ * Still ranks real matches better than a literal scan, but say so rather than
+ * presenting it as equivalent. Returns null when a real provider is configured.
+ */
+export function describeMemoryIndexCaveat(stats) {
+    if (stats.embeddingProviderId === HASHED_MEMORY_EMBEDDING_PROVIDER.id) {
+        return 'running on the hashed-only fallback embedding provider (no dedicated semantic model configured) — ranking is approximate, not modeled semantic understanding';
+    }
+    return null;
+}
+/**
+ * Run a search that HONORS the recall-honesty contract end to end:
+ *  - semantic requested + index consultable → semantic ranking (+ soft caveat when
+ *    on the hashed fallback provider);
+ *  - semantic requested + index NOT consultable → literal scan WITH the stated
+ *    `indexUnavailableReason`, never a silent empty that reads as "nothing stored";
+ *  - `recall: true` → flagged records excluded outright and sub-floor records
+ *    dropped, each exclusion counted rather than silently vanished.
+ *
+ * This is the ONE composition every surface (daemon route, wire client, offline
+ * local store) calls, so the contract is applied identically everywhere.
+ */
+export function runHonestMemorySearch(store, filter = {}, options = {}) {
+    const requestedSemantic = filter.semantic === true;
+    let mode = 'literal';
+    let indexUnavailableReason = null;
+    let caveat = null;
+    let baseRecords;
+    if (requestedSemantic) {
+        const stats = store.vectorStats();
+        indexUnavailableReason = describeMemoryIndexUnavailable(stats);
+        if (indexUnavailableReason !== null) {
+            // Honest degrade: the index cannot be consulted, so fall back to a literal
+            // scan and SAY SO via indexUnavailableReason.
+            baseRecords = store.search({ ...filter, semantic: false });
+        }
+        else {
+            mode = 'semantic';
+            caveat = describeMemoryIndexCaveat(stats);
+            baseRecords = store.searchSemantic(filter).map((entry) => entry.record);
+        }
+    }
+    else {
+        baseRecords = store.search(filter);
+    }
+    const totalBeforeRecallFilter = baseRecords.length;
+    if (!options.recall) {
+        return {
+            records: baseRecords,
+            mode,
+            requestedSemantic,
+            indexUnavailableReason,
+            caveat,
+            recallFiltered: false,
+            excludedFlaggedCount: 0,
+            excludedBelowFloorCount: 0,
+            totalBeforeRecallFilter,
+        };
+    }
+    const kept = [];
+    let excludedFlaggedCount = 0;
+    let excludedBelowFloorCount = 0;
+    for (const record of baseRecords) {
+        if (isPromptActiveMemory(record)) {
+            kept.push(record);
+            continue;
+        }
+        if (record.reviewState === 'stale' || record.reviewState === 'contradicted') {
+            excludedFlaggedCount += 1;
+        }
+        else {
+            excludedBelowFloorCount += 1;
+        }
+    }
+    return {
+        records: kept,
+        mode,
+        requestedSemantic,
+        indexUnavailableReason,
+        caveat,
+        recallFiltered: true,
+        excludedFlaggedCount,
+        excludedBelowFloorCount,
+        totalBeforeRecallFilter,
+    };
+}

package/dist/platform/state/memory-registry.d.ts

@@ -1,6 +1,7 @@
 import type { MemoryAddOptions, MemoryBundle, MemoryDoctorReport, MemoryLink, MemoryRecord, MemoryReviewPatch, MemoryScope, MemorySearchFilter, MemorySemanticSearchResult, MemoryStore } from './memory-store.js';
 import type { MemoryVectorStats } from './memory-vector-store.js';
 import type { MemoryImportResult } from './memory-store.js';
+import { type HonestMemorySearchOptions, type HonestMemorySearchResult } from './memory-recall-contract.js';
 /**
  * MemoryRegistry — thin observable wrapper around the MemoryStore.
  * Panels subscribe via listeners; commands push/retrieve through this.
@@ -15,6 +16,13 @@ export declare class MemoryRegistry {
     add(opts: MemoryAddOptions): Promise<MemoryRecord>;
     search(filter?: MemorySearchFilter): MemoryRecord[];
     searchSemantic(filter?: MemorySearchFilter): MemorySemanticSearchResult[];
+    /**
+     * Search honoring the recall-honesty contract: semantic-or-literal with a stated
+     * fallback reason when the index is unavailable, and (with `options.recall`) the
+     * flagged/confidence-floor exclusion. This is the method a wire client and an
+     * offline surface both route through, so the honesty is identical either way.
+     */
+    honestSearch(filter?: MemorySearchFilter, options?: HonestMemorySearchOptions): HonestMemorySearchResult;
     rebuildVectors(): MemoryVectorStats;
     rebuildVectorsAsync(): Promise<MemoryVectorStats>;
     vectorStats(): MemoryVectorStats;

package/dist/platform/state/memory-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-registry.d.ts","sourceRoot":"","sources":["../../../src/platform/state/memory-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACnN,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAyB;gBAE9B,KAAK,EAAE,WAAW;IAI9B,QAAQ,IAAI,WAAW;IAIvB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAOrC,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAMxD,MAAM,CAAC,MAAM,GAAE,kBAAuB,GAAG,YAAY,EAAE;IAIvD,cAAc,CAAC,MAAM,GAAE,kBAAuB,GAAG,0BAA0B,EAAE;IAI7E,cAAc,IAAI,iBAAiB;IAI7B,mBAAmB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIvD,WAAW,IAAI,iBAAiB;IAI1B,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI3C,WAAW,CAAC,KAAK,SAAK,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,EAAE;IAI5D,YAAY,CAAC,MAAM,GAAE,kBAAuB,GAAG,YAAY;IAIrD,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMrE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI9B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAMtF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,EAAE;IAIlC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,YAAY,GAAG,IAAI;IAM3H,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,IAAI;IAMjE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAM3B,MAAM,IAAI,YAAY,EAAE;CAGzB"}
+{"version":3,"file":"memory-registry.d.ts","sourceRoot":"","sources":["../../../src/platform/state/memory-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACnN,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAyB,KAAK,yBAAyB,EAAE,KAAK,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEnI;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAyB;gBAE9B,KAAK,EAAE,WAAW;IAI9B,QAAQ,IAAI,WAAW;IAIvB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAOrC,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAMxD,MAAM,CAAC,MAAM,GAAE,kBAAuB,GAAG,YAAY,EAAE;IAIvD,cAAc,CAAC,MAAM,GAAE,kBAAuB,GAAG,0BAA0B,EAAE;IAI7E;;;;;OAKG;IACH,YAAY,CAAC,MAAM,GAAE,kBAAuB,EAAE,OAAO,GAAE,yBAA8B,GAAG,wBAAwB;IAIhH,cAAc,IAAI,iBAAiB;IAI7B,mBAAmB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIvD,WAAW,IAAI,iBAAiB;IAI1B,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI3C,WAAW,CAAC,KAAK,SAAK,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,EAAE;IAI5D,YAAY,CAAC,MAAM,GAAE,kBAAuB,GAAG,YAAY;IAIrD,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMrE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI9B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAMtF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,EAAE;IAIlC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,YAAY,GAAG,IAAI;IAM3H,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,IAAI;IAMjE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAM3B,MAAM,IAAI,YAAY,EAAE;CAGzB"}

package/dist/platform/state/memory-registry.js

@@ -1,3 +1,4 @@
+import { runHonestMemorySearch } from './memory-recall-contract.js';
 /**
  * MemoryRegistry — thin observable wrapper around the MemoryStore.
  * Panels subscribe via listeners; commands push/retrieve through this.
@@ -32,6 +33,15 @@ export class MemoryRegistry {
     searchSemantic(filter = {}) {
         return this.store.searchSemantic(filter);
     }
+    /**
+     * Search honoring the recall-honesty contract: semantic-or-literal with a stated
+     * fallback reason when the index is unavailable, and (with `options.recall`) the
+     * flagged/confidence-floor exclusion. This is the method a wire client and an
+     * offline surface both route through, so the honesty is identical either way.
+     */
+    honestSearch(filter = {}, options = {}) {
+        return runHonestMemorySearch(this.store, filter, options);
+    }
     rebuildVectors() {
         return this.store.rebuildVectorIndex();
     }

package/dist/platform/state/memory-store.d.ts

@@ -141,6 +141,8 @@ export declare class MemoryStore {
     constructor(dbPath: string | undefined, options: MemoryStoreOptions);
     init(): Promise<void>;
     get isReady(): boolean;
+    /** The on-disk database path backing this store, or null when ephemeral. */
+    get dbPath(): string | null;
     /** Add a new memory record. Returns the created record. */
     add(opts: MemoryAddOptions): Promise<MemoryRecord>;
     /** Retrieve a single record by ID. */