@atomicmemory/core 1.0.0

package/dist/db/stores.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Domain-facing store interfaces for Phase 5.
+ *
+ * Each interface exposes only the methods its domain consumers need.
+ * Implementations delegate to the existing split repository modules
+ * (repository-read.ts, repository-write.ts, repository-links.ts, etc.).
+ *
+ * For ClaimStore, EntityStore, and LessonStore, the existing repository
+ * classes already serve as implementations — these interfaces are extracted
+ * from their public surfaces.
+ */
+import type pg from 'pg';
+import type { EntityAttributesRepository } from './repository-entity-attributes.js';
+import type { EntityValuesRepository } from './entity-values-repository.js';
+import type { EntityCardsRepository } from './entity-cards-repository.js';
+import type { ContradictionsRepository } from './contradictions-repository.js';
+import type { BeliefEdgesRepository } from './belief-edges-repository.js';
+import type { AgentScope, AtomicFactRow, CanonicalMemoryObjectLineage, ForesightRow, MemoryRow, SearchResult, EpisodeRow, StoreMemoryInput } from './repository-types.js';
+import type { CandidateRow } from './repository-vector-search.js';
+/** A topic-similarity candidate row returned by findTopicCandidates. */
+export interface TopicCandidateRow extends CandidateRow {
+    topic_abstraction: string;
+}
+/** Recap-layer store (Sprint 3 v1). Cross-session synthesis. */
+export interface RecapStore {
+    findUnconsolidatedClusters(userId: string, minSize: number, pivot?: 'topic' | 'session'): Promise<{
+        topic: string;
+        member_ids: string[];
+        member_contents: string[];
+        time_range_start: Date | null;
+        time_range_end: Date | null;
+    }[]>;
+    storeRecap(input: {
+        userId: string;
+        recapText: string;
+        recapEmbedding: number[];
+        topic: string;
+        memberMemoryIds: string[];
+        timeRangeStart: Date | null;
+        timeRangeEnd: Date | null;
+    }): Promise<string>;
+    findRecapCandidates(userId: string, queryEmbedding: number[], limit: number): Promise<{
+        id: string;
+        user_id: string;
+        recap_text: string;
+        recap_embedding: number[];
+        topic: string;
+        member_count: number;
+        similarity: number;
+    }[]>;
+}
+import type { StoreAtomicFactInput, StoreForesightInput } from './repository-representations.js';
+import type { MemoryLink } from './repository-links.js';
+import type { SummariesRepository } from './summaries-repository.js';
+import type { ManagedBlobRefRow } from './raw-document-blob-repository.js';
+export type { StoreMemoryInput };
+export interface MemoryStore {
+    storeMemory(input: StoreMemoryInput): Promise<string>;
+    getMemory(id: string, userId?: string): Promise<MemoryRow | null>;
+    getMemoryIncludingDeleted(id: string, userId?: string): Promise<MemoryRow | null>;
+    listMemories(userId: string, limit?: number, offset?: number, sourceSite?: string, episodeId?: string): Promise<MemoryRow[]>;
+    softDeleteMemory(userId: string, id: string): Promise<void>;
+    updateMemoryContent(userId: string, id: string, content: string, embedding: number[], importance: number, keywords?: string, trustScore?: number): Promise<void>;
+    updateMemoryMetadata(userId: string, id: string, metadata: Record<string, unknown>): Promise<void>;
+    expireMemory(userId: string, id: string): Promise<void>;
+    touchMemory(id: string): Promise<void>;
+    countMemories(userId?: string): Promise<number>;
+    getMemoryStats(userId: string): Promise<{
+        count: number;
+        avgImportance: number;
+        sourceDistribution: Record<string, number>;
+    }>;
+    deleteBySource(userId: string, sourceSite: string): Promise<{
+        deletedMemories: number;
+        deletedEpisodes: number;
+        deletedDocuments: number;
+        /** Managed-blob refs the caller hands to `cleanupManagedBlobs()`
+         * after the DB tx commits. Each ref carries `rawDocumentId` so
+         * the cleanup loop can sync the paired artifact by id. */
+        blobs: ManagedBlobRefRow[];
+    }>;
+    deleteAll(userId?: string): Promise<void>;
+    backdateMemories(ids: string[], timestamp: Date): Promise<void>;
+    updateOpinionConfidence(userId: string, memoryId: string, newConfidence: number): Promise<void>;
+    countNeedsClarification(userId: string): Promise<number>;
+    storeCanonicalMemoryObject(input: {
+        userId: string;
+        objectFamily: 'ingested_fact';
+        payloadFormat?: string;
+        canonicalPayload: {
+            factText: string;
+            factType: string;
+            headline: string;
+            keywords: string[];
+        };
+        provenance: {
+            episodeId: string | null;
+            sourceSite: string;
+            sourceUrl: string;
+        };
+        observedAt?: Date;
+        lineage: CanonicalMemoryObjectLineage;
+    }): Promise<string>;
+    getMemoryInWorkspace(id: string, workspaceId: string, callerAgentId?: string): Promise<MemoryRow | null>;
+    listMemoriesInWorkspace(workspaceId: string, limit?: number, offset?: number, callerAgentId?: string): Promise<MemoryRow[]>;
+    softDeleteMemoryInWorkspace(id: string, workspaceId: string): Promise<void>;
+}
+export interface EpisodeStore {
+    storeEpisode(input: {
+        userId: string;
+        content: string;
+        sourceSite: string;
+        sourceUrl?: string;
+        sessionId?: string;
+        workspaceId?: string;
+        agentId?: string;
+    }): Promise<string>;
+    getEpisode(id: string): Promise<EpisodeRow | null>;
+}
+export interface SearchStore {
+    searchSimilar(userId: string, queryEmbedding: number[], limit: number, sourceSite?: string, referenceTime?: Date): Promise<SearchResult[]>;
+    searchHybrid(userId: string, queryText: string, queryEmbedding: number[], limit: number, sourceSite?: string, referenceTime?: Date): Promise<SearchResult[]>;
+    searchKeyword(userId: string, queryText: string, limit: number, sourceSite?: string): Promise<SearchResult[]>;
+    searchAtomicFactsHybrid(userId: string, queryText: string, queryEmbedding: number[], limit: number, sourceSite?: string, referenceTime?: Date): Promise<SearchResult[]>;
+    findNearDuplicates(userId: string, embedding: number[], threshold: number, limit?: number): Promise<CandidateRow[]>;
+    findKeywordCandidates(userId: string, keywords: string[], limit?: number, includeExpired?: boolean): Promise<CandidateRow[]>;
+    findTopicCandidates(userId: string, queryEmbedding: number[], limit: number): Promise<TopicCandidateRow[]>;
+    findTemporalNeighbors(userId: string, anchorTimestamps: Date[], queryEmbedding: number[], windowMinutes: number, excludeIds: Set<string>, limit: number, referenceTime?: Date): Promise<SearchResult[]>;
+    fetchMemoriesByIds(userId: string, ids: string[], queryEmbedding: number[], referenceTime?: Date, includeExpired?: boolean): Promise<SearchResult[]>;
+    searchSimilarInWorkspace(workspaceId: string, queryEmbedding: number[], limit: number, agentScope?: AgentScope, callerAgentId?: string, referenceTime?: Date): Promise<SearchResult[]>;
+    findNearDuplicatesInWorkspace(workspaceId: string, embedding: number[], threshold: number, limit?: number, agentScope?: AgentScope, callerAgentId?: string): Promise<CandidateRow[]>;
+}
+export interface SemanticLinkStore {
+    createLinks(links: MemoryLink[]): Promise<number>;
+    findLinkCandidates(userId: string, embedding: number[], threshold: number, excludeId: string, limit?: number): Promise<Array<{
+        id: string;
+        similarity: number;
+    }>>;
+    findLinkedMemoryIds(memoryIds: string[], excludeIds: Set<string>, limit: number): Promise<string[]>;
+    countLinks(): Promise<number>;
+}
+export interface RepresentationStore {
+    storeAtomicFacts(facts: StoreAtomicFactInput[]): Promise<string[]>;
+    storeForesight(entries: StoreForesightInput[]): Promise<string[]>;
+    listAtomicFactsForMemory(userId: string, parentMemoryId: string): Promise<AtomicFactRow[]>;
+    listForesightForMemory(userId: string, parentMemoryId: string): Promise<ForesightRow[]>;
+    replaceAtomicFactsForMemory(userId: string, parentMemoryId: string, facts: StoreAtomicFactInput[]): Promise<string[]>;
+    replaceForesightForMemory(userId: string, parentMemoryId: string, entries: StoreForesightInput[]): Promise<string[]>;
+}
+export type ClaimStore = Pick<import('./repository-claims.js').ClaimRepository, 'addEvidence' | 'createClaim' | 'createClaimVersion' | 'createUpdateVersion' | 'findClaimByMemoryId' | 'getActiveClaimTargetBySlot' | 'getClaimVersionByMemoryId' | 'getRecentMutations' | 'getReversalChain' | 'getUserMutationSummary' | 'invalidateClaim' | 'listClaimsMissingSlots' | 'searchClaimVersions' | 'setClaimCurrentVersion' | 'supersedeClaimVersion' | 'updateClaimSlot' | 'deleteAll'>;
+export type EntityStore = Pick<import('./repository-entities.js').EntityRepository, 'resolveEntity' | 'linkMemoryToEntity' | 'getEntitiesForMemory' | 'getEntity' | 'searchEntities' | 'findEntitiesByName' | 'findMemoryIdsByEntities' | 'findRelatedEntityIds' | 'findDeterministicEntity' | 'getRelationsForMemory' | 'upsertRelation' | 'countEntities'>;
+export type LessonStore = Pick<import('./repository-lessons.js').LessonRepository, 'createLesson' | 'findSimilarLessons' | 'getLessonsByUser' | 'getLessonsByType' | 'deactivateLesson' | 'countActiveLessons' | 'deleteAll'>;
+export interface CoreStores {
+    memory: MemoryStore;
+    episode: EpisodeStore;
+    /** Recap layer (Sprint 3 v1). Optional/null disables Recap features. */
+    recap: RecapStore | null;
+    search: SearchStore;
+    link: SemanticLinkStore;
+    representation: RepresentationStore;
+    claim: ClaimStore;
+    entity: EntityStore | null;
+    /** Entity-attribute index (EAI). Null when entityAttributesEnabled is off. */
+    entityAttributes: EntityAttributesRepository | null;
+    lesson: LessonStore | null;
+    /**
+     * Hierarchical retrieval summaries (TBC sprint). Null when
+     * `hierarchicalRetrievalEnabled` is off — gates the 5th RRF arm
+     * in search-pipeline.
+     */
+    summaries: SummariesRepository | null;
+    /**
+     * User-profile store (Sprint 3 v1.5 — H2). Null when
+     * `userProfileChannelEnabled` is off.
+     */
+    userProfile: import('./repository-user-profiles.js').UserProfileRepository | null;
+    /**
+     * Reflection retrieval store (BEAM-0.85 Phase 1, Task 1.9). Null when
+     * `reflectEnabled` is off — the reflect-retrieval helper short-circuits
+     * on the disabled flag so callers always pass the store through.
+     */
+    reflections: import('./reflections-repository.js').ReflectionsRepository | null;
+    /**
+     * Reflection job queue (BEAM-0.85 Phase 1, Task 1.12). Null when
+     * `reflectEnabled` is off.
+     */
+    reflectionJobs: import('./reflection-jobs-repository.js').ReflectionJobsRepository | null;
+    /**
+     * Belief-edges repository for the CR bilateral-contradiction specialist
+     * (BEAM-0.85 Phase 2). Null when `tbcEnabled` is off — the CR specialist
+     * dispatcher short-circuits when the repo is absent.
+     */
+    beliefEdges: BeliefEdgesRepository | null;
+    /**
+     * Entity-values store for the IE/KU literal-value specialist (BEAM-0.85
+     * Phase 2). Null when `phase2SpecialistsEnabled` is off — the specialist
+     * dispatcher short-circuits when the repo is absent.
+     */
+    entityValues: EntityValuesRepository | null;
+    /**
+     * Entity-cards store for the always-on ENTITY_CARD channel (BEAM-0.85 —
+     * Honcho parity). Null when `entityCardEnabled` is off. When present, the
+     * search pipeline reads cards by (userId, conversationId) and injects
+     * them as `## ENTITY_STATE` at the top of every answer-LLM prompt.
+     */
+    entityCards: EntityCardsRepository | null;
+    /**
+     * Contradictions store for AUDN bilateral preservation (BEAM CR fix).
+     * Null when `contradictionPreservationEnabled` is off. When present,
+     * AUDN's DELETE/SUPERSEDE path keeps both memories and records the pair
+     * here instead of discarding the older side.
+     */
+    contradictions: ContradictionsRepository | null;
+    /**
+     * Raw pool access for call sites that still need it (PPR, deferred-audn
+     * reconciliation, link generation). Will be removed when those paths
+     * move behind dedicated store methods.
+     */
+    pool: pg.Pool;
+}

