hippo-memory 1.71.0 → 1.72.0

package/dist/api/learn.d.ts

@@ -1,3 +1,4 @@
+import { type InvalidationOptions, type InvalidationResult, type InvalidationTarget } from '../learn/invalidation.js';
 import type { Context } from './types.js';
 /** How a surface writes what it learns. */
 export interface LearnProfile {
@@ -28,4 +29,7 @@ export interface LearnResult {
 }
 /** Learn from `repoPath`'s last `days` of commits into the caller's tenant. Host admin only. */
 export declare function learn(ctx: Context, opts: LearnOpts): LearnResult;
+export type { InvalidationOptions, InvalidationResult, InvalidationTarget };
+/** `hippo invalidate`: weakens the caller's tenant's memories that reference `target.from`, or only the one `options.onlyId` names. */
+export declare function invalidateMemories(ctx: Context, target: InvalidationTarget, options: InvalidationOptions): InvalidationResult;
 //# sourceMappingURL=learn.d.ts.map

package/dist/api/learn.js

@@ -3,16 +3,16 @@ 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 { embedMemory } from '../search/embed-memories.js';
+import { extractInvalidationTarget, invalidateMatching, invalidateMatchingAmong, } from '../learn/invalidation.js';
+import { createMemory, Layer, schemaFitFrom, schemaFitSourceOf } 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 { canReadScope, personalScopeOf } from '../core/recall-scope.js';
+import { touchableScopeSql } from '../store/rule-sql.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';
+import { writeEntriesSkippingRejected } from '../store/entry-writes.js';
 import { updateStats } from '../store/index-and-stats.js';
 // SHORTCUT: two profiles keep each surface's rows as they were; fold MCP onto the CLI profile once it may invalidate.
 export const CLI_LEARN = Object.freeze({ tags: Object.freeze(['error', 'git-learned']), source: 'git-learn', full: true });
@@ -36,6 +36,34 @@ export function learn(ctx, opts) {
     const { kept, dropped } = partitionLessons(parsed);
     return { status: 'scanned', lowInfo: dropped.length, ...writeLessons(ctx, kept, opts, config) };
 }
+/** Writes `batch` in one transaction; a refused lesson is dropped from `live` and `keys` and must not abort the rest of the git-log scan. */
+function landLessons(ctx, batch, live, keys, counts, full) {
+    if (batch.length === 0)
+        return;
+    // SHORTCUT: hippo.db only, as the port has no batch write, stats bump or whole-tenant read, so another store kind answers 501 at the
+    // open; port groups for them once a served store must learn.
+    const landed = [];
+    writeEntriesSkippingRejected(ctx.hippoRoot, (put) => {
+        for (const { entry, key } of batch) {
+            if (put(entry)) {
+                landed.push(entry);
+                continue;
+            }
+            counts.rejected++;
+            keys.delete(key);
+            const at = live.indexOf(entry);
+            if (at !== -1)
+                live.splice(at, 1);
+        }
+    }, ctx.actor.subject);
+    counts.added += landed.length;
+    if (!full)
+        return;
+    if (landed.length > 0)
+        updateStats(ctx.hippoRoot, { remembered: landed.length });
+    for (const entry of landed)
+        void embedMemory(ctx.hippoRoot, entry);
+}
 function writeLessons(ctx, lessons, opts, config) {
     const { hippoRoot, tenantId } = ctx;
     const { profile } = opts;
@@ -43,19 +71,27 @@ function writeLessons(ctx, lessons, opts, config) {
     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.
+        // 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;
+        // Each lesson is scored against `existing` as it was before the batch, so its tag counts and texts are read once.
+        const fitSource = existing && schemaFitSourceOf(existing);
         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: [] };
+        // Lessons queue and land in one transaction; an invalidation reads the store, so it flushes the queue first.
+        const queue = [];
+        const flush = () => landLessons(ctx, queue.splice(0), live, keys, counts, profile.full);
         for (const lesson of lessons) {
-            if (keys.has(duplicateKey(lesson))) {
+            const key = duplicateKey(lesson);
+            if (keys.has(key)) {
                 counts.skipped++;
                 continue;
             }
             const target = profile.full ? extractInvalidationTarget(lesson) : null;
             if (target) {
+                flush();
                 const { invalidated } = invalidateMatchingAmong(hippoRoot, live, target, tenantId);
                 if (invalidated > 0)
                     counts.invalidations.push({ from: target.from, count: invalidated });
@@ -65,34 +101,24 @@ function writeLessons(ctx, lessons, opts, config) {
                 tags: [...profile.tags],
                 source: profile.source,
                 confidence: 'observed',
-                schema_fit: existing && computeSchemaFit(lesson, [...profile.tags], existing),
+                schema_fit: fitSource && schemaFitFrom(lesson, [...profile.tags], fitSource),
                 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));
+            queue.push({ entry, key });
             if (profile.full)
-                void embedMemory(hippoRoot, entry);
-            counts.added++;
+                live.push(entry);
+            keys.add(key);
         }
+        flush();
         return counts;
     });
 }
