hippo-memory 2.0.0 → 2.1.0

package/dist/store/port/consolidation.d.ts

@@ -0,0 +1,129 @@
+import type { MemoryEntry } from '../../core/memory.js';
+import type { PhysicsParticle } from '../../core/physics.js';
+import type { WriteBudget } from '../../util/write-budget.js';
+import type { AppendAuditOpts, AuditOp } from '../audit.js';
+import type { DetectedConflict } from '../conflicts.js';
+import type { FlushComponent, LoadedRows } from '../delete-and-batch.js';
+import type { EntriesWithBase } from '../entry-reads.js';
+import type { HalfLifeMove, HalfLifeRows } from '../half-life.js';
+import type { SessionDecayContext } from '../index-and-stats.js';
+import type { SessionEvent } from '../rows.js';
+import type { RebuildPatch } from '../summaries.js';
+import type { TombstoneChecks } from '../tombstone-checks.js';
+/** What sleep reads and writes on hippo.db, every tenant at once. */
+export interface Consolidation {
+    /** Every memory of every tenant, with a by-id lookup of each as loaded for the flush to compare against. */
+    entriesWithBase(): EntriesWithBase;
+    /** The ids of every memory a typed object row names; sleep never retires one. */
+    objectBackedIds(): Set<string>;
+    /** The full-text index counts when they drift from `memories` (re-synced when `repair`), else null. */
+    ftsDrift(repair: boolean): {
+        memories: number;
+        fts: number;
+    } | null;
+    /** The sleep count and the average interval between recent sleeps. */
+    sessionDecayContext(): SessionDecayContext;
+    /** Tombstone lookups and refusal audit rows on one lazily opened handle; nothing opens under dryRun. */
+    tombstoneChecks(dryRun: boolean): TombstoneChecks;
+    /** The default half-life base the memories are on. */
+    halfLifeBase(): number;
+    /** Plans from one read of the rows, then writes the moves `plan` returns once (nothing under dryRun). */
+    moveHalfLives<R>(to: number, opts: {
+        dryRun: boolean;
+        actor: string;
+    }, plan: (rows: HalfLifeRows) => {
+        moves: readonly HalfLifeMove[];
+        outcome: R;
+    }): {
+        from: number;
+        outcome: R | null;
+    };
+    /** The tenant's sessions completed since `sinceMs`. */
+    promotableSessions(tenantId: string, sinceMs: number): Array<{
+        session_id: string;
+    }>;
+    /** True when the tenant already holds a trace for the session. */
+    traceExists(tenantId: string, sessionId: string): boolean;
+    /** The tenant's session events, filtered as `listSessionEvents` filters them. */
+    sessionEvents(tenantId: string, opts: {
+        session_id?: string;
+        limit?: number;
+    }): SessionEvent[];
+    /** Every stored physics particle, in load order. */
+    storedParticles(): PhysicsParticle[];
+    /** Writes the particles over their stored state, as one batch. */
+    saveParticles(particles: PhysicsParticle[]): void;
+    /** Commits each component whole, in chunks the budget paces, under sleep's own lock wait; resolves to the ids it
+     * removed. */
+    commitFlush(components: readonly FlushComponent[], opts: {
+        snapshot: LoadedRows;
+        budget: WriteBudget;
+    }): Promise<string[]>;
+    /** Counts (dryRun) or deletes the dormant memories moved before `cutoffIso`, under sleep's own lock wait. */
+    expireDormant(cutoffIso: string, opts: {
+        dryRun: boolean;
+        budget: WriteBudget;
+    }): Promise<number>;
+    /** Replaces the detected conflicts with these. */
+    replaceConflicts(detected: DetectedConflict[], detectedAt: string): void;
+    /** Appends one consolidation-run row. */
+    recordRun(run: {
+        timestamp: string;
+        decayed: number;
+        merged: number;
+        removed: number;
+    }): void;
+    /** Adds one to the store's sleep count. */
+    countSleep(): void;
+    /** Appends each row as its own write; a failed row is logged and counted, and the failures returned as a count. */
+    auditEachRow(events: readonly AppendAuditOpts[]): number;
+    /** Logs and counts an audit row that could not be written, for a caller whose own write threw. */
+    reportAuditFailure(op: AuditOp, reason: string): void;
+    /** Every memory of every tenant, as it stands now. */
+    allEntries(): MemoryEntry[];
+    /** The current distilled memories: no raw row and no superseded one. */
+    currentDistilledEntries(): MemoryEntry[];
+    /** Deletes each target in its own transaction; true where the row went. */
+    deleteOneByOne(targets: readonly {
+        id: string;
+        reason: string;
+    }[], opts: {
+        actor?: string;
+        automatic?: boolean;
+    }): boolean[];
+    /** The ids of the unit a flush stopped before, if `err` is that stop. */
+    failedUnitOf(err: Error | null): string[] | undefined;
+    /** Tenants with pending graph work, each with its highest pending queue id. */
+    dirtyGraphTenants(): {
+        tenantId: string;
+        maxPendingId: number;
+    }[];
+    /** Marks the tenant's pending graph work up to `maxId` processed; returns how many rows it marked. */
+    markGraphDrained(tenantId: string, maxId: number): number;
+    /** Writes one memory through the rejection guard, which throws RejectedValueError on a tombstoned value. */
+    writeEntry(entry: MemoryEntry): void;
+    /** Writes the memories in one transaction; returns how many it wrote. */
+    writeTogether(entries: readonly MemoryEntry[]): number;
+    /** Up to `limit` summaries marked dirty. */
+    dirtySummaries(limit: number): MemoryEntry[];
+    /** The current children of one summary. */
+    childrenOfSummary(summaryId: string, tenantId: string): MemoryEntry[];
+    /** One read of the children of every summary given, looked up per summary. */
+    childrenOfSummaries(summaries: ReadonlyArray<{
+        id: string;
+        tenant_id: string;
+    }>): (summary: {
+        id: string;
+        tenant_id: string;
+    }) => MemoryEntry[];
+    /** Applies a rebuilt summary while it is still dirty; `refused` when its new content is tombstoned. */
+    applyRebuild(summary: MemoryEntry, patch: RebuildPatch): {
+        changed: boolean;
+        refused: boolean;
+    };
+    /** Clears the dirty mark a fresh summary got from its own child links. */
+    clearSummaryDirty(summaryId: string, tenantId: string, actor: string, source?: string): void;
+    /** The L2 topic summaries with no L3 profile above them. */
+    unprofiledTopicSummaries(): MemoryEntry[];
+}
+//# sourceMappingURL=consolidation.d.ts.map

