hippo-memory 1.69.0 → 1.70.0

package/dist/skills.js

@@ -1,367 +0,0 @@
-/**
- * Skills as a first-class, versioned object.
- *
- * A `skill` is a reusable, agent-followable capability: an `instructions` body
- * plus an optional `trigger` ("when to apply"), evolving via the supersede delta
- * lifecycle. "Executable" is scoped to an agent-followable INSTRUCTION that, once
- * exported into the agent's in-force rules (AGENTS.md / CLAUDE.md) via
- * `exportSkills`, is executed by the agent reading it. Literal code/command
- * execution is deferred (security; a future sandbox). The distinguishing
- * capability is therefore the EXPORT renderer, not a runtime.
- *
- * Reuses the process/decision supersede machinery verbatim (superseded_by self-FK
- * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It DROPS process's `steps` (a skill's content is a single
- * `instructions` body) and ADDS `trigger` (stored in the `trigger_text` column -
- * `trigger` is a SQLite reserved keyword).
- *
- * The `skills` table is the source of truth (survives memory decay); the memory
- * mirror is for recall. memory_id is NULLABLE with ON DELETE SET NULL.
- *
- * Lifecycle: active -> superseded (a newer version replaces it) or active ->
- * closed (retired). Export renders ACTIVE skills only.
- */
-import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
-import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry } from './store/entry-writes.js';
-import { assertTenantId } from './tenant.js';
-import { createMemory, Layer } from './memory.js';
-import { appendAuditEvent } from './audit.js';
-import { objectHalfLifeDays } from './half-life-migration.js';
-import { keysetAfter } from './keyset.js';
-export const VALID_SKILL_STATES = new Set([
-    'active',
-    'superseded',
-    'closed',
-]);
-/** Field caps (untrusted at the HTTP/SDK boundary). instructions is a body, so a
- *  larger cap than the 4096 short-field convention. */
-export const MAX_SKILL_NAME_LEN = 256;
-export const MAX_SKILL_INSTRUCTIONS_LEN = 8192;
-export const MAX_SKILL_TRIGGER_LEN = 1024;
-/** Aggregate bound on a single export render so the export body is never unbounded.
- *  Realistic active-skill counts are tens; 1000 is a generous bound. */
-export const MAX_EXPORT_SKILLS = 1000;
-/**
- * Validate + normalise skill fields. skill_name is trimmed and MUST be a single
- * line (no newlines) so it cannot break the H2 header in the export render.
- * instructions are kept verbatim (operator content) but capped.
- * Returns the normalised name + trigger (null when absent/empty).
- */
-function validateSkillFields(skillName, instructions, trigger) {
-    const name = (skillName ?? '').trim();
-    if (name.length === 0)
-        throw new BadRequestError('saveSkill: skillName is required');
-    if (/[\r\n]/.test(name))
-        throw new BadRequestError('saveSkill: skillName must be a single line (no newlines)');
-    if (name.length > MAX_SKILL_NAME_LEN) {
-        throw new BadRequestError(`saveSkill: skillName exceeds the ${MAX_SKILL_NAME_LEN}-char cap`);
-    }
-    if (!instructions || instructions.trim().length === 0) {
-        throw new BadRequestError('saveSkill: instructions are required');
-    }
-    if (instructions.length > MAX_SKILL_INSTRUCTIONS_LEN) {
-        throw new BadRequestError(`saveSkill: instructions exceed the ${MAX_SKILL_INSTRUCTIONS_LEN}-char cap`);
-    }
-    let triggerVal = null;
-    if (trigger !== undefined && trigger !== null && trigger.trim().length > 0) {
-        if (trigger.length > MAX_SKILL_TRIGGER_LEN) {
-            throw new BadRequestError(`saveSkill: trigger exceeds the ${MAX_SKILL_TRIGGER_LEN}-char cap`);
-        }
-        // Single-line, like skill_name: a trigger is a short "when to apply" phrase,
-        // and a newline would let it forge a heading inside the export **When:** line.
-        // Reject rather than emit a multi-line trigger.
-        if (/[\r\n]/.test(trigger)) {
-            throw new BadRequestError('saveSkill: trigger must be a single line (no newlines)');
-        }
-        triggerVal = trigger;
-    }
-    return { name, trigger: triggerVal };
-}
-function rowToSkill(row) {
-    return {
-        id: row.id,
-        memoryId: row.memory_id,
-        tenantId: row.tenant_id,
-        skillName: row.skill_name,
-        instructions: row.instructions,
-        trigger: row.trigger_text,
-        version: row.version,
-        // SAFETY: status is DB-constrained to VALID_SKILL_STATES; this module
-        // is the only writer and always inserts one of those literal strings.
-        status: row.status,
-        supersededBy: row.superseded_by,
-        supersededAt: row.superseded_at,
-        changeSummary: row.change_summary,
-        closedAt: row.closed_at,
-        createdAt: row.created_at,
-    };
-}
-const SKILL_COLS = `
-  id, memory_id, tenant_id, skill_name, instructions, trigger_text, version, status,
-  superseded_by, superseded_at, change_summary, closed_at, created_at
-`;
-/** Recall-surface content for the memory mirror: name + optional trigger +
- *  instructions. Named (mirrors buildProcessContent) so the recall surface is
- *  deterministic + unit-testable. */
-function buildSkillContent(skillName, instructions, trigger) {
-    let content = skillName;
-    if (trigger)
-        content += `\n\nWhen: ${trigger}`;
-    content += `\n\n${instructions}`;
-    return content;
-}
-// Preflight the supersede target BEFORE inserting the new row (so the new
-// autoincrement id can never be its own supersede target); read the
-// predecessor version in the same SELECT for server-derived versioning.
-// Mirrors saveProcess / savePolicy.
-function preflightSkillSupersede(db, tenantId, supersedesId) {
-    // SAFETY: row shape matches the `status, version` columns named in the SELECT below.
-    const pred = db.prepare(`SELECT status, version FROM skills WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
-    if (!pred) {
-        throw new NotFoundError(`saveSkill: skill ${supersedesId} to supersede not found for tenant ${tenantId}`);
-    }
-    if (pred.status !== 'active') {
-        throw new ConflictError(`saveSkill: skill ${supersedesId} is not active (status='${pred.status}'); only active skills can be superseded.`);
-    }
-    return pred.version + 1;
-}
-function insertSkillRow(db, memoryId, w, version) {
-    const result = db.prepare(`
-    INSERT INTO skills(
-      memory_id, tenant_id, skill_name, instructions, trigger_text, version,
-      status, superseded_by, superseded_at, change_summary, closed_at, created_at
-    ) VALUES (?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
-  `).run(memoryId, w.tenantId, w.name, w.instructions, w.trigger, version, w.changeSummary, w.now);
-    return Number(result.lastInsertRowid ?? 0);
-}
-function supersedeSkillRow(db, w, supersedesId, skillId, version) {
-    const sup = db.prepare(`
-    UPDATE skills
-    SET status = 'superseded', superseded_by = ?, superseded_at = ?
-    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-  `).run(skillId, w.now, supersedesId, w.tenantId, skillId);
-    if (sup.changes === 0) {
-        throw new ConflictError(`saveSkill: skill ${supersedesId} could not be superseded (no longer active or self-reference).`);
-    }
-    appendAuditEvent(db, {
-        tenantId: w.tenantId,
-        actor: w.actor,
-        op: 'skill_supersede',
-        targetId: String(supersedesId),
-        metadata: {
-            skill_id: supersedesId,
-            superseded_by: skillId,
-            new_version: version,
-        },
-    });
-}
-/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
-function writeSkillRow(db, memoryId, w) {
-    const version = w.supersedesId !== undefined ? preflightSkillSupersede(db, w.tenantId, w.supersedesId) : 1;
-    const skillId = insertSkillRow(db, memoryId, w, version);
-    if (w.supersedesId !== undefined)
-        supersedeSkillRow(db, w, w.supersedesId, skillId, version);
-    // SAFETY: row's shape matches the columns named in SKILL_COLS above.
-    const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ?`)
-        .get(skillId);
-    if (!row)
-        throw new Error('saveSkill: failed to reload saved skill row');
-    // GDPR-light metadata: ids + flags only, no skill text.
-    appendAuditEvent(db, {
-        tenantId: w.tenantId,
-        actor: w.actor,
-        op: 'skill_create',
-        targetId: String(skillId),
-        metadata: {
-            skill_id: skillId,
-            version,
-            has_trigger: w.trigger !== null,
-        },
-    });
-    return row;
-}
-/**
- * Create a skill (or a new version that supersedes an existing one). Writes the
- * memory mirror + the skills row atomically inside writeEntry's SAVEPOINT. When
- * supersedesSkillId is given, the referenced ACTIVE row is preflighted (status +
- * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same SAVEPOINT;
- * the new version = predecessor.version + 1 (server-derived).
- */
-export function saveSkill(hippoRoot, tenantId, opts, actor = 'cli') {
-    assertTenantId('saveSkill', tenantId);
-    const { name, trigger } = validateSkillFields(opts.skillName, opts.instructions, opts.trigger);
-    const isSupersede = opts.supersedesSkillId !== undefined;
-    const changeSummary = isSupersede ? (opts.changeSummary ?? null) : null;
-    const now = new Date().toISOString();
-    const content = buildSkillContent(name, opts.instructions, trigger);
-    const tags = ['skill', ...(opts.extraTags ?? [])];
-    const mem = createMemory(content, {
-        tags,
-        layer: Layer.Semantic,
-        confidence: 'verified',
-        source: 'skill',
-        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
-        tenantId,
-    });
-    const w = {
-        tenantId,
-        actor,
-        name,
-        instructions: opts.instructions,
-        trigger,
-        changeSummary,
-        supersedesId: opts.supersedesSkillId,
-        now,
-    };
-    let savedRow;
-    writeEntry(hippoRoot, mem, {
-        actor,
-        afterWrite: (db, memoryId) => {
-            savedRow = writeSkillRow(db, memoryId, w);
-        },
-    });
-    if (!savedRow) {
-        throw new Error('saveSkill: afterWrite did not populate the row');
-    }
-    return rowToSkill(savedRow);
-}
-/**
- * Close (retire) an active skill. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. A superseded row is terminal.
- */
-export function closeSkill(hippoRoot, tenantId, id, actor = 'cli') {
-    assertTenantId('closeSkill', tenantId);
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const updateResult = db.prepare(`
-        UPDATE skills
-        SET status = 'closed', closed_at = ?
-        WHERE id = ? AND tenant_id = ? AND status = 'active'
-      `).run(now, id, tenantId);
-            if (updateResult.changes === 0) {
-                // SAFETY: row shape matches the single `status` column named in the SELECT above.
-                const existing = db.prepare(`SELECT status FROM skills WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
-                if (!existing) {
-                    throw new NotFoundError(`closeSkill: skill ${id} not found for tenant ${tenantId}`);
-                }
-                throw new ConflictError(`closeSkill: skill ${id} is not active (status='${existing.status}'); only active skills can be closed.`);
-            }
-            // SAFETY: row's shape matches the columns named in SKILL_COLS above.
-            const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ? AND tenant_id = ?`)
-                .get(id, tenantId);
-            if (!row)
-                throw new NotFoundError(`closeSkill: skill ${id} not found after UPDATE`);
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'skill_close',
-                targetId: String(id),
-                metadata: { skill_id: id },
-            });
-            db.exec('COMMIT');
-            return rowToSkill(row);
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch {
-                // Ignore rollback failures — the throw below is what matters.
-            }
-            throw e;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadSkillById(hippoRoot, tenantId, id) {
-    assertTenantId('loadSkillById', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: row's shape matches the columns named in SKILL_COLS above.
-        const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ? AND tenant_id = ?`)
-            .get(id, tenantId);
-        return row ? rowToSkill(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadSkills(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('loadSkills', tenantId);
-    const limit = opts.limit ?? 100;
-    const after = keysetAfter('created_at', 'id', opts.after);
-    const db = openHippoDb(hippoRoot);
-    try {
-        let rows;
-        if (opts.status) {
-            if (!VALID_SKILL_STATES.has(opts.status)) {
-                throw new BadRequestError(`loadSkills: status must be one of ${Array.from(VALID_SKILL_STATES).join('|')}; got ${opts.status}`);
-            }
-            // SAFETY: rows' shape matches the columns named in SKILL_COLS above.
-            rows = db.prepare(`
-        SELECT ${SKILL_COLS} FROM skills
-        WHERE tenant_id = ? AND status = ?${after.sql}
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, opts.status, ...after.params, limit);
-        }
-        else {
-            // SAFETY: rows' shape matches the columns named in SKILL_COLS above.
-            rows = db.prepare(`
-        SELECT ${SKILL_COLS} FROM skills
-        WHERE tenant_id = ?${after.sql}
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, ...after.params, limit);
-        }
-        return rows.map(rowToSkill);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadActiveSkills(hippoRoot, tenantId, opts = {}) {
-    return loadSkills(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
-}
-/**
- * Render the tenant's ACTIVE skills into ONE AGENTS.md / CLAUDE.md-style markdown
- * block (one H2 per skill, ordered by skill_name ASC for determinism), and RETURN
- * the string. Does NOT write any file. Returns '' when there are no active skills.
- *
- * skill_name is single-line (validated on save) so it cannot break the H2 header;
- * instructions are emitted verbatim (operator content). Bounded by MAX_EXPORT_SKILLS
- * active rows; each field is capped on save, so the rendered string is bounded.
- */
-export function exportSkills(hippoRoot, tenantId) {
-    assertTenantId('exportSkills', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: rows' shape matches the columns named in SKILL_COLS above.
-        const rows = db.prepare(`
-      SELECT ${SKILL_COLS} FROM skills
-      WHERE tenant_id = ? AND status = 'active'
-      ORDER BY skill_name ASC, id ASC
-      LIMIT ?
-    `).all(tenantId, MAX_EXPORT_SKILLS);
-        return rows
-            .map(rowToSkill)
-            .map((s) => {
-            let block = `## ${s.skillName}`;
-            if (s.trigger)
-                block += `\n\n**When:** ${s.trigger}`;
-            block += `\n\n${s.instructions}`;
-            return block;
-        })
-            .join('\n\n');
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-//# sourceMappingURL=skills.js.map

package/dist/store/entry-writes-group.d.ts

@@ -1,9 +0,0 @@
-import { type DatabaseSyncLike } from '../db.js';
-import type { EntryWrites, SupersedeWrite } from '../store-port.js';
-/** Each call on its own handle; mirrors and the forgotten counter follow the commit, so a rolled-back write leaves neither. */
-export declare function sqliteEntryWrites(hippoRoot: string): EntryWrites;
-/** Reach, the CAS on the old row, the successor's insert and the supersede row in one BEGIN IMMEDIATE transaction. Two racing supersedes: one CAS wins. */
-export declare function commitSupersede(db: DatabaseSyncLike, write: SupersedeWrite): void;
-/** A mirror left on disk would bring the archived row back on the next import; on failure the reaper retries, as mirror_cleaned_at stays NULL. */
-export declare function cleanArchivedMirrors(db: DatabaseSyncLike, hippoRoot: string, id: string): void;
-//# sourceMappingURL=entry-writes-group.d.ts.map

package/dist/store-port.d.ts

@@ -1,262 +0,0 @@
-import type { AmbientTallies } from './ambient.js';
-import { type AmbientStoreFilter } from './ambient-store.js';
-import { type ApiKeyListRow, type ApiKeyRecord, type ListApiKeysOpts, type NewApiKey } from './auth.js';
-import { type AppendAuditOpts, type AuditEvent, type ListAuditAfterOpts } from './audit.js';
-import type { ContinuityBlock } from './api/recall-types.js';
-import { type EmbeddingIndexState } from './embeddings.js';
-import { type ActiveGoals, type GetActiveGoalsOpts, type GoalRecallLogRow } from './goals.js';
-import type { SessionHandoff } from './handoff.js';
-import type { JsonValue } from './json.js';
-import type { MemoryEntry } from './memory.js';
-import type { PhysicsParticle } from './physics.js';
-import { type PlanningFallacyEvidence } from './predictions/planning-fallacy.js';
-import { type RecallTraceInput } from './recall-trace.js';
-import { type AmbientLoadResult, type AmbientRecallRequest, type ContextCandidateFilter, type RecentOrigins } from './store/candidates.js';
-import { type StrengthenOptions } from './store/entry-writes.js';
-import { type OriginFilter, type VectorCandidateSpec } from './store/search-rows.js';
-import { type ContinuityKey } from './store/sessions.js';
-import { type TokenUse } from './token-ledger.js';
-/** The arguments of `loadRecallSearchEntries` after the query, by name. */
-export interface RecallSearchArgs {
-    readonly limit: number;
-    readonly tenantId?: string;
-    readonly requestedScope?: string;
-    readonly explicitScopeMode: 'exact' | 'additive';
-    readonly includeSuperseded: boolean;
-    readonly originProjects?: OriginFilter;
-    /** The caller's personal scope, which the default deny admits; undefined admits no personal row. */
-    readonly ownScope: string | undefined;
-}
-/** Everything one recall writes once its reply is decided, so a store writes it on one connection. */
-export interface RecallWrites {
-    /** Insert or ignore on (memory_id, goal_id), so the first row wins, a duplicate inside this batch included. First drop a row
-     *  whose memory_id is in no memories row of this store, whatever that row's tenant, as `localGoalRecallRows` does. */
-    readonly goalLog: readonly GoalRecallLogRow[];
-    /** In the order they happened. */
-    readonly audit: readonly AppendAuditOpts[];
-    readonly trace?: RecallTraceInput;
-    /** Nothing when `recallBoostAblated`. Each id found, in `tenantId` when set, gets the retrieval_count, last_retrieved,
-     *  half_life_days and strength `markRetrieved` computes from the row read before any update, so a repeated id moves once. */
-    readonly strengthen?: {
-        readonly ids: readonly string[];
-        readonly opts: StrengthenOptions;
-    };
-}
-/** The reads behind recall's vector arm. */
-export interface VectorReads {
-    /** The stored model and whether any vector exists, in one snapshot. */
-    embeddingIndexState(): Promise<EmbeddingIndexState>;
-    storedVectors(ids: readonly string[]): Promise<Map<string, number[]>>;
-    /** The `spec.limit ?? 50` rows nearest `queryVector` by `rankVectorRows` among those where the tenant matches (when set), kind is not 'archived', a superseded row
-     *  shows only with `includeSuperseded`, scope follows `RecallScopeFilter`, and origin is '' or listed (when `spec.origin` is set). */
-    nearestEntries(queryVector: readonly number[], spec: VectorCandidateSpec): Promise<MemoryEntry[]>;
-    /** The particles of `ids` only; an empty list reads nothing. */
-    physicsParticles(ids: readonly string[]): Promise<Map<string, PhysicsParticle>>;
-}
-/** One memory's vector, computed by the caller's embedding provider. */
-export interface VectorRowWrite {
-    readonly memoryId: string;
-    readonly vector: readonly number[];
-    /** Kept only when the memory has no particle yet, under `memoryId` whatever its own memoryId says. */
-    readonly particle?: PhysicsParticle;
-}
-export interface VectorWrite {
-    readonly tenantId: string;
-    /** The index identity the vectors were built by, `embeddingIndexIdentity(provider.id)`. */
-    readonly model: string;
-    /** Set only by embedAll's rebuild, so a write that read the index state before another process rebuilt it cannot drop that rebuild. */
-    readonly replaceIndex: boolean;
-    readonly rows: readonly VectorRowWrite[];
-}
-export interface VectorWriteResult {
-    readonly written: number;
-    /** True when another model built the index and `replaceIndex` is false; the store then keeps nothing and `written` is 0. */
-    readonly modelMismatch: boolean;
-}
-export interface VectorBackfillQuery {
-    readonly model: string;
-    /** Only ids above this one in byte order; unset starts at the first. */
-    readonly afterId?: string;
-    /** Clamped to 1..500; a non-integer rejects with RangeError `limit must be an integer`. */
-    readonly limit: number;
-    /** Every tenant when unset, since the backfill covers the whole store. */
-    readonly tenantId?: string;
-}
-/** The writes behind embed on write and the backfill: core computes each vector, the store only keeps it.
- *  A store deletes a memory's vector and particle when the memory is deleted (hippo.db does it by trigger and foreign-key cascade). */
-export interface VectorWrites {
-    /** Memories of any kind with no vector stored under `query.model`, by id ascending in byte order. */
-    entriesWithoutVector(query: VectorBackfillQuery): Promise<MemoryEntry[]>;
-    /** In one transaction: refuses with `modelMismatch` if `replacesIndex` and not `replaceIndex`; else, when a row is writable (memory in `tenantId`, vector non-empty
-     *  and finite), drops every vector and particle if `replacesIndex`, keeps each writable row under `model` with its particle where none exists, sets `model`. No audit row. */
-    writeVectors(write: VectorWrite): Promise<VectorWriteResult>;
-}
-export interface KeyRevoke {
-    readonly tenantId: string;
-    readonly keyId: string;
-    readonly actor: string;
-    readonly at: string;
-}
-export interface KeyAudit {
-    /** Sets revoked_at to `at` and appends one auth_revoke row (the key's tenant, `actor`, the key id) in one transaction, then resolves to `at`. A revoked
-     *  key resolves to its own revoked_at and writes nothing; a key missing from `tenantId` rejects with NotFoundError `Unknown key_id: <keyId>`. */
-    revokeApiKey(revoke: KeyRevoke): Promise<string>;
-    /** As `listAuditEventsAfter`: rows above `afterId` in ascending id order, with its RangeErrors, limit clamp and tenant filter. */
-    auditEventsAfter(opts: ListAuditAfterOpts): Promise<AuditEvent[]>;
-    /** The highest audit id ever assigned, pruned rows included, 0 before the first; a tail that sees it drop knows the log was restored. */
-    auditHighId(): Promise<number>;
-}
-/** One ambient load: the pins, the `recentNeeded` newest rows `admit` keeps, and the prompt-recall candidates. */
-export interface AmbientCandidateRequest {
-    readonly recentNeeded: number;
-    /** Sees each row in the order `loadAmbientCandidates` reads them, since the delivery ledger counts its refusals. */
-    readonly admit: (e: MemoryEntry) => boolean;
-    readonly recall?: AmbientRecallRequest;
-    readonly origins?: RecentOrigins;
-}
-/** The reads behind getContext beyond the base `continuity`: its fallback handoff, candidate rows and ambient tallies.
- *  getContext with a query under an embedding provider needs `vectors` too, and answers 501 without it. */
-export interface ContextReads {
-    /** The newest handoff of the last `maxAgeMs` that is its session's highest id, has no outcome or a partial or failed one, and
-     *  passes recall's default scope deny, as `loadLatestHandoff` with `unfinishedOnly` and `scopeFilter: 'default-deny'`. Rejects an empty tenant id. */
-    unfinishedHandoff(tenantId: string, maxAgeMs: number, key: ContinuityKey | null): Promise<SessionHandoff | null>;
-    /** As `loadAmbientCandidates`; `recall` searches with the query `rarestFtsQuery` builds from FTS document counts over every tenant's rows,
-     *  and finds nothing when no term is indexed. Core keeps only `tenantId`'s rows that its own admit passes, whatever the store returns. */
-    ambientCandidates(tenantId: string, request: AmbientCandidateRequest): Promise<AmbientLoadResult>;
-    /** As `loadContextCandidates`: at most `filter.cap` live rows, pins and then the least decayed first, returned by created, then id. */
-    contextCandidates(tenantId: string, filter: ContextCandidateFilter): Promise<MemoryEntry[]>;
-    /** As `loadAmbientTallies`: one aggregate over the live, unarchived rows `filter` admits, less other projects' secret-tagged rows. */
-    ambientTallies(tenantId: string, filter: AmbientStoreFilter): Promise<AmbientTallies>;
-}
-export interface EntryWrite {
-    readonly entry: MemoryEntry;
-    readonly actor: string;
-}
-/** Who acts on which of a tenant's rows; `ownScope` is the caller's personal scope, so every other personal row is out of reach. */
-export interface EntryTarget {
-    readonly tenantId: string;
-    readonly actor: string;
-    readonly ownScope: string | null;
-}
-export interface OutcomeWrite extends EntryTarget {
-    readonly ids: readonly string[];
-    readonly good: boolean;
-}
-export interface SupersedeWrite extends EntryTarget {
-    readonly oldId: string;
-    readonly successor: MemoryEntry;
-}
-export interface EntryRemoval extends EntryTarget {
-    readonly id: string;
-}
-export interface RawArchive extends EntryRemoval {
-    readonly reason: string;
-}
-/** The memory-row writes behind remember, outcome, supersede, archive and forget. Each writes its audit rows in the write's own transaction,
- *  a child row's change marks its level 2 or 3 summary parent dirty (one summary_marked_dirty row on the flip), and the schema's rules hold. */
-export interface EntryWrites {
-    /** Upserts the row, its full-text row and one remember row ({kind, scope}) in the entry's tenant; an id another tenant holds rejects in the transaction with ConflictError `Memory <id>
-     *  belongs to another tenant`. Content the write brings into a tenant that tombstoned it rejects with RejectedValueError and writes one reject_refusal row after the rollback, best effort. */
-    writeEntry(write: EntryWrite): Promise<void>;
-    /** For each id in order, a row of the tenant within reach gets `entryAfterOutcome`, a rewrite as writeEntry does and one outcome row ({good}); other ids are skipped, a repeated id builds
-     *  on its first outcome. Each read holds the row's lock to commit (SELECT ... FOR UPDATE), so a supersede between read and rewrite is not undone. Resolves to the ids applied, repeats kept. */
-    applyOutcome(outcome: OutcomeWrite): Promise<string[]>;
-    /** Sets the old row's superseded_by where it is within reach and not yet superseded, both checked in the transaction, else rejects with NotFoundError `memory not found: <oldId>` or
-     *  ConflictError `Memory <oldId> already superseded by another writer`. Then writes the successor as writeEntry does and one supersede row ({newId}), all or nothing. */
-    supersede(write: SupersedeWrite): Promise<void>;
-    /** Moves a raw row to raw_archive (metadata only, no content), deletes it and its full-text row and writes one archive_raw row ({reason});
-     *  resolves to the archived_at written. A row out of reach rejects with NotFoundError `memory not found: <id>`, any other kind with BadRequestError. */
-    archiveRaw(archive: RawArchive): Promise<string>;
-    /** Deletes the row and its full-text row and writes one forget row; a raw row rejects, being append-only. A row out of reach rejects with
-     *  NotFoundError `memory not found: <id>`. Archive and forget then add one to the store-wide forgotten counter, best effort. */
-    forget(removal: EntryRemoval): Promise<void>;
-}
-/** A key to insert and the actor and metadata of its auth_create row, whose tenant and target are the key's. Neither holds the plaintext. */
-export interface KeyMint {
-    readonly key: NewApiKey;
-    readonly actor: string;
-    readonly metadata: Readonly<Record<string, JsonValue>>;
-}
-export interface SelfKeyMint extends KeyMint {
-    readonly key: NewApiKey & {
-        readonly ownerSubject: string;
-        readonly expiresAt: string;
-    };
-    /** Live keys the owner may hold in the tenant once this one is in. */
-    readonly perSubject: number;
-}
-/** `listApiKeyRows`'s filters, always inside one tenant. */
-export interface KeyListQuery extends Omit<ListApiKeysOpts, 'tenantId'> {
-    readonly tenantId: string;
-}
-export interface KeyWrites {
-    /** Inserts the key and appends its auth_create row in one transaction; with either one failing, neither is written. A key id taken in any tenant
-     *  rejects, since keys are looked up by id alone. */
-    createApiKey(mint: KeyMint): Promise<void>;
-    /** One transaction, serialized per (tenant, owner) before the count (hippo.db BEGIN IMMEDIATE, Postgres pg_advisory_xact_lock on the pair): revoke at `key.createdAt`
-     *  the owner's oldest live keys in the key's tenant down to `perSubject - 1`, insert the key, append an auth_revoke row `{ replacedBy: <new key id> }` per revoked key,
-     *  then the auth_create row; resolves to the revoked ids. Live: unrevoked, expires_at null or Date.parse(expires_at) after createdAt (NaN counts as expired). */
-    createSelfApiKey(mint: SelfKeyMint): Promise<string[]>;
-    /** As `listApiKeyRows`: newest inserted first, each with its scope grants; `active` drops revoked rows and an expires_at not above now's toISOString. */
-    listApiKeys(query: KeyListQuery): Promise<ApiKeyListRow[]>;
-}
-/** The optional groups: a store sets each one whole or leaves it unset, and a route or MCP tool names the one it needs. */
-export interface StoreGroups {
-    /** Unset on a store built before them, where hybrid and physics recall under an embedding provider answer 501. */
-    readonly vectors: VectorReads;
-    readonly keyAudit: KeyAudit;
-    readonly keyWrites: KeyWrites;
-    /** embedMemory and embedAll with a store need it and `vectors`. */
-    readonly vectorWrites: VectorWrites;
-    readonly entryWrites: EntryWrites;
-    readonly contextReads: ContextReads;
-}
-export type StoreGroup = 'base' | keyof StoreGroups;
-export declare function hasGroup(store: HippoStore, group: StoreGroup): boolean;
-/** The group's methods; a store without them throws StoreNotPortedError, which answers 501 as any unported path does. */
-export declare function requireGroup<G extends keyof StoreGroups>(store: HippoStore, group: G): StoreGroups[G];
-/** What `serve()` reads and writes through. Each method is atomic and no transaction spans an await, since SQLite's lock wait blocks the event loop; a lock timeout throws `StoreBusyError`. */
-export interface HippoStore extends Partial<StoreGroups> {
-    /** 'sqlite' is hippo.db under the served root. Under any other kind, an unported route answers 501 and a hippo.db open inside a request throws. */
-    readonly kind: string;
-    /** The api_keys row for `keyId` with its scope grants, revoked or not; null when no row matches. */
-    findApiKey(keyId: string): Promise<ApiKeyRecord | null>;
-    /** Recall candidates in `loadRecallSearchEntries` order: FTS, then LIKE, then every row in scope. */
-    searchRecallEntries(query: string, args: RecallSearchArgs): Promise<MemoryEntry[]>;
-    /** The rows among the first 500 ids, a tenant narrowing them, ordered by created, then content, then id, all ascending,
-     *  as `loadEntriesByIds` does; the input order is ignored. */
-    entriesByIds(ids: readonly string[], tenantId?: string): Promise<MemoryEntry[]>;
-    /** The session's active goals and their policies, read together so a goal and its policy never disagree. */
-    activeGoals(opts: GetActiveGoalsOpts): Promise<ActiveGoals>;
-    /** The first `count` (at most 200) unsuperseded raw rows a tenant, a non-empty session id and non-null `origins` (those projects and
-     *  user-global rows) must narrow, by created descending, then content and id ascending, as `loadFreshRawMemories` does. */
-    freshRawEntries(count: number, tenantId: string | undefined, sessionId: string | undefined, origins: readonly string[] | null): Promise<MemoryEntry[]>;
-    /** The newest active snapshot a non-null `key` must narrow to one owner and project (null only on an unshared hippo.db), then for its session
-     *  the newest handoff (same key) and `eventLimit` newest events returned oldest first, each tie broken by the larger id; the caller applies scope. */
-    continuity(tenantId: string, eventLimit: number, key: ContinuityKey | null): Promise<ContinuityBlock>;
-    /** Resolves a forward claim's tokens to one class and reads its baserate, writing no audit row. */
-    planningFallacyEvidence(tenantId: string, classQueryTokens: readonly string[]): Promise<PlanningFallacyEvidence>;
-    /** Appends the rows in order, all or none. */
-    appendAuditEvents(events: readonly AppendAuditOpts[]): Promise<void>;
-    /** Writes the goal log and audit rows in one transaction and rejects with none written if it fails. Then the trace and
-     *  the strengthen, each on its own: a failure there logs and still resolves, since the reply is already decided. */
-    finishRecall(writes: RecallWrites): Promise<void>;
-    /** Adds `recalled` to the one store-wide total_recalled counter, no tenant; the SQLite store also rewrites stats.json. */
-    bumpRecallStats(recalled: number): Promise<void>;
-    /** One token-ledger row. Throws, so the caller decides whether a ledger failure matters. */
-    recordTokens(use: TokenUse): Promise<void>;
-    /** Releases the store's connections; `serve()` closes only a store it made itself. */
-    close(): Promise<void>;
-}
-/** The store a request runs on: the served one, else hippo.db under its root, as the CLI and SDK callers have it. */
-export declare function storeFor(ctx: {
-    readonly hippoRoot: string;
-    readonly store?: HippoStore;
-}): HippoStore;
-/** The built-in store: today's synchronous hippo.db functions behind the port, each call on its own short-lived handles, so close has nothing to release. */
-export declare function sqliteStore(hippoRoot: string): HippoStore & StoreGroups;
-/** sqliteStore's continuity read, for the synchronous recall that cannot await the port. */
-export declare function continuityAt(hippoRoot: string, tenantId: string, eventLimit: number, key: ContinuityKey | null): ContinuityBlock;
-/** sqliteStore's finishRecall, for the synchronous recall that cannot await the port. */
-export declare function finishRecallAt(hippoRoot: string, writes: RecallWrites): void;
-//# sourceMappingURL=store-port.d.ts.map