hippo-memory 1.69.0 → 1.71.0

package/dist/api/auth.js

@@ -1,40 +1,47 @@
 // API key management: create, list, revoke, and grant or ungrant restricted scopes.
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from '../api-errors.js';
-import { appendAuditEvent, reportAuditWriteFailure } from '../audit.js';
-import { forgetVerifiedKey, insertApiKey, listApiKeyRows, mintApiKey, revokeApiKey, grantScope, ungrantScope, } from '../auth.js';
-import { DAY_MS } from '../dashboard-snapshot.js';
-import { isRestrictedScope } from '../recall-scope.js';
-import { requireGroup } from '../store-port.js';
-import { createAuditOf, createKeyAt, createSelfKeyAt } from '../store/key-writes.js';
-import { selectApiKeyOwner } from '../store/tenant-lookup.js';
+import { BadRequestError, ForbiddenError, NotFoundError } from '../core/api-errors.js';
+import { mintApiKey, } from '../store/auth.js';
+import { changeScopeGrant } from '../store/sqlite/local.js';
+import { sqliteSyncStore } from '../store/sqlite/store.js';
+import { DAY_MS } from '../util/time.js';
+import { andThen, notPorted, onStore } from './on-store.js';
 const API_KEY_SUBJECT = 'api_key:';
 /** The key id an API-key actor's subject names, or null for any other actor. */
 function keyIdOfSubject(subject) {
     return subject.startsWith(API_KEY_SUBJECT) ? subject.slice(API_KEY_SUBJECT.length) : null;
 }
-/**
- * Mint a new API key. The new key is ALWAYS bound to `ctx.tenantId`. Callers
- * cannot override the tenant via the opts bag — a previous `tenantId` field
- * was removed because the HTTP layer would happily forward `body.tenantId`,
- * letting tenant A mint a key for tenant B. The HTTP route handler at
- * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
- * `tenantId` and uses the resolved Bearer's tenant exclusively.
- *
- * Only an admin actor can mint (ForbiddenError otherwise), and a key never
- * outranks its minter: a resolver admin is tenant-only, so it mints members.
- */
+/** Mints a key always bound to `ctx.tenantId`; opts cannot override the tenant, or tenant A could mint a key for tenant B.
+ * Admin only (ForbiddenError otherwise), and a key never outranks its minter: a resolver admin is tenant-only, so it mints members. */
 export function authCreate(ctx, opts) {
-    // With a store, its keyWrites group stores the key and its auth_create row together, and hippo.db is never opened.
-    const reply = ctx.store ? createThroughStore(ctx, ctx.store, opts) : createOnHippoDb(ctx, opts);
-    // SAFETY: as in authRevoke, a C typed with a store gets the promise its path returns and a C that hides one gets the union.
-    return reply;
+    // The key and its auth_create row commit together on either store, so a failed audit write leaves no key.
+    return onStore(ctx, (port) => {
+        const keyWrites = port.keyWrites ?? notPorted(port, 'keyWrites');
+        const { plaintext, mint } = adminKeyMint(ctx, opts);
+        return andThen(keyWrites.createApiKey(mint), () => createResult(mint, plaintext));
+    });
 }
 /** A key row in the caller's tenant, made here so only its hash ever reaches a store. */
 function newKey(ctx, fields) {
     const { keyId, plaintext, keyHash } = mintApiKey();
     return { plaintext, key: { ...fields, keyId, keyHash, tenantId: ctx.tenantId, createdAt: new Date().toISOString() } };
 }
+/** Days a key lives when its mint names no expiry, so a key nobody remembers stops working by itself. */
+const DEFAULT_KEY_TTL_DAYS = 90;
+// The ceiling keeps toISOString in range.
+const MAX_TTL_DAYS = 3650;
+/** A 400, not a RangeError, since the caller of the mint chose these. */
+function mintExpiry({ ttlDays, noExpiry }) {
+    if (noExpiry && ttlDays !== undefined) {
+        throw new BadRequestError('send ttlDays or noExpiry, not both');
+    }
+    if (noExpiry)
+        return null;
+    const days = ttlDays ?? DEFAULT_KEY_TTL_DAYS;
+    if (!Number.isFinite(days) || days <= 0 || days > MAX_TTL_DAYS) {
+        throw new BadRequestError(`ttlDays must be above 0 and at most ${MAX_TTL_DAYS}`);
+    }
+    return new Date(Date.now() + days * DAY_MS).toISOString();
+}
 function adminKeyMint(ctx, opts) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can create API keys');
