hippo-memory 1.69.0 → 1.71.0

package/dist/api/index.d.ts

@@ -0,0 +1,28 @@
+export { ApiError, BadRequestError, ConflictError, ForbiddenError, NotFoundError } from '../core/api-errors.js';
+export { isPrivateScope, passesScopeFilterForRecall } from '../store/recall-scope.js';
+export { passesCliRecallScopeFilter, ScopeForbiddenError } from '../store/recall-scope.js';
+export type { TokenSummary, TokenSurface, TokenSurfaceSummary } from '../store/token-ledger.js';
+export type { FailureSummary } from '../store/failure-log.js';
+export { classifyOriginProject } from '../core/project-identity.js';
+export * from './types.js';
+export * from './remember.js';
+export * from './remember-local.js';
+export * from './recall-types.js';
+export * from './recall.js';
+export * from './assemble.js';
+export * from './drill-down.js';
+export * from './outcome.js';
+export * from './forget.js';
+export * from './promote.js';
+export * from './auth.js';
+export * from './audit.js';
+export * from './context-types.js';
+export * from './context.js';
+export * from './tokens.js';
+export * from './dormant.js';
+export * from './quarantine.js';
+export * from './sleep.js';
+export * from './goals.js';
+export * from './learn.js';
+export * from './refine.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.js

@@ -0,0 +1,31 @@
+// Domain API layer: Context-taking functions that the CLI, the HTTP server and MCP all call, so the
+// business logic lives in one place. The code lives in src/api/, one module per domain; this barrel
+// keeps every import path that callers already use.
+export { ApiError, BadRequestError, ConflictError, ForbiddenError, NotFoundError } from '../core/api-errors.js';
+// The recall-side scope predicates live in recall-scope.ts (leaf) so shared.ts can use them without an import cycle.
+export { isPrivateScope, passesScopeFilterForRecall } from '../store/recall-scope.js';
+export { passesCliRecallScopeFilter, ScopeForbiddenError } from '../store/recall-scope.js';
+// classifyOriginProject lives in project-identity.ts (leaf) for the same reason.
+export { classifyOriginProject } from '../core/project-identity.js';
+export * from './types.js';
+export * from './remember.js';
+export * from './remember-local.js';
+export * from './recall-types.js';
+export * from './recall.js';
+export * from './assemble.js';
+export * from './drill-down.js';
+export * from './outcome.js';
+export * from './forget.js';
+export * from './promote.js';
+export * from './auth.js';
+export * from './audit.js';
+export * from './context-types.js';
+export * from './context.js';
+export * from './tokens.js';
+export * from './dormant.js';
+export * from './quarantine.js';
+export * from './sleep.js';
+export * from './goals.js';
+export * from './learn.js';
+export * from './refine.js';
+//# sourceMappingURL=index.js.map

package/dist/api/instruction-detect.js