package/dist/store/port/consolidation.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=consolidation.js.map

package/dist/store/port/learning.d.ts

@@ -0,0 +1,19 @@
+import type { MemoryEntry } from '../../core/memory.js';
+/** What auto-learn, extraction and invalidation read and write on hippo.db. */
+export interface Learning {
+    /** Every memory of `tenantId`, or of every tenant when it is undefined. */
+    allEntries(tenantId?: string): MemoryEntry[];
+    /** The memories whose content shares a token with `tokens`, plus those carrying exactly `tag`. */
+    entriesMentioning(tokens: readonly string[], tag: string, tenantId?: string): MemoryEntry[];
+    readEntry(id: string, tenantId?: string): MemoryEntry | null;
+    /** Rows of `tenantId` that are current and whose origin project is one of `origins`. */
+    currentEntriesFromOrigins(tenantId: string, origins: readonly string[]): MemoryEntry[];
+    /** Writes one memory; throws RejectedValueError when its value was rejected. */
+    writeEntry(entry: MemoryEntry): void;
+    /** Writes the rows in one transaction and returns how many. */
+    writeEntriesTogether(entries: readonly MemoryEntry[]): number;
+    addTagToEntries(tenantId: string, ids: readonly string[], tag: string): void;
+    /** When each memory was last confirmed by a good outcome, by id. */
+    confirmedOutcomeTimes(tenantId: string): Map<string, string>;
+}
+//# sourceMappingURL=learning.d.ts.map