package/dist/db/stores.js

@@ -0,0 +1,12 @@
+/**
+ * Domain-facing store interfaces for Phase 5.
+ *
+ * Each interface exposes only the methods its domain consumers need.
+ * Implementations delegate to the existing split repository modules
+ * (repository-read.ts, repository-write.ts, repository-links.ts, etc.).
+ *
+ * For ClaimStore, EntityStore, and LessonStore, the existing repository
+ * classes already serve as implementations — these interfaces are extracted
+ * from their public surfaces.
+ */
+export {};

package/dist/db/summaries-repository.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Repository for hierarchical-retrieval session + conversation summaries.
+ * Schema lives in src/db/schema.sql under "Hierarchical Retrieval" section.
+ * Activated only when `HIERARCHICAL_RETRIEVAL_ENABLED=true`; see
+ * docs/hierarchical-retrieval.md.
+ *
+ * Reads use pgvector cosine distance (`embedding <=> $1`) returning
+ * `1 - distance` as similarity. The `pgvector` package converts JS
+ * arrays to the SQL vector literal at call time.
+ */
+import pg from 'pg';
+export interface AppendSessionSummaryInput {
+    userId: string;
+    sessionId: string;
+    conversationId: string;
+    sessionIndex: number;
+    summaryText: string;
+    summaryEmbedding: number[];
+    topics: string[];
+    factCount: number;
+    occurredStart?: Date | null;
+    occurredEnd?: Date | null;
+    workspaceId?: string | null;
+    agentId?: string | null;
+}
+export interface AppendConvSummaryInput {
+    userId: string;
+    conversationId: string;
+    summaryText: string;
+    summaryEmbedding: number[];
+    sessionCount: number;
+    factCount: number;
+    occurredStart?: Date | null;
+    occurredEnd?: Date | null;
+    workspaceId?: string | null;
+    agentId?: string | null;
+}
+export interface ConvSummaryHit {
+    id: string;
+    conversationId: string;
+    similarity: number;
+    summaryText: string;
+}
+export interface SessionSummaryHit {
+    id: string;
+    sessionId: string;
+    conversationId: string;
+    sessionIndex: number;
+    similarity: number;
+    summaryText: string;
+}
+export declare class SummariesRepository {
+    private readonly pool;
+    constructor(pool: pg.Pool);
+    /** Insert a session summary; returns the new row id. */
+    appendSessionSummary(input: AppendSessionSummaryInput): Promise<string>;
+    /** Insert a conversation summary; returns the new row id. */
+    appendConvSummary(input: AppendConvSummaryInput): Promise<string>;
+    /** Stage 1: top-K conversation summaries by query-embedding similarity. */
+    searchTopConvSummaries(userId: string, queryEmbedding: number[], topK: number): Promise<ConvSummaryHit[]>;
+    /**
+     * Stage 2: top-K session summaries by query-embedding similarity, filtered
+     * to a set of conversation IDs (typically the matches from stage 1).
+     */
+    searchTopSessionSummaries(userId: string, conversationIds: string[], queryEmbedding: number[], topK: number): Promise<SessionSummaryHit[]>;
+    /**
+     * Stage 3: expand from a set of session_ids to atomic-memory ids by
+     * joining through episodes. The 5th RRF arm hands these ids to the
+     * existing rank pipeline.
+     */
+    getMemoryIdsForSessions(userId: string, sessionIds: string[], limit: number): Promise<string[]>;
+    /** Test/dev helper. */
+    deleteAllForUser(userId: string): Promise<void>;
+}

