@atomicmemory/core 1.0.0

package/dist/app/runtime-container.js

@@ -0,0 +1,297 @@
+/**
+ * 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 { applyRuntimeConfigUpdates, config as defaultConfig, } 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 { EntityAttributesRepository } from '../db/repository-entity-attributes.js';
+import { LessonRepository } from '../db/repository-lessons.js';
+import { SummariesRepository } from '../db/summaries-repository.js';
+import { UserProfileRepository } from '../db/repository-user-profiles.js';
+import { ReflectionsRepository } from '../db/reflections-repository.js';
+import { ReflectionJobsRepository } from '../db/reflection-jobs-repository.js';
+import { EntityCardsRepository } from '../db/entity-cards-repository.js';
+import { ContradictionsRepository } from '../db/contradictions-repository.js';
+import { EntityValuesRepository } from '../db/entity-values-repository.js';
+import { TllRepository } from '../db/repository-tll.js';
+import { FirstMentionRepository } from '../db/repository-first-mentions.js';
+import { DocumentService } from '../services/document-service.js';
+import { StorageService } from '../services/storage-service.js';
+import { RawContentStoreBackendAdapter } from '../storage/raw-content-store-backend-adapter.js';
+import { buildBackendRegistry } from '../storage/storage-backend-registry.js';
+import { buildRawContentStore, buildLegacyStores } from '../storage/factory.js';
+import { buildStoreRegistry } from '../storage/store-registry.js';
+import { buildRawContentCodec } from '../storage/codec-factory.js';
+import { FirstMentionService } from '../services/first-mention-service.js';
+import { llm } from '../services/llm.js';
+import { PgMemoryStore } from '../db/pg-memory-store.js';
+import { PgEpisodeStore } from '../db/pg-episode-store.js';
+import { PgRecapStore } from '../db/pg-recap-store.js';
+import { PgSearchStore } from '../db/pg-search-store.js';
+import { PgSemanticLinkStore } from '../db/pg-link-store.js';
+import { PgRepresentationStore } from '../db/pg-representation-store.js';
+import { MemoryService } from '../services/memory-service.js';
+import { initEmbedding, embedText } from '../services/embedding.js';
+import { initLlm, callAnthropicTool } from '../services/llm.js';
+import { runReflectForConversation } from '../services/reflect.js';
+import { startReflectWorker } from '../services/reflect-jobs.js';
+import { setBeliefDualWriteHook } from '../services/tbc-execution.js';
+import { readRuntimeConfigRouteSnapshot, } from './runtime-config-route-snapshot.js';
+/**
+ * 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.
+ */
+// fallow-ignore-next-line complexity
+export async function createCoreRuntime(deps) {
+    const { pool } = deps;
+    const runtimeConfig = deps.config ?? defaultConfig;
+    // Leaf-module config init. Embedding and LLM modules
+    // hold module-local config bound here at composition-root time.
+    // Provider/model selection is startup-only, so rebinding
+    // only happens via explicit init call (e.g., from tests that swap
+    // providers).
+    initEmbedding(runtimeConfig);
+    initLlm(runtimeConfig);
+    // Raw-content adapter. Built up front so it can be threaded
+    // into both the memory store layer (deleteAll honors managed-blob
+    // cleanup) and the document service (upload + delete cascade). Null
+    // for `rawStorageMode='pointer_only'` deployments. Async because the
+    // Filecoin provider construction is async — the
+    // plan's fail-closed rule requires credentials to be resolved at
+    // composition time, not at first upload.
+    const rawContentStore = await buildRawContentStore(runtimeConfig);
+    // Per-row dispatch registry. Active store + any legacy
+    // read-only adapters configured via `RAW_STORAGE_LEGACY_PROVIDERS`,
+    // wrapped in one `RawContentStoreRegistry` that cleanup helpers
+    // dispatch through.
+    const legacyStores = buildLegacyStores(runtimeConfig);
+    const storeRegistry = buildStoreRegistry(rawContentStore, legacyStores);
+    // Content codec — wraps adapter `put()` so the bytes sent
+    // to the provider may differ from the plaintext bytes the upload
+    // service hashes. Plaintext content_hash/size_bytes stay the row's
+    // source of truth; codec sidecar lands under raw_storage_metadata.codec.
+    const rawContentCodec = buildRawContentCodec(runtimeConfig);
+    const reconcilerDeps = buildReconcilerDeps(pool, rawContentStore, rawContentCodec, runtimeConfig);
+    const memory = new MemoryRepository(pool, { rawContentStore, storeRegistry });
+    const claims = new ClaimRepository(pool);
+    const trust = new AgentTrustRepository(pool);
+    const links = new LinkRepository(pool);
+    const entities = runtimeConfig.entityGraphEnabled ? new EntityRepository(pool) : null;
+    const lessons = runtimeConfig.lessonsEnabled ? new LessonRepository(pool) : null;
+    const beliefEdges = runtimeConfig.tbcEnabled ? new BeliefEdgesRepository(pool) : null;
+    const summaries = runtimeConfig.hierarchicalRetrievalEnabled ? new SummariesRepository(pool) : null;
+    const userProfile = runtimeConfig.userProfileChannelEnabled ? new UserProfileRepository(pool) : null;
+    const entityAttributes = runtimeConfig.entityAttributesEnabled ? new EntityAttributesRepository(pool) : null;
+    const reflections = runtimeConfig.reflectEnabled ? new ReflectionsRepository(pool) : null;
+    const reflectionJobs = runtimeConfig.reflectEnabled ? new ReflectionJobsRepository(pool) : null;
+    const entityValues = runtimeConfig.phase2SpecialistsEnabled ? new EntityValuesRepository(pool) : null;
+    const entityCards = runtimeConfig.entityCardEnabled ? new EntityCardsRepository(pool) : null;
+    const contradictions = buildContradictionsRepo(runtimeConfig, pool);
+    // TBC dual-write hook: when TBC is enabled, route belief operations
+    // through BeliefEdgesRepository (typed edges) and a direct SQL update
+    // on memories typed columns (confidence/belief_tier/mutation_type).
+    // The hook is process-global (module-level singleton in tbc-execution).
+    if (beliefEdges) {
+        setBeliefDualWriteHook({
+            async appendEdge(input) {
+                await beliefEdges.appendEdge({
+                    userId: input.userId,
+                    sourceId: input.sourceId,
+                    targetId: input.targetId,
+                    edgeType: input.edgeType,
+                    weight: input.weight,
+                    rationale: input.rationale,
+                });
+            },
+            async updateColumns(input) {
+                const fields = [];
+                const values = [];
+                let i = 1;
+                if (input.confidence !== undefined) {
+                    fields.push(`confidence = $${i++}`);
+                    values.push(input.confidence);
+                }
+                if (input.beliefTier !== undefined) {
+                    fields.push(`belief_tier = $${i++}`);
+                    values.push(input.beliefTier);
+                }
+                if (input.mutationType !== undefined) {
+                    fields.push(`mutation_type = $${i++}`);
+                    values.push(input.mutationType);
+                }
+                if (fields.length === 0)
+                    return;
+                values.push(input.memoryId, input.userId);
+                await pool.query(`UPDATE memories SET ${fields.join(', ')} WHERE id = $${i++} AND user_id = $${i}`, values);
+            },
+        });
+    }
+    else {
+        setBeliefDualWriteHook(undefined);
+    }
+    const stores = {
+        memory: new PgMemoryStore(pool, { rawContentStore, storeRegistry }),
+        episode: new PgEpisodeStore(pool),
+        recap: new PgRecapStore(pool),
+        search: new PgSearchStore(pool),
+        link: new PgSemanticLinkStore(pool),
+        representation: new PgRepresentationStore(pool),
+        claim: claims,
+        entity: entities,
+        entityAttributes,
+        lesson: lessons,
+        summaries,
+        userProfile,
+        reflections,
+        reflectionJobs,
+        beliefEdges,
+        entityValues,
+        entityCards,
+        contradictions,
+        pool,
+    };
+    // TLL — per-entity event chain for EO/MSR/TR queries.
+    // Append on memory store, traverse on retrieval.
+    const tllRepository = entities ? new TllRepository(pool) : null;
+    // First-mention events — chronological topic-introduction list. Caller
+    // (e.g. an external harness) drives extraction explicitly via the
+    // POST /v1/memories/first-mentions/extract route, supplying its own
+    // turn-id-to-memory-id mapping (the ingest pipeline does not retain
+    // turn structure). The chatFn adapter wraps the configured LLM
+    // singleton; per-call cost is logged inside `llm.chat`.
+    const firstMentionRepository = new FirstMentionRepository(pool);
+    const firstMentionService = new FirstMentionService(firstMentionRepository, async (system, user, maxTokens) => {
+        const text = await llm.chat([
+            { role: 'system', content: system },
+            { role: 'user', content: user },
+        ], { maxTokens });
+        // Token usage is intentionally NOT returned here: `LLMProvider.chat`
+        // emits per-call cost telemetry via `writeCostEvent` internally
+        // (see `src/services/llm.ts`). Surfacing zeros at this seam invited
+        // the bug the prior reviewer caught — readers would treat them as
+        // real counts. Drop the field instead until usage is plumbed.
+        return { text };
+    });
+    // Document registry. Raw-content wiring provides a managed-blob
+    // `RawContentStore` when `rawStorageMode='managed_blob'`; pointer-only
+    // deployments get `null` here and the upload route returns 503. The
+    // same store is threaded into MemoryService so reset-source can clean
+    // up managed-blob URIs after the DB cascade.
+    const service = new MemoryService(memory, claims, entities ?? undefined, lessons ?? undefined, undefined, runtimeConfig, stores, tllRepository ?? undefined, firstMentionService, rawContentStore, storeRegistry);
+    const documents = new DocumentService(pool, {
+        rawContentStore,
+        storeRegistry,
+        codec: rawContentCodec,
+        config: runtimeConfig,
+    });
+    // Direct storage API service. Each registered `RawContentStore`
+    // (active + legacy) is wrapped in a `RawContentStoreBackendAdapter`
+    // so the storage service can dispatch by `storage_artifacts.provider`
+    // for read/delete/verify of historical rows whose provider differs
+    // from the current active backend. Pointer artifacts short-circuit
+    // before backend lookup so pointer-only deployments still work.
+    const backendRegistry = buildBackendRegistry(rawContentStore === null ? null : new RawContentStoreBackendAdapter(rawContentStore), storeRegistry.entries
+        .filter(([provider]) => provider !== rawContentStore?.provider)
+        .map(([, store]) => new RawContentStoreBackendAdapter(store)));
+    const storage = new StorageService({
+        pool,
+        backendRegistry,
+        pointerSchemes: runtimeConfig.rawStoragePointerUriSchemes,
+        storageKeyHmacSecret: runtimeConfig.storageKeyHmacSecret,
+    });
+    // Start the reflect background worker when reflect is enabled.
+    // The worker pulls pending reflection_jobs, runs the orchestrator,
+    // and marks each job completed or failed. It is intentionally
+    // fire-and-forget — the returned handle is not used here because the
+    // process lifecycle owns shutdown (SIGTERM/SIGINT in server.ts).
+    if (runtimeConfig.reflectEnabled && reflections && reflectionJobs) {
+        const entityCardDeps = buildEntityCardDeps(runtimeConfig, entityCards);
+        startReflectWorker({
+            jobs: reflectionJobs,
+            runReflect: (userId, conversationId) => runReflectForConversation({
+                fetchMemories: (u, c) => memory.findByConversation(u, c),
+                llmCallTool: (system, user, schema) => callAnthropicTool(runtimeConfig.reflectModel, system, user, schema),
+                embed: (text) => embedText(text),
+                reflections,
+                maxObservations: runtimeConfig.reflectMaxObservations,
+                entityCards: entityCardDeps,
+            }, userId, conversationId),
+        }, runtimeConfig.reflectJobPollMs);
+    }
+    return {
+        config: runtimeConfig,
+        configRouteAdapter: {
+            base() {
+                return runtimeConfig;
+            },
+            current() {
+                return readRuntimeConfigRouteSnapshot(runtimeConfig);
+            },
+            update(updates) {
+                return applyRuntimeConfigUpdates(runtimeConfig, updates);
+            },
+        },
+        pool,
+        repos: { memory, claims, trust, links, entities, lessons, beliefEdges },
+        stores,
+        services: { memory: service, documents, storage },
+        rawContentStore,
+        storeRegistry,
+        reconcilerDeps,
+    };
+}
+/**
+ * Build the optional entity-card synthesis deps for the Reflect worker.
+ * Returns `undefined` when the channel is disabled or the repo is null
+ * — `runReflectForConversation` short-circuits on a missing/disabled bag.
+ */
+function buildEntityCardDeps(runtimeConfig, entityCards) {
+    if (!entityCards || !runtimeConfig.entityCardEnabled)
+        return undefined;
+    return {
+        enabled: true,
+        repo: entityCards,
+        synth: {
+            llmCallTool: (system, user, schema) => callAnthropicTool(runtimeConfig.reflectModel, system, user, schema),
+            minObservations: runtimeConfig.entityCardMinObservations,
+            maxEntities: runtimeConfig.entityCardMaxPerSession,
+        },
+        maxCardsPerSession: runtimeConfig.entityCardMaxPerSession,
+    };
+}
+/**
+ * BEAM CR fix: bilateral preservation. The repo is instantiated when either
+ * the write-side preservation OR the read-side surfacing is enabled, since
+ * retrieval enrichment needs to read pre-existing contradictions even when
+ * the write-side flag has since been turned off. Extracted as a helper to
+ * keep `createCoreRuntime` below the cyclomatic-complexity baseline.
+ */
+function buildContradictionsRepo(runtimeConfig, pool) {
+    const needsRepo = runtimeConfig.contradictionPreservationEnabled ||
+        runtimeConfig.contradictionSurfacingEnabled;
+    return needsRepo ? new ContradictionsRepository(pool) : null;
+}
+/**
+ * Build the reconciler dependency bundle. Returns `null` until
+ * production reconciler scheduling is enabled for the active provider.
+ * The reconciler module remains in place so provider wiring can opt in
+ * without changing the route layer.
+ */
+function buildReconcilerDeps(_pool, _rawContentStore, _codec, _cfg) {
+    return null;
+}

