hippo-memory 1.59.0 → 1.61.0

package/dist/api/remember.js

@@ -0,0 +1,43 @@
+// Write path: remember stores one memory after secret vetting and, for untrusted content, the instruction check.
+import { writeEntry } from '../store/entry-writes.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';
+export function remember(ctx, opts) {
+    const vetted = vetSecrets(opts.content, opts.tags ?? [], opts.untrusted === true);
+    const detection = opts.untrusted ? detectInstruction(vetted.content) : { flagged: false, reason: null };
+    const requestedScope = opts.scope ?? null;
+    const entry = createMemory(vetted.content, {
+        kind: opts.kind ?? 'distilled',
+        scope: detection.flagged ? quarantineScopeFor(requestedScope) : requestedScope,
+        owner: opts.owner ?? null,
+        artifact_ref: opts.artifactRef ?? null,
+        tags: opts.tags,
+        tenantId: ctx.tenantId,
+        baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
+    });
+    // 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, entry, { actor: ctx.actor.subject, afterWrite });
+    const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
+    if (detection.flagged)
+        result.quarantined = { reason: detection.reason ?? 'unknown' };
+    if (vetted.warnings.length > 0)
+        result.warnings = vetted.warnings;
+    return result;
+}
+//# sourceMappingURL=remember.js.map

package/dist/api/sleep.d.ts