package/dist/db/summaries-repository.js

@@ -0,0 +1,125 @@
+/**
+ * Repository for hierarchical-retrieval session + conversation summaries.
+ * Schema lives in src/db/schema.sql under "Hierarchical Retrieval" section.
+ * Activated only when `HIERARCHICAL_RETRIEVAL_ENABLED=true`; see
+ * docs/hierarchical-retrieval.md.
+ *
+ * Reads use pgvector cosine distance (`embedding <=> $1`) returning
+ * `1 - distance` as similarity. The `pgvector` package converts JS
+ * arrays to the SQL vector literal at call time.
+ */
+export class SummariesRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /** Insert a session summary; returns the new row id. */
+    async appendSessionSummary(input) {
+        const pgvector = await import('pgvector/pg');
+        const result = await this.pool.query(`INSERT INTO session_summaries
+        (user_id, session_id, conversation_id, session_index, summary_text,
+         summary_embedding, topics, fact_count, occurred_start, occurred_end,
+         workspace_id, agent_id)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+       RETURNING id`, [
+            input.userId,
+            input.sessionId,
+            input.conversationId,
+            input.sessionIndex,
+            input.summaryText,
+            pgvector.default.toSql(input.summaryEmbedding),
+            input.topics,
+            input.factCount,
+            input.occurredStart ?? null,
+            input.occurredEnd ?? null,
+            input.workspaceId ?? null,
+            input.agentId ?? null,
+        ]);
+        return result.rows[0]?.id ?? '';
+    }
+    /** Insert a conversation summary; returns the new row id. */
+    async appendConvSummary(input) {
+        const pgvector = await import('pgvector/pg');
+        const result = await this.pool.query(`INSERT INTO conv_summaries
+        (user_id, conversation_id, summary_text, summary_embedding,
+         session_count, fact_count, occurred_start, occurred_end,
+         workspace_id, agent_id)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+       RETURNING id`, [
+            input.userId,
+            input.conversationId,
+            input.summaryText,
+            pgvector.default.toSql(input.summaryEmbedding),
+            input.sessionCount,
+            input.factCount,
+            input.occurredStart ?? null,
+            input.occurredEnd ?? null,
+            input.workspaceId ?? null,
+            input.agentId ?? null,
+        ]);
+        return result.rows[0]?.id ?? '';
+    }
+    /** Stage 1: top-K conversation summaries by query-embedding similarity. */
+    async searchTopConvSummaries(userId, queryEmbedding, topK) {
+        const pgvector = await import('pgvector/pg');
+        const result = await this.pool.query(`SELECT id, conversation_id, summary_text,
+              1 - (summary_embedding <=> $1) AS similarity
+       FROM conv_summaries
+       WHERE user_id = $2
+       ORDER BY summary_embedding <=> $1
+       LIMIT $3`, [pgvector.default.toSql(queryEmbedding), userId, topK]);
+        return result.rows.map((row) => ({
+            id: row.id,
+            conversationId: row.conversation_id,
+            similarity: Number(row.similarity),
+            summaryText: row.summary_text,
+        }));
+    }
+    /**
+     * Stage 2: top-K session summaries by query-embedding similarity, filtered
+     * to a set of conversation IDs (typically the matches from stage 1).
+     */
+    async searchTopSessionSummaries(userId, conversationIds, queryEmbedding, topK) {
+        if (conversationIds.length === 0)
+            return [];
+        const pgvector = await import('pgvector/pg');
+        const result = await this.pool.query(`SELECT id, session_id, conversation_id, session_index, summary_text,
+              1 - (summary_embedding <=> $1) AS similarity
+       FROM session_summaries
+       WHERE user_id = $2 AND conversation_id = ANY($3::text[])
+       ORDER BY summary_embedding <=> $1
+       LIMIT $4`, [pgvector.default.toSql(queryEmbedding), userId, conversationIds, topK]);
+        return result.rows.map((row) => ({
+            id: row.id,
+            sessionId: row.session_id,
+            conversationId: row.conversation_id,
+            sessionIndex: row.session_index,
+            similarity: Number(row.similarity),
+            summaryText: row.summary_text,
+        }));
+    }
+    /**
+     * Stage 3: expand from a set of session_ids to atomic-memory ids by
+     * joining through episodes. The 5th RRF arm hands these ids to the
+     * existing rank pipeline.
+     */
+    async getMemoryIdsForSessions(userId, sessionIds, limit) {
+        if (sessionIds.length === 0)
+            return [];
+        const result = await this.pool.query(`SELECT m.id
+       FROM memories m
+       JOIN episodes e ON m.episode_id = e.id
+       WHERE m.user_id = $1
+         AND e.session_id = ANY($2::text[])
+         AND m.deleted_at IS NULL
+         AND m.expired_at IS NULL
+       ORDER BY m.created_at DESC
+       LIMIT $3`, [userId, sessionIds, limit]);
+        return result.rows.map((r) => r.id);
+    }
+    /** Test/dev helper. */
+    async deleteAllForUser(userId) {
+        await this.pool.query(`DELETE FROM session_summaries WHERE user_id = $1`, [userId]);
+        await this.pool.query(`DELETE FROM conv_summaries WHERE user_id = $1`, [userId]);
+    }
+}