+/** `hippo invalidate`: weakens the caller's tenant's memories that reference `target.from`, or only the one `options.onlyId` names. */
+export function invalidateMemories(ctx, target, options) {
+    return invalidateMatching(ctx.hippoRoot, target, ctx.tenantId, options);
+}
 //# sourceMappingURL=learn.js.map

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

@@ -1,4 +1,3 @@
-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 {
@@ -7,15 +6,12 @@ export interface LedgerRootOpts {
 }
 /** `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;
+/** Runs `call` on ledgerRoot's store root. Best-effort: undefined on any failure, because a ledger failure must not break context or recall. */
+export declare function onLedgerRoot<T>(hippoRoot: string, opts: LedgerRootOpts | undefined, call: (root: string) => T): T | undefined;
 /** 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

@@ -1,9 +1,8 @@
 // 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 { 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 { lastSentOnSurface, noteLedgerRowSkipped, recordLedgerTurn } from '../store/ledger-turn.js';
+import { isInitialized } from '../core/project-identity.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) {
@@ -14,35 +13,8 @@ export function ledgerRoot(hippoRoot, opts) {
     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) {
+export function onLedgerRoot(hippoRoot, opts, call) {
     let root = null;
     try {
         root = ledgerRoot(hippoRoot, opts);
@@ -74,8 +46,4 @@ export function bookLedgerTurn(hippoRoot, turn, opts) {
 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

@@ -1,5 +1,23 @@
 import type { MemoryEntry } from '../core/memory.js';
-import type { Context } from './types.js';
+import { type StrengthTallies } from '../store/candidates.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>;
+/** getMemory, but NotFound when the row is another person's personal one, so the reply does not reveal that the id exists. */
+export declare function getTouchableMemory(ctx: Context, id: string): Promise<MemoryEntry | null>;
+export interface MemoryStatus extends StrengthTallies {
+    openConflicts: number;
+}
+/** Tenant-wide counts behind the status verbs: strength tallies at `now` (at risk is under `atRiskBelow`) and open conflicts. */
+export declare function getMemoryStatus(ctx: Context, now: Date, atRiskBelow: number): MemoryStatus;
+/** Which rows a read covers: the caller's tenant, or with `everyTenant` the whole store. */
+export interface TenantReach {
+    everyTenant?: boolean;
+}
+/** Every memory row in reach, oldest first. */
+export declare function listMemories(ctx: Context, reach?: TenantReach): MemoryEntry[];
+/** How many memory rows the whole store holds, counted in SQL. */
+export declare function countAllMemories(ctx: Context): number;
+/** The rows in reach among `ids`; a missing id or one out of reach is absent. */
+export declare function listMemoriesByIds(ctx: Context, ids: readonly string[], reach?: TenantReach): MemoryEntry[];
 //# sourceMappingURL=memories.d.ts.map

package/dist/api/memories.js

@@ -1,7 +1,46 @@
+import { loadStrengthTallies } from '../store/candidates.js';
+import { countOpenConflicts } from '../store/conflicts.js';
+import { NotFoundError } from '../core/api-errors.js';
+import { canTouchScope } from '../core/recall-scope.js';
 import { storeFor } from '../store/index.js';
+import { countAllEntries, loadAllEntries, loadEntriesByIds } from '../store/entry-reads.js';
+import { requireHostAdmin } from './types.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;
 }
