@psiclawops/hypermem 0.8.5 → 0.9.1

package/dist/message-store.d.ts

@@ -1,181 +0,0 @@
-/**
- * hypermem Message Store
- *
- * CRUD operations for conversations and messages in SQLite.
- * All messages are stored in provider-neutral format.
- * This is the write-through layer: Redis → here.
- */
-import type { DatabaseSync } from 'node:sqlite';
-import type { NeutralMessage, StoredMessage, Conversation, ChannelType, ConversationStatus, RecentTurn, ArchivedMiningQuery, ArchivedMiningResult, MultiContextMiningOptions } from './types.js';
-export declare class MessageStore {
-    private readonly db;
-    constructor(db: DatabaseSync);
-    /**
-     * Get or create a conversation for a session.
-     */
-    getOrCreateConversation(agentId: string, sessionKey: string, opts?: {
-        channelType?: ChannelType;
-        channelId?: string;
-        provider?: string;
-        model?: string;
-    }): Conversation;
-    /**
-     * Get a conversation by session key.
-     */
-    getConversation(sessionKey: string): Conversation | null;
-    /**
-     * Get all conversations for an agent, optionally filtered.
-     */
-    getConversations(agentId: string, opts?: {
-        status?: ConversationStatus;
-        channelType?: ChannelType;
-        limit?: number;
-    }): Conversation[];
-    /**
-     * Update conversation metadata.
-     */
-    updateConversation(conversationId: number, updates: {
-        provider?: string;
-        model?: string;
-        status?: ConversationStatus;
-        endedAt?: string;
-    }): void;
-    /**
-     * Record a message to the database.
-     * Returns the stored message with its assigned ID.
-     *
-     * Phase 2 (Turn DAG): automatically sets parent_id and depth.
-     *   - parent_id = context.head_message_id (the previous message on this branch)
-     *   - depth = parent.depth + 1 (or 0 if first message)
-     */
-    recordMessage(conversationId: number, agentId: string, message: NeutralMessage, opts?: {
-        tokenCount?: number;
-        isHeartbeat?: boolean;
-        contextId?: number;
-    }): StoredMessage;
-    /**
-     * Get recent messages for a conversation.
-     */
-    getRecentMessages(conversationId: number, limit?: number, minMessageId?: number): StoredMessage[];
-    /**
-     * Get recent messages scoped to a topic (P3.4, Option B).
-     * Returns messages matching the topic_id OR with topic_id IS NULL
-     * (legacy messages created before topic tracking was introduced).
-     * This is transition-safe: no legacy messages are silently dropped.
-     */
-    getRecentMessagesByTopic(conversationId: number, topicId: string, limit?: number, minMessageId?: number): StoredMessage[];
-    /**
-     * Get messages across all conversations for an agent (cross-session query).
-     */
-    getAgentMessages(agentId: string, opts?: {
-        since?: string;
-        limit?: number;
-        excludeHeartbeats?: boolean;
-    }): StoredMessage[];
-    /**
-     * Full-text search across all messages for an agent.
-     */
-    searchMessages(agentId: string, query: string, limit?: number): StoredMessage[];
-    /**
-     * Get recent turns for a session, in chronological order, with tool calls stripped.
-     * Joins messages through conversations to find by session_key.
-     * Returns up to `n` turns (capped at 50).
-     */
-    getRecentTurns(sessionKey: string, n: number): RecentTurn[];
-    /**
-     * Get messages by walking the parent_id chain from a head message backward.
-     * This is the DAG-native read path introduced in Phase 3.
-     *
-     * Walks from headMessageId backward through parent_id links, collecting
-     * up to `limit` messages in chronological order.
-     *
-     * Falls back to getRecentMessages if the head message has no parent chain
-     * (e.g., legacy data before backfill).
-     *
-     * @boundary SHARED DAG PRIMITIVE — not for direct call at mining call sites.
-     * @policy See specs/DAG_HELPER_POLICY.md for operator-boundary rules.
-     * Use mineArchivedContext / mineArchivedContexts for archived context mining,
-     * and the active-composition paths for live session history. Direct call sites
-     * outside this class should be limited to exceptional diagnostic use.
-     */
-    getHistoryByDAGWalk(headMessageId: number, limit?: number): StoredMessage[];
-    /**
-     * Get messages scoped to a specific context_id.
-     * Used by keystone/FTS/topic recall to constrain results to the active branch.
-     */
-    getMessagesByContextId(contextId: number, limit?: number, opts?: {
-        excludeHeartbeats?: boolean;
-        requireText?: boolean;
-    }): StoredMessage[];
-    /**
-     * Full-text search constrained to a specific context_id.
-     * Phase 3: replaces unscoped searchMessages for composition paths.
-     */
-    searchMessagesByContextId(contextId: number, query: string, limit?: number): StoredMessage[];
-    /**
-     * Get message count for a conversation.
-     */
-    getMessageCount(conversationId: number): number;
-    /**
-     * Get the full message chain for an archived or forked context.
-     *
-     * Throws if the context does not exist or is active (not archived/forked).
-     * Returns an empty array if the context has no head message.
-     * Delegates to getHistoryByDAGWalk for the actual chain retrieval.
-     */
-    getArchivedChain(contextId: number, limit?: number): StoredMessage[];
-    /**
-     * Default maximum number of contextIds accepted by mineArchivedContexts.
-     * Callers may supply a lower value but not a higher one.
-     */
-    static readonly ARCHIVED_MULTI_CONTEXT_DEFAULT_MAX = 20;
-    /**
-     * Hard ceiling for mineArchivedContexts.
-     * Values above this are clamped to this number regardless of caller intent.
-     * This prevents unbounded DB fan-out on misconfigured or adversarial inputs.
-     */
-    static readonly ARCHIVED_MULTI_CONTEXT_HARD_CEILING = 50;
-    /**
-     * Mine messages from a single archived or forked context.
-     *
-     * - Rejects active or missing contexts with a clear error.
-     * - Hard-caps limit at 200.
-     * - Defaults excludeHeartbeats to true.
-     * - Optionally filters by ftsQuery (client-side substring match for Sprint 3; SQL FTS is deferred).
-     * - Routes through getHistoryByDAGWalk for DAG-native retrieval.
-     * - Returns ArchivedMiningResult<StoredMessage[]> with isHistorical: true.
-     *
-     * This method does NOT widen active composition — it only operates on
-     * explicitly non-active (archived/forked) contexts.
-     */
-    mineArchivedContext(query: ArchivedMiningQuery): ArchivedMiningResult<StoredMessage[]>;
-    /**
-     * Mine messages from multiple archived or forked contexts.
-     *
-     * ## maxContexts gate (Phase 4 Sprint 3, Task 1)
-     * Accepts an optional `maxContexts` in opts to control how many contextIds
-     * are accepted in a single call:
-     * - Default: ARCHIVED_MULTI_CONTEXT_DEFAULT_MAX (20).
-     * - Hard ceiling: ARCHIVED_MULTI_CONTEXT_HARD_CEILING (50).
-     * - A caller-supplied value above the hard ceiling is clamped to the ceiling
-     *   (not rejected), so callers need not know the exact constant.
-     * - A caller-supplied value at or below the ceiling is used as-is.
-     * - If contextIds.length exceeds the effective max, this method THROWS
-     *   immediately — it does NOT soft-skip or truncate.
-     *
-     * ## Other behaviors (unchanged from Sprint 2)
-     * - Soft-skips active or missing contextIds with a warning (does not throw).
-     * - Preserves input order in the result array.
-     * - Applies per-context limit and same filters as mineArchivedContext.
-     * - Returns one ArchivedMiningResult per valid archived context.
-     *
-     * This method does NOT widen active composition — it only operates on
-     * explicitly non-active (archived/forked) contexts.
-     */
-    mineArchivedContexts(contextIds: number[], opts?: MultiContextMiningOptions): ArchivedMiningResult<StoredMessage[]>[];
-    /**
-     * Infer channel type from session key format.
-     */
-    private inferChannelType;
-}
-//# sourceMappingURL=message-store.d.ts.map

package/dist/message-store.d.ts.map

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