package/dist/eval/beam-10m-loader.d.ts

@@ -0,0 +1,98 @@
+/**
+ * BEAM-10M dataset loader (T3.1 scaffold).
+ *
+ * Source: HuggingFace `Mohammadta/BEAM-10M` (200 questions / 10 conversations).
+ * The 10M tier averages ~1.4M tokens of conversation context per system —
+ * the highest-difficulty BEAM tier and the SOTA target for this sprint.
+ *
+ * This loader is a *stub*: it returns the typed shape for tests and the
+ * smoke design without invoking the HuggingFace API. Real loading lives
+ * in `atomicmemory-benchmarks/atomicbench/src/eval/` once the loader is
+ * promoted out of the worktree.
+ */
+/** A single ingest-time message in a session. */
+export interface Beam10MMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    /** ISO timestamp anchoring the turn for temporal queries. */
+    timestamp: string;
+}
+/** One session = one chunked conversation segment with shared time anchor. */
+export interface Beam10MSession {
+    /** Stable session id used as both ingest scope and summary key. */
+    sessionId: string;
+    /** 0-based position within the parent conversation. */
+    sessionIndex: number;
+    /** ISO date the session started (for temporal RRF arm). */
+    startedAt: string;
+    /** Ordered messages in this session. */
+    messages: Beam10MMessage[];
+}
+/** A BEAM probing question — same shape across all tiers. */
+export interface Beam10MQuestion {
+    /** Stable id (e.g. `c1-q3-KU`). */
+    id: string;
+    /** BEAM ability category; one of the 10 standard codes. */
+    ability: 'ABS' | 'CR' | 'EO' | 'IE' | 'IF' | 'KU' | 'MSR' | 'PF' | 'SUM' | 'TR';
+    /** Question text. */
+    question: string;
+    /** Ground-truth answer / rubric anchor — used by the judge. */
+    ideal: string;
+    /** Optional per-rubric criteria the judge scores. */
+    rubric: string[];
+}
+/** One conversation = many sessions + a fixed set of probing questions. */
+export interface Beam10MConversation {
+    /** 1-based conversation id (matches Mem0's published numbering). */
+    conversationId: number;
+    /** Ordered sessions; ingest happens session-by-session. */
+    sessions: Beam10MSession[];
+    /** 20 probing questions per conversation × 10 conversations = 200 total. */
+    questions: Beam10MQuestion[];
+    /** Approximate total tokens of conversation transcript (≈ 1.4M for 10M tier). */
+    approxTokens: number;
+}
+/** The full BEAM-10M dataset as returned by the loader. */
+export interface Beam10MDataset {
+    schemaVersion: 'beam-10m.v1';
+    /** Tier identifier. */
+    tier: '10M';
+    conversations: Beam10MConversation[];
+    /** Total question count across all conversations (200 in the canonical set). */
+    totalQuestions: number;
+}
+export interface LoadBeam10MOptions {
+    /** Limit to first N questions per conversation (for smoke / cost control). */
+    sliceSize?: number;
+    /** Restrict to specific conversation ids (e.g. [1] for conv-1 smoke). */
+    conversationIds?: number[];
+}
+/**
+ * Load the BEAM-10M dataset. If the normalized JSON cache produced by
+ * `atomicmemory-benchmarks/data/beam-10m/preprocess.py` exists at the
+ * resolved path, parses it and returns the real dataset. Otherwise falls
+ * back to a deterministic stub fixture matching the canonical
+ * 10-conversation × 20-question shape, so tests and cost-estimator code
+ * keep working without the ~344 MB parquet shards on disk.
+ */
+export declare function loadBeam10MDataset(opts?: LoadBeam10MOptions): Promise<Beam10MDataset>;
+/**
+ * Cost projection for a given dataset slice. Used by the smoke plan to
+ * estimate per-seed cost before committing the full multirun budget.
+ *
+ * Cost components per system per question:
+ *   - ingest (one-time): ~$0.002/fact × ~150 facts/conv = $0.30/conv
+ *   - summary generation (hierarchical only): ~$0.001/session × 50 sessions = $0.05/conv
+ *   - search + answer + judge: ~$0.10/question (multi-iter)
+ *
+ * Per-conv: ~$2 ingest + $2 questions = ~$4/conv. 10 convs = ~$40/seed.
+ * The smoke (conv-1 × 20 q) is ~$4. n=3 multirun on full set = ~$120.
+ */
+export declare function estimateBeamCost(dataset: Beam10MDataset, opts?: {
+    hierarchicalEnabled?: boolean;
+}): {
+    ingestUsd: number;
+    summaryUsd: number;
+    questionsUsd: number;
+    totalUsd: number;
+};