+/** getMemory, but NotFound when the row is another person's personal one, so the reply does not reveal that the id exists. */
+export async function getTouchableMemory(ctx, id) {
+    const entry = await getMemory(ctx, id);
+    if (!canTouchScope(ctx.actor, entry?.scope ?? null))
+        throw new NotFoundError(`Memory not found: ${id}`);
+    return entry;
+}
+/** Tenant-wide counts behind the status verbs: strength tallies at `now` (at risk is under `atRiskBelow`) and open conflicts. */
+export function getMemoryStatus(ctx, now, atRiskBelow) {
+    return {
+        ...loadStrengthTallies(ctx.hippoRoot, ctx.tenantId, now, atRiskBelow),
+        openConflicts: countOpenConflicts(ctx.hippoRoot, ctx.tenantId),
+    };
+}
+function tenantFilter(ctx, reach) {
+    if (!reach.everyTenant)
+        return ctx.tenantId;
+    requireHostAdmin(ctx, 'Reading every tenant');
+    return undefined;
+}
+/** Every memory row in reach, oldest first. */
+export function listMemories(ctx, reach = {}) {
+    return loadAllEntries(ctx.hippoRoot, tenantFilter(ctx, reach));
+}
+/** How many memory rows the whole store holds, counted in SQL. */
+export function countAllMemories(ctx) {
+    requireHostAdmin(ctx, 'Reading every tenant');
+    return countAllEntries(ctx.hippoRoot);
+}
+/** The rows in reach among `ids`; a missing id or one out of reach is absent. */
+export function listMemoriesByIds(ctx, ids, reach = {}) {
+    return loadEntriesByIds(ctx.hippoRoot, ids, tenantFilter(ctx, reach));
+}
 //# sourceMappingURL=memories.js.map

package/dist/api/objects.d.ts

@@ -1,5 +1,5 @@
 import type { SavableDescriptor } from '../objects/descriptor.js';
-import type { ObjectByKind, SavableKind } from '../store/object-types.js';
+import type { ObjectByKind, SavableKind } from '../core/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. */

package/dist/api/outcome.js

@@ -1,5 +1,5 @@
 // Outcome feedback on recalled memories.
