@atomicmemory/core 1.0.0

package/dist/app/create-app.js

@@ -0,0 +1,156 @@
+/**
+ * Express application factory — wires routers onto a runtime container.
+ *
+ * Separates composition (done in `runtime-container.ts`) from HTTP
+ * transport concerns. Tests and harnesses can create an Express app from
+ * any runtime container without touching the server bootstrap.
+ */
+import express from 'express';
+import { createAgentRouter } from '../routes/agents.js';
+import { createDocumentRouter } from '../routes/documents.js';
+import { createMemoryRouter } from '../routes/memories.js';
+import { makeReflectFlushHandler } from '../routes/reflect.js';
+import { runReflectForConversation } from '../services/reflect.js';
+import { callAnthropicTool } from '../services/llm.js';
+import { embedText } from '../services/embedding.js';
+import { createStorageRouter } from '../routes/storage.js';
+import { MAX_INDEX_TEXT_BYTES } from '../schemas/documents.js';
+import { requireBearer } from '../middleware/require-bearer.js';
+import { CORS_ALLOWED_HEADERS_VALUE } from './cors-headers.js';
+/** Default JSON-body cap for non-document routers. */
+const DEFAULT_JSON_BODY_LIMIT = '1mb';
+/**
+ * Build an Express application from a composed runtime container. The
+ * runtime owns all deps; this module only wires HTTP concerns (CORS, body
+ * parsing, routes, health).
+ *
+ * Body parsing is **route-scoped per router**, not global. Each
+ * `app.use('/v1/<area>', ..., createXRouter())` call declares the cap
+ * its router needs at the mount point — no router relies on inheriting
+ * a parser from above. The documents router additionally owns its own
+ * per-route parsing internally (the `/:id/index` body uses a 25 MiB cap
+ * sourced from `MAX_INDEX_TEXT_BYTES`; everything else falls through to
+ * the documents router's own 1 MiB JSON parser). Mounting a global
+ * `express.json` on the app would silently override that ordering, so
+ * we deliberately do NOT.
+ */
+export function createApp(runtime) {
+    const app = express();
+    // Global CORS layer. Must short-circuit OPTIONS to 204 BEFORE any
+    // mounted `requireBearer` middleware so browser preflights (which
+    // never carry `Authorization`) succeed without a 401. The
+    // router-level `applyCorsHeaders` in `routes/memories.ts` reads the
+    // same canonical Allow-Headers list (`./cors-headers.js`) so the
+    // header surface stays consistent regardless of which layer
+    // produced the response.
+    app.use((req, res, next) => {
+        res.header('Access-Control-Allow-Origin', '*');
+        res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+        res.header('Access-Control-Allow-Headers', CORS_ALLOWED_HEADERS_VALUE);
+        if (req.method === 'OPTIONS') {
+            res.sendStatus(204);
+            return;
+        }
+        next();
+    });
+    // `requireBearer` validates `Authorization: Bearer <CORE_API_KEY>`
+    // on every SDK-facing `/v1/*` router. Built once and reused so the
+    // expected-key buffer is captured a single time (timingSafeEqual
+    // wants matching-length buffers; cheap but allocation-stable).
+    // `/health` and `/openapi.json` stay outside this scope.
+    const auth = requireBearer(runtime.config.coreApiKey);
+    // Route-scoped 1 MiB JSON parsers for the non-document routers.
+    app.use('/v1/memories', auth, express.json({ limit: DEFAULT_JSON_BODY_LIMIT }), createMemoryRouter(runtime.services.memory, runtime.configRouteAdapter));
+    app.use('/v1/agents', auth, express.json({ limit: DEFAULT_JSON_BODY_LIMIT }), createAgentRouter(runtime.repos.trust));
+    // The documents router owns its own body parsing — see
+    // `createDocumentRouter` for the per-route ordering. We pass
+    // `MAX_INDEX_TEXT_BYTES` and the raw-storage capability snapshot
+    // through `limits` so the route layer never imports the config
+    // singleton.
+    const rawStorageEnabled = runtime.config.rawStorageMode === 'managed_blob';
+    // Filecoin lifecycle refactor (Slice 4): when an adapter is
+    // configured, source its `provider` + `capabilities` from
+    // `runtime.rawContentStore`. The snapshot stays internal-camelCase;
+    // `formatDocumentLimitsResponse` flips to snake_case at the wire.
+    // Pointer-only deployments omit `provider`/`capabilities` so the
+    // schema's optional fields validate cleanly.
+    const activeStore = runtime.rawContentStore;
+    const rawStorageSnapshot = rawStorageEnabled
+        ? {
+            enabled: true,
+            mode: runtime.config.rawStorageMode,
+            ...(activeStore
+                ? {
+                    provider: activeStore.provider,
+                    capabilities: activeStore.capabilities,
+                }
+                : {}),
+        }
+        : {
+            enabled: false,
+            mode: runtime.config.rawStorageMode,
+            reason: 'raw_storage_mode is pointer_only; managed-blob upload disabled',
+        };
+    app.use('/v1/documents', auth, createDocumentRouter(runtime.services.documents, {
+        rawUploadMaxBytes: runtime.config.rawUploadMaxBytes,
+        limits: {
+            rawUploadMaxBytes: runtime.config.rawUploadMaxBytes,
+            indexMaxTextBytes: MAX_INDEX_TEXT_BYTES,
+            rawStorage: rawStorageSnapshot,
+        },
+    }));
+    // Storage-sibling Step 3 added capabilities; Step 5 adds artifact
+    // CRUD on the same router. The router owns its own per-route body
+    // parsers (JSON for pointer-mode put + verify, `express.raw` for
+    // managed-mode put), so we mount it WITHOUT a global JSON parser
+    // at this prefix to avoid double-parsing managed-mode bodies.
+    app.use('/v1/storage', auth, createStorageRouter({
+        capabilities: {
+            activeStore,
+            rawUploadMaxBytes: runtime.config.rawUploadMaxBytes,
+        },
+        service: runtime.services.storage,
+        managedUploadMaxBytes: runtime.config.rawUploadMaxBytes,
+    }));
+    // Reflect flush: synchronous queue drain for benchmark / eval harnesses.
+    // Wired regardless of reflectEnabled so the route always exists; the
+    // handler returns 503 when reflect is disabled.
+    const { reflectionJobs, reflections, entityCards } = runtime.stores;
+    const reflectEnabled = runtime.config.reflectEnabled;
+    const entityCardDeps = entityCards && runtime.config.entityCardEnabled
+        ? {
+            enabled: true,
+            repo: entityCards,
+            synth: {
+                llmCallTool: (system, user, schema) => callAnthropicTool(runtime.config.reflectModel, system, user, schema),
+                minObservations: runtime.config.entityCardMinObservations,
+                maxEntities: runtime.config.entityCardMaxPerSession,
+            },
+            maxCardsPerSession: runtime.config.entityCardMaxPerSession,
+        }
+        : undefined;
+    const reflectFlushDeps = {
+        jobs: reflectionJobs ?? {
+            fetchPending: async () => [],
+            markInProgress: async () => undefined,
+            markCompleted: async () => undefined,
+            markFailed: async () => undefined,
+        },
+        runReflect: (userId, conversationId) => runReflectForConversation({
+            fetchMemories: (u, c) => runtime.repos.memory.findByConversation(u, c),
+            llmCallTool: (system, user, schema) => callAnthropicTool(runtime.config.reflectModel, system, user, schema),
+            embed: (text) => embedText(text),
+            reflections: reflections ?? { insertMany: async () => undefined },
+            maxObservations: runtime.config.reflectMaxObservations,
+            entityCards: entityCardDeps,
+        }, userId, conversationId),
+    };
+    app.post('/v1/reflect/flush', makeReflectFlushHandler(reflectFlushDeps, reflectEnabled));
+    // `/health` is intentionally unversioned — it is an infrastructure
+    // liveness probe (load balancers, Docker, Railway), not part of the
+    // versioned application API. Versioned endpoints live under `/v1/*`.
+    app.get('/health', (_req, res) => {
+        res.json({ status: 'ok' });
+    });
+    return app;
+}