@@ -42,45 +49,16 @@ function adminKeyMint(ctx, opts) {
     if (ctx.actor.viaAuthResolver && opts.role === 'admin') {
         throw new ForbiddenError('A key minted through the auth resolver can only be a member key');
     }
-    const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
+    const role = opts.role ?? 'member';
     const label = opts.label ?? null;
-    const { plaintext, key } = newKey(ctx, { label, role, ownerSubject: null, expiresAt: null });
-    // The plaintext is NEVER logged; metadata carries label + role, keyId is non-secret.
-    return { plaintext, mint: { key, actor: ctx.actor.subject, metadata: { label, role } } };
+    const expiresAt = mintExpiry(opts);
+    const { plaintext, key } = newKey(ctx, { label, role, ownerSubject: null, expiresAt });
+    // The plaintext is NEVER logged; the audit row carries what the key can do and for how long, keyId is non-secret.
+    return { plaintext, mint: { key, actor: ctx.actor.subject, metadata: { label, role, expiresAt } } };
 }
 function createResult({ key }, plaintext) {
-    return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: key.role };
-}
-async function createThroughStore(ctx, store, opts) {
-    const keyWrites = requireGroup(store, 'keyWrites');
-    const { plaintext, mint } = adminKeyMint(ctx, opts);
-    await keyWrites.createApiKey(mint);
-    return createResult(mint, plaintext);
-}
-function createOnHippoDb(ctx, opts) {
-    const { plaintext, mint } = adminKeyMint(ctx, opts);
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        // A resolver admin's keys are found again only through their audit rows, so the key and its row commit together.
-        if (ctx.actor.viaAuthResolver) {
-            createKeyAt(db, mint);
-            return createResult(mint, plaintext);
-        }
-        insertApiKey(db, mint.key);
-        try {
-            appendAuditEvent(db, createAuditOf(mint));
-        }
-        catch (error) {
-            // Audit must not crash a successful mint.
-            reportAuditWriteFailure('auth_create', String(error), mint.key.keyId);
-        }
-        return createResult(mint, plaintext);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: key.role, expiresAt: key.expiresAt };
 }