package/dist/eval/beam-10m-loader.js

@@ -0,0 +1,128 @@
+/**
+ * BEAM-10M dataset loader (T3.1 scaffold).
+ *
+ * Source: HuggingFace `Mohammadta/BEAM-10M` (200 questions / 10 conversations).
+ * The 10M tier averages ~1.4M tokens of conversation context per system —
+ * the highest-difficulty BEAM tier and the SOTA target for this sprint.
+ *
+ * This loader is a *stub*: it returns the typed shape for tests and the
+ * smoke design without invoking the HuggingFace API. Real loading lives
+ * in `atomicmemory-benchmarks/atomicbench/src/eval/` once the loader is
+ * promoted out of the worktree.
+ */
+/**
+ * Resolve the on-disk normalized JSON cache path. Set
+ * `BEAM_10M_NORMALIZED_PATH` to override (used by tests + the in-tree
+ * `atomicmemory-benchmarks/data/beam-10m/preprocess.py` output).
+ */
+function resolveCachePath() {
+    const env = process.env.BEAM_10M_NORMALIZED_PATH;
+    if (env)
+        return env;
+    // Default: sibling repo path. The harness runs from the benchmarks repo
+    // so this resolves correctly when invoked through atomicbench.
+    const candidate = '/Users/moralespanitz/me/supernet/atomicmemory-benchmarks/data/beam-10m/beam-10m-normalized.json';
+    return candidate;
+}
+/**
+ * Load the BEAM-10M dataset. If the normalized JSON cache produced by
+ * `atomicmemory-benchmarks/data/beam-10m/preprocess.py` exists at the
+ * resolved path, parses it and returns the real dataset. Otherwise falls
+ * back to a deterministic stub fixture matching the canonical
+ * 10-conversation × 20-question shape, so tests and cost-estimator code
+ * keep working without the ~344 MB parquet shards on disk.
+ */
+export async function loadBeam10MDataset(opts = {}) {
+    const allConversations = await loadConversationsOrStub();
+    const filtered = opts.conversationIds && opts.conversationIds.length > 0
+        ? allConversations.filter((c) => opts.conversationIds.includes(c.conversationId))
+        : allConversations;
+    const sliced = opts.sliceSize !== undefined
+        ? filtered.map((c) => ({ ...c, questions: c.questions.slice(0, opts.sliceSize) }))
+        : filtered;
+    const totalQuestions = sliced.reduce((sum, c) => sum + c.questions.length, 0);
+    return {
+        schemaVersion: 'beam-10m.v1',
+        tier: '10M',
+        conversations: sliced,
+        totalQuestions,
+    };
+}
+async function loadConversationsOrStub() {
+    const cachePath = resolveCachePath();
+    if (!cachePath)
+        return buildStubFixture();
+    try {
+        const fs = await import('node:fs/promises');
+        const raw = await fs.readFile(cachePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.conversations || !Array.isArray(parsed.conversations)) {
+            return buildStubFixture();
+        }
+        return parsed.conversations;
+    }
+    catch {
+        return buildStubFixture();
+    }
+}
+/**
+ * Cost projection for a given dataset slice. Used by the smoke plan to
+ * estimate per-seed cost before committing the full multirun budget.
+ *
+ * Cost components per system per question:
+ *   - ingest (one-time): ~$0.002/fact × ~150 facts/conv = $0.30/conv
+ *   - summary generation (hierarchical only): ~$0.001/session × 50 sessions = $0.05/conv
+ *   - search + answer + judge: ~$0.10/question (multi-iter)
+ *
+ * Per-conv: ~$2 ingest + $2 questions = ~$4/conv. 10 convs = ~$40/seed.
+ * The smoke (conv-1 × 20 q) is ~$4. n=3 multirun on full set = ~$120.
+ */
+export function estimateBeamCost(dataset, opts = {}) {
+    const convCount = dataset.conversations.length;
+    const factsPerConv = 150; // empirical average from BEAM-100K
+    const sessionsPerConv = 50;
+    const questionsTotal = dataset.totalQuestions;
+    const ingestUsd = convCount * factsPerConv * 0.002;
+    const summaryUsd = opts.hierarchicalEnabled
+        ? convCount * sessionsPerConv * 0.001 + convCount * 0.005
+        : 0;
+    const questionsUsd = questionsTotal * 0.10;
+    const totalUsd = ingestUsd + summaryUsd + questionsUsd;
+    return { ingestUsd, summaryUsd, questionsUsd, totalUsd };
+}
+/**
+ * Stub fixture: 10 conversations × 1 session × 1 message + 20 placeholder
+ * questions per conversation. Real data has ~50 sessions × ~30 messages
+ * each per conversation; this stub gives the shape only.
+ */
+function buildStubFixture() {
+    const convs = [];
+    for (let cid = 1; cid <= 10; cid += 1) {
+        const sessions = [
+            {
+                sessionId: `c${cid}-s0`,
+                sessionIndex: 0,
+                startedAt: '2026-01-01T00:00:00Z',
+                messages: [
+                    { role: 'user', content: `placeholder-c${cid}-msg`, timestamp: '2026-01-01T00:00:00Z' },
+                ],
+            },
+        ];
+        const questions = [];
+        const abilities = [
+            'ABS', 'CR', 'EO', 'IE', 'IF', 'KU', 'MSR', 'PF', 'SUM', 'TR',
+        ];
+        for (let qi = 1; qi <= 20; qi += 1) {
+            const ability = abilities[(qi - 1) % abilities.length];
+            questions.push({
+                id: `c${cid}-q${qi}-${ability}`,
+                ability,
+                question: `placeholder-question-${qi}`,
+                ideal: `placeholder-answer-${qi}`,
+                rubric: [],
+            });
+        }
+        convs.push({ conversationId: cid, sessions, questions, approxTokens: 1_400_000 });
+    }
+    return convs;
+}