package/dist/app/runtime-config-route-snapshot.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared runtime-config route snapshot shape and formatter.
+ *
+ * Both the composed runtime container and the legacy route module need the
+ * same public config subset. Keeping the projection here prevents drift in
+ * `/v1/memories/health` and `/v1/memories/config` responses.
+ */
+import type { EmbeddingProviderName, LLMProviderName, RuntimeConfig } from '../config.js';
+export interface RuntimeConfigRouteSnapshot {
+    retrievalProfile: string;
+    embeddingProvider: EmbeddingProviderName;
+    embeddingModel: string;
+    voyageDocumentModel: string;
+    voyageQueryModel: string;
+    llmProvider: LLMProviderName;
+    llmModel: string;
+    clarificationConflictThreshold: number;
+    maxSearchResults: number;
+    hybridSearchEnabled: boolean;
+    iterativeRetrievalEnabled: boolean;
+    entityGraphEnabled: boolean;
+    crossEncoderEnabled: boolean;
+    agenticRetrievalEnabled: boolean;
+    repairLoopEnabled: boolean;
+    runtimeConfigMutationEnabled: boolean;
+}
+export declare function readRuntimeConfigRouteSnapshot(config: RuntimeConfig): RuntimeConfigRouteSnapshot;

package/dist/app/runtime-config-route-snapshot.js