-const MAX_TTL_DAYS = 3650;
 /** A RangeError, not a 4xx, since the operator's config sets these; the ttl ceiling keeps toISOString in range and a departed user's key short-lived. */
 function assertSelfMintOpts({ ttlDays, perSubject }) {
     if (!Number.isFinite(ttlDays) || ttlDays <= 0 || ttlDays > MAX_TTL_DAYS) {
@@ -90,12 +68,14 @@ function assertSelfMintOpts({ ttlDays, perSubject }) {
         throw new RangeError(`authCreateSelf: perSubject must be a whole number of at least 1, got ${String(perSubject)}`);
     }
 }
-/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together.
- *  With `ctx.store`, its keyWrites group runs that transaction; hippo.db is opened only when there is no store. */
+/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the
+ * binary floor, the cap's revokes, the mint and its audit rows commit or fail together. */
 export function authCreateSelf(ctx, opts) {
-    const reply = ctx.store ? createSelfThroughStore(ctx, ctx.store, opts) : createSelfOnHippoDb(ctx, opts);
-    // SAFETY: as in authRevoke, a C typed with a store gets the promise its path returns and a C that hides one gets the union.
-    return reply;
+    return onStore(ctx, (port) => {
+        const keyWrites = port.keyWrites ?? notPorted(port, 'keyWrites');
+        const { plaintext, mint } = selfKeyMint(ctx, opts);
+        return andThen(keyWrites.createSelfApiKey(mint), () => selfResult(mint, plaintext));
+    });
 }
 function selfKeyMint(ctx, opts) {
     if (!ctx.actor.viaAuthResolver) {
@@ -108,69 +88,25 @@ function selfKeyMint(ctx, opts) {
     // Not destructured: a binding pattern makes TypeScript infer F as KeyFields and lose ownerSubject's string type.
     const made = newKey(ctx, { label, role: 'member', ownerSubject: subject, expiresAt });
     // Same op and actor as an admin mint, so a lookup by audit row finds this key too.
-    return { plaintext: made.plaintext, mint: { key: made.key, actor: subject, metadata: { label, role: 'member', self: true, expiresAt }, perSubject: opts.perSubject } };
+    return {
+        plaintext: made.plaintext,
+        mint: { key: made.key, actor: subject, metadata: { label, role: 'member', self: true, expiresAt }, perSubject: opts.perSubject }
+    };
 }
 function selfResult({ key }, plaintext) {
     return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: 'member', expiresAt: key.expiresAt };
 }
-/** The store revokes the replaced keys without this process's verified-key cache, so they leave it here once the mint commits. */
-async function createSelfThroughStore(ctx, store, opts) {
-    const keyWrites = requireGroup(store, 'keyWrites');
-    const { plaintext, mint } = selfKeyMint(ctx, opts);
-    for (const keyId of await keyWrites.createSelfApiKey(mint))
-        forgetVerifiedKey(keyId);
-    return selfResult(mint, plaintext);
-}
-function createSelfOnHippoDb(ctx, opts) {
-    const { plaintext, mint } = selfKeyMint(ctx, opts);
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        createSelfKeyAt(db, mint);
-        return selfResult(mint, plaintext);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * List API keys visible to the calling tenant.
- *
- * Divergence from `cmdAuthList` in src/cli.ts: the CLI today returns ALL keys
- * regardless of tenant (single-tenant deployments). The API surface is tenant-
- * scoped because future multi-tenant deployments will share a hippoRoot, and
- * tenant A must not see tenant B's keys. Read-only, so no audit emit.
- */
-export function authList(ctx, opts) {
-    const keysOf = (rows) => rows.map((r) => r.key);
-    const rows = listRows(ctx, opts);
-    // SAFETY: the promise comes back exactly when ctx has a store, as StoreReply says.
-    return (rows instanceof Promise ? rows.then(keysOf) : keysOf(rows));
-}
-/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from.
- *  With `ctx.store`, its keyWrites group reads them; hippo.db is opened only when there is no store. */
+/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from. */
 export function authListRows(ctx, opts) {
-    // SAFETY: the promise comes back exactly when ctx has a store, as StoreReply says.
-    return listRows(ctx, opts);
-}
-function listRows(ctx, opts) {
-    return ctx.store ? listThroughStore(ctx, ctx.store, opts) : listOnHippoDb(ctx, opts);
+    return onStore(ctx, (port) => listRows(ctx, port, opts));
 }
-async function listThroughStore(ctx, store, opts) {
-    const keyWrites = requireGroup(store, 'keyWrites');
+function listRows(ctx, port, opts) {
+    const keyWrites = port.keyWrites ?? notPorted(port, 'keyWrites');
     const keyId = memberKeyIdOf(ctx.actor);
-    const filter = memberListFilter(ctx.actor, keyId === null ? undefined : (await store.findApiKey(keyId))?.ownerSubject);
-    return filter === null ? [] : keyWrites.listApiKeys({ ...opts, tenantId: ctx.tenantId, ...filter });
-}
-function listOnHippoDb(ctx, opts) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const keyId = memberKeyIdOf(ctx.actor);
-        const filter = memberListFilter(ctx.actor, keyId === null ? undefined : selectApiKeyOwner(db, keyId)?.ownerSubject);
-        return filter === null ? [] : listApiKeyRows(db, { ...opts, tenantId: ctx.tenantId, ...filter });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    return andThen(keyId === null ? undefined : port.findApiKey(keyId), (record) => {
+        const filter = memberListFilter(ctx.actor, record?.ownerSubject);
+        return filter === null ? [] : keyWrites.listApiKeys({ ...opts, tenantId: ctx.tenantId, ...filter });
+    });
 }
 /** The key id of a member API key caller, whose owner decides what it lists; null for any other caller. */
 function memberKeyIdOf(actor) {
@@ -202,12 +138,17 @@ function assertMayRevoke(ctx, keyId, row) {
     }
 }
 /** Revoke a key in the caller's tenant: a member API key may revoke only itself, a resolver member only the keys it minted.
- *  With `ctx.store`, its keyAudit group revokes and writes the auth_revoke row; hippo.db is opened only when there is no store. */
+ *  The revoke and its auth_revoke row commit together on either store, so a failed audit write leaves the key live. */
 export function authRevoke(ctx, keyId) {
-    const reply = ctx.store ? revokeThroughStore(ctx, ctx.store, keyId) : revokeOnHippoDb(ctx, keyId);
-    // SAFETY: a C typed with a store gets the promise its path returns; a C whose type hides a runtime store (a Pick of
-    // Context) is typed as the union, which a caller has to await anyway.
-    return reply;
+    return onStore(ctx, (port) => {
+        const keyAudit = port.keyAudit ?? notPorted(port, 'keyAudit');
+        assertMemberKeyRevokesSelf(ctx, keyId);
+        return andThen(port.findApiKey(keyId), (record) => {
+            assertMayRevoke(ctx, keyId, keyOwnerOf(record));
+            const revoke = { tenantId: ctx.tenantId, keyId, actor: ctx.actor.subject, at: new Date().toISOString() };
+            return andThen(keyAudit.revokeApiKey(revoke), (revokedAt) => ({ ok: true, revokedAt }));
+        });
+    });
 }
 function assertMemberKeyRevokesSelf(ctx, keyId) {
     if (ctx.actor.role !== 'admin' && !ctx.actor.viaAuthResolver && keyIdOfSubject(ctx.actor.subject) !== keyId) {
@@ -217,110 +158,29 @@ function assertMemberKeyRevokesSelf(ctx, keyId) {
 function keyOwnerOf(record) {
     return record ? { tenantId: record.tenantId, revokedAt: record.revokedAt, role: record.role, ownerSubject: record.ownerSubject ?? null } : undefined;
 }
-/** The store keeps no handle on this process's verified-key cache, so the key leaves it here once the revoke commits. */
-async function revokeThroughStore(ctx, store, keyId) {
-    const keyAudit = requireGroup(store, 'keyAudit');
-    assertMemberKeyRevokesSelf(ctx, keyId);
-    assertMayRevoke(ctx, keyId, keyOwnerOf(await store.findApiKey(keyId)));
-    const revokedAt = await keyAudit.revokeApiKey({ tenantId: ctx.tenantId, keyId, actor: ctx.actor.subject, at: new Date().toISOString() });
-    forgetVerifiedKey(keyId);
-    return { ok: true, revokedAt };
-}
-/** The auth_revoke row carries the KEY ROW's tenant, as cmdAuthRevoke does, and is skipped for an already-revoked key. */
-function revokeOnHippoDb(ctx, keyId) {
-    assertMemberKeyRevokesSelf(ctx, keyId);
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const row = selectApiKeyOwner(db, keyId);
-        assertMayRevoke(ctx, keyId, row);
-        let revokedAt;
-        let alreadyRevoked = false;
-        if (row.revokedAt) {
-            alreadyRevoked = true;
-            revokedAt = row.revokedAt;
-        }
-        else {
-            revokeApiKey(db, keyId);
-            revokedAt = selectApiKeyOwner(db, keyId)?.revokedAt ?? new Date().toISOString();
-        }
-        if (!alreadyRevoked) {
-            try {
-                appendAuditEvent(db, {
-                    tenantId: row.tenantId, // KEY's tenant, not ctx.tenantId.
-                    actor: ctx.actor.subject,
-                    op: 'auth_revoke',
-                    targetId: keyId,
-                });
-            }
-            catch (error) {
-                // Audit must not crash a successful revoke.
-                reportAuditWriteFailure('auth_revoke', String(error), keyId);
-            }
-        }
-        return { ok: true, revokedAt };
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
- * so the local CLI can run revoke and grant in the key's own tenant.
- */
+/** The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
+ * so the local CLI can run revoke and grant in the key's own tenant. */
 export function authKeyTenant(ctx, keyId) {
     if (!ctx.actor.hostAdmin) {
         throw new ForbiddenError('Only the host admin can look up a key across tenants');
     }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        return selectApiKeyOwner(db, keyId)?.tenantId;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    // Synchronous for the CLI, so it reads hippo.db whatever store ctx names.
+    return sqliteSyncStore(ctx.hippoRoot).findApiKey(keyId)?.tenantId;
 }
 /** Grant `keyId` read access to one restricted `scope`. Admin only. */
 export function authGrant(ctx, keyId, scope) {
-    return changeScopeGrant(ctx, keyId, scope, 'auth_grant');
+    return changeGrant(ctx, keyId, scope, 'auth_grant');
 }
 /** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
 export function authUngrant(ctx, keyId, scope) {
-    return changeScopeGrant(ctx, keyId, scope, 'auth_ungrant');
+    return changeGrant(ctx, keyId, scope, 'auth_ungrant');
 }
-function changeScopeGrant(ctx, keyId, scope, op) {
+/** hippo.db only: both callers are synchronous published functions, so no store's Promise can answer them. */
+function changeGrant(ctx, keyId, scope, op) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can change scope grants');
     }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const row = selectApiKeyOwner(db, keyId);
-        if (!row || row.tenantId !== ctx.tenantId) {
-            throw new NotFoundError(`Unknown key_id: ${keyId}`);
-        }
-        if (op === 'auth_grant' && row.revokedAt) {
-            throw new ConflictError(`${keyId} is revoked; a grant on it would never apply`);
-        }
-        if (op === 'auth_grant' && /^personal:/i.test(scope)) {
-            throw new BadRequestError(`${scope} is a personal scope: only its owner reads it, and no grant can change that`);
-        }
-        if (!isRestrictedScope(scope)) {
-            throw new BadRequestError(`${scope} is not a restricted scope; it is already readable by default`);
-        }
-        if (op === 'auth_grant')
-            grantScope(db, keyId, scope);
-        else
-            ungrantScope(db, keyId, scope);
-        try {
-            appendAuditEvent(db, { tenantId: ctx.tenantId, actor: ctx.actor.subject, op, targetId: keyId, metadata: { scope } });
-        }
-        catch (err) {
-            // Audit must not undo a grant change that already committed; surface it instead.
-            reportAuditWriteFailure(op, String(err), keyId);
-        }
-        return { ok: true };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    changeScopeGrant(ctx.hippoRoot, { tenantId: ctx.tenantId, keyId, scope, op, actor: ctx.actor.subject });
+    return { ok: true };
 }
 //# sourceMappingURL=auth.js.map

package/dist/api/auto-sleep.d.ts

@@ -0,0 +1,13 @@
+import type { HippoConfig } from '../core/config.js';
+export declare const autoSleepInFlight: Set<string>;
+export interface AutoSleepDue {
+    enabled: boolean;
+    count: number;
+    threshold: number;
+    due: boolean;
+}
+/** Counts only when enabled: the count opens the store. */
+export declare function autoSleepDue(hippoRoot: string, tenantId: string, config: HippoConfig['autoSleep']): AutoSleepDue;
+/** One run per store at a time; `allowed` is the caller's own gate. Consolidation is host-wide, so only the host tenant may start it. */
+export declare function startAutoSleepIfDue(hippoRoot: string, tenantId: string, config: HippoConfig['autoSleep'], allowed: boolean): void;
+//# sourceMappingURL=auto-sleep.d.ts.map

package/dist/api/auto-sleep.js

@@ -0,0 +1,32 @@
+// When a write starts a background sleep; the MCP remember tool and the session-close hook share it.
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { countCreatedSinceLastSleep } from '../store/index-and-stats.js';
+import { consolidate } from '../consolidate/sleep.js';
+import { outsideRequestStores, runWithRequestStores, scopedBusyWait } from '../db/index.js';
+import { resolveTenantId } from '../store/tenant.js';
+export const autoSleepInFlight = new Set();
+/** Counts only when enabled: the count opens the store. */
+export function autoSleepDue(hippoRoot, tenantId, config) {
+    const { enabled, threshold } = config;
+    const count = enabled ? countCreatedSinceLastSleep(hippoRoot, tenantId) : 0;
+    return { enabled, count, threshold, due: enabled && count >= threshold };
+}
+/** One run per store at a time; `allowed` is the caller's own gate. Consolidation is host-wide, so only the host tenant may start it. */
+export function startAutoSleepIfDue(hippoRoot, tenantId, config, allowed) {
+    if (!allowed ||
+        !config.enabled ||
+        tenantId !== resolveTenantId({}) ||
+        autoSleepInFlight.has(hippoRoot) ||
+        !autoSleepDue(hippoRoot, tenantId, config).due)
+        return;
+    autoSleepInFlight.add(hippoRoot);
+    // Fire-and-forget (never block the response); an unhandled rejection would kill the server, so log it.
+    // Its own scope: the call's closes a handle the sleep still holds across its pauses, but the caller's lock wait carries over.
+    const busyWaitMs = scopedBusyWait();
+    outsideRequestStores(() => runWithRequestStores(() => consolidate(hippoRoot), { busyWaitMs }))
+        .catch((err) => {
+        log.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${errorMessage(err)}`, errorFields(err));
+    })
+        .finally(() => autoSleepInFlight.delete(hippoRoot));
+}
+//# sourceMappingURL=auto-sleep.js.map

package/dist/{availability.d.ts → api/availability.d.ts}

@@ -1,5 +1,5 @@
 /** A minimal age reference: a memory id plus its ISO-8601 creation timestamp
- *  (MemoryEntry.created, canonical ISO per the src/memory.ts invariant). */
+ *  (MemoryEntry.created, canonical ISO per the src/core/memory.ts invariant). */
 export interface AgeRef {
     id: string;
     created: string;
@@ -41,25 +41,12 @@ export interface DetectAvailabilityBiasOpts {
     /** Minimum older-passed-over count required to fire. Default 3. */
     minOlderPassedOver?: number;
 }
-export declare const DEFAULT_RECENCY_WINDOW_MS: number;
+export declare const DEFAULT_RECENCY_WINDOW_MS = 86400000;
 export declare const DEFAULT_RECENT_FRACTION_THRESHOLD = 0.7;
 export declare const DEFAULT_MIN_RETURNED = 3;
 export declare const DEFAULT_MIN_POOL = 10;
 export declare const DEFAULT_MIN_OLDER_PASSED_OVER = 3;
-/**
- * Detect availability/recency bias in a recall result.
- *
- * Returns an AvailabilityHint when ALL of the following hold:
- *   1. topK.length >= minReturned AND pool.length >= minPool (enough signal);
- *   2. recentFraction > recentFractionThreshold (returned slice is recency-dominated);
- *   3. poolMedianAgeDays > topKMedianAgeDays (the pool genuinely skews older,
- *      so recency is not just the corpus being young);
- *   4. olderCandidatesPassedOver >= minOlderPassedOver (older matched memories
- *      actually existed and were not returned).
- * Otherwise returns null.
- *
- * Entries with an unparseable `created` are dropped defensively so a malformed
- * row cannot poison the medians with NaN.
- */
+/** Returns an AvailabilityHint when the returned slice is recency-dominated, the pool skews older and older matches were passed over; else null.
+ * Entries with an unparseable `created` are dropped so a malformed row cannot poison the medians with NaN. */
 export declare function detectAvailabilityBias(opts: DetectAvailabilityBiasOpts): AvailabilityHint | null;
 //# sourceMappingURL=availability.d.ts.map

package/dist/{availability.js → api/availability.js}

@@ -1,27 +1,9 @@
-// ---------------------------------------------------------------------------
-// Availability-bias detector (biases over memory state)
-// ---------------------------------------------------------------------------
-//
-// Flags when a recall's returned top-K is dominated by recent entries while
-// substantially older relevant candidates in the same MATCHED pool were passed
-// over. This is the availability / recency heuristic (Tversky-Kahneman): what
-// is most mentally available (recent) gets over-weighted relative to what is
-// most relevant. Hippo's substrate makes this measurable: every entry carries a
-// creation timestamp, so we can compare the age distribution of what was
-// RETURNED against the age distribution of the pool it was drawn from.
-//
-// Soft warning ONLY: this never filters, reorders, or suppresses a result. It surfaces
-// a hint the calling agent may act on, like anchoringHint / planningFallacyHint / suppressionSummary.
-//
-// PURE: no I/O, no env reads. The env gate (HIPPO_AVAILABILITY=off) and the
-// audit emission live in the callers (api.recall, cmdRecall, MCP), mirroring
-// detectAnchoring in recall-history.ts.
-export const DEFAULT_RECENCY_WINDOW_MS = 24 * 60 * 60 * 1000;
+import { DAY_MS } from '../util/time.js';
+export const DEFAULT_RECENCY_WINDOW_MS = DAY_MS;
 export const DEFAULT_RECENT_FRACTION_THRESHOLD = 0.7;
 export const DEFAULT_MIN_RETURNED = 3;
 export const DEFAULT_MIN_POOL = 10;
 export const DEFAULT_MIN_OLDER_PASSED_OVER = 3;
-const MS_PER_DAY = 24 * 60 * 60 * 1000;
 const MS_PER_HOUR = 60 * 60 * 1000;
 function median(nums) {
     if (nums.length === 0)
@@ -30,21 +12,13 @@ function median(nums) {
     const mid = Math.floor(sorted.length / 2);
     return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
 }
-/**
- * Detect availability/recency bias in a recall result.
- *
- * Returns an AvailabilityHint when ALL of the following hold:
- *   1. topK.length >= minReturned AND pool.length >= minPool (enough signal);
- *   2. recentFraction > recentFractionThreshold (returned slice is recency-dominated);
- *   3. poolMedianAgeDays > topKMedianAgeDays (the pool genuinely skews older,
- *      so recency is not just the corpus being young);
- *   4. olderCandidatesPassedOver >= minOlderPassedOver (older matched memories
- *      actually existed and were not returned).
- * Otherwise returns null.
- *
- * Entries with an unparseable `created` are dropped defensively so a malformed
- * row cannot poison the medians with NaN.
- */
+function parseTimestamps(refs) {
+    return refs
+        .map((e) => ({ id: e.id, ts: Date.parse(e.created) }))
+        .filter((e) => Number.isFinite(e.ts));
+}
+/** Returns an AvailabilityHint when the returned slice is recency-dominated, the pool skews older and older matches were passed over; else null.
+ * Entries with an unparseable `created` are dropped so a malformed row cannot poison the medians with NaN. */
 export function detectAvailabilityBias(opts) {
     const now = opts.now ?? Date.now();
     const recencyWindowMs = opts.recencyWindowMs ?? DEFAULT_RECENCY_WINDOW_MS;
@@ -52,24 +26,20 @@ export function detectAvailabilityBias(opts) {
     const minReturned = opts.minReturned ?? DEFAULT_MIN_RETURNED;
     const minPool = opts.minPool ?? DEFAULT_MIN_POOL;
     const minOlderPassedOver = opts.minOlderPassedOver ?? DEFAULT_MIN_OLDER_PASSED_OVER;
-    const topK = opts.topK
-        .map((e) => ({ id: e.id, ts: Date.parse(e.created) }))
-        .filter((e) => Number.isFinite(e.ts));
-    const pool = opts.pool
-        .map((e) => ({ id: e.id, ts: Date.parse(e.created) }))
-        .filter((e) => Number.isFinite(e.ts));
+    const topK = parseTimestamps(opts.topK);
+    const pool = parseTimestamps(opts.pool);
     if (topK.length < minReturned || pool.length < minPool)
         return null;
     const recentCount = topK.filter((e) => now - e.ts <= recencyWindowMs).length;
     const recentFraction = recentCount / topK.length;
     if (recentFraction <= recentFractionThreshold)
         return null;
-    const topKMedianAgeDays = median(topK.map((e) => (now - e.ts) / MS_PER_DAY));
-    const poolMedianAgeDays = median(pool.map((e) => (now - e.ts) / MS_PER_DAY));
+    const topKMedianAgeDays = median(topK.map((e) => (now - e.ts) / DAY_MS));
+    const poolMedianAgeDays = median(pool.map((e) => (now - e.ts) / DAY_MS));
     if (poolMedianAgeDays <= topKMedianAgeDays)
         return null;
     const topKIds = new Set(topK.map((e) => e.id));
-    const olderCandidatesPassedOver = pool.filter((e) => !topKIds.has(e.id) && (now - e.ts) / MS_PER_DAY > topKMedianAgeDays).length;
+    const olderCandidatesPassedOver = pool.filter((e) => !topKIds.has(e.id) && (now - e.ts) / DAY_MS > topKMedianAgeDays).length;
     if (olderCandidatesPassedOver < minOlderPassedOver)
         return null;
     const pct = Math.round(recentFraction * 100);

package/dist/{context-auto.js → api/context-auto.js}

@@ -1,4 +1,5 @@
 import { execFileSync } from 'child_process';
+const MAX_DIFF_TERMS = 10;
 const SKIPPED_PATH_TERMS = ['src', 'dist', 'test', 'tests', 'node_modules', 'index'];
 // stderr is dropped because git's warnings (line-ending notices, for one) would otherwise become query terms.
 function readGit(args) {
@@ -13,7 +14,7 @@ export function autoDetectContext() {
                 .split('\n')
                 .flatMap((f) => f.replace(/[/\\.]/g, ' ').split(/\s+/))
                 .filter((t) => t.length > 2 && !SKIPPED_PATH_TERMS.includes(t))
-                .slice(0, 10);
+                .slice(0, MAX_DIFF_TERMS);
             if (terms.length > 0)
                 return terms.join(' ');
         }

package/dist/{context-render.d.ts → api/context-render.d.ts}

@@ -1,7 +1,7 @@
-import { type MemoryEntry } from './memory.js';
-import { type SessionHandoff } from './handoff.js';
-import type { SessionEvent, TaskSnapshot } from './store/rows.js';
-import type { AssembleCost, AssembleResult, AssembledContextItem, ContextCost, ContextResultEntry, DrillDownChild, DrillDownCost, DrillDownResult } from './api.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type SessionHandoff } from '../core/handoff.js';
+import type { SessionEvent, TaskSnapshot } from '../store/rows.js';
+import type { AssembleCost, AssembleResult, AssembledContextItem, ContextCost, ContextResultEntry, DrillDownChild, DrillDownCost, DrillDownResult } from './index.js';
 export declare function snapshotText(s: TaskSnapshot): string;
 export declare function handoffText(h: SessionHandoff): string;
 /** Needs at least one event; the header reads the latest. */

package/dist/{context-render.js → api/context-render.js}

@@ -1,9 +1,10 @@
 // The strings a context block prints. The budget prices these same strings, so selection and print cannot drift.
-import { calculateStrength, confidenceFacets, confidenceLabel } from './memory.js';
-import { evalNow } from './ablation.js';
-import { estimateTokens } from './token-ledger.js';
-import { renderAmbientSummary } from './ambient.js';
-import { formatHandoffEvidenceLine } from './handoff.js';
+import { calculateStrength, confidenceFacets, confidenceLabel } from '../core/memory.js';
+import { evalNow } from '../core/ablation.js';
+import { estimateTokens } from '../util/token-text.js';
+import { renderAmbientSummary } from '../core/ambient.js';
+import { formatHandoffEvidenceLine } from '../core/handoff.js';
+import { DATE_PREFIX_CHARS } from '../util/token-text.js';
 export function snapshotText(s) {
     return [
         '## Active Task Snapshot\n',
@@ -78,7 +79,7 @@ export function contextLine(item, framing, showStrength, now, strengthPct = Math
     const label = confidenceLabel(e, now);
     const confTag = `[${label.text}]${label.warn ? ' ⚠️' : ''}`;
     if (framing === 'observe') {
-        const dateStr = new Date(e.created).toISOString().slice(0, 10);
+        const dateStr = new Date(e.created).toISOString().slice(0, DATE_PREFIX_CHARS);
         // Verified rules print without the date prefix.
         if (confidenceFacets(e, now).tier === 'verified')
             return `- **${confTag} ${globalPrefix}${e.content}**${tagStr}${strengthStr}`;

package/dist/api/context-select.d.ts

@@ -1,9 +1,9 @@
 import type { AmbientLoadResult } from '../store/candidates.js';
-import { type MemoryEntry } from '../memory.js';
-import type { ContextReads, HippoStore } from '../store-port.js';
-import { type HippoConfig } from '../config.js';
-import type { ProjectRef } from '../project-identity.js';
-import type { DeliveryObserver } from '../delivery-recorder.js';
+import { type MemoryEntry } from '../core/memory.js';
+import type { ContextReads, HippoStore } from '../store/index.js';
+import { type HippoConfig } from '../core/config.js';
+import type { ProjectRef } from '../core/project-identity.js';
+import type { DeliveryObserver } from '../store/delivery-recorder.js';
 import type { ContextCost, ContextOpts, ContextResultEntry } from './context-types.js';
 import type { Context } from './types.js';
 /** One store getContext reads rows from: its base search and its context reads. */