package/dist/app/startup-checks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Startup guard functions run before the HTTP server accepts traffic.
+ *
+ * Extracted from `server.ts` so tests can exercise individual checks and
+ * future startup guards can be added without growing the server bootstrap
+ * module. Phase 1A of the rearchitecture.
+ */
+import pg from 'pg';
+import type { CoreRuntimeConfig } from './runtime-container.js';
+/**
+ * Result of an embedding dimension check against the `memories.embedding`
+ * column. `ok=false` means the process should exit before serving traffic.
+ */
+export interface EmbeddingDimensionCheckResult {
+    ok: boolean;
+    dbDims: number | null;
+    configDims: number;
+    message: string;
+}
+/**
+ * Verify DB embedding column dimensions match the configured embedding size.
+ * Catches the "expected N dimensions, not M" class of errors at startup,
+ * which would otherwise surface as opaque insert failures during ingest.
+ *
+ * This function never throws or exits — it returns a structured result so
+ * the caller decides how to react (log + exit at boot, throw in tests).
+ */
+export declare function checkEmbeddingDimensions(pool: pg.Pool, config: CoreRuntimeConfig): Promise<EmbeddingDimensionCheckResult>;

package/dist/app/startup-checks.js

@@ -0,0 +1,45 @@
+/**
+ * Startup guard functions run before the HTTP server accepts traffic.
+ *
+ * Extracted from `server.ts` so tests can exercise individual checks and
+ * future startup guards can be added without growing the server bootstrap
+ * module. Phase 1A of the rearchitecture.
+ */
+/**
+ * Verify DB embedding column dimensions match the configured embedding size.
+ * Catches the "expected N dimensions, not M" class of errors at startup,
+ * which would otherwise surface as opaque insert failures during ingest.
+ *
+ * This function never throws or exits — it returns a structured result so
+ * the caller decides how to react (log + exit at boot, throw in tests).
+ */
+export async function checkEmbeddingDimensions(pool, config) {
+    const { rows } = await pool.query(`SELECT atttypmod AS typmod
+     FROM pg_attribute a
+     JOIN pg_class c ON a.attrelid = c.oid
+     WHERE c.relname = 'memories' AND a.attname = 'embedding'`);
+    if (rows.length === 0) {
+        return {
+            ok: false,
+            dbDims: null,
+            configDims: config.embeddingDimensions,
+            message: 'memories.embedding column not found — run npm run migrate first',
+        };
+    }
+    const dbDims = rows[0].typmod > 0 ? rows[0].typmod : null;
+    if (dbDims !== null && dbDims !== config.embeddingDimensions) {
+        return {
+            ok: false,
+            dbDims,
+            configDims: config.embeddingDimensions,
+            message: `DB vector column is ${dbDims} dimensions but EMBEDDING_DIMENSIONS=${config.embeddingDimensions}. ` +
+                `Fix: set EMBEDDING_DIMENSIONS=${dbDims} or run 'npm run migrate' to recreate the schema.`,
+        };
+    }
+    return {
+        ok: true,
+        dbDims,
+        configDims: config.embeddingDimensions,
+        message: `Embedding dimensions OK: config=${config.embeddingDimensions}, DB=${dbDims ?? 'unset'}`,
+    };
+}