@@ -0,0 +1,27 @@
+/**
+ * Shared runtime-config route snapshot shape and formatter.
+ *
+ * Both the composed runtime container and the legacy route module need the
+ * same public config subset. Keeping the projection here prevents drift in
+ * `/v1/memories/health` and `/v1/memories/config` responses.
+ */
+export function readRuntimeConfigRouteSnapshot(config) {
+    return {
+        retrievalProfile: config.retrievalProfile,
+        embeddingProvider: config.embeddingProvider,
+        embeddingModel: config.embeddingModel,
+        voyageDocumentModel: config.voyageDocumentModel,
+        voyageQueryModel: config.voyageQueryModel,
+        llmProvider: config.llmProvider,
+        llmModel: config.llmModel,
+        clarificationConflictThreshold: config.clarificationConflictThreshold,
+        maxSearchResults: config.maxSearchResults,
+        hybridSearchEnabled: config.hybridSearchEnabled,
+        iterativeRetrievalEnabled: config.iterativeRetrievalEnabled,
+        entityGraphEnabled: config.entityGraphEnabled,
+        crossEncoderEnabled: config.crossEncoderEnabled,
+        agenticRetrievalEnabled: config.agenticRetrievalEnabled,
+        repairLoopEnabled: config.repairLoopEnabled,
+        runtimeConfigMutationEnabled: config.runtimeConfigMutationEnabled,
+    };
+}