@@ -0,0 +1,136 @@
+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 { consolidate } from '../consolidate/sleep.js';
+import { loadConfig } from '../config.js';
+import { deduplicateStore } from '../dedupe.js';
+import { computeAmbientState, type AmbientState } from '../ambient.js';
+import { loadPendingExtractionTenants } from '../graph/read.js';
+import { extractGraph } from '../graph-extract.js';
+import type { Context } from './types.js';
+/**
+ * Options for `sleep` — run the pure-storage consolidation pipeline
+ * (consolidate + dedup + audit + share + ambient) and return structured counts.
+ *
+ * Extracted from `cmdSleepCore` Phase 2-6 in Episode A. NOT covered by api.sleep:
+ * the cli-only auto-learn phase (Phase 1: learnFromRepo + the agent memory import),
+ * which is intrinsically host-bound (uses `process.cwd()` / `os.homedir()`).
+ * Auto-learn stays in cli.ts cmdSleepCore as a pre-api block.
+ *
+ * The CLI `cmdSleep` wrapper continues to own the log-file tee + console
+ * rendering + `process.exit`; `api.sleep` is pure (no console.log, no IO
+ * beyond the store).
+ */
+export interface SleepOpts {
+    dryRun?: boolean;
+    noShare?: boolean;
+    /**
+     * @internal Test-only DI seam — see `tests/api-sleep-phase-faults.test.ts`.
+     * Override one or more phase dependencies (typically a throwing stub) to
+     * force mid-phase failure paths deterministically. Production callers
+     * MUST NOT use this field. The runtime defaults at `DEFAULT_SLEEP_PHASES`
+     * preserve all current behaviour when `__phases` is undefined.
+     */
+    __phases?: Partial<SleepPhases>;
+}
+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`.
+     */
+    dormant?: number;
+    /**
+     * Dormant memories deleted for good this sleep because they outlived
+     * `dormant.retentionDays`. Absent when 0. Same per-invocation class as
+     * `removed`.
+     */
+    dormantExpired?: number;
+    mergedEpisodic: number;
+    newSemantic: number;
+    dryRun: boolean;
+    deduped?: {
+        removed: number;
+        semDups: number;
+        epiDups: number;
+        crossDups: number;
+    };
+    audit?: {
+        errorsRemoved: number;
+        warningCount: number;
+    };
+    shared?: number;
+    /**
+     * v1.25.0: 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.
+     */
+    secretSkipped?: number;
+    /**
+     * AT1: count of auto-share candidates the GLOBAL store's rejection
+     * tombstone refused this sleep (docs/plans/2026-08-15-at1-rejected-value-tombstone.md
+     * plan §3 — copy paths must not let one rejected candidate abort the
+     * batch). Absent when 0 or when auto-share did not run.
+     */
+    rejectedSkipped?: number;
+    ambient?: AmbientState | null;
+    /**
+     * E3 sleep enqueue-hook: 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?: {
+        tenants: number;
+        entities: number;
+        relations: number;
+    };
+    details?: string[];
+}
+/**
+ * Run the pure-storage consolidation pipeline.
+ *
+ * Tenant scope note: sleep operates on the WHOLE hippoRoot (all tenants in
+ * it), matching the pre-refactor cmdSleepCore behavior. Correct for a CLI
+ * maintenance op invoked by the operator. Episode B (v1.11.4) exposed this
+ * over HTTP `/v1/sleep` with loopback-only enforcement (per-request guard
+ * in the handler plus serve()'s boot-time host check). The TODOS.md
+ * per-tenant scoping follow-up remains open for the day non-loopback
+ * serving lands — at that point the route will need an admin-role gate OR
+ * api.sleep itself will need to scope dedup / audit / delete by ctx.tenantId.
+ *
+ * Dedup and audit deletes each log a `forget` row with the ctx actor and a
+ * `metadata.reason`. Pinned, raw, kept and object-backing rows are never auto-deleted (AUTOMATIC_DELETE_SQL).
+ * dryRun previews consolidate, dedup and audit, then returns before share/ambient.
+ */
+/**
+ * v1.12.2: Test-only DI seam shape for `sleep`'s phase dependencies.
+ *
+ * Each field defaults to the real production implementation imported at the
+ * top of this file. Test files pass a `Partial<SleepPhases>` override via
+ * `SleepOpts.__phases` (note the `__` prefix — internal-only) to inject
+ * deterministic throws for mid-phase failure-path coverage (the
+ * `partial: true` + `errorMessage` audit-row branch at line ~2098).
+ *
+ * Production callers MUST NOT use `__phases`. The field exists solely so
+ * `tests/api-sleep-phase-faults.test.ts` can force each phase boundary to
+ * throw without depending on store-corruption fragility.
+ */
+export interface SleepPhases {
+    consolidate: typeof consolidate;
+    deduplicateStore: typeof deduplicateStore;
+    auditMemories: typeof auditMemories;
+    autoShare: typeof autoShare;
+    loadAllEntries: typeof loadAllEntries;
+    deleteEntry: typeof deleteEntry;
+    computeAmbientState: typeof computeAmbientState;
+    loadConfig: typeof loadConfig;
+    loadPendingExtractionTenants: typeof loadPendingExtractionTenants;
+    extractGraph: typeof extractGraph;
+}
+export declare function sleep(ctx: Context, opts?: SleepOpts): Promise<SleepResult>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/api/sleep.js

@@ -0,0 +1,271 @@
+// The sleep cycle: decay, consolidation, dedupe, graph extraction and the other maintenance passes.
+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 { 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 { markPendingProcessedUpTo } from '../graph/write.js';
+import { extractGraph } from '../graph-extract.js';
+const DEFAULT_SLEEP_PHASES = {
+    consolidate,
+    deduplicateStore,
+    auditMemories,
+    autoShare,
+    loadAllEntries,
+    deleteEntry,
+    computeAmbientState,
+    loadConfig,
+    loadPendingExtractionTenants,
+    extractGraph,
+};
+export async function sleep(ctx, opts = {}) {
+    const dryRun = Boolean(opts.dryRun);
+    // v1.12.2: resolve phase dependencies, allowing test-only `__phases`
+    // override to inject deterministic throws for mid-phase failure coverage.
+    const phases = { ...DEFAULT_SLEEP_PHASES, ...(opts.__phases ?? {}) };
+    // v1.11.5: 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.
+    let consolidationCount = 0;
+    let dedupCount = 0;
+    let auditDeletedCount = 0;
+    let ambientTotal = 0;
+    let phaseError = null;
+    let graphSnapshotError = null;
+    let result = null;
+    try {
+        // Snapshot dirty tenants BEFORE any memory-deleting phase (consolidate /
+        // dedup / audit). The graph_extraction_queue rows are FK'd to mirror
+        // memories with ON DELETE CASCADE, so a phase that deletes a queued mirror
+        // (e.g. dedup removing a near-duplicate superseding decision) would drop the
+        // tenant from a drain-time load and leave its graph stale (codex P1). The
+        // MAX(id) watermark captured here stays valid: arrivals during sleep get a
+        // higher id and remain pending.
+        //
+        // Fail-soft (codex P2): a queue-read failure here must NOT abort core sleep
+        // (consolidation / dedup / audit run regardless). On failure, skip graph
+        // refresh this sleep (recovered next sleep) and surface a detail once
+        // `result` exists (Phase 6).
+        let dirtyTenants = [];
+        if (!dryRun) {
+            try {
+                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.
+                graphSnapshotError = snapErr.message;
+            }
+        }
+        // Phase 1: Consolidation.
+        const consolidateResult = await phases.consolidate(ctx.hippoRoot, { dryRun });
+        consolidationCount = consolidateResult.semanticCreated + consolidateResult.merged;
+        result = {
+            active: consolidateResult.decayed,
+            removed: consolidateResult.removed,
+            mergedEpisodic: consolidateResult.merged,
+            newSemantic: consolidateResult.semanticCreated,
+            dryRun,
+            details: consolidateResult.details,
+        };
+        // Set only when non-zero, so a store without dormant memories gets a
+        // byte-identical result (HTTP /v1/sleep, the CLI render snapshot).
+        if (consolidateResult.dormant > 0) {
+            result.dormant = consolidateResult.dormant;
+        }
+        if (consolidateResult.dormantExpired > 0) {
+            result.dormantExpired = consolidateResult.dormantExpired;
+        }
+        // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
+        const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject });
+        dedupCount = dedupResult.removed;
+        if (dedupResult.removed > 0) {
+            const semDups = dedupResult.pairs.filter((p) => p.keptLayer === 'semantic' && p.removedLayer === 'semantic').length;
+            const epiDups = dedupResult.pairs.filter((p) => p.keptLayer === 'episodic' && p.removedLayer === 'episodic').length;
+            const crossDups = dedupResult.pairs.filter((p) => p.keptLayer !== p.removedLayer).length;
+            result.deduped = {
+                removed: dedupResult.removed,
+                semDups,
+                epiDups,
+                crossDups,
+            };
+        }
+        // Phase 3: Quality audit (remove junk, report warnings; a dry run skips rows earlier phases would remove).
+        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) {
+            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++;
+            }
+            auditDeletedCount = removed;
+            if (removed > 0 || warnings.length > 0) {
+                result.audit = {
+                    errorsRemoved: removed,
+                    warningCount: warnings.length,
+                };
+            }
+        }
+        if (dryRun)
+            return result;
+        // Phase 4: Auto-share high-transfer-score memories to global.
+        if (!opts.noShare) {
+            const sleepConfig = phases.loadConfig(ctx.hippoRoot);
+            if (sleepConfig.autoShareOnSleep) {
+                // v1.25.0: surface the secret-veto skip count (v39 follow-up #2) so
+                // the veto is observable instead of silent.
+                // AT1: rejectedSkipped is autoShare's sibling counter for candidates
+                // the global store's rejection tombstone refused (threaded the same
+                // way as secretSkipped just below).
+                const autoShareStats = { secretSkipped: 0, rejectedSkipped: 0 };
+                const shared = phases.autoShare(ctx.hippoRoot, { minScore: 0.6, stats: autoShareStats });
+                if (shared.length > 0) {
+                    result.shared = shared.length;
+                }
+                if (autoShareStats.secretSkipped > 0) {
+                    result.secretSkipped = autoShareStats.secretSkipped;
+                }
+                if (autoShareStats.rejectedSkipped > 0) {
+                    result.rejectedSkipped = autoShareStats.rejectedSkipped;
+                }
+            }
+        }
+        // Phase 5: Post-sleep ambient state summary.
+        const postSleepConfig = phases.loadConfig(ctx.hippoRoot);
+        if (postSleepConfig.ambient.enabled) {
+            const postSleepEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !e.superseded_by);
+            if (postSleepEntries.length > 0) {
+                result.ambient = phases.computeAmbientState(postSleepEntries);
+                ambientTotal = result.ambient.totalMemories;
+            }
+        }
+        // Phase 6: Graph extraction drain (E3 sleep enqueue-hook). Rebuild the
+        // entity/relation graph for every tenant marked dirty (by markGraphDirty)
+        // since the last sleep, so `recall --hops` + cross-object `references` edges
+        // run on fresh data without a manual `hippo graph extract`. Fully
+        // fault-isolated: the consolidation work above has already committed, so a
+        // failure here must never abort sleep; a per-tenant extract failure leaves
+        // that tenant's queue items pending for the next sleep. (Skipped under
+        // dryRun via the early return above.)
+        try {
+            if (graphSnapshotError) {
+                // The dirty-tenant snapshot failed (codex P2 fail-soft). Core sleep
+                // already succeeded; surface the skipped graph refresh as a detail.
+                result.details = [
+                    ...(result.details ?? []),
+                    `graph: dirty-tenant snapshot failed (skipped graph refresh): ${graphSnapshotError}`,
+                ];
+            }
+            let gTenants = 0;
+            let gEntities = 0;
+            let gRelations = 0;
+            // dirtyTenants was snapshotted before the memory-deleting phases above.
+            for (const { tenantId, maxPendingId } of dirtyTenants) {
+                try {
+                    const ext = 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;
+                    // Watermark drain: mark processed only items enqueued before this
+                    // rebuild started (id <= maxPendingId). Arrivals during the rebuild
+                    // keep pending status and are caught next sleep; rows whose mirror was
+                    // cascade-deleted earlier this sleep are already gone (no-op).
+                    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}`,
+                    ];
+                }
+            }
+            if (gTenants > 0) {
+                result.graph = { tenants: gTenants, entities: gEntities, relations: gRelations };
+            }
+        }
+        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}`,
+            ];
+        }
+        return result;
+    }
+    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.
+        phaseError = err;
+        throw err;
+    }
+    finally {
+        // v1.11.5: emit one 'consolidate' audit_log row per api.sleep invocation,
+        // with phase counters in metadata. Closes the CLI/MCP parity gap that T6
+        // fixed for cmdOutcome (Episode A follow-up). In finally so partial-failure
+        // paths still emit; `partial: true` + errorMessage flag the failure.
+        // Dedicated handle for this emit only (phase helpers above each open their
+        // own handle via hippoRoot — SQLite single-writer makes parallel handles
+        // safe for the read-heavy phases).
+        //
+        // TODO(v1.12.0 + A5 v2): the audit row is tagged with ctx.tenantId but
+        // api.sleep is host-wide (cross-tenant dedup is intentional). When
+        // /v1/sleep moves off loopback-only, either tag with a synthetic "host"
+        // tenant or scope api.sleep per-tenant. Independent-review-critic flag,
+        // v1.11.5 ship.
+        //
+        // Error preservation: if openHippoDb or appendAuditEvent throws here, we
+        // do NOT let it replace the original phaseError (independent-review HIGH:
+        // would mask the underlying consolidation failure). Audit emit failure
+        // is logged to stderr but the original throw wins.
+        try {
+            const db = openHippoDb(ctx.hippoRoot);
+            try {
+                const sleepAuditMetadata = {
+                    consolidationCount,
+                    dedupCount,
+                    auditDeletedCount,
+                    ambientTotal,
+                    dryRun,
+                    noShare: opts.noShare ?? false,
+                    partial: phaseError !== null,
+                    triggeredByTenant: ctx.tenantId, // preserve for audit forensics
+                };
+                if (phaseError)
+                    sleepAuditMetadata.errorMessage = phaseError.message;
+                appendAuditEvent(db, {
+                    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.
+            reportAuditWriteFailure('consolidate', String(auditErr));
+        }
+    }
+}
+//# sourceMappingURL=sleep.js.map

package/dist/api/tokens.d.ts

@@ -0,0 +1,26 @@
+import { type TokenSummary, type TokenSurface } from '../token-ledger.js';
+import { type FailureSummary } from '../failure-log.js';
+import type { Context } from './types.js';
+/**
+ * Record memory text handed to an agent in the token ledger (ROADMAP TE0).
+ * Best-effort: never throws, because a ledger failure must not fail the
+ * recall or context call that produced the text.
+ */
+export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
+    items: number;
+    tokens: number;
+    sessionId?: string | null;
+}): 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.
+ */
+export declare function tokenSummary(ctx: Context, opts?: {
+    days?: number;
+}): TokenSummary;
+/** Failed tool calls by outcome, and repeats across sessions, over the last `days` days (default 30); ROADMAP CD13. */
+export declare function failureSummary(ctx: Context, opts?: {
+    days?: number;
+}): FailureSummary;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/api/tokens.js

@@ -0,0 +1,60 @@
+// Token-use and failure reports.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { recordTokenUse, summarizeTokenUse } from '../token-ledger.js';
+import { summarizeFailures } from '../failure-log.js';
+import { log } from '../log.js';
+/**
+ * Record memory text handed to an agent in the token ledger (ROADMAP TE0).
+ * Best-effort: never throws, because a ledger failure must not fail the
+ * recall or context call that produced the text.
+ */
+export function recordTokens(ctx, surface, use) {
+    try {
+        const db = openHippoDb(ctx.hippoRoot);
+        try {
+            recordTokenUse(db, {
+                tenantId: ctx.tenantId,
+                sessionId: use.sessionId ?? null,
+                surface,
+                event: 'inject',
+                items: use.items,
+                tokens: use.tokens,
+            });
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch (err) {
+        log.warnThenDebug('api-token-ledger', `token ledger write failed; the reply is unaffected: ${err instanceof Error ? err.message : String(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.
+ */
+export function tokenSummary(ctx, opts = {}) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return summarizeTokenUse(db, ctx.tenantId, reportWindowStart(opts.days));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Failed tool calls by outcome, and repeats across sessions, over the last `days` days (default 30); ROADMAP CD13. */
+export function failureSummary(ctx, opts = {}) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return summarizeFailures(db, ctx.tenantId, reportWindowStart(opts.days));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function reportWindowStart(days) {
+    const span = days !== undefined && Number.isFinite(days) && days > 0 ? days : 30;
+    return new Date(Date.now() - span * 86_400_000).toISOString();
+}
+//# sourceMappingURL=tokens.js.map

package/dist/api/types.d.ts

@@ -0,0 +1,56 @@
+import { BadRequestError } from '../api-errors.js';
+/**
+ * Actor identity + authorization role for a Context. v1.12.0 A5 v2 sub-1.
+ *
+ * Before v1.12.0, Context.actor was a bare string. v1.12.0 promotes it to an
+ * object carrying both the audit-log subject (formerly the string itself) and
+ * a role for /v1/sleep admin gating. Audit helpers continue accepting `string`
+ * — callers pass `ctx.actor.subject`. Role checks happen at the request
+ * boundary (e.g. /v1/sleep), except in authCreate and authRevoke (ForbiddenError).
+ */
+export interface Actor {
+    /** 'cli' | 'localhost:cli' | 'api_key:<key_id>' | 'mcp' | 'connector:slack' | 'connector:github' */
+    subject: string;
+    role: 'admin' | 'member';
+    /** EI2: restricted scopes a member key may read (auth.ts grantScope). Unused for admin actors. */
+    scopes?: readonly string[];
+    /** An auth resolver vouched for this caller, so its admin role stops at its own tenant. */
+    viaAuthResolver?: true;
+    /** The host's operator (CLI, stdio MCP, keyless loopback, host-tenant admin key): may act beyond its tenant. */
+    hostAdmin?: true;
+}
+export interface Context {
+    hippoRoot: string;
+    tenantId: string;
+    actor: Actor;
+}
+/**
+ * Helper for building process-local Actor values (admin and host admin),
+ * used by CLI and CLI-run connector Context constructors so the role
+ * boilerplate isn't repeated at every site. Bearer-authed callers (HTTP
+ * /v1/*) construct Actor directly from the api_keys row's role column via
+ * buildContextWithAuth in src/server.ts.
+ */
+export declare function adminActor(subject: string): Actor;
+/**
+ * Thrown by `api.recall` when a caller's options violate a recall contract
+ * that has been opted into via env. Carries a stable `code` field for HTTP /
+ * MCP / CLI render paths to discriminate without parsing the message.
+ *
+ * Codes:
+ *   - 'fresh_tail_requires_session_id' — `freshTailCount > 0` AND no
+ *     `freshTailSessionId` AND `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1`.
+ *     Default behaviour (env unset) returns tenant-wide rows; the env gate
+ *     is opt-in so multi-session tenants can fail loud instead of silently
+ *     surfacing cross-session rows tagged `isFreshTail=true`.
+ *   - 'invalid_scorer_window' — `opts.scorerWindow` is set to a non-positive,
+ *     non-integer, or non-finite value. Pre-v1.7.0 the value 0 routed
+ *     through FTS/LIKE `LIMIT 0` and then fell through to an uncapped
+ *     full-store fallback (codex v1.7.0 diff-pass P1). Validated upfront
+ *     so the contract holds.
+ */
+export declare class RecallContractError extends BadRequestError {
+    readonly code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window';
+    constructor(code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window', message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/types.js

@@ -0,0 +1,38 @@
+// Request context (caller identity and tenant) shared by every API module, plus the recall contract error.
+import { BadRequestError } from '../api-errors.js';
+/**
+ * Helper for building process-local Actor values (admin and host admin),
+ * used by CLI and CLI-run connector Context constructors so the role
+ * boilerplate isn't repeated at every site. Bearer-authed callers (HTTP
+ * /v1/*) construct Actor directly from the api_keys row's role column via
+ * buildContextWithAuth in src/server.ts.
+ */
+export function adminActor(subject) {
+    return { subject, role: 'admin', hostAdmin: true };
+}
+/**
+ * Thrown by `api.recall` when a caller's options violate a recall contract
+ * that has been opted into via env. Carries a stable `code` field for HTTP /
+ * MCP / CLI render paths to discriminate without parsing the message.
+ *
+ * Codes:
+ *   - 'fresh_tail_requires_session_id' — `freshTailCount > 0` AND no
+ *     `freshTailSessionId` AND `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1`.
+ *     Default behaviour (env unset) returns tenant-wide rows; the env gate
+ *     is opt-in so multi-session tenants can fail loud instead of silently
+ *     surfacing cross-session rows tagged `isFreshTail=true`.
+ *   - 'invalid_scorer_window' — `opts.scorerWindow` is set to a non-positive,
+ *     non-integer, or non-finite value. Pre-v1.7.0 the value 0 routed
+ *     through FTS/LIKE `LIMIT 0` and then fell through to an uncapped
+ *     full-store fallback (codex v1.7.0 diff-pass P1). Validated upfront
+ *     so the contract holds.
+ */
+export class RecallContractError extends BadRequestError {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'RecallContractError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=types.js.map