@@ -0,0 +1,85 @@
+/** Prompt-injection detection for untrusted memory content. Same shape as secret-detect.ts; leaf module, no store/api/shared imports. */
+const INSTRUCTION_PATTERNS = [
+    { name: 'override-instructions', re: /\b(?:ignore|disregard|forget)\b[^.\n]{0,40}\b(?:previous|prior|above)\b[^.\n]{0,40}\binstructions?\b/i },
+    { name: 'role-reassignment', re: /\b(?:you are now|act as|pretend to be)\b[^.\n]{0,40}\b(?:an?\s+)?(?:ai|assistant|agent|system)\b/i },
+    { name: 'chat-role-markup', re: /<\|im_start\|>|<\|system\|>|\[INST\]|<\/?system>|###\s*system\s*:/i },
+    { name: 'system-prompt-reference', re: /\b(?:(?:override|ignore|bypass|replace|reveal)\b[^.\n]{0,40}\b(?:system prompt|developer message)|(?:system prompt|developer message)\b[^.\n]{0,40}\b(?:override|ignore|bypass|replace|reveal))\b/i },
+    // "always"/"never" alone (ordinary PR prose) doesn't flag without an agent-facing target nearby too.
+    {
+        name: 'standing-order',
+        re: /\b(?:from now on|whenever you|always|never)\b[^.\n]{0,50}\b(?:you must|(?:the ai|the assistant|the agent|claude|copilot)\s+(?:must|should|will)\b)/i
+    },
+    { name: 'concealment', re: /\b(?:do not|never|don't)\b[^.\n]{0,40}\b(?:tell|mention|reveal)\b[^.\n]{0,40}\bthe user\b/i },
+    {
+        name: 'remote-script-exec',
+        re: /\b(?:curl|wget)\b[^\n|]{0,80}\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b|\biex\s*\(\s*(?:iwr|invoke-webrequest|new-object\s+net\.webclient)/i
+    },
+    {
+        name: 'exfiltration',
+        re: /\b(?:send|post|upload|exfiltrate)\b[^.\n]{0,40}\b(?:secrets?|tokens?|api[- ]?keys?|credentials?|env(?:ironment)? variables?)\b/i
+    },
+    { name: 'unicode-tag-chars', re: /[\u{E0000}-\u{E007F}]/u },
+];
+// A stray zero-width char has legitimate uses (ZWJ); only a run of 3+ adjacent ones reads as smuggling.
+const ZERO_WIDTH_RUN_RE = /[\u200B-\u200F\u2060-\u2064]{3,}/;
+// Reorders what is drawn without changing a byte a pattern reads, and ordinary right-to-left prose never needs one.
+const BIDI_CONTROL_RE = /[\u202A-\u202E\u2066-\u2069]/;
+// A renderer draws a reference as the character it names: decimal, hex, or one of the five names XML defines.
+const CHARACTER_REFERENCE_RE = /&(?:#(\d{1,7})|#[xX]([0-9a-fA-F]{1,6})|(amp|lt|gt|quot|apos));/g;
+const NAMED_REFERENCES = new Map([['amp', '&'], ['lt', '<'], ['gt', '>'], ['quot', '"'], ['apos', "'"]]);
+// Drawn with no width, so one inside a word splits it for a pattern and not for a reader: soft hyphen, joiners, zero-width and bidi format characters.
+const INVISIBLE_RE = /[\u034F\u00AD\u180E\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g;
+// Cyrillic, then Greek, letters drawn like a c e i j o p s x y; closed at those, so Russian or Greek prose folds into no phrase a pattern names.
+const LOOKALIKES = new Map([
+    ['\u0430', 'a'], ['\u0441', 'c'], ['\u0435', 'e'], ['\u0456', 'i'], ['\u0458', 'j'], ['\u043E', 'o'], ['\u0440', 'p'], ['\u0455', 's'],
+    ['\u0445', 'x'], ['\u0443', 'y'],
+    ['\u0410', 'A'], ['\u0421', 'C'], ['\u0415', 'E'], ['\u0406', 'I'], ['\u0408', 'J'], ['\u041E', 'O'], ['\u0420', 'P'], ['\u0405', 'S'],
+    ['\u0425', 'X'], ['\u0423', 'Y'],
+    ['\u03B1', 'a'], ['\u03B5', 'e'], ['\u03B9', 'i'], ['\u03F3', 'j'], ['\u03BF', 'o'], ['\u03C1', 'p'], ['\u03C7', 'x'], ['\u03B3', 'y'],
+    ['\u0391', 'A'], ['\u0395', 'E'], ['\u0399', 'I'], ['\u037F', 'J'], ['\u039F', 'O'], ['\u03A1', 'P'], ['\u03A7', 'X'], ['\u03A5', 'Y'],
+]);
+const GREEK_OR_CYRILLIC_RE = /[\u0370-\u03FF\u0400-\u04FF]/g;
+// A line break stays: it is the sentence bound the patterns rely on where a list or a chat message ends a line with no full stop.
+const SPACE_RUN_RE = /[^\S\n]+/g;
+function referencedCharacter(reference, decimal, hex, name) {
+    if (name !== undefined)
+        return NAMED_REFERENCES.get(name) ?? reference;
+    const code = decimal !== undefined ? Number.parseInt(decimal, 10) : Number.parseInt(hex ?? '', 16);
+    // NUL, half a surrogate pair and a number past Unicode name no character, so the reference is read as written.
+    const drawn = code > 0 && code <= 0x10ffff && (code < 0xd800 || code > 0xdfff);
+    return drawn ? String.fromCodePoint(code) : reference;
+}
+/** `content` as a reader or a model takes it in. For matching only: what is stored is never this. */
+function screeningForm(content) {
+    return content
+        .replace(CHARACTER_REFERENCE_RE, referencedCharacter)
+        // Full-width, mathematical and enclosed letters become the plain ones, and every space character a U+0020.
+        .normalize('NFKC')
+        .replace(INVISIBLE_RE, '')
+        .replace(GREEK_OR_CYRILLIC_RE, (letter) => LOOKALIKES.get(letter) ?? letter)
+        .replace(SPACE_RUN_RE, ' ');
+}
+function matchedPattern(text) {
+    for (const { name, re } of INSTRUCTION_PATTERNS) {
+        if (re.test(text))
+            return `pattern:${name}`;
+    }
+    return null;
+}
+export function detectInstruction(content) {
+    // The text as written goes first: a phrase in plain sight is named before any smuggling rule, and the screening form only adds flags.
+    const plain = matchedPattern(content);
+    if (plain !== null)
+        return { flagged: true, reason: plain };
+    if (ZERO_WIDTH_RUN_RE.test(content)) {
+        return { flagged: true, reason: 'pattern:zero-width-smuggling' };
+    }
+    const screened = screeningForm(content);
+    const disguised = screened === content ? null : matchedPattern(screened);
+    if (disguised !== null)
+        return { flagged: true, reason: disguised };
+    if (BIDI_CONTROL_RE.test(content))
+        return { flagged: true, reason: 'pattern:bidi-control' };
+    return { flagged: false, reason: null };
+}
+//# sourceMappingURL=instruction-detect.js.map

package/dist/api/learn.js

@@ -1,14 +1,15 @@
 // Git auto-learn: fix/revert/bug commit subjects become memories. `hippo learn`, init, sleep and MCP hippo_learn share it.
-import { ForbiddenError } from '../api-errors.js';
-import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../autolearn.js';
-import { loadConfig } from '../config.js';
-import { embedMemory } from '../embeddings.js';
-import { extractInvalidationTarget, invalidateMatching } from '../invalidation.js';
-import { computeSchemaFit, createMemory, Layer } from '../memory.js';
-import { extractPathTags } from '../path-context.js';
-import { canReadScope, personalScopeOf, touchableScopeSql } from '../recall-scope.js';
-import { RejectedValueError } from '../rejection.js';
-import { duplicateKey, longestWord, storedTextKeys } from '../same-text.js';
+import { ForbiddenError } from '../core/api-errors.js';
+import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../learn/autolearn.js';
+import { loadConfig } from '../core/config.js';
+import { withRequestStoresSync } from '../db/request-stores.js';
+import { embedMemory } from '../store/embeddings/index.js';
+import { extractInvalidationTarget, invalidateMatchingAmong } from '../learn/invalidation.js';
+import { computeSchemaFit, createMemory, Layer } from '../core/memory.js';
+import { extractPathTags } from '../search/path-context.js';
+import { canReadScope, personalScopeOf, touchableScopeSql } from '../store/recall-scope.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { duplicateKey, longestWord, storedTextKeys } from '../util/same-text.js';
 import { loadTextsHoldingWords } from '../store/candidates.js';
 import { loadAllEntries } from '../store/entry-reads.js';
 import { writeEntry } from '../store/entry-writes.js';
@@ -38,53 +39,60 @@ export function learn(ctx, opts) {
 function writeLessons(ctx, lessons, opts, config) {
     const { hippoRoot, tenantId } = ctx;
     const { profile } = opts;
-    // Schema fit needs every row; without it, only rows holding a lesson's longest word can be its copy. Learn is host-admin only, so both read what an admin can.
-    const existing = profile.full ? loadAllEntries(hippoRoot, tenantId).filter((e) => e.scope == null || canReadScope(ctx.actor, e.scope)) : undefined;
-    const readable = touchableScopeSql('', personalScopeOf(ctx.actor));
-    const keys = storedTextKeys(existing ?? loadTextsHoldingWords(hippoRoot, tenantId, lessons.map(longestWord), undefined, readable));
-    const pathTags = profile.full ? extractPathTags(opts.repoPath) : [];
-    const counts = { added: 0, skipped: 0, rejected: 0, invalidations: [] };
-    for (const lesson of lessons) {
-        if (keys.has(duplicateKey(lesson))) {
-            counts.skipped++;
-            continue;
-        }
-        const target = profile.full ? extractInvalidationTarget(lesson) : null;
-        if (target) {
-            const { invalidated } = invalidateMatching(hippoRoot, target, tenantId);
-            if (invalidated > 0)
-                counts.invalidations.push({ from: target.from, count: invalidated });
-        }
-        const entry = createMemory(lesson, {
-            layer: Layer.Episodic,
-            tags: [...profile.tags],
-            source: profile.source,
-            confidence: 'observed',
-            schema_fit: existing && computeSchemaFit(lesson, [...profile.tags], existing),
-            tenantId,
-            baseHalfLifeDays: config.defaultHalfLifeDays,
-        });
-        for (const tag of pathTags)
-            if (!entry.tags.includes(tag))
-                entry.tags.push(tag);
-        // A refused lesson must not abort the rest of the git-log scan.
-        try {
-            writeEntry(hippoRoot, entry, { actor: ctx.actor.subject });
-        }
-        catch (err) {
-            if (err instanceof RejectedValueError) {
-                counts.rejected++;
+    // `hippo init` calls this outside any request, so the batch brings its own scope: every read and write below shares one handle.
+    return withRequestStoresSync(() => {
+        // One read serves the batch: invalidation matches against `live`, which follows every write below, as a reload per lesson did.
+        const live = profile.full ? loadAllEntries(hippoRoot, tenantId) : [];
+        // Schema fit needs every row; without it, only rows holding a lesson's longest word can be its copy. Learn is host-admin only, so both read what an admin can.
+        const existing = profile.full ? live.filter((e) => e.scope == null || canReadScope(ctx.actor, e.scope)) : undefined;
+        const readable = touchableScopeSql('', personalScopeOf(ctx.actor));
+        const keys = storedTextKeys(existing ?? loadTextsHoldingWords(hippoRoot, tenantId, lessons.map(longestWord), undefined, readable));
+        const pathTags = profile.full ? extractPathTags(opts.repoPath) : [];
+        const counts = { added: 0, skipped: 0, rejected: 0, invalidations: [] };
+        for (const lesson of lessons) {
+            if (keys.has(duplicateKey(lesson))) {
+                counts.skipped++;
                 continue;
             }
-            throw err;
+            const target = profile.full ? extractInvalidationTarget(lesson) : null;
+            if (target) {
+                const { invalidated } = invalidateMatchingAmong(hippoRoot, live, target, tenantId);
+                if (invalidated > 0)
+                    counts.invalidations.push({ from: target.from, count: invalidated });
+            }
+            const entry = createMemory(lesson, {
+                layer: Layer.Episodic,
+                tags: [...profile.tags],
+                source: profile.source,
+                confidence: 'observed',
+                schema_fit: existing && computeSchemaFit(lesson, [...profile.tags], existing),
+                tenantId,
+                baseHalfLifeDays: config.defaultHalfLifeDays,
+            });
+            for (const tag of pathTags)
+                if (!entry.tags.includes(tag))
+                    entry.tags.push(tag);
+            // A refused lesson must not abort the rest of the git-log scan.
+            try {
+                writeEntry(hippoRoot, entry, { actor: ctx.actor.subject });
+            }
+            catch (err) {
+                if (err instanceof RejectedValueError) {
+                    counts.rejected++;
+                    continue;
+                }
+                throw err;
+            }
+            if (profile.full) {
+                updateStats(hippoRoot, { remembered: 1 });
+                live.push(entry);
+            }
+            keys.add(duplicateKey(lesson));
+            if (profile.full)
+                void embedMemory(hippoRoot, entry);
+            counts.added++;
         }
-        if (profile.full)
-            updateStats(hippoRoot, { remembered: 1 });
-        keys.add(duplicateKey(lesson));
-        if (profile.full)
-            void embedMemory(hippoRoot, entry);
-        counts.added++;
-    }
-    return counts;
+        return counts;
+    });
 }
 //# sourceMappingURL=learn.js.map

package/dist/api/ledger-db.d.ts

@@ -0,0 +1,21 @@
+import { type openHippoDb } from '../db/index.js';
+import { type LedgerTurn } from '../store/ledger-turn.js';
+import type { LastSent, TokenSurface, TokenUse } from '../store/token-ledger.js';
+export interface LedgerRootOpts {
+    /** The store serves many people, so the global store of the user running it belongs to none of them. */
+    readonly sharedStore?: boolean;
+}
+/** `hippoRoot` when it holds a store, else the global store (the prompt hook fires where no local one exists), else null. */
+export declare function ledgerRoot(hippoRoot: string, opts?: LedgerRootOpts): string | null;
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through
+ * noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+export declare function noteLedgerRowSkipped<E>(error: E): void;
+/** Books one row in ledgerRoot's store, best-effort. */
+export declare function bookTokenUse(hippoRoot: string, use: TokenUse, opts?: LedgerRootOpts): void;
+/** Books a turn's rows and then its delivery event on one connection of ledgerRoot's store, best-effort. */
+export declare function bookLedgerTurn(hippoRoot: string, turn: LedgerTurn, opts?: LedgerRootOpts): void;
+/** What the session last sent on `surface` in ledgerRoot's store; undefined with no ledger or a failed read. */
+export declare function ledgerLastSent(hippoRoot: string, tenantId: string, sessionId: string | null | undefined, surface: TokenSurface, opts?: LedgerRootOpts): LastSent | null | undefined;
+/** Runs `fn` on a handle of ledgerRoot's store, best-effort as the calls above. */
+export declare function withLedgerDb<T>(hippoRoot: string, fn: (db: ReturnType<typeof openHippoDb>) => T, opts?: LedgerRootOpts): T | undefined;
+//# sourceMappingURL=ledger-db.d.ts.map

package/dist/api/ledger-db.js

@@ -0,0 +1,81 @@
+// The store the token ledger writes to for a caller's root; context, recall and the session hooks share it.
+import { isSqliteBusy, noteStoreBusy } from '../db/index.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { lastSentOnSurface, recordLedgerTurn } from '../store/ledger-turn.js';
+import { isInitialized, onHandle } from '../store/open.js';
+import { sqliteSyncStore } from '../store/sqlite/store.js';
+/** `hippoRoot` when it holds a store, else the global store (the prompt hook fires where no local one exists), else null. */
+export function ledgerRoot(hippoRoot, opts) {
+    if (isInitialized(hippoRoot))
+        return hippoRoot;
+    if (opts?.sharedStore)
+        return null;
+    const globalRoot = getGlobalRoot();
+    return isInitialized(globalRoot) ? globalRoot : null;
+}
+// SQLite's result codes for a hippo.db it cannot read: a corrupt image, and a file that is no database.
+const SQLITE_CORRUPT = 11;
+const SQLITE_NOTADB = 26;
+/** The one rule for a skipped ledger row. `absent` is a store with no token_ledger table or a hippo.db
+ * SQLite cannot read; the command that owns the store reports that, and a hook must stay quiet about it. */
+function ledgerSkipClass(error) {
+    if (isSqliteBusy(error))
+        return 'busy';
+    const code = error instanceof Error && 'errcode' in error ? error.errcode : undefined;
+    if (code === SQLITE_CORRUPT || code === SQLITE_NOTADB)
+        return 'absent';
+    return errorMessage(error).includes('no such table: token_ledger') ? 'absent' : 'unexpected';
+}
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through
+ * noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+export function noteLedgerRowSkipped(error) {
+    const skip = ledgerSkipClass(error);
+    if (skip === 'busy') {
+        noteStoreBusy('token ledger row skipped');
+        return;
+    }
+    const message = `token ledger row skipped: ${errorMessage(error)}`;
+    if (skip === 'absent')
+        log.debug(message);
+    else
+        log.warnThenDebug('token-ledger-row', message, errorFields(error));
+}
+/** Runs `call` on ledgerRoot's store root. Best-effort: undefined on any failure, because a ledger failure must not break context or recall. */
+function onLedgerRoot(hippoRoot, opts, call) {
+    let root = null;
+    try {
+        root = ledgerRoot(hippoRoot, opts);
+    }
+    catch (error) {
+        // An unreadable store root means no ledger write; the ledger must never break context or recall.
+        log.debug(`token ledger skipped, store root unreadable: ${errorMessage(error)}`);
+        return undefined;
+    }
+    if (root === null)
+        return undefined;
+    try {
+        return call(root);
+    }
+    catch (error) {
+        noteLedgerRowSkipped(error);
+        return undefined;
+    }
+}
+/** Books one row in ledgerRoot's store, best-effort. */
+export function bookTokenUse(hippoRoot, use, opts) {
+    onLedgerRoot(hippoRoot, opts, (root) => sqliteSyncStore(root).recordTokens(use));
+}
+/** Books a turn's rows and then its delivery event on one connection of ledgerRoot's store, best-effort. */
+export function bookLedgerTurn(hippoRoot, turn, opts) {
+    onLedgerRoot(hippoRoot, opts, (root) => recordLedgerTurn(root, turn));
+}
+/** What the session last sent on `surface` in ledgerRoot's store; undefined with no ledger or a failed read. */
+export function ledgerLastSent(hippoRoot, tenantId, sessionId, surface, opts) {
+    return onLedgerRoot(hippoRoot, opts, (root) => lastSentOnSurface(root, tenantId, sessionId, surface));
+}
+/** Runs `fn` on a handle of ledgerRoot's store, best-effort as the calls above. */
+export function withLedgerDb(hippoRoot, fn, opts) {
+    return onLedgerRoot(hippoRoot, opts, (root) => onHandle(root, fn));
+}
+//# sourceMappingURL=ledger-db.js.map

package/dist/api/memories.d.ts

@@ -0,0 +1,5 @@
+import type { MemoryEntry } from '../core/memory.js';
+import type { Context } from './types.js';
+/** The row `id` in the caller's tenant, or null when it is missing or another tenant's. */
+export declare function getMemory(ctx: Context, id: string): Promise<MemoryEntry | null>;
+//# sourceMappingURL=memories.d.ts.map

package/dist/api/memories.js

@@ -0,0 +1,7 @@
+import { storeFor } from '../store/index.js';
+/** The row `id` in the caller's tenant, or null when it is missing or another tenant's. */
+export async function getMemory(ctx, id) {
+    const [entry] = await storeFor(ctx).entriesByIds([id], ctx.tenantId);
+    return entry ?? null;
+}
+//# sourceMappingURL=memories.js.map

package/dist/api/objects.d.ts

@@ -0,0 +1,9 @@
+import type { SavableDescriptor } from '../objects/descriptor.js';
+import type { ObjectByKind, SavableKind } from '../store/object-types.js';
+import type { Objects } from '../store/port.js';
+import type { Context } from './types.js';
+/** The request store's object group; the dispatcher has already answered 501 for a store without it. */
+export declare function objectsOf(ctx: Context): Objects;
+/** Saves through the request's store as the authenticated caller. */
+export declare function saveFor<K extends SavableKind, W>(ctx: Context, d: SavableDescriptor<K, W>, write: W): Promise<ObjectByKind[K]>;
+//# sourceMappingURL=objects.d.ts.map

package/dist/api/objects.js

@@ -0,0 +1,11 @@
+import { saveObject } from '../objects/lifecycle.js';
+import { requireGroup, storeFor } from '../store/index.js';
+/** The request store's object group; the dispatcher has already answered 501 for a store without it. */
+export function objectsOf(ctx) {
+    return requireGroup(storeFor(ctx), 'objects');
+}
+/** Saves through the request's store as the authenticated caller. */
+export function saveFor(ctx, d, write) {
+    return saveObject(objectsOf(ctx), d, { hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, actor: ctx.actor.subject }, write);
+}
+//# sourceMappingURL=objects.js.map

package/dist/api/on-store.d.ts

@@ -0,0 +1,16 @@
+import type { HippoStore, StoreGroups } from '../store/port.js';
+import { type SqliteLocal } from '../store/sqlite/local.js';
+import { type SqliteSyncStore } from '../store/sqlite/store.js';
+import type { Context, StoreReply } from './types.js';
+/** What a port call answers: a Promise from a served store, the value itself from hippo.db. */
+export type Reply<T> = T | Promise<T>;
+/** The port one body is written against: a served store, or hippo.db answering the same methods at once. */
+export type StorePort = HippoStore | SqliteSyncStore;
+/** `next` on the reply's value, at once for a value, so hippo.db's path never becomes a Promise. */
+export declare function andThen<T, U>(reply: Reply<T>, next: (value: T) => Reply<U>): Reply<U>;
+/** Stands in for a group the store lacks, as `port.keyAudit ?? notPorted(port, 'keyAudit')`; it answers 501 as any unported path does. */
+export declare function notPorted(port: StorePort, group: keyof StoreGroups): never;
+/** Runs `run` on `ctx.store`, where a throw rejects, else on hippo.db under `ctx.hippoRoot`, where it throws. The store path never reads `hippoRoot`.
+ *  `local` runs what needs hippo.db's own handle or meta table; a served store refuses it, or does without where the write allows. */
+export declare function onStore<C extends Context, R>(ctx: C, run: (port: StorePort, local: SqliteLocal) => Reply<R>): StoreReply<C, R>;
+//# sourceMappingURL=on-store.d.ts.map

package/dist/api/on-store.js

@@ -0,0 +1,38 @@
+// The one place an api function picks between a served store and hippo.db, so each operation has one body.
+// Only functions published as StoreReply use this carrier (see "Sync core, async port" in docs/ARCHITECTURE.md);
+// a new operation is async and goes through storeFor(ctx).
+import { SqliteBlockedError, StoreNotPortedError } from '../util/sqlite-blocked.js';
+import { REFUSED_ON_A_STORE, sqliteLocal } from '../store/sqlite/local.js';
+import { sqliteSyncStore } from '../store/sqlite/store.js';
+/** `next` on the reply's value, at once for a value, so hippo.db's path never becomes a Promise. */
+export function andThen(reply, next) {
+    return reply instanceof Promise ? reply.then(next) : next(reply);
+}
+/** Stands in for a group the store lacks, as `port.keyAudit ?? notPorted(port, 'keyAudit')`; it answers 501 as any unported path does. */
+export function notPorted(port, group) {
+    throw new StoreNotPortedError(port.kind, group);
+}
+/** A served store's stand-in for SqliteLocal. The last recall sits in hippo.db's
+ * meta table, so only a store that is hippo.db keeps and reads it, on `hippoRoot`. */
+function servedLocal(store, hippoRoot) {
+    if (store.kind === 'sqlite')
+        return { ...sqliteLocal(hippoRoot), ...REFUSED_ON_A_STORE };
+    return {
+        ...REFUSED_ON_A_STORE,
+        applyOutcomeToLastRecall() {
+            throw new SqliteBlockedError(store.kind);
+        },
+        finishLastRecall: (writes) => store.finishRecall(writes).then(() => null),
+    };
+}
+/** Runs `run` on `ctx.store`, where a throw rejects, else on hippo.db under `ctx.hippoRoot`, where it throws. The store path never reads `hippoRoot`.
+ *  `local` runs what needs hippo.db's own handle or meta table; a served store refuses it, or does without where the write allows. */
+export function onStore(ctx, run) {
+    const { store } = ctx;
+    // No await before `run`: an add-on relies on the first port call starting inside this call.
+    const reply = store ? (async () => run(store, servedLocal(store, ctx.hippoRoot)))() : run(sqliteSyncStore(ctx.hippoRoot), sqliteLocal(ctx.hippoRoot));
+    // SAFETY: the store path is an async function's Promise and hippo.db's port calls answer
+    // values, so the Promise comes back exactly when ctx has a store, as StoreReply says.
+    return reply;
+}
+//# sourceMappingURL=on-store.js.map

package/dist/api/outcome.d.ts

@@ -1,53 +1,16 @@
 import type { Context, StoreReply } from './types.js';
-/**
- * Apply a positive/negative outcome to a list of recently-recalled memory ids.
- * Used by the MCP `hippo_outcome` tool and the HTTP `POST /v1/outcome` route.
- * Tenant-scoped: ids outside ctx.tenantId, or in someone else's personal scope, are silently skipped
- * (matches the prior MCP semantics — a stale id from another tenant doesn't
- * crash the call). Each successful outcome emits one audit_log row with
- * op='outcome' tagged with ctx.actor.subject.
- *
- * Returns `{applied, appliedIds}`. `appliedIds` is the tenant-filtered subset
- * of input ids that actually had `applyOutcome` run on them (i.e. ids found
- * in ctx.tenantId). Callers that surface the id list
- * over a multi-tenant boundary (HTTP /v1/outcome last-recall path, Python SDK)
- * MUST return `appliedIds` instead of the raw input list — otherwise the
- * non-applied (cross-tenant) ids leak to the caller.
- *
- * `opts.traceId`:
- * OPTIONAL additive opt so a programmatic caller can link this outcome to
- * the recall_traces row it judges. NOT applied unconditionally — an SDK
- * caller passing explicit ids with no preceding CLI/context recall would
- * otherwise get linked to a stale, unrelated trace. `outcomeForLastRecall`
- * supplies this automatically from `last_trace_id`; every other caller
- * (server.ts explicit-ids path, MCP hippo_outcome) omits it and gets no
- * linkage, which is correct.
- */
+/** An id outside ctx.tenantId, or in someone else's personal scope, is skipped, so a stale id never fails the call.
+ *  `appliedIds` holds only the ids applied: a caller that answers across tenants returns it, never the ids it was sent. */
 export interface OutcomeResult {
     applied: number;
     appliedIds: string[];
 }
+/** `opts.traceId` links the outcome to the recall trace it judges. Only outcomeForLastRecall sends one: explicit ids may follow no recall at all. */
 export declare function outcome<C extends Context>(ctx: C, ids: ReadonlyArray<string>, good: boolean, opts?: {
     traceId?: number;
 }): StoreReply<C, OutcomeResult>;
-/**
- * Apply an outcome to the ids most recently returned by `recall()`.
- *
- * Reads `loadIndex(ctx.hippoRoot).last_retrieval_ids` (per-hippoRoot local
- * state; not tenant-scoped at the index layer) and forwards to `outcome()`,
- * which DOES tenant-filter its read by `ctx.tenantId`. Cross-tenant
- * ids in `last_retrieval_ids` are silently skipped, matching the MCP
- * `hippo_outcome` semantics.
- *
- * **Tenant-safe response shape:** the returned `ids`
- * field contains ONLY the tenant-filtered subset that actually had outcomes
- * applied (i.e. `appliedIds` from the inner `outcome()` call). It lives in this
- * helper so every caller (CLI, HTTP /v1/outcome, MCP) inherits the contract.
- *
- * Do NOT tighten `loadIndex` with `tenantId` inside this helper — doing so
- * would break the (correct) cross-tenant-silent-skip behavior covered by
- * the test in `tests/api-outcome-for-last-recall.test.ts`.
- */
+/** The last recall's ids and its trace sit in hippo.db's meta table, which only the CLI and context write, so a store of another kind is refused.
+ *  `ids` holds only the ids applied in ctx.tenantId: the index is not tenant-scoped, so the ids read from it are never returned. */
 export interface OutcomeForLastRecallResult {
     applied: number;
     ids: string[];