package/dist/app/runtime-container.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Core runtime container — the explicit composition root for atomicmemory-core.
+ *
+ * Owns the construction of config, pool, repositories, and services so
+ * startup (`server.ts`), tests, and in-process research harnesses all boot
+ * through the same seam. Replaces the hidden singleton wiring that used to
+ * live inline in `server.ts`.
+ *
+ * Runtime-container wiring — the composition root that replaces
+ * per-startup hand-wiring of repos and services in `server.ts`.
+ */
+import pg from 'pg';
+import { type CrossEncoderDtype, type RuntimeConfig, type RuntimeConfigUpdates } from '../config.js';
+import { AgentTrustRepository } from '../db/agent-trust-repository.js';
+import { BeliefEdgesRepository } from '../db/belief-edges-repository.js';
+import { ClaimRepository } from '../db/claim-repository.js';
+import { LinkRepository } from '../db/link-repository.js';
+import { MemoryRepository } from '../db/memory-repository.js';
+import { EntityRepository } from '../db/repository-entities.js';
+import { LessonRepository } from '../db/repository-lessons.js';
+import { DocumentService } from '../services/document-service.js';
+import { StorageService } from '../services/storage-service.js';
+import type { RawContentStore } from '../storage/raw-content-store.js';
+import { type RawContentStoreRegistry } from '../storage/store-registry.js';
+import type { CoreStores } from '../db/stores.js';
+import type { RetrievalProfile } from '../services/retrieval-profiles.js';
+import { MemoryService } from '../services/memory-service.js';
+import { type RuntimeConfigRouteSnapshot } from './runtime-config-route-snapshot.js';
+/**
+ * Explicit runtime configuration subset currently needed by the runtime
+ * container, startup checks, search/runtime seams, and MemoryService deps.
+ *
+ * This is intentionally narrower than the module-level config singleton:
+ * it describes the config surface already threaded through those seams
+ * today, without claiming full runtime-wide configurability yet.
+ *
+ * NOTE (phase 1b status): `runtime.config` is normally the module-level
+ * singleton, but benchmark harnesses may pass an explicit composition-time
+ * RuntimeConfig through `createCoreRuntime({ config })`. MemoryService accepts
+ * an optional runtimeConfig override (stored as deps.config), and the search-
+ * pipeline orchestration and ingest orchestration files (memory-ingest,
+ * memory-storage, memory-audn, memory-lineage) read the fields listed
+ * in `CoreRuntimeConfig` and `IngestRuntimeConfig` through deps.config
+ * rather than the singleton. The route layer reads through an injectable
+ * adapter seam (`configRouteAdapter`) backed by this runtime config object.
+ *
+ * Leaf modules initialized by this composition root (embedding.ts and llm.ts)
+ * are rebound to the runtime config. Other leaf helpers still import the
+ * singleton directly, so config overrides are intended for isolated single-
+ * runtime harnesses, not multiple concurrently-active runtimes in one process.
+ *
+ * Remaining singleton importers: 33 non-test source files (tracked by
+ * config-singleton-audit.test.ts). This includes infrastructure, CRUD/
+ * lifecycle, leaf helpers, the DB repository layer, and index.ts.
+ */
+export interface CoreRuntimeConfig {
+    adaptiveRetrievalEnabled: boolean;
+    adaptiveSimpleLimit: number;
+    adaptiveMediumLimit: number;
+    adaptiveComplexLimit: number;
+    adaptiveMultiHopLimit: number;
+    adaptiveAggregationLimit: number;
+    agenticRetrievalEnabled: boolean;
+    auditLoggingEnabled: boolean;
+    consensusMinMemories: number;
+    consensusValidationEnabled: boolean;
+    crossEncoderDtype: CrossEncoderDtype;
+    crossEncoderEnabled: boolean;
+    crossEncoderModel: string;
+    embeddingDimensions: number;
+    entityGraphEnabled: boolean;
+    entitySearchMinSimilarity: number;
+    hierarchicalRetrievalEnabled: boolean;
+    hybridSearchEnabled: boolean;
+    iterativeRetrievalEnabled: boolean;
+    lessonsEnabled: boolean;
+    linkExpansionBeforeMMR: boolean;
+    linkExpansionEnabled: boolean;
+    linkExpansionMax: number;
+    linkSimilarityThreshold: number;
+    literalListProtectionEnabled: boolean;
+    literalListProtectionMaxProtected: number;
+    maxSearchResults: number;
+    mmrEnabled: boolean;
+    mmrLambda: number;
+    namespaceClassificationEnabled: boolean;
+    pprDamping: number;
+    pprEnabled: boolean;
+    port: number;
+    queryAugmentationEnabled: boolean;
+    queryAugmentationMaxEntities: number;
+    queryAugmentationMinSimilarity: number;
+    queryExpansionEnabled: boolean;
+    queryExpansionMinSimilarity: number;
+    repairConfidenceFloor: number;
+    repairDeltaThreshold: number;
+    repairLoopEnabled: boolean;
+    repairLoopMinSimilarity: number;
+    rerankSkipMinGap: number;
+    rerankSkipTopSimilarity: number;
+    retrievalProfileSettings: RetrievalProfile;
+    similarityThreshold: number;
+    temporalQueryConstraintBoost: number;
+    temporalQueryConstraintEnabled: boolean;
+    topicSearchEnabled: boolean;
+    rerankerEnabled: boolean;
+    rerankerTopN: number;
+    recapSearchEnabled: boolean;
+    counterEvidenceEnabled: boolean;
+    packagingUseObservedAt: boolean;
+    packagingDualDate: boolean;
+    timelineChannelEnabled: boolean;
+    answerOnlyRetrievalFilter: boolean;
+    retrievalDedupEnabled: boolean;
+    keywordRrfWeight: number;
+    entityAttributesEnabled: boolean;
+    entityAttributesTopK: number;
+    userProfileChannelEnabled: boolean;
+    episodesChannelEnabled: boolean;
+    episodesChannelTopK: number;
+    verifierPassEnabled: boolean;
+    answerFormatAlignmentEnabled: boolean;
+    eventChainPackagingEnabled: boolean;
+    /** Reflect channel gate (BEAM-0.85 Phase 1, Task 1.9). */
+    reflectEnabled: boolean;
+    /** Top-K reflections to fetch when reflect retrieval is enabled. */
+    reflectRetrievalTopK: number;
+    /** Anthropic model used by the reflect worker. */
+    reflectModel: string;
+    /** Maximum observations the reflect worker persists per conversation. */
+    reflectMaxObservations: number;
+    /** Polling interval (ms) for the reflect background worker. */
+    reflectJobPollMs: number;
+    /** Debounce delay (ms) reserved for future worker throttling. */
+    reflectDebounceMs: number;
+    /**
+     * Phase 2 specialists gate (BEAM-0.85 Phase 2). When true, the dispatcher
+     * runs after top-K retrieval. First specialist with handled=true short-
+     * circuits the shared spine. Default false.
+     */
+    phase2SpecialistsEnabled: boolean;
+    /** LLM model ID (e.g. 'claude-haiku-4-5'). Used by specialist LLM calls. */
+    llmModel: string;
+    /** Master gate for all three abstention-rescue interventions. Default false. */
+    abstentionRescueEnabled: boolean;
+    /** Top-K for the iterative-retrieval rescue pass. Default 8. */
+    abstentionRescueRetrieveK: number;
+    /** Model used for the Sonnet rescue step. Default 'claude-sonnet-4-5'. */
+    abstentionRescueSonnetModel: string;
+    /**
+     * Per-question-type adaptive confidence prefix (v36). When true, the forced
+     * FORBIDDEN-abstention block only applies to SUMMARY/PREFERENCE/
+     * NUMERIC_COUNT/EXACT_DATE; ORDERED_LIST/CONTRADICTION/OTHER get a soft
+     * variant (rubric phrasing + KU temporal anchor, no FORBIDDEN block); ABSTAIN
+     * passes through unchanged. Requires abstentionRescueEnabled=true.
+     */
+    confidencePrefixAdaptiveEnabled: boolean;
+    /**
+     * KU recency sort (v42). When true, NUMERIC_COUNT queries matching the
+     * KU-style framing reorder packaged retrieval by observed_at DESC before
+     * injection. See RuntimeConfig for full semantics. Default false.
+     */
+    kuRecencySortEnabled: boolean;
+    /**
+     * MSR cross-conversation aggregator (v39-multihop). When true, queries
+     * classified as multi-session-reasoning (regex via `msr-detector.ts`) get
+     * an extra `## CROSS-SESSION SUMMARY` channel inserted before the standard
+     * OBSERVATIONS / TIMELINE / ENTITY_STATE blocks. See RuntimeConfig for
+     * full semantics. Default false.
+     */
+    msrAggregatorEnabled: boolean;
+    /**
+     * Anthropic API key, threaded through CoreRuntimeConfig for Sonnet rescue.
+     * Optional: only required when abstentionRescueEnabled is true and
+     * llmProvider is not 'anthropic'.
+     */
+    anthropicApiKey?: string;
+    /**
+     * Always-on ENTITY_CARD channel gate (BEAM-0.85 — Honcho parity).
+     * When true, the Reflect worker synthesizes per-entity summary cards and
+     * the search pipeline injects them at the top of every answer-LLM prompt.
+     */
+    entityCardEnabled: boolean;
+    /** Max entity cards synthesized per Reflect run. */
+    entityCardMaxPerSession: number;
+    /** Minimum observations an entity needs before its card is synthesized. */
+    entityCardMinObservations: number;
+    /** BEAM CR fix: bilateral preservation gate. See RuntimeConfig. */
+    contradictionPreservationEnabled: boolean;
+    /** BEAM CR fix: retrieval-side enrichment gate. See RuntimeConfig. */
+    contradictionSurfacingEnabled: boolean;
+    /**
+     * BEAM v38: temporal state layer. When true, ingest classifies each new
+     * memory with a stable `state_key` and supersedes prior memories with the
+     * same key; CURRENT_STATE intent reranks active state above superseded.
+     * Default false. See RuntimeConfig for full description.
+     */
+    temporalStateEnabled: boolean;
+}
+/** Repositories constructed by the runtime container. */
+export interface CoreRuntimeRepos {
+    memory: MemoryRepository;
+    claims: ClaimRepository;
+    trust: AgentTrustRepository;
+    links: LinkRepository;
+    entities: EntityRepository | null;
+    lessons: LessonRepository | null;
+    beliefEdges: BeliefEdgesRepository | null;
+}
+/** Services constructed on top of repositories. */
+export interface CoreRuntimeServices {
+    memory: MemoryService;
+    /** Pointer-only document registry. */
+    documents: DocumentService;
+    /** Direct storage API service. */
+    storage: StorageService;
+}
+export interface CoreRuntimeConfigRouteAdapter {
+    base: () => RuntimeConfig;
+    current: () => RuntimeConfigRouteSnapshot;
+    update: (updates: RuntimeConfigUpdates) => string[];
+}
+/**
+ * Explicit dependency bundle accepted by `createCoreRuntime`.
+ *
+ * `pool` is required — the composition root never reaches around to
+ * import the singleton `pg.Pool` itself.
+ *
+ * Optional `config` is a composition-time override for isolated harnesses
+ * such as AtomicBench. It is not a per-request override and should not be
+ * used for multiple concurrently-active runtimes in one process while
+ * singleton-importing leaf modules remain.
+ */
+export interface CoreRuntimeDeps {
+    pool: pg.Pool;
+    config?: RuntimeConfig;
+}
+/** The composed runtime — single source of truth for route registration. */
+export interface CoreRuntime {
+    config: RuntimeConfig;
+    configRouteAdapter: CoreRuntimeConfigRouteAdapter;
+    pool: pg.Pool;
+    repos: CoreRuntimeRepos;
+    /** Domain-facing store interfaces. Will replace repos once migration is complete. */
+    stores: CoreStores;
+    services: CoreRuntimeServices;
+    /**
+     * Active managed-blob adapter when `rawStorageMode='managed_blob'`;
+     * `null` for pointer-only deployments. Exposed so the composition
+     * root (`create-app.ts`) can read `capabilities` without re-running
+     * the factory or reaching back through `services.documents`.
+     * (Filecoin lifecycle refactor, Slice 4.)
+     */
+    rawContentStore: RawContentStore | null;
+    /**
+     * Per-row provider dispatch. Holds the active store plus
+     * any legacy read-only adapters built from
+     * `RAW_STORAGE_LEGACY_PROVIDERS`. Cleanup helpers use this to route
+     * a DELETE to the right adapter for historical rows that pre-date a
+     * provider switch.
+     */
+    storeRegistry: RawContentStoreRegistry;
+    /**
+     * Reconciler dependency bundle. Populated whenever the
+     * deployment has `RAW_STORAGE_PROVIDER=filecoin` AND a configured
+     * active Filecoin adapter; `null` otherwise. `null` is the signal
+     * the production bootstrap reads to decide whether to call
+     * `startReconciler`. `createCoreRuntime` does NOT start the
+     * scheduler — tests stay deterministic by calling `runOnce(deps)`
+     * directly.
+     */
+    reconcilerDeps: import('../services/raw-storage-reconciler.js').ReconcilerDeps | null;
+}
+/**
+ * Compose the core runtime. Instantiates repositories and the memory
+ * service from an explicit pool. Uses either the module-level config singleton
+ * or an explicit composition-time config and passes that same object into leaf
+ * module initializers and MemoryService so the composition root owns the seam.
+ * No mutation.
+ */
+export declare function createCoreRuntime(deps: CoreRuntimeDeps): Promise<CoreRuntime>;