hippo-memory 1.60.0 → 1.62.0

package/dist/ambient-store.js

@@ -0,0 +1,90 @@
+import { closeHippoDb } from './db.js';
+import { strengthSql } from './memory.js';
+import { RECALL_DEFAULT_DENY_SCOPES } from './recall-scope.js';
+import { SECRET_TAGS } from './secret-detect.js';
+import { openStore } from './store/open.js';
+import { isErrorTagged } from './ambient.js';
+// A malformed or non-array JSON list reads as empty, as parseJsonArray does, instead of failing json_each.
+const jsonList = (column) => `(CASE WHEN json_valid(${column}) AND json_type(${column}) = 'array' THEN ${column} ELSE '[]' END)`;
+// SHORTCUT: mirrors loadContextCandidates' WHERE (request-path snapshots pin the match); share it once store.ts is split.
+function contextRowsWhere(tenantId, filter) {
+    const where = ['tenant_id = ?', `COALESCE(superseded_by, '') = ''`, `COALESCE(kind, '') != 'archived'`];
+    const params = [tenantId];
+    if (filter.exactScope) {
+        where.push('scope = ?');
+        params.push(filter.exactScope);
+    }
+    else {
+        where.push(`(scope IS NULL OR (scope NOT IN (${RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ')}) AND scope NOT LIKE '%:private:%'))`);
+        params.push(...RECALL_DEFAULT_DENY_SCOPES);
+    }
+    if (filter.project !== undefined) {
+        where.push(`(origin_project = '' OR origin_project = ?)`);
+        params.push(filter.project);
+    }
+    return { where, params };
+}
+/** A secret tag's row, the half of detectSecret SQL can check; the LIKEs only skip json_each on rows that cannot match. */
+function secretTaggedSql() {
+    const tags = [...SECRET_TAGS];
+    return {
+        sql: `((${tags.map(() => 'tags_json LIKE ?').join(' OR ')})
+      AND EXISTS (SELECT 1 FROM json_each(${jsonList('tags_json')}) WHERE lower(value) IN (${tags.map(() => '?').join(', ')})))`,
+        params: [...tags.map((t) => `%"${t}"%`), ...tags],
+    };
+}
+/** Whole-store ambient tallies in one aggregate pass, no row loaded. Content-pattern secrets and session-local
+ *  rows (own compaction items, a printed handoff's digest) still count: only injection drops them. */
+export function loadAmbientTallies(hippoRoot, tenantId, filter) {
+    const { where, params } = contextRowsWhere(tenantId, filter);
+    const secret = secretTaggedSql();
+    const sevenDaysAgo = new Date(filter.now.getTime() - 7 * 86400000).toISOString();
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: one aggregate row whose columns are the aliases named below. Tag lists come back as one JSON array of
+        // arrays and are counted in JS, which maps items through String() as parseJsonArray does.
+        const row = db.prepare(`SELECT
+      COUNT(*) AS total,
+      COALESCE(SUM(${strengthSql(filter.now)}), 0) AS strengthSum,
+      COALESCE(SUM(julianday(created) > julianday(?)), 0) AS fresh,
+      COALESCE(SUM(emotional_valence IN ('negative', 'critical')), 0) AS negative,
+      COALESCE(SUM(COALESCE(schema_fit, 0.5) > 0.7), 0) AS highSchemaFit,
+      COALESCE(SUM(layer = 'semantic'), 0) AS semantic,
+      COALESCE(SUM(layer = 'episodic'), 0) AS episodic,
+      COALESCE(SUM(json_array_length(${jsonList('conflicts_with_json')})), 0) AS conflicts,
+      COALESCE(SUM(COALESCE(extracted_from, '') != ''), 0) AS extracted,
+      MAX(0, COALESCE(MAX(COALESCE(dag_level, 0)), 0)) AS maxDagLevel,
+      '[' || COALESCE(group_concat(${jsonList('tags_json')}, ','), '') || ']' AS tagLists
+      FROM memories
+      WHERE ${where.join(' AND ')}
+        AND ((origin_project = ? AND origin_project != '') OR NOT ${secret.sql})`).get(sevenDaysAgo, ...params, filter.currentProject, ...secret.params);
+        const tagCounts = new Map();
+        let errors = 0;
+        const lists = /* SAFETY: jsonList yields an array per row, joined into one array */ JSON.parse(row.tagLists);
+        for (const raw of lists) {
+            const tags = raw.map((item) => String(item));
+            for (const tag of tags)
+                tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+            if (isErrorTagged(tags))
+                errors++;
+        }
+        return {
+            total: Number(row.total),
+            strengthSum: Number(row.strengthSum),
+            fresh: Number(row.fresh),
+            negative: Number(row.negative),
+            highSchemaFit: Number(row.highSchemaFit),
+            errors,
+            semantic: Number(row.semantic),
+            episodic: Number(row.episodic),
+            conflicts: Number(row.conflicts),
+            extracted: Number(row.extracted),
+            maxDagLevel: Number(row.maxDagLevel),
+            tagCounts,
+        };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=ambient-store.js.map

package/dist/ambient.d.ts

@@ -20,7 +20,30 @@ export interface AmbientState {
     dagDepth: number;
     totalMemories: number;
 }
+/** Row counts and sums an AmbientState is derived from; two stores' tallies add with addAmbientTallies. */
+export interface AmbientTallies {
+    total: number;
+    strengthSum: number;
+    fresh: number;
+    negative: number;
+    highSchemaFit: number;
+    errors: number;
+    semantic: number;
+    episodic: number;
+    conflicts: number;
+    extracted: number;
+    maxDagLevel: number;
+    tagCounts: Map<string, number>;
+}
+/** The tallies of two disjoint row sets taken together. */
+export declare function addAmbientTallies(a: AmbientTallies, b: AmbientTallies): AmbientTallies;
+/** Whether a tag list marks its memory as an error for errorDensity. */
+export declare function isErrorTagged(tags: readonly string[]): boolean;
+/** Tallies over loaded entries; superseded rows count toward the total only, as they always have here. */
+export declare function tallyAmbientEntries(entries: readonly MemoryEntry[], now?: Date): AmbientTallies;
 export declare function computeAmbientState(entries: MemoryEntry[], now?: Date): AmbientState;
+/** The ambient state of a row set from its tallies, however they were counted. */
+export declare function ambientStateFromTallies(t: AmbientTallies): AmbientState;
 export declare function renderAmbientSummary(state: AmbientState): string;
 export declare function formatAmbientVector(state: AmbientState): string;
 //# sourceMappingURL=ambient.d.ts.map

package/dist/ambient.js

@@ -9,67 +9,89 @@
 import { evalNow } from './ablation.js';
 import { Layer } from './memory.js';
 import { calculateStrength } from './memory.js';
-export function computeAmbientState(entries, now) {
-    const n = entries.length;
-    if (n === 0) {
-        return {
-            tagEntropy: 0, avgStrength: 0, recencyFreshness: 0,
-            emotionalSkew: 0, schemaFitRatio: 0, errorDensity: 0,
-            consolidationRatio: 0, conflictIntensity: 0,
-            extractionCoverage: 0, dagDepth: 0, totalMemories: 0,
-        };
-    }
+/** The tallies of two disjoint row sets taken together. */
+export function addAmbientTallies(a, b) {
+    const tagCounts = new Map(a.tagCounts);
+    for (const [tag, count] of b.tagCounts)
+        tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + count);
+    return {
+        total: a.total + b.total,
+        strengthSum: a.strengthSum + b.strengthSum,
+        fresh: a.fresh + b.fresh,
+        negative: a.negative + b.negative,
+        highSchemaFit: a.highSchemaFit + b.highSchemaFit,
+        errors: a.errors + b.errors,
+        semantic: a.semantic + b.semantic,
+        episodic: a.episodic + b.episodic,
+        conflicts: a.conflicts + b.conflicts,
+        extracted: a.extracted + b.extracted,
+        maxDagLevel: Math.max(a.maxDagLevel, b.maxDagLevel),
+        tagCounts,
+    };
+}
+/** Whether a tag list marks its memory as an error for errorDensity. */
+export function isErrorTagged(tags) {
+    return tags.some(tag => tag === 'error' || tag === 'critical' || tag.startsWith('error:'));
+}
+/** Tallies over loaded entries; superseded rows count toward the total only, as they always have here. */
+export function tallyAmbientEntries(entries, now) {
     const currentTime = now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only)
-    const tagCounts = new Map();
-    let strengthSum = 0;
-    let freshCount = 0;
-    let negativeCount = 0;
-    let highSchemaCount = 0;
-    let errorCount = 0;
-    let semanticCount = 0;
-    let episodicCount = 0;
-    let conflictSum = 0;
-    let extractedCount = 0;
-    let maxDagLevel = 0;
     const sevenDaysAgo = currentTime.getTime() - 7 * 86400000;
+    const t = {
+        total: entries.length, strengthSum: 0, fresh: 0, negative: 0, highSchemaFit: 0, errors: 0,
+        semantic: 0, episodic: 0, conflicts: 0, extracted: 0, maxDagLevel: 0, tagCounts: new Map(),
+    };
     for (const entry of entries) {
         if (entry.superseded_by)
             continue;
-        for (const tag of entry.tags) {
-            tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
-        }
-        const strength = calculateStrength(entry, currentTime);
-        strengthSum += strength;
+        for (const tag of entry.tags)
+            t.tagCounts.set(tag, (t.tagCounts.get(tag) ?? 0) + 1);
+        t.strengthSum += calculateStrength(entry, currentTime);
         if (new Date(entry.created).getTime() > sevenDaysAgo)
-            freshCount++;
-        if (entry.emotional_valence === 'negative' || entry.emotional_valence === 'critical') {
-            negativeCount++;
-        }
-        if (entry.tags.some(t => t === 'error' || t === 'critical' || t.startsWith('error:'))) {
-            errorCount++;
-        }
+            t.fresh++;
+        if (entry.emotional_valence === 'negative' || entry.emotional_valence === 'critical')
+            t.negative++;
+        if (isErrorTagged(entry.tags))
+            t.errors++;
         if (entry.schema_fit > 0.7)
-            highSchemaCount++;
+            t.highSchemaFit++;
         if (entry.layer === Layer.Semantic)
-            semanticCount++;
+            t.semantic++;
         if (entry.layer === Layer.Episodic)
-            episodicCount++;
-        conflictSum += entry.conflicts_with.length;
+            t.episodic++;
+        t.conflicts += entry.conflicts_with.length;
         if (entry.extracted_from)
-            extractedCount++;
-        if (entry.dag_level > maxDagLevel)
-            maxDagLevel = entry.dag_level;
+            t.extracted++;
+        if (entry.dag_level > t.maxDagLevel)
+            t.maxDagLevel = entry.dag_level;
+    }
+    return t;
+}
+export function computeAmbientState(entries, now) {
+    return ambientStateFromTallies(tallyAmbientEntries(entries, now));
+}
+/** The ambient state of a row set from its tallies, however they were counted. */
+export function ambientStateFromTallies(t) {
+    const n = t.total;
+    if (n === 0) {
+        return {
+            tagEntropy: 0, avgStrength: 0, recencyFreshness: 0,
+            emotionalSkew: 0, schemaFitRatio: 0, errorDensity: 0,
+            consolidationRatio: 0, conflictIntensity: 0,
+            extractionCoverage: 0, dagDepth: 0, totalMemories: 0,
+        };
     }
-    const tagEntropy = shannonEntropy(tagCounts, n);
-    const avgStrength = strengthSum / n;
-    const recencyFreshness = freshCount / n;
-    const emotionalSkew = (negativeCount / n) * 2 - 0.5;
-    const schemaFitRatio = highSchemaCount / n;
-    const errorDensity = errorCount / n;
-    const totalLayered = semanticCount + episodicCount;
-    const consolidationRatio = totalLayered > 0 ? semanticCount / totalLayered : 0;
-    const conflictIntensity = conflictSum / (n * 2);
-    const extractionCoverage = episodicCount > 0 ? extractedCount / episodicCount : 0;
+    const tagEntropy = shannonEntropy(t.tagCounts, n);
+    const avgStrength = t.strengthSum / n;
+    const recencyFreshness = t.fresh / n;
+    const emotionalSkew = (t.negative / n) * 2 - 0.5;
+    const schemaFitRatio = t.highSchemaFit / n;
+    const errorDensity = t.errors / n;
+    const totalLayered = t.semantic + t.episodic;
+    const consolidationRatio = totalLayered > 0 ? t.semantic / totalLayered : 0;
+    const conflictIntensity = t.conflicts / (n * 2);
+    const extractionCoverage = t.episodic > 0 ? t.extracted / t.episodic : 0;
+    const maxDagLevel = t.maxDagLevel;
     return {
         tagEntropy,
         avgStrength,

package/dist/api/assemble.d.ts

@@ -0,0 +1,93 @@
+import type { Context } from './types.js';
+export interface AssembleOpts {
+    /** Token budget. Default 4000. */
+    budget?: number;
+    /** Recent raw rows always kept verbatim. Default 10. */
+    freshTailCount?: number;
+    /** Substitute parent summaries for older raws when ≥2 share a level-2
+     *  ancestor. Default true. */
+    summarizeOlder?: boolean;
+    /**
+     * Restrict to a specific scope. v1.6.1 senior-review P1 #3 parity with
+     * `recall`: when set, exact match required (so an authorised caller can
+     * assemble a `slack:private:CSEC` session by passing scope explicitly).
+     * When undefined, default-deny applies to ANY `<source>:private:*` and
+     * `unknown:legacy` rows.
+     */
+    scope?: string;
+    /**
+     * Hard row cap on the SELECT that loads session raws. Default 5000 to
+     * protect against degenerate sessions. When the cap is hit, `truncated`
+     * is set on the result so the caller knows to widen.
+     */
+    rowCap?: number;
+    cost?: AssembleCost;
+}
+export interface AssembleCost {
+    item: (it: AssembledContextItem) => number;
+    fixed: (widest: number) => number;
+}
+export interface AssembledContextItem {
+    id: string;
+    content: string;
+    /** ISO timestamp of the source row's `created` field (or `earliest_at`
+     *  for substituted summaries). */
+    createdAt: string;
+    /** Fresh-tail protected window (last freshTailCount raws). */
+    isFreshTail?: boolean;
+    /** Level-2 summary substituted for older raw rows that share a parent. */
+    isSummary?: boolean;
+    /** When isSummary, the raw ids this summary covers. drillDown
+     *  recovers the originals. */
+    substitutedFor?: string[];
+    /** Decay × retrieval × emotional. Lets callers render a confidence
+     *  hint without re-deriving from MemoryEntry. */
+    strength: number;
+}
+export interface AssembleResult {
+    sessionId: string;
+    items: AssembledContextItem[];
+    tokens: number;
+    /**
+     * Tenant + scope-filtered raw row count for the session — what the caller
+     * could have seen given their grant. Pre-v1.6.1 was pre-filter (confusing
+     * for all-private sessions); pre-v1.6.3 was capped (under-reported on
+     * sessions > rowCap). v1.6.3 reports the FULL post-filter count via a
+     * separate COUNT(*) query so consumers can render "session has N msgs"
+     * accurately even when items[] is the windowed view.
+     */
+    totalRaw: number;
+    summarized: number;
+    evicted: number;
+    /**
+     * True when `rowCap` truncated the loaded window. With v1.6.2's NEWEST-cap
+     * semantics, the items[] array represents the freshest tail of the session;
+     * older rows beyond the cap are silently absent. Use `totalRaw - items.length
+     * - summarized + ...` to estimate how much you didn't see, or widen `rowCap`.
+     */
+    truncated: boolean;
+}
+/**
+ * Build a chronologically-ordered context window for a session. Adapts the
+ * lossless-claw context-engine pattern to Hippo's score-ranked memory store.
+ *
+ * Algorithm:
+ *   1. Load all kind='raw' rows for the session, tenant + scope filtered.
+ *   2. Split: newest `freshTailCount` are protected (fresh tail).
+ *   3. For older rows, when ≥2 share a level-2 parent, substitute the
+ *      summary; everything else passes through as raw.
+ *   4. Hippo-additive eviction: when over-budget, drop the lowest-strength
+ *      non-fresh-tail item first. Fresh-tail rows are never evicted.
+ *
+ * Strength-weighted eviction is the differentiator from lossless-claw,
+ * which evicts oldest-first. A high-strength older row (high retrieval
+ * count, slow decay) survives; a low-strength recent row (newer but
+ * unimportant) goes first.
+ *
+ * Returns `items: []` cleanly when:
+ *   - sessionId is empty
+ *   - no raws exist for the session
+ *   - all rows fail the scope/tenant filter
+ */
+export declare function assemble(ctx: Context, sessionId: string, opts?: AssembleOpts): AssembleResult;
+//# sourceMappingURL=assemble.d.ts.map

package/dist/api/assemble.js

@@ -0,0 +1,153 @@
+// Session context assembly under a token budget.
+import { loadEntriesByIds, loadSessionRawMemories, countSessionRawMemories } from '../store/entry-reads.js';
+import { estimateTokens } from '../token-ledger.js';
+import { passesScopeFilterForRecall, assertScopeRequestAllowed } from '../recall-scope.js';
+/**
+ * Build a chronologically-ordered context window for a session. Adapts the
+ * lossless-claw context-engine pattern to Hippo's score-ranked memory store.
+ *
+ * Algorithm:
+ *   1. Load all kind='raw' rows for the session, tenant + scope filtered.
+ *   2. Split: newest `freshTailCount` are protected (fresh tail).
+ *   3. For older rows, when ≥2 share a level-2 parent, substitute the
+ *      summary; everything else passes through as raw.
+ *   4. Hippo-additive eviction: when over-budget, drop the lowest-strength
+ *      non-fresh-tail item first. Fresh-tail rows are never evicted.
+ *
+ * Strength-weighted eviction is the differentiator from lossless-claw,
+ * which evicts oldest-first. A high-strength older row (high retrieval
+ * count, slow decay) survives; a low-strength recent row (newer but
+ * unimportant) goes first.
+ *
+ * Returns `items: []` cleanly when:
+ *   - sessionId is empty
+ *   - no raws exist for the session
+ *   - all rows fail the scope/tenant filter
+ */
+export function assemble(ctx, sessionId, opts = {}) {
+    assertScopeRequestAllowed(ctx.actor, opts.scope);
+    const budget = opts.budget ?? 4000;
+    const freshTailCount = opts.freshTailCount ?? 10;
+    const summarizeOlder = opts.summarizeOlder ?? true;
+    const rowCap = opts.rowCap ?? 5000;
+    if (!sessionId) {
+        return { sessionId, items: [], tokens: 0, totalRaw: 0, summarized: 0, evicted: 0, truncated: false };
+    }
+    const rows = loadSessionRawMemories(ctx.hippoRoot, sessionId, ctx.tenantId, rowCap);
+    const truncated = rows.length === rowCap;
+    // v1.6.3 senior-review P0-1: report the FULL post-filter row count even
+    // when the cap windows the loaded set. Pre-v1.6.3 used `scoped.length`
+    // which under-reported on long sessions and made consumers render
+    // wrong "session has N msgs" UX.
+    const scoped = rows.filter((r) => passesScopeFilterForRecall(r.scope ?? null, opts.scope));
+    let totalRaw;
+    if (truncated) {
+        // v1.6.3 codex P1 / senior P0: scope-aware unbounded COUNT. The helper
+        // SQL-encodes the same default-deny rule passesScopeFilterForRecall
+        // applies in TS, so a no-scope caller cannot infer private rows by
+        // comparing totalRaw to items.length on a truncated session.
+        totalRaw = countSessionRawMemories(ctx.hippoRoot, sessionId, ctx.tenantId, opts.scope);
+    }
+    else {
+        totalRaw = scoped.length;
+    }
+    if (scoped.length === 0) {
+        return { sessionId, items: [], tokens: 0, totalRaw, summarized: 0, evicted: 0, truncated };
+    }
+    // Split newest N into fresh tail; rest is older.
+    const tailStartIdx = Math.max(0, scoped.length - freshTailCount);
+    const olderRows = scoped.slice(0, tailStartIdx);
+    const tailRows = scoped.slice(tailStartIdx);
+    // Substitute parent summaries for older rows that share one.
+    const { olderItems, summarized } = summarizeOlder && olderRows.length > 0
+        ? substituteSummaries(ctx, olderRows, opts.scope)
+        : { olderItems: olderRows.map(rawItem), summarized: 0 };
+    const tailItems = tailRows.map((r) => ({
+        id: r.id,
+        content: r.content,
+        createdAt: r.created,
+        isFreshTail: true,
+        strength: r.strength,
+    }));
+    // F4 (v1.6.5): byte compare canonical UTC ISO timestamps. ~50× faster than
+    // localeCompare and chronological by virtue of the timestamp invariant
+    // documented in src/memory.ts above MemoryEntry.
+    const cmpIso = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    olderItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
+    tailItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
+    const itemCost = opts.cost?.item ?? ((it) => estimateTokens(it.content));
+    const room = budget - (opts.cost?.fixed(Math.max(budget, totalRaw)) ?? 0);
+    const { items, tokens, evicted } = evictToBudget([...olderItems, ...tailItems], itemCost, room);
+    return { sessionId, items, tokens, totalRaw, summarized, evicted, truncated };
+}
+function rawItem(r) {
+    return {
+        id: r.id,
+        content: r.content,
+        createdAt: r.created,
+        strength: r.strength,
+    };
+}
+function substituteSummaries(ctx, olderRows, scope) {
+    const olderItems = [];
+    let summarized = 0;
+    const olderByParent = new Map();
+    for (const r of olderRows) {
+        if (!r.dag_parent_id)
+            continue;
+        const list = olderByParent.get(r.dag_parent_id) ?? [];
+        list.push(r);
+        olderByParent.set(r.dag_parent_id, list);
+    }
+    const eligibleParentIds = Array.from(olderByParent.keys()).filter((pid) => (olderByParent.get(pid)?.length ?? 0) >= 2);
+    const parents = eligibleParentIds.length > 0
+        ? loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId)
+            .filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by)
+            .filter((p) => passesScopeFilterForRecall(p.scope ?? null, scope))
+        : [];
+    const claimedRawIds = new Set();
+    for (const parent of parents) {
+        const claimed = (olderByParent.get(parent.id) ?? []).map((r) => r.id);
+        claimed.forEach((id) => claimedRawIds.add(id));
+        olderItems.push({
+            id: parent.id,
+            content: parent.content,
+            createdAt: parent.earliest_at ?? parent.created,
+            isSummary: true,
+            substitutedFor: claimed,
+            strength: parent.strength,
+        });
+        summarized += claimed.length;
+    }
+    for (const r of olderRows) {
+        if (claimedRawIds.has(r.id))
+            continue;
+        olderItems.push(rawItem(r));
+    }
+    return { olderItems, summarized };
+}
+function evictToBudget(start, itemCost, room) {
+    let items = start;
+    let tokens = items.reduce((acc, it) => acc + itemCost(it), 0);
+    let evicted = 0;
+    while (tokens > room && items.length > 0) {
+        let worstIdx = -1;
+        let worstStrength = Infinity;
+        for (let i = 0; i < items.length; i++) {
+            if (items[i].isFreshTail)
+                continue;
+            if (items[i].strength < worstStrength) {
+                worstStrength = items[i].strength;
+                worstIdx = i;
+            }
+        }
+        if (worstIdx === -1)
+            break;
+        const cost = itemCost(items[worstIdx]);
+        items = items.filter((_, i) => i !== worstIdx);
+        tokens -= cost;
+        evicted++;
+    }
+    return { items, tokens, evicted };
+}
+//# sourceMappingURL=assemble.js.map