-import { personalScopeOf } from '../store/recall-scope.js';
+import { personalScopeOf } from '../core/recall-scope.js';
 import { andThen, notPorted, onStore } from './on-store.js';
 /** `opts.traceId` links the outcome to the recall trace it judges. Only outcomeForLastRecall sends one: explicit ids may follow no recall at all. */
 export function outcome(ctx, ids, good, opts) {

package/dist/api/pilot-arm.d.ts

@@ -1,19 +1,9 @@
-import { type DatabaseSyncLike } from '../db/index.js';
 import { type LedgerRootOpts } from './ledger-db.js';
-export type PilotArm = 'hippo' | 'holdout';
+import { type PilotArm } from '../store/pilot-arm.js';
 export interface SessionArmOpts extends LedgerRootOpts {
     /** Only the caller tenant's arm row counts, so a caller holding another tenant's session id cannot claim that session's arm. */
     readonly ownTenantOnly?: boolean;
 }
-/** Deterministic split: the same session and rate always land in the same arm. */
-export declare function hashArm(sessionId: string, rateBp: number): PilotArm;
-/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
-export declare function readPilotArm(db: DatabaseSyncLike, sessionId: string, tenantId?: string): PilotArm | null;
-/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
-export declare function ensurePilotArm(db: DatabaseSyncLike, tenantId: string, sessionId: string, rateBp: number, opts?: {
-    ownTenantOnly?: boolean;
-    now?: string;
-}): PilotArm;
 /** The session's arm, or null at rate 0, with no session id, or with no store.
  *  `write` books the arm row; a read-only caller (env-only id, sub-agent) follows the stored arm, else the hash. */
 export declare function sessionPilotArm(hippoRoot: string, tenantId: string, sessionId: string | undefined, write: boolean, opts?: SessionArmOpts): PilotArm | null;

package/dist/api/pilot-arm.js

@@ -1,46 +1,8 @@
-// Pilot arm: one token_ledger row per session names its arm, `hippo` or `holdout`, so a pilot can compare them.
-// `items` holds the holdout rate in basis points; readers outside this repo depend on these rows, so their shape is fixed.
-import { createHash } from 'node:crypto';
+// Which pilot arm a session is in: the rate comes from the ledger store's config, the arm row from src/store/pilot-arm.ts.
 import { loadConfig } from '../core/config.js';
-import { HOOK_DB_WAIT_MS, scopedBusyWait, withWriteScope } from '../db/index.js';
-import { ledgerRoot, withLedgerDb } from './ledger-db.js';
-import { errorMessage, log } from '../util/log.js';
-import { firstPilotArmHash } from '../store/token-ledger-rows.js';
-import { recordTokenUse } from '../store/token-ledger.js';
-/** Deterministic split: the same session and rate always land in the same arm. */
-export function hashArm(sessionId, rateBp) {
-    const bucket = parseInt(createHash('sha256').update(sessionId).digest('hex').slice(0, 8), 16) % 10000;
-    return bucket < rateBp ? 'holdout' : 'hippo';
-}
-/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
-export function readPilotArm(db, sessionId, tenantId) {
-    const row = firstPilotArmHash(db, sessionId, tenantId);
-    return row?.block_hash === 'holdout' || row?.block_hash === 'hippo' ? row.block_hash : null;
-}
-/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
-// The wait is the caller's lock-wait scope (a hook's 1 s, a server request's 250 ms); it holds on a handle opened in that scope.
-export function ensurePilotArm(db, tenantId, sessionId, rateBp, opts = {}) {
-    const hashed = hashArm(sessionId, rateBp);
-    const readTenant = opts.ownTenantOnly ? tenantId : undefined;
-    try {
-        // A stored row is the common case after the first prompt, so it must not take the write lock.
-        const existing = readPilotArm(db, sessionId, readTenant);
-        if (existing !== null)
-            return existing;
-        return withWriteScope(db, 'pilot_arm', () => {
-            const stored = readPilotArm(db, sessionId, readTenant);
-            if (stored === null) {
-                recordTokenUse(db, { tenantId, sessionId, surface: 'pilot', event: 'arm', items: rateBp, tokens: 0, hash: hashed, now: opts.now });
-            }
-            return stored ?? hashed;
-        }, { busyWaitMs: scopedBusyWait() ?? HOOK_DB_WAIT_MS });
-    }
-    catch (err) {
-        // A prompt hook must not fail on pilot bookkeeping; concurrent callers still agree on the hash arm.
-        log.debug(`pilot arm not stored, using the hash arm: ${errorMessage(err)}`);
-        return hashed;
-    }
-}
+import { ledgerRoot, onLedgerRoot } from './ledger-db.js';
+import { pilotArmOnRoot } from '../store/ledger-turn.js';
+import { hashArm } from '../store/pilot-arm.js';
 /** The session's arm, or null at rate 0, with no session id, or with no store.
  *  `write` books the arm row; a read-only caller (env-only id, sub-agent) follows the stored arm, else the hash. */
 export function sessionPilotArm(hippoRoot, tenantId, sessionId, write, opts = {}) {
@@ -53,9 +15,7 @@ export function sessionPilotArm(hippoRoot, tenantId, sessionId, write, opts = {}
     if (rate <= 0)
         return null;
     const { ownTenantOnly } = opts;
-    const arm = withLedgerDb(hippoRoot, (db) => write
-        ? ensurePilotArm(db, tenantId, sessionId, rate, { ownTenantOnly })
-        : readPilotArm(db, sessionId, ownTenantOnly ? tenantId : undefined) ?? hashArm(sessionId, rate), opts);
+    const arm = onLedgerRoot(hippoRoot, opts, (at) => pilotArmOnRoot(at, tenantId, sessionId, rate, { write, ownTenantOnly }));
     return arm ?? hashArm(sessionId, rate);
 }
 //# sourceMappingURL=pilot-arm.js.map

package/dist/api/predictions.d.ts

@@ -1,7 +1,9 @@
-import type { Prediction, PredictionBaserate } from '../store/predictions.js';
+import { type Prediction, type PredictionBaserate, type SavePredictionOpts } from '../store/predictions.js';
 import type { PredictionClose, PredictionSave, Predictions } from '../store/port.js';
 import type { Context } from './types.js';
 export declare function savePrediction(ctx: Context, input: PredictionSave): Promise<Prediction>;
+/** A claim saved with its recall mirror, built under the store root's half-life as the HTTP create route builds it. */
+export declare function recordPrediction(ctx: Context, claim: SavePredictionOpts): Promise<Prediction>;
 export declare function listPredictions(ctx: Context, query: Parameters<Predictions['listPredictions']>[1]): Promise<Prediction[]>;
 export declare function predictionBaserate(ctx: Context, classTag: string): Promise<PredictionBaserate>;
 export declare function predictionById(ctx: Context, id: number): Promise<Prediction | null>;

package/dist/api/predictions.js

@@ -1,8 +1,14 @@
+import { predictionMirror } from '../store/predictions.js';
+import { loadConfig } from '../core/config.js';
 import { requireGroup, storeFor } from '../store/index.js';
 const predictionsOf = (ctx) => requireGroup(storeFor(ctx), 'predictions');
 export async function savePrediction(ctx, input) {
     return predictionsOf(ctx).savePrediction(ctx.tenantId, input, ctx.actor.subject);
 }
+/** A claim saved with its recall mirror, built under the store root's half-life as the HTTP create route builds it. */
+export async function recordPrediction(ctx, claim) {
+    return savePrediction(ctx, { ...claim, mirror: predictionMirror(ctx.tenantId, claim, loadConfig(ctx.hippoRoot).defaultHalfLifeDays) });
+}
 export async function listPredictions(ctx, query) {
     return predictionsOf(ctx).listPredictions(ctx.tenantId, query);
 }

package/dist/api/projects.d.ts

@@ -0,0 +1,21 @@
+import { type MergeResult, type ProjectSummary, type RepairResult } from '../sharing/project-merge.js';
+import type { Context } from './types.js';
+export type { MergeResult, ProjectCollision, ProjectSummary, RepairResult } from '../sharing/project-merge.js';
+export type { ProjectFold } from '../agent-memories/project-folds.js';
+export interface MergeProjectNamesOpts {
+    from: string;
+    into: string;
+    /** Plans in a transaction that rolls back: nothing is written, mirrors and backup included. */
+    dryRun: boolean;
+}
+/** Live rows per project name in the caller's tenant, newest write first. */
+export declare function listProjectNames(ctx: Context): ProjectSummary[];
+/** Folds project `from` into `into`, backed up and audited as `ctx.actor`; throws on user-global, unknown or equal names. */
+export declare function mergeProjectNames(ctx: Context, opts: MergeProjectNamesOpts): MergeResult;
+/** Sets aside stray imports, folds renamed projects and re-tags sleep's user-global merges; a dry run only plans. */
+export declare function repairProjectNames(ctx: Context, opts: {
+    dryRun: boolean;
+}): RepairResult;
+/** The repair sleep runs once per store; null when it already ran. */
+export declare function repairProjectNamesOnce(ctx: Context): RepairResult | null;
+//# sourceMappingURL=projects.d.ts.map

package/dist/api/projects.js

@@ -0,0 +1,24 @@
+// Project names for every front end: list them, fold one into another, and repair old tags; the store opens hippo.db and owns each transaction.
+// SHORTCUT: hippo.db only, since the store port has no project calls; a projects group when a served store needs them.
+import { listProjects, mergeProjects, repairOnceOnSleep, repairProjects, } from '../sharing/project-merge.js';
+import { onProjectTags } from '../store/project-tags.js';
+function onProjects(ctx, fn) {
+    return onProjectTags({ hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, actor: ctx.actor.subject }, fn);
+}
+/** Live rows per project name in the caller's tenant, newest write first. */
+export function listProjectNames(ctx) {
+    return onProjects(ctx, listProjects);
+}
+/** Folds project `from` into `into`, backed up and audited as `ctx.actor`; throws on user-global, unknown or equal names. */
+export function mergeProjectNames(ctx, opts) {
+    return onProjects(ctx, (store) => mergeProjects(store, opts));
+}
+/** Sets aside stray imports, folds renamed projects and re-tags sleep's user-global merges; a dry run only plans. */
+export function repairProjectNames(ctx, opts) {
+    return onProjects(ctx, (store) => repairProjects(store, opts));
+}
+/** The repair sleep runs once per store; null when it already ran. */
+export function repairProjectNamesOnce(ctx) {
+    return onProjects(ctx, repairOnceOnSleep);
+}
+//# sourceMappingURL=projects.js.map

package/dist/api/promote.js

@@ -6,7 +6,7 @@ import { promoteToGlobal } from '../sharing/global-store.js';
 import { loadConfig } from '../core/config.js';
 import { andThen, notPorted, onStore } from './on-store.js';
 import { memoryReach } from '../store/tenant-lookup.js';
-import { canTouchScope, personalScopeOf } from '../store/recall-scope.js';
+import { canTouchScope, personalScopeOf } from '../core/recall-scope.js';
 export function promote(ctx, id) {
     // promoteToGlobal reads without a tenant filter, so pre-check the row's tenant_id and deny cross-tenant access with archiveRaw's not-found wording
     // (no leak about whether the id exists in another tenant).

package/dist/api/prompt-hook.d.ts

@@ -1,9 +1,22 @@
 import { type Context, type ContextResult, type ContextResultEntry } from './index.js';
-import type { DeliveryRecorder } from '../store/delivery-recorder.js';
+import { type DeliveryEventType, type DeliveryRecorder } from '../store/delivery-recorder.js';
+import type { HookRuntime } from '../core/capture-contract.js';
 import { type JsonValue } from '../util/json.js';
 import type { MemoryEntry } from '../core/memory.js';
-import { type PilotArm } from './pilot-arm.js';
+import type { PilotArm } from '../store/pilot-arm.js';
 import type { DeliveryWrite } from '../store/ledger-turn.js';
+/** What a hook's delivery row says about the call it records. */
+export interface DeliveryStart {
+    stdinText: string | undefined;
+    runtime: HookRuntime;
+    eventType?: DeliveryEventType;
+    /** The host's own session id from its environment, used when the payload names none. */
+    envSessionId: string | undefined;
+}
+/** A delivery recorder for a hook on `ctx.hippoRoot` when the ledger store enables one, else null; never throws. */
+export declare function startDeliveryRecorder(ctx: Context, start: DeliveryStart): DeliveryRecorder | null;
+/** A recorder for `hippo capture-error`, only when the failure log and the ledger are one store, so `failure_id` never points into another. */
+export declare function startToolFailureRecorder(ctx: Context, start: Omit<DeliveryStart, 'eventType'>): DeliveryRecorder | null;
 /** With `write`, stores on the token ledger's connection (same store); without it, opens its own. A second flush is a no-op. */
 export declare function flushDeliveryRecorder(rec: DeliveryRecorder | null, write?: DeliveryWrite): void;
 /** What one render needs once api.getContext has answered. */

package/dist/api/prompt-hook.js

@@ -5,16 +5,56 @@ import { getContext } from './index.js';
 import { BadRequestError } from '../core/api-errors.js';
 import { isSharedStore, loadConfig } from '../core/config.js';
 import { contextBlockLines, contextCost, crossProjectLines, handoffText, sessionTrailText, settleTokens, snapshotText } from './context-render.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
+import { createDeliveryRecorder } from '../store/delivery-recorder.js';
+import { realpathOrResolve } from '../util/real-path.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 import { isJsonString } from '../util/json.js';
-import { bookLedgerTurn, ledgerLastSent, noteLedgerRowSkipped } from './ledger-db.js';
+import { bookLedgerTurn, ledgerLastSent, ledgerRoot } from './ledger-db.js';
+import { noteLedgerRowSkipped } from '../store/ledger-turn.js';
 import { sessionPilotArm } from './pilot-arm.js';
-import { assertCallerProject, MAX_PROJECT_ALIASES } from '../core/project-identity.js';
+import { assertCallerProject, isGlobalStoreRoot, MAX_PROJECT_ALIASES } from '../core/project-identity.js';
 import { writeDeliveryEventAtRoot } from '../store/recall-trace.js';
-import { hookPayloadString, isSubagentPayload, shouldSkipUnchanged, } from '../store/token-ledger.js';
+import { shouldSkipUnchanged } from '../store/token-ledger.js';
+import { hookPayloadString, isSubagentPayload } from '../util/hook-payload.js';
 import { blockHash, estimateTokens } from '../util/token-text.js';
 import { errorMessage, log } from '../util/log.js';
 import { DEFAULT_CONTEXT_BUDGET } from './context.js';
+/** A delivery recorder for a hook on `ctx.hippoRoot` when the ledger store enables one, else null; never throws. */
+export function startDeliveryRecorder(ctx, start) {
+    try {
+        // The same store the token ledger writes to, so its config governs both.
+        const root = ledgerRoot(ctx.hippoRoot);
+        if (root === null || !loadConfig(root).deliveryLedger.enabled)
+            return null;
+        return createDeliveryRecorder({
+            root,
+            storeHash: blockHash(realpathOrResolve(root)),
+            writeStore: isGlobalStoreRoot(root) ? 'global' : 'local',
+            tenantId: ctx.tenantId,
+            stdinText: start.stdinText,
+            envSessionId: start.envSessionId,
+            runtime: start.runtime === 'copilot' ? 'copilot' : undefined,
+            eventType: start.eventType,
+        });
+    }
+    catch (error) {
+        log.warn(`delivery ledger skipped: ${errorMessage(error)}`);
+        return null;
+    }
+}
+/** A recorder for `hippo capture-error`, only when the failure log and the ledger are one store, so `failure_id` never points into another. */
+export function startToolFailureRecorder(ctx, start) {
+    try {
+        const root = ledgerRoot(ctx.hippoRoot);
+        if (root === null || realpathOrResolve(root) !== realpathOrResolve(ctx.hippoRoot))
+            return null;
+        return startDeliveryRecorder(ctx, { ...start, eventType: 'tool-failure' });
+    }
+    catch (error) {
+        log.warn(`delivery ledger skipped: ${errorMessage(error)}`);
+        return null;
+    }
+}
 /** With `write`, stores on the token ledger's connection (same store); without it, opens its own. A second flush is a no-op. */
 export function flushDeliveryRecorder(rec, write) {
     if (rec === null)

package/dist/api/recall-cli.d.ts

@@ -19,6 +19,9 @@ export interface CliRecallOrigin {
     readonly isGlobal: (id: string) => boolean;
 }
 export declare function cliRecallOrigin(ctx: Context, setting: CliRecallSetting): CliRecallOrigin;
+/** How many of `query`'s search candidates the scope rule hides from a recall asking for `requested`; the read is
+ *  window-capped, so this is a floor on a large store. */
+export declare function scopeHiddenCount(ctx: Context, query: string, globalRoot: string | undefined, requested: string | undefined): number;
 /** The active snapshot, its session's latest handoff and last five events, each kept only when its scope passes. */
 export declare function loadCliRecallContinuity(ctx: Context, setting: CliRecallSetting, wanted: boolean): ContinuityBlock;
 export interface CliRecallRerankerPick {

package/dist/api/recall-cli.js

@@ -1,17 +1,17 @@
 // What the `hippo recall` verb reads beside its ranking core: the stores it searches, the resume packet and the JSON rows.
 import { confidenceFacets, Layer } from '../core/memory.js';
-import { isGlobalStoreRoot } from '../core/project-identity.js';
+import { isGlobalStoreRoot, isInitialized } from '../core/project-identity.js';
 import { getReranker } from '../rerankers/index.js';
 import { isClefModel } from '../rerankers/clef.js';
 import { JEV_DEFAULT_TOP_K } from '../rerankers/jev.js';
 import { explainMatch } from '../search/explain.js';
 import { fitBudget } from '../search/finalize.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
-import { detectScope } from '../sharing/scope.js';
+import { detectScope } from '../core/active-scope.js';
 import { loadLatestHandoff } from '../store/handoffs.js';
 import { loadIndex } from '../store/index-and-stats.js';
-import { isInitialized } from '../store/open.js';
-import { passesScopeFilterForRecall } from '../store/recall-scope.js';
+import { passesCliRecallScopeFilter, passesScopeFilterForRecall } from '../core/recall-scope.js';
+import { loadSearchEntries } from '../store/search-rows.js';
 import { listSessionEvents, loadActiveTaskSnapshot } from '../store/sessions.js';
 export { DEFAULT_MAX_NEIGHBORS, MAX_HOPS } from '../graph/recall.js';
 /** The active scope merges `--scope` with the detected one, which only boosts. */
@@ -23,6 +23,15 @@ export function cliRecallOrigin(ctx, setting) {
     const globalOn = isInitialized(setting.globalRoot);
     return { globalOn, isGlobal: (id) => setting.primaryIsGlobal || (globalOn && !localIndex.entries[id]) };
 }
+/** How many of `query`'s search candidates the scope rule hides from a recall asking for `requested`; the read is
+ *  window-capped, so this is a floor on a large store. */
+export function scopeHiddenCount(ctx, query, globalRoot, requested) {
+    const probe = [
+        ...loadSearchEntries(ctx.hippoRoot, query, undefined, ctx.tenantId),
+        ...(globalRoot ? loadSearchEntries(globalRoot, query, undefined, ctx.tenantId) : []),
+    ];
+    return probe.filter((e) => !passesCliRecallScopeFilter(e.scope ?? null, requested)).length;
+}
 /** The active snapshot, its session's latest handoff and last five events, each kept only when its scope passes. */
 export function loadCliRecallContinuity(ctx, setting, wanted) {
     if (!wanted || setting.primaryIsGlobal)