hippo-memory 1.70.0 → 1.72.0

package/dist/store/port.d.ts

@@ -2,7 +2,7 @@ import type { AmbientTallies } from '../core/ambient.js';
 import type { AmbientStoreFilter } from './ambient.js';
 import type { ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from './auth.js';
 import type { AppendAuditOpts, AuditEvent, ListAuditAfterOpts, QueryAuditOpts } from './audit.js';
-import type { EmbeddingIndexState } from './embeddings/index.js';
+import type { EmbeddingIndexState } from './vector-index.js';
 import type { Entity, Relation } from './graph-rows.js';
 import type { ActiveGoals, GetActiveGoalsOpts, GoalRecallLogRow } from './goals.js';
 import type { SessionHandoff } from '../core/handoff.js';
@@ -10,14 +10,15 @@ import type { JsonValue } from '../util/json.js';
 import type { KeysetPosition } from '../util/keyset.js';
 import type { MemoryEntry } from '../core/memory.js';
 import type { PhysicsParticle } from '../core/physics.js';
-import type { BriefReceipt, Incident, IncidentFields, ObjectByKind, ObjectFields, ObjectKind, Policy, SavableKind, Skill } from './object-types.js';
+import type { BriefReceipt, Incident, IncidentFields, ObjectByKind, ObjectFields, ObjectKind, Policy, SavableKind, Skill } from '../core/object-types.js';
 import type { PlanningFallacyEvidence } from './planning-fallacy-evidence.js';
-import type { ClosureState, Prediction, PredictionBaserate, SavePredictionOpts } from './predictions.js';
+import type { Prediction, PredictionBaserate, SavePredictionOpts } from './predictions.js';
+import type { ClosureState } from '../core/prediction.js';
 import type { QuarantineRow, QuarantineStatus } from './quarantine.js';
-import type { ScopeActor } from './recall-scope.js';
+import type { ScopeActor } from '../core/recall-scope.js';
 import type { RecallTraceInput } from './recall-trace.js';
 import type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, RecentOrigins } from './candidates.js';
-import type { GithubDlqWrite, GithubRouting } from './connectors/github.js';
+import type { GitHubDlqInsert, GitHubRouting } from './connectors/github.js';
 import type { SlackDlqInsert, SlackTeamRoute } from './connectors/slack.js';
 import type { StrengthenOptions } from './entry-writes.js';
 import type { SessionEvent, TaskSnapshot } from './rows.js';
@@ -55,8 +56,8 @@ 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). */
+    /** The `spec.limit ?? 50` rows nearest `queryVector` by `rankVectorRows`, filtered by tenant (when set), kind != 'archived', superseded only with
+     * `includeSuperseded`, scope per `RecallScopeFilter`, and origin '' 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>>;
@@ -95,8 +96,8 @@ export interface VectorBackfillQuery {
 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. */