package/dist/api/audit.d.ts

@@ -0,0 +1,17 @@
+import { type AuditEvent, type AuditOp } from '../audit.js';
+import type { KeysetPosition } from '../keyset.js';
+import type { Context } from './types.js';
+export interface AuditListOpts {
+    op?: AuditOp;
+    /** ISO timestamp lower bound. */
+    since?: string;
+    limit?: number;
+    /** Resume after this row: the (ts, id) position the previous page ended on. */
+    after?: KeysetPosition;
+}
+/**
+ * Read audit events scoped to `ctx.tenantId`. Read-only — no audit emit (matches
+ * A5: cmdAuditList does not record a 'recall'-style read event).
+ */
+export declare function auditList(ctx: Context, opts: AuditListOpts): AuditEvent[];
+//# sourceMappingURL=audit.d.ts.map

package/dist/api/audit.js

@@ -0,0 +1,23 @@
+// Audit log queries.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { queryAuditEvents } from '../audit.js';
+/**
+ * Read audit events scoped to `ctx.tenantId`. Read-only — no audit emit (matches
+ * A5: cmdAuditList does not record a 'recall'-style read event).
+ */
+export function auditList(ctx, opts) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return queryAuditEvents(db, {
+            tenantId: ctx.tenantId,
+            op: opts.op,
+            since: opts.since,
+            limit: opts.limit,
+            after: opts.after,
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/api/auth.d.ts

@@ -0,0 +1,79 @@
+import { type ApiKeyListItem, type ApiKeyListRow } from '../auth.js';
+import type { KeysetPosition } from '../keyset.js';
+import type { Context } from './types.js';
+export interface AuthCreateOpts {
+    label?: string;
+    /**
+     * v1.12.3: authorization role for the new key. Defaults to `'admin'` for
+     * back-compat with v1.12.0-v1.12.2 (the api_keys.role column DEFAULT also
+     * resolves to 'admin' if omitted from the INSERT). Member keys are
+     * 403-blocked from admin-gated routes (e.g. `POST /v1/sleep`).
+     */
+    role?: 'admin' | 'member';
+}
+export interface AuthCreateResult {
+    keyId: string;
+    plaintext: string;
+    tenantId: string;
+    /** v1.12.3: the role bound to the new key (admin | member). */
+    role: 'admin' | 'member';
+}
+/**
+ * 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.
+ */
+export declare function authCreate(ctx: Context, opts: AuthCreateOpts): AuthCreateResult;
+/**
+ * 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 — no audit emit (matches A5).
+ */
+export declare function authList(ctx: Context, opts: {
+    active: boolean;
+}): ApiKeyListItem[];
+/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from. */
+export declare function authListRows(ctx: Context, opts: {
+    active: boolean;
+    limit?: number;
+    after?: KeysetPosition;
+}): ApiKeyListRow[];
+/**
+ * Revoke an API key.
+ *
+ * Security: the key must belong to `ctx.tenantId`. Cross-tenant revoke is
+ * rejected with the "not found" message used for missing keys, and a member may
+ * revoke only its own key (checked first), so no caller can probe other key_ids.
+ *
+ * Audit: emits 'auth_revoke' with `tenantId` set to the KEY ROW's tenant_id
+ * (M1 fix from A5 review, mirrors src/cli.ts:cmdAuthRevoke). Skipped on no-op
+ * revoke (already revoked) so re-running doesn't pad the audit log.
+ */
+export interface AuthRevokeResult {
+    ok: true;
+    revokedAt: string;
+}
+export declare function authRevoke(ctx: Context, keyId: string): AuthRevokeResult;
+/**
+ * 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 declare function authKeyTenant(ctx: Context, keyId: string): string | undefined;
+/** Shared result shape for authGrant/authUngrant, named per the file's oxlint anti-slop rule. */
+export interface AuthGrantResult {
+    ok: true;
+}
+/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
+export declare function authGrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
+/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
+export declare function authUngrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
+//# sourceMappingURL=auth.d.ts.map