package/dist/bin.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * AtomicMemory Core CLI entry point.
+ *
+ * Keeps npm execution intentionally thin: it applies an explicit local
+ * development profile when requested, then delegates to the same server and
+ * migration entry points used by source and Docker workflows.
+ */
+type CommandName = 'start' | 'migrate';
+type ProfileName = 'local';
+interface ParsedArgs {
+    command: CommandName | null;
+    help: boolean;
+    profile: ProfileName | null;
+}
+export declare function parseCliArgs(argv: string[]): ParsedArgs;
+export {};

package/dist/bin.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * AtomicMemory Core CLI entry point.
+ *
+ * Keeps npm execution intentionally thin: it applies an explicit local
+ * development profile when requested, then delegates to the same server and
+ * migration entry points used by source and Docker workflows.
+ */
+import { fileURLToPath } from 'node:url';
+const LOCAL_PROFILE_DEFAULTS = {
+    CORE_API_KEY: 'local-dev-key',
+    EMBEDDING_DIMENSIONS: '384',
+    EMBEDDING_MODEL: 'Xenova/all-MiniLM-L6-v2',
+    EMBEDDING_PROVIDER: 'transformers',
+    LLM_PROVIDER: 'claude-code',
+    PORT: '3050',
+    RAW_STORAGE_DEPLOYMENT_ENV: 'local',
+    RAW_STORAGE_MODE: 'pointer_only',
+    STORAGE_KEY_HMAC_SECRET: '000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f',
+};
+function printHelp() {
+    console.log(`AtomicMemory Core
+
+Usage:
+  atomicmemory-core start [--profile local]
+  atomicmemory-core migrate [--profile local]
+
+Commands:
+  start      Start the HTTP API server
+  migrate    Apply the Postgres/pgvector schema
+
+Profiles:
+  local      Fill local-only defaults for port, auth, storage policy,
+             transformers embeddings, and Claude Code LLM.
+
+Required:
+  DATABASE_URL must point at a reachable Postgres database with pgvector.
+`);
+}
+export function parseCliArgs(argv) {
+    const [commandArg, ...rest] = argv;
+    return {
+        command: parseCommand(commandArg),
+        help: shouldShowHelp(argv, commandArg),
+        profile: parseProfile(rest),
+    };
+}
+function parseCommand(value) {
+    if (value === 'start' || value === 'migrate')
+        return value;
+    return null;
+}
+function shouldShowHelp(argv, commandArg) {
+    return argv.includes('--help') || argv.includes('-h') || !commandArg;
+}
+function parseProfile(argv) {
+    const profileIndex = argv.indexOf('--profile');
+    if (profileIndex < 0) {
+        assertNoUnknownArgs(argv);
+        return null;
+    }
+    const value = argv[profileIndex + 1];
+    if (value !== 'local')
+        throw new Error(`Unsupported profile: ${value ?? '<missing>'}`);
+    assertNoUnknownArgs([
+        ...argv.slice(0, profileIndex),
+        ...argv.slice(profileIndex + 2),
+    ]);
+    return value;
+}
+function assertNoUnknownArgs(argv) {
+    const unknown = argv.find((arg) => arg !== '--help' && arg !== '-h');
+    if (unknown)
+        throw new Error(`Unknown argument: ${unknown}`);
+}
+function applyLocalProfileDefaults() {
+    const applied = [];
+    for (const [key, value] of Object.entries(LOCAL_PROFILE_DEFAULTS)) {
+        if (process.env[key])
+            continue;
+        process.env[key] = value;
+        applied.push(key);
+    }
+    return applied;
+}
+function assertLocalProfileReady() {
+    if (process.env.DATABASE_URL)
+        return;
+    throw new Error("DATABASE_URL is required. For local testing, start Postgres/pgvector and set " +
+        "DATABASE_URL='postgresql://user:pass@host:5432/database'.");
+}
+async function runCommand(command) {
+    if (command === 'start') {
+        await import('./server.js');
+        return;
+    }
+    await import('./db/migrate.js');
+}
+async function main(argv) {
+    const parsed = parseCliArgs(argv);
+    if (parsed.help) {
+        printHelp();
+        return;
+    }
+    if (!parsed.command)
+        throw new Error(`Unknown command: ${argv[0]}`);
+    applyProfile(parsed.profile);
+    await runCommand(parsed.command);
+}
+function applyProfile(profile) {
+    if (profile !== 'local')
+        return;
+    const applied = applyLocalProfileDefaults();
+    if (applied.length > 0) {
+        console.log(`[cli] Applied local profile defaults: ${applied.join(', ')}`);
+    }
+    assertLocalProfileReady();
+}
+function isEntrypoint() {
+    const invokedPath = process.argv[1] ?? '';
+    return invokedPath === fileURLToPath(import.meta.url) || invokedPath.endsWith('/atomicmemory-core');
+}
+if (isEntrypoint()) {
+    main(process.argv.slice(2)).catch((err) => {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}