hippo-memory 1.69.0 → 1.71.0

package/dist/api/remember.js

@@ -1,15 +1,14 @@
 // Write path: remember stores one memory after secret vetting and, for untrusted content, the instruction check.
-import { writeEntry } from '../store/entry-writes.js';
 import { stampOriginProject } from '../store/entry-row.js';
-import { requireGroup } from '../store-port.js';
-import { detectInstruction } from '../instruction-detect.js';
-import { quarantineScopeFor, recordQuarantine } from '../quarantine.js';
-import { createMemory } from '../memory.js';
-import { loadConfig } from '../config.js';
-import { vetSecrets } from '../secret-detect.js';
-import { assertCallerProject } from '../project-identity.js';
-import { BadRequestError } from '../api-errors.js';
-import { assertClientScope, personalScopeOf } from '../recall-scope.js';
+import { detectInstruction } from './instruction-detect.js';
+import { quarantineScopeFor } from '../trust/quarantine.js';
+import { createMemory } from '../core/memory.js';
+import { loadConfig } from '../core/config.js';
+import { vetSecrets } from '../util/secret-detect.js';
+import { assertCallerProject } from '../core/project-identity.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { assertClientScope, personalScopeOf } from '../store/recall-scope.js';
+import { andThen, notPorted, onStore } from './on-store.js';
 /** The scope a write lands in: the caller's own personal scope when asked for, else the client's, which may not be a personal one. */
 function rememberScope(ctx, opts) {
     if (!opts.personal) {
@@ -32,7 +31,15 @@ function prepareRemember(ctx, opts) {
     const requestedScope = rememberScope(ctx, opts);
     const vetted = vetSecrets(opts.content, opts.tags ?? [], opts.untrusted === true);
     const detection = opts.untrusted ? detectInstruction(vetted.content) : { flagged: false, reason: null };
-    const entry = createMemory(vetted.content, {
+    const local = opts.local ?? {};
+    const created = createMemory(vetted.content, {
+        layer: local.layer,
+        pinned: local.pinned,
+        confidence: local.confidence,
+        source: local.source,
+        schema_fit: local.schemaFit,
+        trace_outcome: local.traceOutcome,
+        source_session_id: local.sourceSessionId,
         kind: opts.kind ?? 'distilled',
         scope: detection.flagged ? quarantineScopeFor(requestedScope) : requestedScope,
         owner: opts.owner ?? null,
@@ -41,54 +48,43 @@ function prepareRemember(ctx, opts) {
         tenantId: ctx.tenantId,
         baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
     });
+    const entry = local.weaken ? weakened(created, local.weaken) : created;
     // Aliases only widen what a reader matches; a row has one origin. A personal row's '' follows its owner into every project.
     const origin = opts.personal ? '' : opts.project?.name;
     const stamped = origin !== undefined ? { ...entry, origin_project: origin } : entry;
     return { entry: stamped, requestedScope, detection, warnings: vetted.warnings };
 }
-function rememberResult(ctx, prepared) {
+function weakened(entry, weaken) {
+    return { ...entry, strength: weaken.strength, half_life_days: Math.max(1, entry.half_life_days * weaken.halfLifeFactor) };
+}
+function rememberResult(ctx, prepared, written) {
     const { entry, detection, warnings } = prepared;
     const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
     if (detection.flagged)
         result.quarantined = { reason: detection.reason ?? 'unknown' };
     if (warnings.length > 0)
         result.warnings = [...warnings];
+    if (written?.outcome === 'duplicate')
+        result.duplicate = { memoryId: written.memoryId };
     return result;
 }
-/** Store one memory. With `ctx.store`, its entryWrites group writes the row and its remember row; hippo.db is opened only when there is no store. */
-export function remember(ctx, opts) {
-    const reply = ctx.store ? rememberThroughStore(ctx, ctx.store, opts) : rememberOnHippoDb(ctx, opts);
-    // SAFETY: a C typed with a store gets the promise its path returns; a wide C is typed as the union, which a caller has to await anyway.
-    return reply;
-}
-/** afterWrite and the quarantine row write on hippo.db's own handle, and only connectors send them, so a store refuses both. */
-async function rememberThroughStore(ctx, store, opts) {
-    const entryWrites = requireGroup(store, 'entryWrites');
-    if (opts.afterWrite || opts.untrusted)
-        throw new Error('afterWrite and untrusted content are written to hippo.db only, never through a store');
-    const prepared = prepareRemember(ctx, opts);
-    // The store writes origin_project as given, so the served folder's fallback is stamped here.
-    await entryWrites.writeEntry({ entry: stampOriginProject(ctx.hippoRoot, prepared.entry), actor: ctx.actor.subject });
-    return rememberResult(ctx, prepared);
+/** A flagged row's review record, which the store writes in the row's own transaction. */
+function quarantineOf({ requestedScope, detection }) {
+    return detection.flagged ? { originalScope: requestedScope, reason: detection.reason ?? 'unknown' } : undefined;
 }
-function rememberOnHippoDb(ctx, opts) {
-    const prepared = prepareRemember(ctx, opts);
-    const { requestedScope, detection } = prepared;
-    // writeEntry threads ctx.actor.subject into its internal audit hook, so exactly
-    // one 'remember' event lands in the log with the supplied actor.
-    const afterWrite = detection.flagged
-        ? (db, memoryId) => {
-            recordQuarantine(db, {
-                tenantId: ctx.tenantId,
-                memoryId,
-                originalScope: requestedScope,
-                reason: detection.reason ?? 'unknown',
-                actor: ctx.actor.subject,
-            });
-            opts.afterWrite?.(db, memoryId);
-        }
-        : opts.afterWrite;
-    writeEntry(ctx.hippoRoot, prepared.entry, { actor: ctx.actor.subject, afterWrite });
-    return rememberResult(ctx, prepared);
+/** Store one memory: the store's entryWrites group writes the row and its one remember audit row, under the caller's subject.
+ *  A write that carries a connector event or untrusted content goes through connectorWrites, which commits its companion rows with it. */
+export function remember(ctx, opts) {
+    return onStore(ctx, (port) => {
+        const entryWrites = port.entryWrites ?? notPorted(port, 'entryWrites');
+        const prepared = prepareRemember(ctx, opts);
+        // A store writes origin_project as given, so the served folder's fallback is stamped here.
+        const write = { entry: stampOriginProject(ctx.hippoRoot, prepared.entry), actor: ctx.actor.subject };
+        if (opts.untrusted !== true && opts.event === undefined)
+            return andThen(entryWrites.writeEntry(write), () => rememberResult(ctx, prepared));
+        const connectorWrites = port.connectorWrites ?? notPorted(port, 'connectorWrites');
+        const written = connectorWrites.writeConnectorEntry({ ...write, event: opts.event, quarantine: quarantineOf(prepared) });
+        return andThen(written, (outcome) => rememberResult(ctx, prepared, outcome));
+    });
 }
 //# sourceMappingURL=remember.js.map

package/dist/api/session-owners.d.ts

@@ -0,0 +1,4 @@
+import { type Context } from './types.js';
+/** Binds `sessionId` to the caller's owner on first use; a session another owner holds is a 409, so the client can set it aside. */
+export declare function bindSessionOwner(ctx: Context, sessionId: string): void;
+//# sourceMappingURL=session-owners.d.ts.map

package/dist/api/session-owners.js

@@ -0,0 +1,17 @@
+// A session id belongs to the first owner that binds it, so one developer's client cannot write into another's session.
+import { ConflictError } from '../core/api-errors.js';
+import { ownerOrSubject } from './types.js';
+import { sessionOwnerOrBind } from '../store/sessions.js';
+import { assertTenantId } from '../store/tenant.js';
+import { DAY_MS } from '../util/time.js';
+/** Bindings older than this are pruned when a new session binds. */
+const BINDING_RETENTION_DAYS = 90;
+/** Binds `sessionId` to the caller's owner on first use; a session another owner holds is a 409, so the client can set it aside. */
+export function bindSessionOwner(ctx, sessionId) {
+    assertTenantId('bindSessionOwner', ctx.tenantId);
+    const owner = ownerOrSubject(ctx.actor);
+    const bound = sessionOwnerOrBind(ctx.hippoRoot, { tenantId: ctx.tenantId, sessionId, owner, retentionMs: BINDING_RETENTION_DAYS * DAY_MS });
+    if (bound !== owner)
+        throw new ConflictError('session id belongs to another caller');
+}
+//# sourceMappingURL=session-owners.js.map

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

@@ -1,13 +1,12 @@
 import { loadAllEntries } from '../store/entry-reads.js';
-import { deleteEntry } from '../store/delete-and-batch.js';
-import { auditMemories } from '../audit.js';
-import { autoShare } from '../shared.js';
+import { auditMemories } from '../store/audit.js';
+import { autoShare } from '../sharing/share.js';
 import { consolidate } from '../consolidate/sleep.js';
-import { loadConfig } from '../config.js';
-import { deduplicateStore } from '../dedupe.js';
-import { computeAmbientState } from '../ambient.js';
-import { loadPendingExtractionTenants } from '../graph/read.js';
-import { type ExtractResult } from '../graph-extract.js';
+import { loadConfig } from '../core/config.js';
+import { deduplicateStore } from '../consolidate/dedupe.js';
+import { computeAmbientState } from '../core/ambient.js';
+import { loadPendingExtractionTenants } from '../store/graph-queue.js';
+import { type ExtractResult } from '../graph/extract.js';
 import type { Context } from './types.js';
 import type { SleepOpts, SleepResult } from './sleep.js';
 /** Test-only seam: `runSleep` overrides force a phase to throw into emitSleepAudit's `partial: true` row; production never sets them. */
@@ -17,7 +16,6 @@ export interface SleepPhases {
     auditMemories: typeof auditMemories;
     autoShare: typeof autoShare;
     loadAllEntries: typeof loadAllEntries;
-    deleteEntry: typeof deleteEntry;
     computeAmbientState: typeof computeAmbientState;
     loadConfig: typeof loadConfig;
     loadPendingExtractionTenants: typeof loadPendingExtractionTenants;

package/dist/api/sleep-run.js

@@ -1,24 +1,24 @@
 // The sleep pipeline behind `sleep`, with its phase dependencies injectable; kept out of the package root.
-import { openHippoDb, closeHippoDb } from '../db.js';
 import { loadAllEntries } from '../store/entry-reads.js';
-import { deleteEntry, memoriesBackingObjects } from '../store/delete-and-batch.js';
-import { appendAuditEvent, reportAuditWriteFailure, auditMemories } from '../audit.js';
-import { autoShare } from '../shared.js';
+import { memoriesBackingObjects } from '../store/delete-and-batch.js';
+import { reportAuditWriteFailure, auditMemories } from '../store/audit.js';
+import { sqliteSyncStore } from '../store/sqlite/store.js';
+import { autoShare } from '../sharing/share.js';
 import { consolidate } from '../consolidate/sleep.js';
 import { failedUnitOf } from '../store/delete-and-batch.js';
-import { loadConfig } from '../config.js';
-import { deduplicateStore } from '../dedupe.js';
-import { computeAmbientState } from '../ambient.js';
-import { loadPendingExtractionTenants } from '../graph/read.js';
-import { markPendingProcessedUpTo } from '../graph/write.js';
-import { extractGraphChunked } from '../graph-extract.js';
+import { loadConfig } from '../core/config.js';
+import { deduplicateStore } from '../consolidate/dedupe.js';
+import { computeAmbientState } from '../core/ambient.js';
+import { loadPendingExtractionTenants, markPendingProcessedUpTo } from '../store/graph-queue.js';
+import { extractGraphChunked } from '../graph/extract.js';
+import { removeAuditErrors } from './audit.js';
+import { errorMessage } from '../util/log.js';
 const DEFAULT_SLEEP_PHASES = {
     consolidate,
     deduplicateStore,
     auditMemories,
     autoShare,
     loadAllEntries,
-    deleteEntry,
     computeAmbientState,
     loadConfig,
     loadPendingExtractionTenants,
@@ -28,18 +28,15 @@ const DEFAULT_SLEEP_PHASES = {
 export async function runSleep(ctx, opts, overrides = {}) {
     const dryRun = Boolean(opts.dryRun);
     const phases = { ...DEFAULT_SLEEP_PHASES, ...overrides };
-    // Phase counters for the consolidate audit emit (in finally).
-    // Accumulated as each phase completes so partial-failure paths still report
-    // accurate "what got done before the failure" data.
+    // Phase counters for the consolidate audit emit (in finally), accumulated per phase so a partial failure still reports what got done.
     const counts = { consolidation: 0, dedup: 0, auditDeleted: 0, ambient: 0 };
     let phaseError = null;
     try {
         return await runSleepPhases(ctx, opts, phases, counts);
     }
     catch (err) {
-        // SAFETY: phaseError is read via phaseError.message / (phaseError !==
-        // null) below, both safe even if a non-Error was thrown; this mirrors
-        // the existing lenient (err as Error) pattern used throughout this catch chain.
+        // SAFETY: phaseError is only read via phaseError.message / (phaseError !== null) below, safe even if a non-Error was thrown;
+        // this mirrors the lenient (err as Error) pattern used through this catch chain.
         phaseError = err;
         throw err;
     }
@@ -60,14 +57,15 @@ async function runSleepPhases(ctx, opts, phases, counts) {
     if (dedupResult.removed > 0)
         result.deduped = dedupSummary(dedupResult);
     // Phase 3: Quality audit (remove junk, report warnings; a dry run skips rows earlier phases would remove).
-    counts.auditDeleted = runQualityAudit(ctx, phases, dryRun, consolidateResult, dedupResult, result);
+    const audited = runQualityAudit(ctx, phases, { dryRun, consolidateResult, dedupResult, result });
+    counts.auditDeleted = audited.removed;
     if (dryRun)
         return result;
     // Phase 4: Auto-share high-transfer-score memories to global.
     if (!opts.noShare)
         shareOnSleep(ctx, phases, result);
     // Phase 5: Post-sleep ambient state summary.
-    counts.ambient = summarizeAmbient(ctx, phases, result);
+    counts.ambient = summarizeAmbient(ctx, phases, result, audited.remaining);
     await drainGraphQueue(ctx, phases, snapshot, result);
     return result;
 }
@@ -80,10 +78,7 @@ function snapshotDirtyTenants(ctx, phases, dryRun) {
             snapshot.dirtyTenants = phases.loadPendingExtractionTenants(ctx.hippoRoot);
         }
         catch (snapErr) {
-            // SAFETY: this is a best-effort log message only; property access on
-            // any JS value is safe (undefined if absent), preserving the existing
-            // lenient formatting even when something non-Error was thrown.
-            snapshot.error = snapErr.message;
+            snapshot.error = errorMessage(snapErr);
         }
     }
     return snapshot;
@@ -118,28 +113,26 @@ function dedupSummary(dedupResult) {
         crossDups,
     };
 }
-/** Returns how many audit errors were deleted, or would be under dryRun. */
-function runQualityAudit(ctx, phases, dryRun, consolidateResult, dedupResult, result) {
+/** `removed` counts audit errors deleted (or that would be under dryRun); `remaining` is what the audit read, less the rows it deleted. */
+function runQualityAudit(ctx, phases, options) {
+    const { dryRun, consolidateResult, dedupResult, result } = options;
     const planned = new Set(dryRun ? [...(consolidateResult.removedIds ?? []), ...dedupResult.pairs.map((p) => p.removed)] : []);
     const allEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !planned.has(e.id));
     const auditOut = phases.auditMemories(allEntries, memoriesBackingObjects(ctx.hippoRoot));
     if (auditOut.issues.length === 0)
-        return 0;
+        return { removed: 0, remaining: allEntries };
     const errors = auditOut.issues.filter((i) => i.severity === 'error');
     const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
-    let removed = 0;
-    for (const issue of errors) {
-        const reason = `sleep-audit: ${issue.reason}`;
-        if (dryRun || phases.deleteEntry(ctx.hippoRoot, issue.memoryId, { actor: ctx.actor.subject, reason, automatic: true }))
-            removed++;
-    }
+    const gone = dryRun ? errors.map((issue) => issue.memoryId) : removeAuditErrors(ctx, 'sleep-audit', errors);
+    const removed = gone.length;
+    const deleted = new Set(gone);
     if (removed > 0 || warnings.length > 0) {
         result.audit = {
             errorsRemoved: removed,
             warningCount: warnings.length,
         };
     }
-    return removed;
+    return { removed, remaining: allEntries.filter((e) => !deleted.has(e.id)) };
 }
 function shareOnSleep(ctx, phases, result) {
     const sleepConfig = phases.loadConfig(ctx.hippoRoot);
@@ -159,11 +152,11 @@ function shareOnSleep(ctx, phases, result) {
     }
 }
 /** Returns the ambient total the audit row reports: 0 when ambient is off or no current row is left. */
-function summarizeAmbient(ctx, phases, result) {
+function summarizeAmbient(ctx, phases, result, loaded) {
     const postSleepConfig = phases.loadConfig(ctx.hippoRoot);
     if (!postSleepConfig.ambient.enabled)
         return 0;
-    const postSleepEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !e.superseded_by);
+    const postSleepEntries = loaded.filter((e) => !e.superseded_by);
     if (postSleepEntries.length === 0)
         return 0;
     result.ambient = phases.computeAmbientState(postSleepEntries);
@@ -180,49 +173,45 @@ async function drainGraphQueue(ctx, phases, snapshot, result) {
                 `graph: dirty-tenant snapshot failed (skipped graph refresh): ${snapshot.error}`,
             ];
         }
-        let gTenants = 0;
-        let gEntities = 0;
-        let gRelations = 0;
+        const rebuilt = { tenants: 0, entities: 0, relations: 0 };
         // dirtyTenants was snapshotted before the memory-deleting phases above.
         for (const { tenantId, maxPendingId } of snapshot.dirtyTenants) {
-            try {
-                const ext = await phases.extractGraph(ctx.hippoRoot, tenantId);
-                // Count the rebuild as soon as it succeeds — it happened regardless of
-                // the drain-mark below.
-                gTenants += 1;
-                gEntities += ext.entities;
-                gRelations += ext.relations;
-                if (ext.skipped) {
-                    result.details = [
-                        ...(result.details ?? []),
-                        `graph: ${ext.skipped} stale op(s) skipped for a tenant; the next sleep redoes them`,
-                    ];
-                }
-                // Watermark drain: only items enqueued before this rebuild started are marked; later arrivals stay pending.
-                // Marked only after the last chunk, so a run stopped between chunks leaves the tenant for the next one.
-                markPendingProcessedUpTo(ctx.hippoRoot, tenantId, maxPendingId);
-            }
-            catch (tenantErr) {
-                // SAFETY: this is a best-effort log message only; property access
-                // on any JS value is safe (undefined if absent), preserving the
-                // existing lenient formatting even when something non-Error was thrown.
-                result.details = [
-                    ...(result.details ?? []),
-                    `graph: extract failed for a dirty tenant (left pending): ${tenantErr.message}`,
-                ];
-            }
+            await rebuildDirtyTenant(ctx, phases, { tenantId, maxPendingId }, rebuilt, result);
         }
-        if (gTenants > 0) {
-            result.graph = { tenants: gTenants, entities: gEntities, relations: gRelations };
+        if (rebuilt.tenants > 0) {
+            result.graph = rebuilt;
         }
     }
     catch (graphErr) {
-        // SAFETY: this is a best-effort log message only; property access on
-        // any JS value is safe (undefined if absent), preserving the existing
-        // lenient formatting even when something non-Error was thrown.
         result.details = [
             ...(result.details ?? []),
-            `graph: drain phase failed (skipped): ${graphErr.message}`,
+            `graph: drain phase failed (skipped): ${errorMessage(graphErr)}`,
+        ];
+    }
+}
+/** Rebuilds one dirty tenant's graph into `rebuilt` and drains its queue; a failure is a detail line and the tenant stays pending. */
+async function rebuildDirtyTenant(ctx, phases, dirty, rebuilt, result) {
+    try {
+        const ext = await phases.extractGraph(ctx.hippoRoot, dirty.tenantId);
+        // Count the rebuild as soon as it succeeds — it happened regardless of
+        // the drain-mark below.
+        rebuilt.tenants += 1;
+        rebuilt.entities += ext.entities;
+        rebuilt.relations += ext.relations;
+        if (ext.skipped) {
+            result.details = [
+                ...(result.details ?? []),
+                `graph: ${ext.skipped} stale op(s) skipped for a tenant; the next sleep redoes them`,
+            ];
+        }
+        // Watermark drain: only items enqueued before this rebuild started are marked; later arrivals stay pending.
+        // Marked only after the last chunk, so a run stopped between chunks leaves the tenant for the next one.
+        markPendingProcessedUpTo(ctx.hippoRoot, dirty.tenantId, dirty.maxPendingId);
+    }
+    catch (tenantErr) {
+        result.details = [
+            ...(result.details ?? []),
+            `graph: extract failed for a dirty tenant (left pending): ${errorMessage(tenantErr)}`,
         ];
     }
 }
@@ -230,34 +219,29 @@ async function drainGraphQueue(ctx, phases, snapshot, result) {
 // Its own handle; an audit failure is logged and never replaces the original phase error.
 function emitSleepAudit(ctx, opts, dryRun, counts, phaseError) {
     try {
-        const db = openHippoDb(ctx.hippoRoot);
-        try {
-            const sleepAuditMetadata = {
-                consolidationCount: counts.consolidation,
-                dedupCount: counts.dedup,
-                auditDeletedCount: counts.auditDeleted,
-                ambientTotal: counts.ambient,
-                dryRun,
-                noShare: opts.noShare ?? false,
-                partial: phaseError !== null,
-                triggeredByTenant: ctx.tenantId, // preserve for audit forensics
-            };
-            if (phaseError)
-                sleepAuditMetadata.errorMessage = phaseError.message;
-            // A flush stopped between chunks names the unit it would have committed next, so a unit that fails every night can be found.
-            const nextUnitIds = failedUnitOf(phaseError);
-            if (nextUnitIds)
-                sleepAuditMetadata.nextUnitIds = nextUnitIds;
-            appendAuditEvent(db, {
+        // Tagged '__host__' because sleep is host-wide; the actor still names the operator who ran it.
+        const sleepAuditMetadata = {
+            consolidationCount: counts.consolidation,
+            dedupCount: counts.dedup,
+            auditDeletedCount: counts.auditDeleted,
+            ambientTotal: counts.ambient,
+            dryRun,
+            noShare: opts.noShare ?? false,
+            partial: phaseError !== null,
+            triggeredByTenant: ctx.tenantId, // preserve for audit forensics
+        };
+        if (phaseError)
+            sleepAuditMetadata.errorMessage = phaseError.message;
+        // A flush stopped between chunks names the unit it would have committed next, so a unit that fails every night can be found.
+        const nextUnitIds = failedUnitOf(phaseError);
+        if (nextUnitIds)
+            sleepAuditMetadata.nextUnitIds = nextUnitIds;
+        sqliteSyncStore(ctx.hippoRoot).appendAuditEvents([{
                 tenantId: '__host__',
                 actor: ctx.actor.subject,
                 op: 'consolidate',
                 metadata: { ...sleepAuditMetadata },
-            });
-        }
-        finally {
-            closeHippoDb(db);
-        }
+            }]);
     }
     catch (auditErr) {
         // Logged, never thrown: a second failure must not mask the original phaseError.

package/dist/api/sleep.d.ts

@@ -1,26 +1,20 @@
-import type { AmbientState } from '../ambient.js';
+import type { AmbientState } from '../core/ambient.js';
 import type { Context } from './types.js';
 /** Options for `sleep`, one consolidation cycle on a SQLite store that returns counts; unlike `hippo sleep` it skips the auto-learn step. */
 export interface SleepOpts {
     /** Report what a sleep would change without applying it; sharing, the ambient summary and the graph refresh are skipped. */
     dryRun?: boolean;
-    /** Skip copying high-scoring memories to the global store under `HIPPO_HOME`. Default false, so every tenant's memories are eligible; multi-tenant callers pass `true`. */
+    /** Skip copying high-scoring memories to the global store under `HIPPO_HOME`. Default
+     * false, so every tenant's memories are eligible; multi-tenant callers pass `true`. */
     noShare?: boolean;
 }
 export interface SleepResult {
     active: number;
     removed: number;
-    /**
-     * Faded memories the decay pass moved to the dormant store instead of
-     * deleting (config `dormant.enabled`). Absent when 0. Per-invocation
-     * activity counter, same class as `removed`.
-     */
+    /** Faded memories the decay pass moved to the dormant store instead of deleting (config `dormant.enabled`); absent when 0. Per-invocation counter, like
+     * `removed`. */
     dormant?: number;
-    /**
-     * Dormant memories deleted for good this sleep because they outlived
-     * `dormant.retentionDays`. Absent when 0. Same per-invocation class as
-     * `removed`.
-     */
+    /** Dormant memories deleted for good this sleep for outliving `dormant.retentionDays`; absent when 0. Per-invocation counter, like `removed`. */
     dormantExpired?: number;
     mergedEpisodic: number;
     newSemantic: number;
@@ -36,26 +30,13 @@ export interface SleepResult {
         warningCount: number;
     };
     shared?: number;
-    /**
-     * Count of memories the auto-share secret veto withheld this sleep
-     * — rows that passed every other admission gate (transfer score,
-     * not-already-global) and were blocked solely by `detectSecret`. Absent
-     * when 0 or when auto-share did not run.
-     */
+    /** Memories the auto-share secret veto withheld: rows that passed every other gate but `detectSecret`; absent when 0 or auto-share did not run. */
     secretSkipped?: number;
-    /**
-     * Count of auto-share candidates the GLOBAL store's rejection
-     * tombstone refused this sleep; copy paths must not let one rejected
-     * candidate abort the batch. Absent when 0 or when auto-share did not run.
-     */
+    /** Auto-share candidates the GLOBAL store's rejection tombstone refused (one must not abort the batch); absent when 0 or auto-share did not run. */
     rejectedSkipped?: number;
     ambient?: AmbientState | null;
-    /**
-     * Graph re-extraction totals across the tenants rebuilt
-     * this sleep. Absent when no tenant was dirty, and under dryRun (the graph
-     * phase runs only on a real sleep). Cross-tenant aggregate, one reason
-     * /v1/sleep stays loopback-only.
-     */
+    /** Graph re-extraction totals across tenants rebuilt this sleep; absent when none was dirty or under dryRun.
+     * Cross-tenant aggregate: one reason /v1/sleep stays loopback-only. */
     graph?: {
         tenants: number;
         entities: number;

package/dist/api/tokens.d.ts

@@ -1,21 +1,14 @@
-import { type TokenSummary, type TokenSurface } from '../token-ledger.js';
-import { type FailureSummary } from '../failure-log.js';
+import type { TokenSummary, TokenSurface } from '../store/token-ledger.js';
+import type { FailureSummary } from '../store/failure-log.js';
 import type { Context } from './types.js';
-/**
- * Record memory text handed to an agent in the token ledger.
- * Best-effort: never throws, because a ledger failure must not fail the
- * recall or context call that produced the text.
- */
+/** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since a ledger failure must not fail the recall or context call. */
 export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
     items: number;
     tokens: number;
     sessionId?: string | null;
 }): Promise<void>;
-/**
- * Token ledger totals for the tenant over the last `days` days (default 30):
- * tokens sent, skipped as unchanged and re-read by later model calls, per
- * surface, with session counts and mean tokens per session.
- */
+/** Token ledger totals for the tenant over the last `days` days (default 30): tokens sent, skipped as unchanged and re-read,
+ * per surface, with session counts and mean tokens per session. */
 export declare function tokenSummary(ctx: Context, opts?: {
     days?: number;
 }): TokenSummary;

package/dist/api/tokens.js

@@ -1,14 +1,10 @@
 // Token-use and failure reports.
-import { openHippoDb, closeHippoDb, rethrowIfSqliteBlocked } from '../db.js';
-import { summarizeTokenUse } from '../token-ledger.js';
-import { storeFor } from '../store-port.js';
-import { summarizeFailures } from '../failure-log.js';
-import { log } from '../log.js';
-/**
- * Record memory text handed to an agent in the token ledger.
- * Best-effort: never throws, because a ledger failure must not fail the
- * recall or context call that produced the text.
- */
+import { rethrowIfSqliteBlocked } from '../db/index.js';
+import { storeFor } from '../store/index.js';
+import { failureLogSummary, tokenUseSummary } from '../store/usage-reports.js';
+import { errorMessage, log } from '../util/log.js';
+import { DAY_MS } from '../util/time.js';
+/** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since a ledger failure must not fail the recall or context call. */
 export async function recordTokens(ctx, surface, use) {
     try {
         await storeFor(ctx).recordTokens({
@@ -22,35 +18,20 @@ export async function recordTokens(ctx, surface, use) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        log.warnThenDebug('api-token-ledger', `token ledger write failed; the reply is unaffected: ${err instanceof Error ? err.message : String(err)}`);
+        log.warnThenDebug('api-token-ledger', `token ledger write failed; the reply is unaffected: ${errorMessage(err)}`);
     }
 }
-/**
- * Token ledger totals for the tenant over the last `days` days (default 30):
- * tokens sent, skipped as unchanged and re-read by later model calls, per
- * surface, with session counts and mean tokens per session.
- */
+/** Token ledger totals for the tenant over the last `days` days (default 30): tokens sent, skipped as unchanged and re-read,
+ * per surface, with session counts and mean tokens per session. */
 export function tokenSummary(ctx, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        return summarizeTokenUse(db, ctx.tenantId, reportWindowStart(opts.days));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    return tokenUseSummary(ctx.hippoRoot, ctx.tenantId, reportWindowStart(opts.days));
 }
 /** Failed tool calls by outcome, and repeats across sessions, over the last `days` days (default 30). */
 export function failureSummary(ctx, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        return summarizeFailures(db, ctx.tenantId, reportWindowStart(opts.days));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    return failureLogSummary(ctx.hippoRoot, ctx.tenantId, reportWindowStart(opts.days));
 }
 function reportWindowStart(days) {
     const span = days !== undefined && Number.isFinite(days) && days > 0 ? days : 30;
-    return new Date(Date.now() - span * 86_400_000).toISOString();
+    return new Date(Date.now() - span * DAY_MS).toISOString();
 }
 //# sourceMappingURL=tokens.js.map