package/dist/store/port/learning.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=learning.js.map

package/dist/store/port/local-files.d.ts

@@ -0,0 +1,18 @@
+import type { AgentImport } from './agent-import.js';
+import type { Consolidation } from './consolidation.js';
+import type { Learning } from './learning.js';
+import type { Promotion } from './promotion.js';
+export type { AgentImport, ContainerTx, ImportTarget } from './agent-import.js';
+export type { Consolidation } from './consolidation.js';
+export type { Learning } from './learning.js';
+export type { Promotion } from './promotion.js';
+/** The store is hippo.db and its files under `hippoRoot`, so a path that reopens them by folder (sleep, its child
+ * process, the global store) may run. */
+export interface LocalFiles {
+    readonly hippoRoot: string;
+    readonly consolidation: Consolidation;
+    readonly agentImport: AgentImport;
+    readonly promotion: Promotion;
+    readonly learning: Learning;
+}
+//# sourceMappingURL=local-files.d.ts.map

package/dist/store/port/local-files.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=local-files.js.map

package/dist/store/port/promotion.d.ts

@@ -0,0 +1,20 @@
+import type { MemoryEntry } from '../../core/memory.js';
+export interface PromoteOptions {
+    actor?: string;
+    tenantId?: string;
+    /** Also writes one `promote` audit row for the copy ({sourceId}), in the copy's own transaction. */
+    auditAs?: {
+        tenantId: string;
+        actor: string;
+    };
+}
+export interface Promotion {
+    /** The tenant and scope of the local memory, or undefined when no row has the id. */
+    reach(id: string): {
+        tenantId: string;
+        scope: string | null;
+    } | undefined;
+    /** Copies the local memory into the global store as a new `g_` row; the caller embeds the copy. */
+    copyToGlobal(id: string, opts: PromoteOptions): MemoryEntry;
+}
+//# sourceMappingURL=promotion.d.ts.map

package/dist/store/port/promotion.js

@@ -0,0 +1,3 @@
+// The local-to-global copy behind `promote`, sync like the rest of LocalFiles so its audit row commits with the copy.
+export {};
+//# sourceMappingURL=promotion.js.map

package/dist/store/port-groups.d.ts

