hippo-memory 1.60.0 → 1.62.0

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,256 @@
+// 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.
+    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.
+        phaseError = err;
+        throw err;
+    }
+    finally {
+        emitSleepAudit(ctx, opts, dryRun, counts, phaseError);
+    }
+}
+async function runSleepPhases(ctx, opts, phases, counts) {
+    const dryRun = Boolean(opts.dryRun);
+    const snapshot = snapshotDirtyTenants(ctx, phases, dryRun);
+    // Phase 1: Consolidation.
+    const consolidateResult = await phases.consolidate(ctx.hippoRoot, { dryRun });
+    counts.consolidation = consolidateResult.semanticCreated + consolidateResult.merged;
+    const result = sleepResultFrom(consolidateResult, dryRun);
+    // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
+    const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject });
+    counts.dedup = dedupResult.removed;
+    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);
+    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);
+    drainGraphQueue(ctx, phases, snapshot, result);
+    return result;
+}
+// Taken before any memory-deleting phase: queue rows cascade-delete with their mirror, so a later read would miss
+// tenants dedup touched. Fail-soft: a failed read skips the graph refresh this sleep and never aborts core sleep.
+function snapshotDirtyTenants(ctx, phases, dryRun) {
+    const snapshot = { dirtyTenants: [], error: null };
+    if (!dryRun) {
+        try {
+            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;
+        }
+    }
+    return snapshot;
+}
+function sleepResultFrom(consolidateResult, dryRun) {
+    const 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;
+    }
+    return result;
+}
+function dedupSummary(dedupResult) {
+    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;
+    return {
+        removed: dedupResult.removed,
+        semDups,
+        epiDups,
+        crossDups,
+    };
+}
+/** Returns how many audit errors were deleted, or would be under dryRun. */
+function runQualityAudit(ctx, phases, dryRun, consolidateResult, dedupResult, result) {
+    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;
+    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++;
+    }
+    if (removed > 0 || warnings.length > 0) {
+        result.audit = {
+            errorsRemoved: removed,
+            warningCount: warnings.length,
+        };
+    }
+    return removed;
+}
+function shareOnSleep(ctx, phases, result) {
+    const sleepConfig = phases.loadConfig(ctx.hippoRoot);
+    if (!sleepConfig.autoShareOnSleep)
+        return;
+    // Both skip counters are surfaced so the secret veto and the rejection tombstone are observable, not silent.
+    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;
+    }
+}
+/** Returns the ambient total the audit row reports: 0 when ambient is off or no current row is left. */
+function summarizeAmbient(ctx, phases, result) {
+    const postSleepConfig = phases.loadConfig(ctx.hippoRoot);
+    if (!postSleepConfig.ambient.enabled)
+        return 0;
+    const postSleepEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !e.superseded_by);
+    if (postSleepEntries.length === 0)
+        return 0;
+    result.ambient = phases.computeAmbientState(postSleepEntries);
+    return result.ambient.totalMemories;
+}
+// Phase 6: rebuild the graph of every tenant marked dirty since the last sleep, so graph recall runs on fresh data.
+// Fault-isolated: consolidation has already committed, so no failure here aborts sleep; a failed tenant stays pending.
+function drainGraphQueue(ctx, phases, snapshot, result) {
+    try {
+        if (snapshot.error) {
+            // Core sleep already succeeded; surface the skipped graph refresh as a detail.
+            result.details = [
+                ...(result.details ?? []),
+                `graph: dirty-tenant snapshot failed (skipped graph refresh): ${snapshot.error}`,
+            ];
+        }
+        let gTenants = 0;
+        let gEntities = 0;
+        let gRelations = 0;
+        // dirtyTenants was snapshotted before the memory-deleting phases above.
+        for (const { tenantId, maxPendingId } of snapshot.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: only items enqueued before this rebuild started are marked; later arrivals stay pending.
+                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}`,
+        ];
+    }
+}
+// One 'consolidate' row per sleep, emitted from finally so a partial failure still reports what got done.
+// 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;
+            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