hippo-memory 0.35.0 → 0.37.0

package/README.md

@@ -60,6 +60,23 @@ hippo recall "data pipeline issues" --budget 2000
 
 ---
 
+### What's new in v0.37.0
+
+- **Slack ingestion (E1.3).** First end-to-end ingestion connector. `POST /v1/connectors/slack/events` accepts HMAC-signed Events API webhooks; messages land as `kind='raw'` memories with `slack://team/channel/ts` provenance and a `slack:public:*` or `slack:private:*` scope. Source deletions route through `archiveRawMemory` (GDPR). Backfill via `hippo slack backfill --channel <id>`; malformed events to `hippo slack dlq list`.
+- **Schema v17.** New tables: `slack_event_log` (idempotency), `slack_cursors` (backfill resume), `slack_dlq` (parse failures), `slack_workspaces` (team_id to tenant_id routing).
+- **PUBLIC_ROUTES allow-list + HIPPO_REQUIRE_AUTH knob.** Slack webhook is the first explicit public `/v1/*` route (HMAC-signed, no Bearer). Every other `/v1/*` route returns 401 without auth when `HIPPO_REQUIRE_AUTH=1`.
+- **Recall default-deny on private scopes.** No-scope queries cannot see `slack:private:*` memories. Frontend callers passing undefined scope no longer leak private content.
+- **api.remember afterWrite hook.** Connectors stamp idempotency rows atomically with the memory row via a SAVEPOINT-scoped callback.
+
+### What's new in v0.36.0
+
+- **`hippo serve` daemon.** Persistent HTTP server on 127.0.0.1:6789. CLI auto-detects and becomes a thin client; one process owns the SQLite DB.
+- **MCP-over-HTTP.** MCP clients can now connect over HTTP/SSE in addition to stdio. Same tool surface.
+- **Bearer-token auth + loopback trust.** Set HIPPO_API_KEY for remote calls; loopback connections work without a key. Server refuses to bind to non-loopback host without auth.
+- **Audit log fix.** Mutations on non-default tenants are now correctly attributed in the audit log (was using HIPPO_TENANT env, now uses the row's tenant_id).
+- **Tenant deny on archive/forget.** A valid Bearer for tenant A can no longer affect tenant B's memories, cross-tenant requests return "memory not found".
+- **Known issue:** p99 recall latency is 58.4ms on a 10k store, target is 50ms. Architecture ships; latency hardening in v0.37.0.
+
 ### What's new in v0.35.0
 
 - **Stub auth landed.** API keys + audit log + per-tenant data isolation. `hippo auth create` mints a scrypt-hashed key shown plaintext exactly once. `hippo audit list` exposes the mutation trail.
@@ -353,6 +370,14 @@ hippo capture --file conversation.md
 hippo capture --file conversation.md --dry-run
 ```
 
+### Slack ingestion (E1.3)
+
+Hippo accepts Slack Events API webhooks at `POST /v1/connectors/slack/events`. Configure `SLACK_SIGNING_SECRET` (validated on every request) and point Slack at `https://<your-host>/v1/connectors/slack/events`. Messages land as `kind='raw'` memories with `slack://team/channel/ts` provenance and a `slack:public:Cxxx` or `slack:private:Cxxx` scope. Source deletions are honored (GDPR).
+
+Backfill an existing channel: `SLACK_BOT_TOKEN=xoxb-... hippo slack backfill --channel C0000`. Inspect malformed events: `hippo slack dlq list`.
+
+Multi-workspace deployments populate `slack_workspaces (team_id, tenant_id)` to route events per tenant; single-workspace falls back to `HIPPO_TENANT`.
+
 ### Active task snapshots
 
 Long-running work needs short-term continuity, not just long-term memory. Hippo can persist the current in-flight task so a later `continue` has something concrete to recover.

package/dist/api.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Domain API layer for Hippo.
+ *
+ * Pure functions taking a Context (hippoRoot + tenantId + actor) plus
+ * operation options. Both the CLI (direct mode) and the HTTP server
+ * (`hippo serve`, A1) call into this module so the business logic lives
+ * in exactly one place.
+ */
+import { type DatabaseSyncLike } from './db.js';
+import { type MemoryKind } from './memory.js';
+import { type AuditEvent, type AuditOp } from './audit.js';
+import { type ApiKeyListItem } from './auth.js';
+export interface Context {
+    hippoRoot: string;
+    tenantId: string;
+    /** 'cli' | 'localhost:cli' | 'api_key:<key_id>' | 'mcp' */
+    actor: string;
+}
+export interface RememberOpts {
+    content: string;
+    kind?: MemoryKind;
+    scope?: string;
+    owner?: string;
+    artifactRef?: string;
+    tags?: string[];
+    /**
+     * Optional hook invoked inside the same transaction as the underlying
+     * memories INSERT. Used by ingestion connectors (E1.3+) to stamp
+     * idempotency / cursor rows atomically with the memory row, so a crash
+     * mid-write cannot produce a memory without its corresponding side-effect
+     * log row (or vice versa). If the callback throws, the INSERT is rolled
+     * back and the error is rethrown.
+     */
+    afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
+}
+export interface RememberResult {
+    id: string;
+    kind: MemoryKind;
+    tenantId: string;
+}
+export declare function remember(ctx: Context, opts: RememberOpts): RememberResult;
+export interface RecallOpts {
+    query: string;
+    limit?: number;
+    mode?: 'bm25' | 'hybrid' | 'physics';
+    /**
+     * Restrict results to memories whose `scope` equals this value exactly.
+     *
+     * When `scope` is undefined or empty, recall applies a DEFAULT-DENY rule:
+     * any memory whose scope starts with `'slack:private:'` is filtered out so
+     * a frontend caller passing `undefined` cannot accidentally surface
+     * private-channel content. Memories with scope=null (the common case for
+     * non-Slack content) are still returned.
+     */
+    scope?: string;
+}
+export interface RecallResultItem {
+    id: string;
+    content: string;
+    score: number;
+    layer: string;
+    strength: number;
+}
+export interface RecallResult {
+    results: RecallResultItem[];
+    total: number;
+    tokens: number;
+}
+/**
+ * Domain-level recall. Loads BM25-ranked candidates from SQLite scoped to
+ * `ctx.tenantId`. The `mode` flag is accepted for forward compatibility (the
+ * CLI exposes hybrid/physics paths) but Task 2 wires only the BM25 candidate
+ * loader; later tasks can extend this to call the physics/hybrid scorer.
+ */
+export declare function recall(ctx: Context, opts: RecallOpts): RecallResult;
+/**
+ * Delete a memory by id. `deleteEntry` threads ctx.actor into its internal
+ * audit hook, so exactly one 'forget' event lands with the supplied actor.
+ *
+ * Tenant scope: deleteEntry looks up the row by id alone, so without an
+ * explicit tenant guard a Bearer for tenant A could delete tenant B's row
+ * by guessing or leaking the id. Pre-check the row's tenant_id and deny
+ * cross-tenant access with a not-found error (no info leak about whether
+ * the id exists in another tenant).
+ */
+export declare function forget(ctx: Context, id: string): {
+    ok: true;
+    id: string;
+};
+/**
+ * Copy a local memory into the global store. Mirrors `cmdPromote` in cli.ts:
+ * the `writeEntry` inside `promoteToGlobal` emits a 'remember' on the global
+ * db; we add a 'promote' audit event on the global db so the user-facing
+ * intent stays distinct from the underlying upsert.
+ *
+ * Note: `promoteToGlobal` does not currently take a tenantId override — it
+ * reads the entry from the local root via `readEntry` (no tenant filter) and
+ * preserves the entry's existing tenantId on the global side. Task 4 may
+ * tighten this once writeEntry/readEntry thread tenant context.
+ */
+export declare function promote(ctx: Context, id: string): {
+    ok: true;
+    sourceId: string;
+    globalId: string;
+};
+/**
+ * Replace an old memory with new content, chaining old.superseded_by = new.id.
+ * Mirrors `cmdSupersede` in cli.ts (without flag-driven layer/tag/pin overrides
+ * — A1 keeps the API minimal; the CLI handler will continue to handle those
+ * flags and pass the resolved values once Task 4 lands).
+ */
+export declare function supersede(ctx: Context, oldId: string, newContent: string): {
+    ok: true;
+    oldId: string;
+    newId: string;
+};
+/**
+ * Archive a kind='raw' memory: snapshot into raw_archive, mark archived, delete.
+ *
+ * `archiveRawMemory` audits the operation internally (op='archive_raw') using the
+ * row's own tenant_id. We DO NOT emit a second audit event here to avoid double-
+ * emitting the archive_raw op (unlike Task 1 remember/forget where the underlying
+ * helpers hardcode actor='cli'). Instead we pass `ctx.actor` through as `who`,
+ * and raw-archive.ts uses that for the audit row.
+ */
+export declare function archiveRaw(ctx: Context, id: string, reason: string): {
+    ok: true;
+    archivedAt: string;
+};
+export interface AuthCreateOpts {
+    label?: string;
+    /** Override the calling tenant (e.g. admin minting a key for tenant B). */
+    tenantId?: string;
+}
+export interface AuthCreateResult {
+    keyId: string;
+    plaintext: string;
+    tenantId: string;
+}
+/**
+ * Mint a new API key. Per A5 v2 follow-ups (TODOS.md), `auth_create` is currently
+ * unaudited — we intentionally match that behavior here for consistency. When A5
+ * v2 lands and adds the audit op, this function should mirror the cli handler.
+ */
+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[];
+/**
+ * Revoke an API key.
+ *
+ * Security: the key must belong to `ctx.tenantId`. Cross-tenant revoke is
+ * rejected with the same "not found" message used for missing keys, so that a
+ * caller cannot probe which key_ids exist on other tenants.
+ *
+ * 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 declare function authRevoke(ctx: Context, keyId: string): {
+    ok: true;
+    revokedAt: string;
+};
+export interface AuditListOpts {
+    op?: AuditOp;
+    /** ISO timestamp lower bound. */
+    since?: string;
+    limit?: number;
+}
+/**
+ * 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=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -0,0 +1,343 @@
+/**
+ * Domain API layer for Hippo.
+ *
+ * Pure functions taking a Context (hippoRoot + tenantId + actor) plus
+ * operation options. Both the CLI (direct mode) and the HTTP server
+ * (`hippo serve`, A1) call into this module so the business logic lives
+ * in exactly one place.
+ */
+import { openHippoDb, closeHippoDb } from './db.js';
+import { writeEntry, readEntry, deleteEntry, loadSearchEntries, removeEntryMirrors, } from './store.js';
+import { createMemory, Layer, } from './memory.js';
+import { appendAuditEvent, queryAuditEvents, } from './audit.js';
+import { promoteToGlobal, getGlobalRoot } from './shared.js';
+import { archiveRawMemory } from './raw-archive.js';
+import { createApiKey, listApiKeys, revokeApiKey, } from './auth.js';
+export function remember(ctx, opts) {
+    const entry = createMemory(opts.content, {
+        kind: opts.kind ?? 'distilled',
+        scope: opts.scope ?? null,
+        owner: opts.owner ?? null,
+        artifact_ref: opts.artifactRef ?? null,
+        tags: opts.tags,
+        tenantId: ctx.tenantId,
+    });
+    // writeEntry threads ctx.actor into its internal audit hook, so exactly
+    // one 'remember' event lands in the log with the supplied actor.
+    writeEntry(ctx.hippoRoot, entry, { actor: ctx.actor, afterWrite: opts.afterWrite });
+    return { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
+}
+/**
+ * Domain-level recall. Loads BM25-ranked candidates from SQLite scoped to
+ * `ctx.tenantId`. The `mode` flag is accepted for forward compatibility (the
+ * CLI exposes hybrid/physics paths) but Task 2 wires only the BM25 candidate
+ * loader; later tasks can extend this to call the physics/hybrid scorer.
+ */
+export function recall(ctx, opts) {
+    const limit = opts.limit ?? 10;
+    const all = loadSearchEntries(ctx.hippoRoot, opts.query, undefined, ctx.tenantId);
+    // Scope filtering runs AFTER the tenant filter inside loadSearchEntries, so
+    // a tenant-mismatched scope cannot surface another tenant's row even when
+    // both share the same scope string (e.g. 'slack:private:CSHARED').
+    let entries;
+    if (opts.scope !== undefined && opts.scope !== '') {
+        entries = all.filter((e) => e.scope === opts.scope);
+    }
+    else {
+        // Default-deny: a no-scope caller cannot see private slack channels. This
+        // is load-bearing because frontend callers will pass `undefined` and must
+        // not see `slack:private:*` rows by default.
+        entries = all.filter((e) => !(e.scope ?? '').startsWith('slack:private:'));
+    }
+    // BM25 ordering already comes from loadSearchEntries; cap to `limit`.
+    // Score is a placeholder — the physics/hybrid scorers in src/search.ts
+    // produce richer breakdowns and will replace this when wired up.
+    const ranked = entries.slice(0, limit).map((entry, idx) => ({
+        id: entry.id,
+        content: entry.content,
+        score: Math.max(0, 1 - idx / Math.max(1, limit)),
+        layer: entry.layer,
+        strength: entry.strength,
+    }));
+    const tokens = ranked.reduce((acc, r) => acc + Math.ceil(r.content.length / 4), 0);
+    // TODO(a1-task-4): emit via the shared audit hook in store.ts so we don't
+    // double-emit. Recall does not currently write through writeEntry, so no
+    // duplicate exists today, but we keep the same shape for symmetry.
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        appendAuditEvent(db, {
+            tenantId: ctx.tenantId,
+            actor: ctx.actor,
+            op: 'recall',
+            metadata: { query: opts.query.slice(0, 200), results: ranked.length },
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return { results: ranked, total: entries.length, tokens };
+}
+// ---------------------------------------------------------------------------
+// forget
+// ---------------------------------------------------------------------------
+/**
+ * Delete a memory by id. `deleteEntry` threads ctx.actor into its internal
+ * audit hook, so exactly one 'forget' event lands with the supplied actor.
+ *
+ * Tenant scope: deleteEntry looks up the row by id alone, so without an
+ * explicit tenant guard a Bearer for tenant A could delete tenant B's row
+ * by guessing or leaking the id. Pre-check the row's tenant_id and deny
+ * cross-tenant access with a not-found error (no info leak about whether
+ * the id exists in another tenant).
+ */
+export function forget(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const row = db
+            .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
+            .get(id);
+        if (!row || row.tenant_id !== ctx.tenantId) {
+            throw new Error(`memory not found: ${id}`);
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    const removed = deleteEntry(ctx.hippoRoot, id, { actor: ctx.actor });
+    if (!removed) {
+        throw new Error(`memory not found: ${id}`);
+    }
+    return { ok: true, id };
+}
+// ---------------------------------------------------------------------------
+// promote
+// ---------------------------------------------------------------------------
+/**
+ * Copy a local memory into the global store. Mirrors `cmdPromote` in cli.ts:
+ * the `writeEntry` inside `promoteToGlobal` emits a 'remember' on the global
+ * db; we add a 'promote' audit event on the global db so the user-facing
+ * intent stays distinct from the underlying upsert.
+ *
+ * Note: `promoteToGlobal` does not currently take a tenantId override — it
+ * reads the entry from the local root via `readEntry` (no tenant filter) and
+ * preserves the entry's existing tenantId on the global side. Task 4 may
+ * tighten this once writeEntry/readEntry thread tenant context.
+ */
+export function promote(ctx, id) {
+    // promoteToGlobal threads ctx.actor into the writeEntry call on the global
+    // db, which emits a 'remember' audit row. We then add the user-facing
+    // 'promote' event on the global db so the audit trail keeps the intent
+    // distinct from the underlying upsert.
+    const globalEntry = promoteToGlobal(ctx.hippoRoot, id, { actor: ctx.actor });
+    const db = openHippoDb(getGlobalRoot());
+    try {
+        appendAuditEvent(db, {
+            tenantId: ctx.tenantId,
+            actor: ctx.actor,
+            op: 'promote',
+            targetId: globalEntry.id,
+            metadata: { sourceId: id },
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return { ok: true, sourceId: id, globalId: globalEntry.id };
+}
+// ---------------------------------------------------------------------------
+// supersede
+// ---------------------------------------------------------------------------
+/**
+ * Replace an old memory with new content, chaining old.superseded_by = new.id.
+ * Mirrors `cmdSupersede` in cli.ts (without flag-driven layer/tag/pin overrides
+ * — A1 keeps the API minimal; the CLI handler will continue to handle those
+ * flags and pass the resolved values once Task 4 lands).
+ */
+export function supersede(ctx, oldId, newContent) {
+    const old = readEntry(ctx.hippoRoot, oldId, ctx.tenantId);
+    if (!old) {
+        throw new Error(`Memory not found: ${oldId}`);
+    }
+    if (old.superseded_by) {
+        throw new Error(`Memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
+    }
+    const newEntry = createMemory(newContent, {
+        layer: old.layer ?? Layer.Episodic,
+        tags: [...old.tags],
+        pinned: old.pinned,
+        source: old.source,
+        confidence: 'verified',
+        tenantId: ctx.tenantId,
+    });
+    old.superseded_by = newEntry.id;
+    writeEntry(ctx.hippoRoot, old, { actor: ctx.actor });
+    writeEntry(ctx.hippoRoot, newEntry, { actor: ctx.actor });
+    // The two writeEntry calls above emit 'remember' audit rows; the 'supersede'
+    // event below carries the user-facing intent and the chained newId.
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        appendAuditEvent(db, {
+            tenantId: ctx.tenantId,
+            actor: ctx.actor,
+            op: 'supersede',
+            targetId: oldId,
+            metadata: { newId: newEntry.id },
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return { ok: true, oldId, newId: newEntry.id };
+}
+// ---------------------------------------------------------------------------
+// archive_raw
+// ---------------------------------------------------------------------------
+/**
+ * Archive a kind='raw' memory: snapshot into raw_archive, mark archived, delete.
+ *
+ * `archiveRawMemory` audits the operation internally (op='archive_raw') using the
+ * row's own tenant_id. We DO NOT emit a second audit event here to avoid double-
+ * emitting the archive_raw op (unlike Task 1 remember/forget where the underlying
+ * helpers hardcode actor='cli'). Instead we pass `ctx.actor` through as `who`,
+ * and raw-archive.ts uses that for the audit row.
+ */
+export function archiveRaw(ctx, id, reason) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        // Tenant scope: archiveRawMemory looks up the row by id alone, so a
+        // Bearer for tenant A could archive tenant B's raw row without this
+        // pre-check. Deny cross-tenant access with the same not-found message
+        // archiveRawMemory itself would throw on a missing row, so we don't
+        // leak whether the id exists in another tenant.
+        const row = db
+            .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
+            .get(id);
+        if (!row || row.tenant_id !== ctx.tenantId) {
+            throw new Error(`memory not found: ${id}`);
+        }
+        archiveRawMemory(db, id, { reason, who: ctx.actor });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    // archiveRawMemory deletes the memories row but leaves any legacy markdown
+    // mirror in <root>/{buffer,episodic,semantic}/<id>.md untouched. If we left
+    // the mirror in place, a subsequent initStore() on an empty memories table
+    // would silently re-import the row via bootstrapLegacyStore — defeating the
+    // archive (and the GDPR right-to-be-forgotten promise on raw rows). Mirror
+    // forget() at src/store.ts:1046, which uses the same removeEntryMirrors call.
+    removeEntryMirrors(ctx.hippoRoot, id);
+    // archiveRawMemory does not return the archive_at timestamp it wrote. We
+    // emit a fresh ISO timestamp here for the API response. Within a millisecond
+    // of the actual write, fine for a server response shape.
+    return { ok: true, archivedAt: new Date().toISOString() };
+}
+/**
+ * Mint a new API key. Per A5 v2 follow-ups (TODOS.md), `auth_create` is currently
+ * unaudited — we intentionally match that behavior here for consistency. When A5
+ * v2 lands and adds the audit op, this function should mirror the cli handler.
+ */
+export function authCreate(ctx, opts) {
+    const tenantId = opts.tenantId ?? ctx.tenantId;
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const result = createApiKey(db, { tenantId, label: opts.label });
+        return { keyId: result.keyId, plaintext: result.plaintext, tenantId };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * List API keys visible to the calling tenant.
+ *
+ * Divergence from `cmdAuthList` in src/cli.ts: the CLI today returns ALL keys
+ * regardless of tenant (single-tenant deployments). The API surface is tenant-
+ * scoped because future multi-tenant deployments will share a hippoRoot, and
+ * tenant A must not see tenant B's keys. Read-only — no audit emit (matches A5).
+ */
+export function authList(ctx, opts) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const all = listApiKeys(db, opts);
+        return all.filter((k) => k.tenantId === ctx.tenantId);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Revoke an API key.
+ *
+ * Security: the key must belong to `ctx.tenantId`. Cross-tenant revoke is
+ * rejected with the same "not found" message used for missing keys, so that a
+ * caller cannot probe which key_ids exist on other tenants.
+ *
+ * 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 function authRevoke(ctx, keyId) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const row = db
+            .prepare(`SELECT key_id, tenant_id, revoked_at FROM api_keys WHERE key_id = ?`)
+            .get(keyId);
+        if (!row) {
+            throw new Error(`Unknown key_id: ${keyId}`);
+        }
+        // Cross-tenant access denied: same message as missing key, no info leak.
+        if (row.tenant_id !== ctx.tenantId) {
+            throw new Error(`Unknown key_id: ${keyId}`);
+        }
+        let revokedAt;
+        let alreadyRevoked = false;
+        if (row.revoked_at) {
+            alreadyRevoked = true;
+            revokedAt = row.revoked_at;
+        }
+        else {
+            revokeApiKey(db, keyId);
+            const updated = db
+                .prepare(`SELECT revoked_at FROM api_keys WHERE key_id = ?`)
+                .get(keyId);
+            revokedAt = updated?.revoked_at ?? new Date().toISOString();
+        }
+        if (!alreadyRevoked) {
+            try {
+                appendAuditEvent(db, {
+                    tenantId: row.tenant_id, // M1: KEY's tenant, not ctx.tenantId.
+                    actor: ctx.actor,
+                    op: 'auth_revoke',
+                    targetId: keyId,
+                });
+            }
+            catch {
+                // Audit must not crash a successful revoke.
+            }
+        }
+        return { ok: true, revokedAt };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * 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,
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/benchmarks/e1.3/incident-recall-eval.js

@@ -0,0 +1,74 @@
+/**
+ * E1.3 incident-recall eval (Task 17).
+ *
+ * ROADMAP success criterion: recall surfaces incident context faster than
+ * transcript replay on at least 7 of 10 staged scenarios.
+ *
+ * Approach (review patch #8): stamp a per-message sentinel
+ * `[s:<scenario.id>:<m.ts>]` into the ingested text. Sentinels are unique
+ * across the corpus, so checking sentinel substring presence in
+ * `RecallResultItem.content` is a deterministic equality test — no false
+ * positives from ambient phrase repetition, no need to extend the recall
+ * response shape with artifact_ref.
+ *
+ * Baseline: take the last 10 messages of the raw transcript (the
+ * "transcript replay" a human would do by scrolling to the bottom). Answers
+ * are buried mid-transcript so the baseline misses them. Recall must beat
+ * that on >=7/10 scenarios.
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { ingestMessage } from '../../src/connectors/slack/ingest.js';
+import { recall } from '../../src/api.js';
+export async function runIncidentRecallEval(opts) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const scenarios = JSON.parse(readFileSync(join(here, 'scenarios.json'), 'utf-8'));
+    const ctx = {
+        hippoRoot: opts.hippoRoot,
+        tenantId: 'default',
+        actor: 'eval:slack',
+    };
+    const results = [];
+    for (const sc of scenarios) {
+        const sentinel = (m) => `[s:${sc.id}:${m.ts}]`;
+        for (const m of sc.transcript) {
+            ingestMessage(ctx, {
+                teamId: 'T1',
+                channel: { id: sc.channel, is_private: false },
+                message: {
+                    type: 'message',
+                    channel: sc.channel,
+                    user: m.user,
+                    text: `${m.text} ${sentinel(m)}`,
+                    ts: m.ts,
+                },
+                eventId: `${sc.id}:${m.ts}`,
+            });
+        }
+        const r = recall(ctx, {
+            query: sc.query,
+            limit: 10,
+            scope: `slack:public:${sc.channel}`,
+        });
+        const recallHit = sc.answer_ts.filter((ts) => r.results.some((res) => res.content.includes(sentinel({ ts })))).length;
+        const recallPrecision = recallHit / sc.answer_ts.length;
+        // Baseline: linear transcript scan returning the last 10 messages — what a
+        // human does when they scroll to the bottom of a Slack channel. Direct
+        // ts equality is enough; sentinels are not in the raw transcript.
+        const tail = sc.transcript.slice(-10);
+        const baselineHit = sc.answer_ts.filter((ts) => tail.some((m) => m.ts === ts)).length;
+        const baselinePrecision = baselineHit / sc.answer_ts.length;
+        results.push({
+            id: sc.id,
+            recallPrecision,
+            baselinePrecision,
+            beat: recallPrecision > baselinePrecision,
+        });
+    }
+    return {
+        scenarios: results,
+        scenariosBeaten: results.filter((r) => r.beat).length,
+    };
+}
+//# sourceMappingURL=incident-recall-eval.js.map

package/dist/benchmarks/e1.3/incident-recall-eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incident-recall-eval.js","sourceRoot":"","sources":["../../../benchmarks/e1.3/incident-recall-eval.ts"],"names":[],"mappings":"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"}