+    /** In one transaction: refuses with `modelMismatch` if `replacesIndex` and not `replaceIndex`; else drops every vector and particle if `replacesIndex`,
+     * keeps each writable row (memory in `tenantId`, finite non-empty vector) under `model` with its particle, sets `model`. No audit row. */
     writeVectors(write: VectorWrite): Promise<VectorWriteResult>;
 }
 export interface KeyRevoke {
@@ -163,14 +164,14 @@ export interface RawArchive extends EntryRemoval {
 /** 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. */
+    /** Upserts the row, its full-text row and one remember row ({kind, scope}) in the entry's tenant; an id held by another tenant rejects with ConflictError.
+     * Content from 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. */
+    /** Per id in order, a row of the tenant within reach gets `entryAfterOutcome` (rewrite as writeEntry does) and one outcome row ({good}); other ids skipped.
+     * Each read holds the row lock to commit (SELECT ... FOR UPDATE), so a concurrent supersede 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. */
+    /** Sets the old row's superseded_by if it is within reach and not yet superseded (both checked in the transaction), else rejects NotFoundError or
+     * ConflictError. 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. */
@@ -201,14 +202,14 @@ 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). */
+    /** Serialized per (tenant, owner) before the count (BEGIN IMMEDIATE / pg_advisory_xact_lock): revoke the owner's oldest live keys to `perSubject - 1`,
+     * then insert the key; append auth_revoke `{ replacedBy }` per revoked key, then auth_create. Live: unrevoked and not expired (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[]>;
 }
-/** A claim to save and the memory row that mirrors it into recall: core builds it with `predictionMirror` in the tenant the save names, so every store keeps the same row. */
+/** A claim to save and the memory row that mirrors it into recall: core builds it with
+ * `predictionMirror` in the tenant the save names, so every store keeps the same row. */
 export interface PredictionSave extends SavePredictionOpts {
     readonly mirror: MemoryEntry;
 }
@@ -217,7 +218,8 @@ export interface PredictionClose {
     readonly actualValue?: number;
     readonly closureNote?: string;
 }
-/** Which of a tenant's predictions a list reads: every class when `classTag` is unset (it is never empty), every state when `closureState` is, and a closed state only inside a class. */
+/** Which of a tenant's predictions a list reads: every class when `classTag` is unset (it is
+ * never empty), every state when `closureState` is, and a closed state only inside a class. */
 export type PredictionFilter = {
     readonly classTag?: string;
     readonly closureState?: 'open';
@@ -229,25 +231,26 @@ export type PredictionListQuery = PredictionFilter & {
     readonly limit: number;
     readonly after?: KeysetPosition;
 };
-/** The reads and writes behind the predictions routes. createdAt and closedAt are the store's own clock at the write, as `toISOString` gives it, since the list orders createdAt as text. */
+/** The reads and writes behind the predictions routes. createdAt and closedAt are the store's
+ * own clock at the write, as `toISOString` gives it, since the list orders createdAt as text. */
 export interface Predictions {
-    /** In one transaction: writes `mirror` as `EntryWrites.writeEntry` does, inserts the open row pointing at it under the next id, and appends one predict_create row
-     *  ({prediction_id, class_tag, has_estimate, target_date}, target the id) ahead of the mirror's remember row. Resolves to the row saved. */
+    /** In one transaction: writes `mirror` as `EntryWrites.writeEntry` does, inserts the open row under the next id, and appends one predict_create row
+     * ({prediction_id, class_tag, has_estimate, target_date}) ahead of the mirror's remember row. Resolves to the row saved. */
     savePrediction(tenantId: string, input: PredictionSave, actor: string): Promise<Prediction>;
-    /** Closes the tenant's open row and appends one predict_close row ({prediction_id, closure_state, has_actual}, target the id) in one transaction; the mirror stays as saved. A missing
-     *  id or another tenant's rejects with NotFoundError `closePrediction: prediction <id> not found for tenant <tenantId>`, a row already closed with BadRequestError, neither writing anything. */
+    /** Closes the tenant's open row and appends one predict_close row ({prediction_id, closure_state, has_actual}) in one transaction; the mirror stays as saved.
+     * A missing or other-tenant id rejects with NotFoundError, an already-closed row with BadRequestError; neither writes anything. */
     closePrediction(tenantId: string, id: number, close: PredictionClose, actor: string): Promise<Prediction>;
     /** The tenant's row; null for a missing id or another tenant's. No audit row. */
     predictionById(tenantId: string, id: number): Promise<Prediction | null>;
     /** At most `limit` rows, newest first: by createdAt compared as text in byte order, then by id, both descending, so the order is total.
      *  `after` keeps only the rows below its (createdAt, id) pair in that order. No audit row. */
     listPredictions(tenantId: string, query: PredictionListQuery): Promise<Prediction[]>;
-    /** `predictionBaserateOf` over the tenant's rows of the class that are closed (not closed-unknown) with an estimate and an actual, handed over in ascending id order
-     *  because its float sums depend on the order. Then appends one predict_baserate row ({class_tag, n_closed}, target the class), for a class with no such row too. */
+    /** `predictionBaserateOf` over the tenant's closed (not closed-unknown) rows of the class with an estimate and an actual, in ascending id order (its
+     * float sums depend on it). Then appends one predict_baserate row ({class_tag, n_closed}), also for a class with no such row. */
     predictionBaserate(tenantId: string, classTag: string, actor: string): Promise<PredictionBaserate>;
 }
-/** Which of a tenant's rows of one kind a list reads: every status when `status` is unset, and every value of the kind's one filter column (a customer note's customer,
- *  a project brief's repo) when `filter` is. Neither is ever empty, and a kind with no filter column ignores `filter`. */
+/** Which of a tenant's rows of one kind a list reads: every status when `status` is unset, every value of the kind's one filter column (customer, repo)
+ * when `filter` is. Neither is ever empty; a kind with no filter column ignores `filter`. */
 export interface ObjectListQuery<K extends ObjectKind = ObjectKind> {
     readonly status?: ObjectByKind[K]['status'];
     readonly filter?: string;
@@ -261,7 +264,8 @@ export interface ObjectClose<K extends ObjectKind = ObjectKind> {
     /** The row's closedAt: core's clock, as `toISOString` gives it. */
     readonly at: string;
 }
-/** One row to save and the memory that mirrors it into recall: core builds the mirror in the tenant the save names with the kind as its `source`, so every store keeps the same row. */
+/** One row to save and the memory that mirrors it into recall: core builds the mirror in the
+ * tenant the save names with the kind as its `source`, so every store keeps the same row. */
 export interface ObjectSave<K extends SavableKind = SavableKind> {
     readonly mirror: MemoryEntry;
     readonly fields: ObjectFields[K];
@@ -295,7 +299,8 @@ export interface IncidentOpen {
     /** The row's createdAt: core's clock, as `toISOString` gives it. */
     readonly at: string;
 }
-/** Why an incident was not opened: `memoryId` is the first linked id, in the order given, that is no memory of the tenant; or the written row could not be read back. */
+/** Why an incident was not opened: `memoryId` is the first linked id, in the order
+ * given, that is no memory of the tenant; or the written row could not be read back. */
 export type IncidentOpenRefusal = {
     readonly refused: 'unlinked';
     readonly memoryId: string;
@@ -315,39 +320,33 @@ export interface PoliciesInForceQuery {
     readonly name?: string;
     readonly limit: number;
 }
-/** The reads and writes behind the typed-object routes. An audit row names the object under the kind's id key: decision_id, incident_id, process_id, policy_id, skill_id, brief_id, note_id.
- *  A row belongs to one tenant: another tenant's id reads as missing in every method. */
+/** The reads and writes behind the typed-object routes. An audit row names the object under the kind's id key (decision_id, incident_id, ...).
+ * A row belongs to one tenant: another tenant's id reads as missing in every method. */
 export interface Objects {
     /** At most `limit` rows of the kind, newest first: by createdAt compared as text in byte order, then by id, both descending, so the order is total.
      *  `after` keeps only the rows below its (createdAt, id) pair in that order. No audit row. */
     listObjects<K extends ObjectKind>(tenantId: string, kind: K, query: ObjectListQuery<K>): Promise<ObjectByKind[K][]>;
     /** The tenant's row; null for a missing id or another tenant's. No audit row. */
     objectById<K extends ObjectKind>(tenantId: string, kind: K, id: number): Promise<ObjectByKind[K] | null>;
-    /** In one transaction: moves the tenant's row from a status in `close.from` to closed with closedAt `close.at`, then appends one <kind>_close row ({<kind's id key>: id}, target the id).
-     *  A refusal (`missing`, or `status` with the status held) writes nothing. After the commit a kind the graph reads has its graph rows dropped and its mirror queued for a rebuild; a failure there is logged, never thrown. */
+    /** In one transaction: moves the tenant's row from a `close.from` status to closed at `close.at` and appends one <kind>_close row; a refusal writes nothing.
+     * After the commit a kind the graph reads has its graph rows dropped and its mirror queued for a rebuild; a failure there is logged, never thrown. */
     closeObject<K extends ObjectKind>(tenantId: string, kind: K, id: number, close: ObjectClose<K>): Promise<ObjectByKind[K] | ObjectRefusal>;
-    /** In one transaction, in this order: writes `mirror` as `EntryWrites.writeEntry` does; inserts the row as active under the next id, version 1 or the replaced row's plus one;
-     *  with `supersedesId`, moves that row from active to superseded (supersededBy the new id, supersededAt `at`) and appends a <kind>_supersede row ({<id key>: replaced, superseded_by,
-     *  new_version on a versioned kind, then a brief's refresh keys}, target the replaced id); appends the <kind>_create row ({<id key>: id, then the kind's own keys}, target the id); then the
-     *  mirror's remember row. The kind's own keys: decision has_context; process version, step_count, has_description; policy version, open_ended; skill version, has_trigger; project_brief
-     *  repo, version, refreshed, and receipt_count when refreshed; customer_note customer, version. A refusal (`missing` or `status` for the replaced row, `raced`, `vanished`) leaves no
-     *  mirror, row or audit row. After the commit a kind the graph reads has its mirror queued for a rebuild, which is logged on failure and never thrown. */
+    /** In one transaction, in order: writes `mirror` as `EntryWrites.writeEntry` does; inserts the row active (version 1, or the replaced row's plus one);
+     * with `supersedesId`, supersedes that row; appends the supersede and create rows. A refusal (`missing`, `status`, `raced`, `vanished`) writes nothing. */
     saveObject<K extends SavableKind>(tenantId: string, kind: K, save: ObjectSave<K>): Promise<ObjectByKind[K] | ObjectRefusal>;
-    /** In one transaction, in this order: writes `mirror` as `EntryWrites.writeEntry` does; checks, in the order given, that each linked id is a memory of the tenant; inserts the row as open
-     *  under the next id, holding the linked ids as given; appends the incident_open row ({incident_id, has_context, linked_memory_count}, target the id; has_context is true for a context
-     *  that is not empty); then the mirror's remember row. A refusal leaves no mirror, row or audit row. */
+    /** In one transaction, in order: writes `mirror` as `EntryWrites.writeEntry` does; checks each linked id is a memory of the tenant; inserts the row open
+     * under the next id; appends the incident_open row, then the mirror's remember row. A refusal leaves no mirror, row or audit row. */
     openIncident(tenantId: string, open: IncidentOpen): Promise<Incident | IncidentOpenRefusal>;
-    /** In one transaction: moves the tenant's incident from open to resolved with resolutionText `resolve.text` and resolvedAt `resolve.at`, then appends one incident_resolve row
-     *  ({incident_id}, target the id). A refusal (`missing`, `status` with the status held, or `vanished`) writes nothing. */
+    /** In one transaction: moves the tenant's incident from open to resolved with `resolve.text` and `resolve.at`, then appends one incident_resolve row.
+     * A refusal (`missing`, `status`, or `vanished`) writes nothing. */
     resolveIncident(tenantId: string, id: number, resolve: IncidentResolve): Promise<Incident | ObjectRefusal>;
-    /** At most `limit` of the tenant's policies in force at `asOf`: a row that is not closed, whose validFrom is at or before `asOf` and whose validTo is unset or after it, and that is
-     *  active, or is superseded by a row whose validFrom is after `asOf`. Newest validFrom first, compared as text in byte order, then the larger id. No audit row. */
+    /** Policies in force at `asOf` (max `limit`): not closed, validFrom <= asOf < validTo (or unset), and active or superseded by a row whose validFrom is
+     * after asOf. Newest validFrom first, compared as text in byte order, then larger id. No audit row. */
     policiesInForce(tenantId: string, query: PoliciesInForceQuery): Promise<Policy[]>;
     /** At most `limit` of the tenant's active skills, by skillName ascending compared as text in byte order, then by id ascending. No audit row. */
     activeSkillsByName(tenantId: string, limit: number): Promise<Skill[]>;
-    /** At most `limit` of the tenant's memories that carry `tag`, whose source is not project_brief and whose scope recall admits when no scope is asked for, newest first: by created
-     *  compared as text in byte order, then by id, both descending. A memory carries the tag when its tag list, written as JSON, holds the tag between double quotes, the tag as
-     *  given and not escaped, once the ASCII letters of both are folded. No audit row. */
+    /** At most `limit` of the tenant's memories carrying `tag` (tag list as JSON, matched between double quotes, unescaped, ASCII case-folded) whose source
+     * is not project_brief and whose scope recall admits with no scope asked, newest first by created (text, byte order) then id. No audit row. */
     briefReceipts(tenantId: string, tag: string, limit: number): Promise<BriefReceipt[]>;
 }
 /** One session's unsuperseded raw rows inside a tenant; `origins` keeps those projects' rows and rows of no project, unset keeps every origin. */
@@ -391,12 +390,14 @@ export interface SummaryDescendants {
 }
 /** The reads behind session assembly and summary drill-down. None writes an audit row. */
 export interface DagReads {
-    /** The newest `cap` rows by created then id, returned oldest first (created, then id, ascending) as `loadSessionRawMemories` does; an empty session id reads nothing. */
+    /** The newest `cap` rows by created then id, returned oldest first (created, then id,
+     * ascending) as `loadSessionRawMemories` does; an empty session id reads nothing. */
     sessionRawEntries(query: SessionRawWindow): Promise<MemoryEntry[]>;
-    /** How many rows the session holds with no cap, under the scope rule `passesScopeFilterForRecall` applies, so the count never tells of a row the caller could not read. */
+    /** How many rows the session holds with no cap, under the scope rule `passesScopeFilterForRecall`
+     * applies, so the count never tells of a row the caller could not read. */
     sessionRawCount(query: SessionRawCount): Promise<number>;
-    /** The tenant's row `id` and up to `walk.depth` levels under it, read in one call so no write of this process lands between two levels; null when the tenant holds no such row.
-     *  A level lists the children of the level above it, parent by parent in that level's order and each parent's children by created then id ascending; a row is listed once, at the first level that reaches it. */
+    /** The tenant's row `id` and up to `walk.depth` levels under it, read in one call so no write of this process lands between levels; null if no such row.
+     * Each level lists the children of the one above, parent by parent, children by created then id ascending; a row is listed once, at its first level. */
     summaryWithDescendants(tenantId: string, id: string, walk: DescendantWalk): Promise<SummaryDescendants | null>;
 }
 /** The read behind the audit list. It writes no audit row. */
@@ -438,21 +439,21 @@ export type QuarantineRejection = {
 } | QuarantineRefusal;
 /** The review queue behind the quarantine routes. A refusal is a resolved value, never a rejection, and writes nothing. */
 export interface Quarantine {
-    /** At most `limit` of the tenant's records, newest first: by quarantinedAt compared as text in byte order, then by memoryId, both descending; `after` keeps only the records below its
-     *  (quarantinedAt, memoryId) pair in that order. 'pending' leaves out a record whose memory row is gone from the tenant; every other status keeps it, with null content. No audit row. */
+    /** At most `limit` of the tenant's records, newest first (quarantinedAt as text in byte order, then memoryId, both descending); `after` keeps only
+     * records below its pair. 'pending' leaves out a record whose memory row is gone; every other status keeps it, with null content. No audit row. */
     listQuarantined(tenantId: string, query: QuarantineListQuery): Promise<QuarantinedMemory[]>;
-    /** In one transaction, all three or none: sets the memory's scope to the record's originalScope where the row is in the tenant and still under `quarantine:private:<originalScope, or 'unscoped' for null>`;
-     *  marks the record approved, decidedAt the store's own clock as `toISOString` gives it and decidedBy `actor`; appends one quarantine_approve row ({originalScope}, target the id). */
+    /** In one transaction, all or none: restores the memory's originalScope if it is in the tenant and still under `quarantine:private:...`;
+     * marks the record approved (decidedAt from the store's clock, decidedBy `actor`); appends one quarantine_approve row ({originalScope}). */
     approveQuarantined(tenantId: string, id: string, actor: string): Promise<QuarantineApproval>;
-    /** In one transaction, both or neither: marks the record rejected, decidedAt and decidedBy as approve sets them, and appends one quarantine_reject row ({}, target the id).
-     *  The memory row is not read or written, so it stays under its quarantine scope and a record with no memory row can still be rejected. */
+    /** In one transaction, both or neither: marks the record rejected (decidedAt/decidedBy as approve) and appends one quarantine_reject row.
+     * The memory row is not touched, so it stays under its quarantine scope and a record with no memory row can still be rejected. */
     rejectQuarantined(tenantId: string, id: string, actor: string): Promise<QuarantineRejection>;
 }
-/** What one graph view reads. `limit` is a positive integer and caps each read on its own. Newest means by createdAt, then id, both descending.
- *  A row shows when it cites no memory, or its memory is in the tenant under a null scope or one `canReadScope(reader, scope)` admits; with no `reader` every row shows. */
+/** What one graph view reads. `limit` is a positive integer capping each read on its own; newest means createdAt, then id, both descending. A row shows
+ * when it cites no memory, or its memory is in the tenant with a null scope or one `canReadScope(reader, scope)` admits; no `reader` shows every row. */
 export interface GraphViewQuery {
-    /** Unset reads the whole graph. Set, the start entities are the first `limit` of exactly this name, lowest id first, less the ones that do not show; none left answers empty and not truncated.
-     *  Per 400 start ids in order, the newest `limit` relations with an end among them join in, each once; in that order each adds its other end to the ids held, which begin as the start ids, until `limit` ids are held. */
+    /** Unset reads the whole graph. Set, the start entities are the first `limit` of exactly this name (lowest id first) that show; none left answers empty.
+     * Per 400 start ids, the newest `limit` relations with an end among them join in, each adding its other end to the ids held, until `limit` ids are held. */
     readonly entity?: string;
     readonly limit: number;
     readonly reader?: ScopeActor;
@@ -461,14 +462,14 @@ export interface GraphRows {
     readonly entities: Entity[];
     /** May name an entity `entities` lacks; the caller drops such a relation. */
     readonly relations: Relation[];
-    /** Judged before a row is hidden: the start entities, the relations joined in, the relations returned or (whole graph) the entities returned came back `limit` long,
-     *  or the walk held `limit` ids with a relation still to join. */
+    /** Judged before a row is hidden: true when start entities, joined relations, returned relations or (whole graph) returned entities came back `limit` long,
+     * or the walk held `limit` ids with a relation still to join. */
     readonly truncated: boolean;
 }
 /** The rows behind GET /v1/graph. */
 export interface GraphReads {
-    /** Every read from one snapshot, then the rows that do not show are dropped. Whole graph: the tenant's newest `limit` entities and newest `limit` relations.
-     *  From a name: the tenant's entities of the ids held, id ascending within each 400 of them, and the newest `limit` relations with both ends among those ids. */
+    /** Every read from one snapshot, then rows that do not show are dropped. Whole graph: the tenant's newest `limit` entities and relations.
+     * From a name: the entities of the ids held (id ascending, 400 at a time) and the newest `limit` relations with both ends among those ids. */
     graphRows(tenantId: string, query: GraphViewQuery): Promise<GraphRows>;
 }
 /** The source event a connector's write answers, by the source's own key. The store logs each key once per connector, across every tenant. */
@@ -499,14 +500,14 @@ export type ConnectorWriteOutcome = {
 export interface ConnectorArchive extends RawArchive {
     readonly event: ConnectorEvent;
 }
-/** A connector's writes with the rows that must commit with them: the event log row that turns a redelivery into a no-op, and the quarantine record of flagged content. */
+/** A connector's writes with the rows that must commit with them: the event log row
+ * that turns a redelivery into a no-op, and the quarantine record of flagged content. */
 export interface ConnectorWrites {
-    /** entryWrites.writeEntry and, in its transaction: with `quarantine`, one pending record for the entry's tenant and id and one quarantine row ({reason, originalScope}), ahead of the
-     *  remember row; with `event`, one log row naming the entry's id. All commit or none. A key logged before, by an earlier write or by the winner of a race, resolves 'duplicate' and
-     *  stores nothing of this write: no memory, no record, no audit row. A duplicate is a resolved value, never a rejection; every other refusal is writeEntry's own and is decided first, so a refused entry rejects under a logged key too. */
+    /** entryWrites.writeEntry plus, in its transaction: with `quarantine`, one pending record and quarantine row; with `event`, one log row. All commit or none.
+     * A key logged before resolves 'duplicate' and stores nothing (never a rejection); every other refusal is writeEntry's own, decided first. */
     writeConnectorEntry(write: ConnectorWrite): Promise<ConnectorWriteOutcome>;
-    /** entryWrites.archiveRaw and, in its transaction, one log row for `event` naming the archived id, so a redelivery finds the event logged; a log write that fails undoes the archive.
-     *  A key logged before keeps its row and does not stop the archive. Reach and every rejection are archiveRaw's own. */
+    /** entryWrites.archiveRaw plus, in its transaction, one log row for `event` naming the archived id, so a redelivery finds it logged; a failed log write
+     * undoes the archive. A key logged before keeps its row and does not stop the archive. Reach and every rejection are archiveRaw's own. */
     archiveConnectorEntry(archive: ConnectorArchive): Promise<string>;
 }
 /** What the event log holds for one event's key; `memoryId` is null for an event logged with no memory. */
@@ -542,17 +543,19 @@ export type ConnectorDeadLetter = ({
     readonly connector: 'slack';
 } & SlackDlqInsert) | ({
     readonly connector: 'github';
-} & GithubDlqWrite);
-/** What a connector delivery reads and writes beside connectorWrites: the event log, tenant routing, the dead-letter queue and the archive of a deleted artifact. */
+} & GitHubDlqInsert);
+/** What a connector delivery reads and writes beside connectorWrites: the event log,
+ * tenant routing, the dead-letter queue and the archive of a deleted artifact. */
 export interface ConnectorEvents {
     /** The log row of the event's key, in its connector's own key space. */
     eventRecord(event: ConnectorEvent): Promise<ConnectorEventRecord>;
     /** Logs an event that stored no memory, so its redelivery finds it. A key logged before keeps its row, the memory id it names included. */
     markEventSeen(event: ConnectorEvent): Promise<void>;
-    /** Both reads on one snapshot: an event logged before answers `seen`, else the raw row the tenant holds for the artifact. Another tenant's row under the same ref is never returned. */
+    /** Both reads on one snapshot: an event logged before answers `seen`, else the raw row the
+     * tenant holds for the artifact. Another tenant's row under the same ref is never returned. */
     deletionTarget(lookup: DeletionLookup): Promise<DeletionTarget>;
-    /** An event logged before answers `duplicate` and changes nothing. Else, in one transaction, every raw row the tenant holds for the artifact is archived with one archive_raw row
-     *  ({reason}) under `actor`, and the event is logged naming the first of them, or no memory when there was none. One failed archive undoes them all and the log row. No reach check. */
+    /** A logged event answers `duplicate` and changes nothing. Else one transaction archives every raw row of the artifact (archive_raw row each, under `actor`)
+     * and logs the event naming the first, or no memory if none; one failed archive undoes all and the log row. No reach check. */
     archiveDeletedArtifact(archive: ArtifactArchive): Promise<{
         readonly duplicate: boolean;
         readonly archived: number;
@@ -563,7 +566,7 @@ export interface ConnectorEvents {
     githubRouting(query: {
         readonly installationId?: string | null;
         readonly repoFullName?: string | null;
-    }): Promise<GithubRouting>;
+    }): Promise<GitHubRouting>;
     /** Appends the row and answers its id. */
     parkDeadLetter(letter: ConnectorDeadLetter): Promise<number>;
 }
@@ -601,7 +604,13 @@ 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 declare const STORE_BUSY_MESSAGE = "store busy (another hippo process holds the write lock); retry shortly";
+/** A store behind the port throws this when its lock wait runs out, so the server answers 503 as it does for a busy hippo.db. */
+export declare class StoreBusyError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+/** 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;

package/dist/store/port.js

@@ -14,4 +14,12 @@ export function requireGroup(store, group) {
         throw new StoreNotPortedError(store.kind, group);
     return methods;
 }
+export const STORE_BUSY_MESSAGE = 'store busy (another hippo process holds the write lock); retry shortly';
+/** A store behind the port throws this when its lock wait runs out, so the server answers 503 as it does for a busy hippo.db. */
+export class StoreBusyError extends Error {
+    constructor(message = STORE_BUSY_MESSAGE, options) {
+        super(message, options);
+        this.name = 'StoreBusyError';
+    }
+}
 //# sourceMappingURL=port.js.map

package/dist/store/predictions.d.ts

@@ -1,32 +1,10 @@
-/**
- * Prediction first-class object.
- *
- * Canonical store for ex-ante claims that can be closed against ex-post
- * outcomes. The `predictions` table holds every field (including
- * `claim_text`); a memory row mirrors the claim for recall/inspect surfaces
- * but is NOT the source of truth — ON DELETE SET NULL on memory_id means
- * memory deletion gracefully orphans the prediction without losing data.
- *
- * Tenant scoping: every helper requires tenantId. The schema's BEFORE INSERT
- * + BEFORE UPDATE triggers (`trg_predictions_tenant_match_*`) enforce that
- * `predictions.tenant_id` matches the referenced memory's tenant_id when
- * `memory_id IS NOT NULL`. Cross-tenant references are unrepresentable at
- * the schema level.
- *
- * Dual-write atomicity: `savePrediction` writes the memory + predictions
- * row inside `writeEntry`'s SAVEPOINT 'write_entry' (store/entry-writes.ts). The
- * afterWrite hook (store/entry-writes.ts) runs inside the same SAVEPOINT, so
- * a failure in either step rolls back both. Pattern matches supersede
- * (api.ts:1486) and the Slack/GitHub connectors.
- *
- * The planning-fallacy detector reads `loadPredictionsByClass` and computes
- * per-class base rates from (estimate_value, actual_value) at query time.
- */
+/** First-class prediction: an ex-ante claim closed against an outcome. The `predictions` table is the source of truth; the memory row only mirrors the claim.
+ * Every helper requires tenantId; `trg_predictions_tenant_match_*` triggers enforce the prediction's tenant matches the referenced memory's.
+ * `savePrediction` writes memory and prediction inside `writeEntry`'s SAVEPOINT (via afterWrite), so a failure in either rolls back both. */
 import { type MemoryEntry } from '../core/memory.js';
 import { type KeysetPosition } from '../util/keyset.js';
 import type { PredictionSave } from './port.js';
-export type ClosureState = 'open' | 'closed' | 'closed-unknown';
-export declare const VALID_CLOSURE_STATES: ReadonlySet<ClosureState>;
+import { type ClosureState } from '../core/prediction.js';
 export interface Prediction {
     id: number;
     /** Nullable: ON DELETE SET NULL allows memory deletion (forget /
@@ -62,27 +40,16 @@ export interface ListPredictionsOpts {
     /** Resume after this row: the position the previous page ended on. */
     after?: KeysetPosition;
 }
-/**
- * Create a new prediction. Writes a memory mirror + a predictions table
- * row atomically inside `writeEntry`'s SAVEPOINT 'write_entry'. On any
- * failure (audit write, predictions INSERT, trigger ABORT), the SAVEPOINT
- * rolls back — neither the memory row nor the predictions row lands.
- *
- * The memory is tagged `['prediction', classTag]` with `source='prediction'`
- * and `kind='distilled'`. It surfaces in `hippo recall` so the agent can
- * see open predictions naturally; the predictions table is the canonical
- * structured store used by the planning-fallacy detector.
- */
+/** Create a prediction: memory mirror and predictions row land atomically inside `writeEntry`'s SAVEPOINT; any failure rolls back both.
+ * The memory (tags `['prediction', classTag]`, kind 'distilled') surfaces in `hippo recall`; the predictions table feeds the planning-fallacy detector. */
 export declare function savePrediction(hippoRoot: string, tenantId: string, opts: SavePredictionOpts, actor?: string): Prediction;
 /** The memory row that mirrors a claim into recall, built here alone so every store keeps the same row for it. */
 export declare function predictionMirror(tenantId: string, claim: SavePredictionOpts, baseHalfLifeDays: number): MemoryEntry;
-/** The store port's save on hippo.db: the mirror goes in as the port's writeEntry has it, tenant check included, and its predictions row shares that write scope, so neither lands alone. */
+/** The store port's save on hippo.db: the mirror goes in as the port's writeEntry has it, tenant
+ * check included, and its predictions row shares that write scope, so neither lands alone. */
 export declare function writePrediction(hippoRoot: string, tenantId: string, save: PredictionSave, actor: string): Prediction;
-/**
- * Close an existing open prediction. Updates the predictions row only;
- * the memory mirror is NOT mutated in v1 (predictions table is canonical).
- * Accuracy is computed from (estimateValue, actualValue) at query time.
- */
+/** Close an open prediction. Updates the predictions row only; the memory mirror is not mutated (the predictions table is the source of truth).
+ * Accuracy is computed from (estimateValue, actualValue) at query time. */
 export declare function closePrediction(hippoRoot: string, tenantId: string, id: number, opts: ClosePredictionOpts, actor?: string): Prediction;
 export declare function loadPredictionById(hippoRoot: string, tenantId: string, id: number): Prediction | null;
 export declare function loadPredictionsByClass(hippoRoot: string, tenantId: string, classTag: string, opts?: ListPredictionsOpts): Prediction[];
@@ -117,16 +84,8 @@ export interface BaserateRow {
     estimate_value: number;
     actual_value: number;
 }
-/**
- * Compute base-rate stats for closed predictions in a class for the
- * planning-fallacy detector: Lovallo-Kahneman (2003) inside-vs-outside view.
- *
- * Filter: closure_state='closed' AND estimate_value IS NOT NULL AND
- * actual_value IS NOT NULL. Excludes closed-unknown (no actual to
- * compare against) and open (not yet resolved).
- *
- * Audit-emit is built in here, not at the 3 call sites, so callers cannot drift.
- */
+/** Base-rate stats for closed predictions in a class (Lovallo-Kahneman inside-vs-outside view): closure_state='closed' with estimate and actual non-null;
+ * closed-unknown and open are excluded. Audit-emit is built in here, not at the 3 call sites, so callers cannot drift. */
 export declare function computePredictionBaserate(hippoRoot: string, tenantId: string, classTag: string, actor?: string, 
 /** False skips the predict_baserate audit so that channel only records deliberate
  *  baserate calls, not every recall the planning-fallacy orchestrator inspects. */