@@ -0,0 +1,160 @@
+import type { Card, CardComment, CardRun, CardStatus } from '../core/card.js';
+import type { HandoffOutcome, SessionHandoff } from '../core/handoff.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { CardDetail } from './card-detail.js';
+import type { StrengthTallies } from './candidates.js';
+import type { ResolveConflictOpts, ResolveConflictRequest } from './conflicts.js';
+import type { DormantMemory, DormantRestoreOutcome, DormantSnapshot, ListDormantOpts } from './dormant.js';
+import type { EntryCursor, EntryPage } from './entry-reads.js';
+import type { FailureSummary } from './failure-log.js';
+import type { CompleteGoalOpts, Goal, PushGoalOpts } from './goals.js';
+import type { HandoffFilter, SessionEndHandoffRequest } from './handoffs.js';
+import type { MemoryConflict, SessionEvent, TaskSnapshot } from './rows.js';
+import type { ContinuityKey, SessionEventInput, SnapshotInput } from './sessions.js';
+import type { TokenSummary } from './token-ledger.js';
+import type { JsonObject, WorkingMemoryItem } from './working-memory.js';
+export interface WorkingMemoryFilter {
+    readonly scope?: string;
+    readonly sessionId?: string;
+}
+export interface WorkingMemoryPush {
+    readonly scope: string;
+    readonly content: string;
+    readonly importance?: number;
+    readonly sessionId?: string;
+    readonly taskId?: string;
+    readonly metadata?: JsonObject;
+}
+/** Snapshots, session events, handoffs, working memory and session-owner binding. Every keyed method takes
+ * `key: ContinuityKey | null`, since a group cannot gain members once it ships. */
+export interface Sessions {
+    saveSnapshot(tenantId: string, snapshot: SnapshotInput, key: ContinuityKey | null): Promise<TaskSnapshot>;
+    loadSnapshot(tenantId: string, key: ContinuityKey | null): Promise<TaskSnapshot | null>;
+    loadFreshSnapshot(tenantId: string, opts: {
+        readonly maxAgeMs?: number;
+        readonly sessionId?: string | null;
+    }, key: ContinuityKey | null): Promise<TaskSnapshot | null>;
+    /** True when an active snapshot was cleared. */
+    clearSnapshot(tenantId: string, clearedStatus: string): Promise<boolean>;
+    /** Rows closed. */
+    closeSessionSnapshots(tenantId: string, sessionId: string, status: string, key: ContinuityKey | null): Promise<number>;
+    appendEvent(tenantId: string, event: SessionEventInput): Promise<SessionEvent>;
+    listEvents(tenantId: string, opts: {
+        readonly sessionId?: string;
+        readonly task?: string;
+        readonly limit?: number;
+    }): Promise<SessionEvent[]>;
+    saveHandoff(tenantId: string, handoff: Omit<SessionHandoff, 'updatedAt'>, key: ContinuityKey | null): Promise<SessionHandoff>;
+    latestHandoff(tenantId: string, sessionId: string | null, filter: HandoffFilter, key: ContinuityKey | null): Promise<SessionHandoff | null>;
+    handoffById(tenantId: string, id: number): Promise<SessionHandoff | null>;
+    /** Rows stamped. */
+    stampHandoffOutcome(tenantId: string, sessionId: string, outcome: HandoffOutcome): Promise<number>;
+    writeSessionEndHandoff(tenantId: string, request: Omit<SessionEndHandoffRequest, 'tenantId'>): Promise<SessionHandoff | null>;
+    pushWorkingMemory(tenantId: string, item: WorkingMemoryPush): Promise<number>;
+    readWorkingMemory(tenantId: string, filter: WorkingMemoryFilter & {
+        readonly limit?: number;
+    }): Promise<WorkingMemoryItem[]>;
+    /** Rows cleared; a session-end flush is the same call. */
+    clearWorkingMemory(tenantId: string, filter: WorkingMemoryFilter): Promise<number>;
+    /** The stored owner, which is not `owner` when a concurrent first bind won. */
+    bindSessionOwner(tenantId: string, sessionId: string, owner: string, retentionMs: number): Promise<string | null>;
+}
+export interface CardCreate {
+    readonly title: string;
+    readonly repo?: string;
+    readonly contract?: string;
+    readonly budget?: number;
+    readonly dependsOn?: readonly string[];
+}
+export interface Cards {
+    create(tenantId: string, input: CardCreate): Promise<Card>;
+    load(tenantId: string, id: string): Promise<Card | null>;
+    /** The card with its runs and comments, read together. */
+    detail(tenantId: string, id: string): Promise<CardDetail | null>;
+    list(tenantId: string, opts: {
+        readonly status?: CardStatus;
+    }): Promise<Card[]>;
+    runs(tenantId: string, id: string): Promise<CardRun[]>;
+    claim(tenantId: string, id: string, runtime: string, sessionId?: string): Promise<(Card & {
+        runId: number;
+    }) | null>;
+    heartbeat(tenantId: string, id: string, runId: number): Promise<Card | null>;
+    block(tenantId: string, id: string, reason: string, runId?: number): Promise<Card | null>;
+    review(tenantId: string, id: string, runId?: number): Promise<Card | null>;
+    complete(tenantId: string, id: string, outcome: HandoffOutcome, runId?: number): Promise<{
+        card: Card;
+        promotedChildren: string[];
+    } | null>;
+    /** Ids reclaimed. */
+    reclaimExpired(tenantId: string): Promise<string[]>;
+    comment(tenantId: string, cardId: string, author: string, body: string): Promise<CardComment>;
+}
+export interface Goals {
+    push(tenantId: string, goal: Omit<PushGoalOpts, 'tenantId'>): Promise<Goal>;
+    /** Every status, for `hippo goal list --all`; active-only reads use base `activeGoals`. */
+    sessionGoals(tenantId: string, sessionId: string): Promise<Goal[]>;
+    /** By id. Goal ids are not tenant-scoped in hippo.db, so the SQLite store ignores `tenantId` and the api keeps the
+     * host-admin check; a tenant-keyed store filters on it. */
+    complete(tenantId: string, goalId: string, opts: CompleteGoalOpts): Promise<void>;
+    suspend(tenantId: string, goalId: string): Promise<void>;
+    resume(tenantId: string, goalId: string): Promise<void>;
+}
+export interface Conflicts {
+    /** `tenantId` null reads every tenant (host admin; the api checks). */
+    list(tenantId: string | null, status: string): Promise<MemoryConflict[]>;
+    /** Conflicts whose both rows the actor may touch; status '*' reads every status. */
+    listTouchable(tenantId: string, status: string, actor: {
+        readonly owner?: string;
+    }): Promise<MemoryConflict[]>;
+    resolve(tenantId: string, request: Omit<ResolveConflictRequest, 'tenantId'>, opts: ResolveConflictOpts): Promise<{
+        conflict: MemoryConflict;
+        loserId: string;
+    } | null>;
+}
+export interface DormantRestoreRequest {
+    readonly id: string;
+    readonly actor: string;
+    readonly inReach: (scope: string | null) => boolean;
+    readonly revive: (snapshot: DormantSnapshot, now: Date) => MemoryEntry;
+}
+/** `ownScope` is the caller's personal scope; the store builds its own scope test, so no SQL crosses the port. */
+export interface Dormant {
+    list(tenantId: string, ownScope: string | null, opts: ListDormantOpts): Promise<DormantMemory[]>;
+    holds(tenantId: string, ownScope: string | null, id: string): Promise<boolean>;
+    /** `revive` runs inside the store's write, so a throw refuses before any row changes. */
+    restore(tenantId: string, request: DormantRestoreRequest): Promise<DormantRestoreOutcome>;
+    /** Deletes for good, writes the `forget` audit row and counts it; false when no row in reach. */
+    forget(tenantId: string, ownScope: string | null, id: string, actor: string): Promise<boolean>;
+}
+/** Read-only reports for `hippo status`, `hippo tokens`, `hippo failures` and the listing verbs. */
+export interface Reports {
+    tokenUse(tenantId: string, sinceIso: string): Promise<TokenSummary>;
+    failures(tenantId: string, sinceIso: string): Promise<FailureSummary>;
+    /** Strength tallies and the open-conflict count, read on one snapshot. */
+    memoryStatus(tenantId: string, now: Date, atRiskBelow: number): Promise<StrengthTallies & {
+        openConflicts: number;
+    }>;
+    /** `tenantId` null pages every tenant (host admin; the api checks). */
+    entriesPage(tenantId: string | null, page: {
+        readonly limit: number;
+        readonly after?: EntryCursor;
+    }): Promise<EntryPage>;
+    /** Every row in the store, no tenant: host admin. */
+    countEntries(): Promise<number>;
+}
+/** The groups StoreGroups gains beyond port.ts, each set whole or left unset. */
+export interface SessionAndAdminGroups {
+    /** Unset on a store without it; the continuity, session-end and working-memory paths then answer 501. */
+    readonly sessions: Sessions;
+    /** Unset on a store without it, where the card verbs answer 501. */
+    readonly cards: Cards;
+    /** Unset on a store without it, where the goal verbs answer 501. */
+    readonly goals: Goals;
+    /** Unset on a store without it, where conflict listing and resolving answer 501. */
+    readonly conflicts: Conflicts;
+    /** Unset on a store without it, where the dormant verbs answer 501. */
+    readonly dormant: Dormant;
+    /** Unset on a store without it, where status, tokens, failures and the memory listings answer 501. */
+    readonly reports: Reports;
+}
+//# sourceMappingURL=port-groups.d.ts.map

package/dist/store/port-groups.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=port-groups.js.map