@atomicmemory/core 1.0.0

package/dist/config.d.ts

@@ -0,0 +1,680 @@
+/**
+ * Runtime configuration for the prototype backend.
+ * Loads validated env-backed defaults, then allows limited in-memory updates
+ * for local UI experimentation via PUT /v1/memories/config.
+ */
+import { type RetrievalProfile, type RetrievalProfileName } from './services/retrieval-profiles.js';
+import { type FilecoinProviderConfig } from './storage/providers/filecoin/config.js';
+export type EmbeddingProviderName = 'openai' | 'ollama' | 'openai-compatible' | 'transformers' | 'voyage';
+export type LLMProviderName = EmbeddingProviderName | 'groq' | 'anthropic' | 'google-genai' | 'claude-code';
+export type VectorBackendName = 'pgvector' | 'ruvector-mock' | 'zvec-mock';
+export type CrossEncoderDtype = 'auto' | 'fp32' | 'fp16' | 'q8' | 'int8' | 'uint8' | 'q4' | 'bnb4' | 'q4f16';
+/**
+ * Phases 1 + 3 of the large-file ingestion plan ship `pointer_only`
+ * and `managed_blob`. `inline_small_text` is reserved for a later
+ * phase — `parseRawStorageMode` rejects it explicitly.
+ */
+export type RawStorageMode = 'pointer_only' | 'managed_blob';
+/**
+ * Content-codec selector that sits between the upload service and the
+ * raw-content adapter. `none` is the pass-through (immediate providers'
+ * default); `aes_gcm` wraps the bytes in AES-256-GCM ciphertext so the
+ * adapter (and downstream content-addressing) only sees encrypted
+ * bytes. The codec keyring (`RAW_CONTENT_CODEC_KEYS` +
+ * `RAW_CONTENT_CODEC_ACTIVE_KEY_ID`) holds the rotation state.
+ */
+export type RawContentCodecName = 'none' | 'aes_gcm';
+/**
+ * Deployment-env classifier driving fail-closed policy decisions
+ * (plaintext-Filecoin escape hatch, error `.cause` sanitization).
+ * REQUIRED at startup; no `NODE_ENV` is read anywhere.
+ */
+export type RawStorageDeploymentEnv = 'production' | 'staging' | 'local';
+export interface RuntimeConfig {
+    databaseUrl: string;
+    openaiApiKey: string;
+    /**
+     * Shared API key required on every authenticated `/v1/*` request.
+     * Validated against `Authorization: Bearer <key>` by the
+     * `requireBearer` middleware. REQUIRED at startup in every
+     * environment; tests set it via `.env.test`. Operators rotate by
+     * restarting the server with a new value.
+     */
+    coreApiKey: string;
+    /**
+     * Hex-encoded secret used to derive per-user storage-key prefixes
+     * via HMAC-SHA256. Storage keys take the form `s/<32hex>/<uuid>.bin`
+     * where the 32 hex chars are the first 16 bytes of
+     * `HMAC_SHA256(secret, userId)`. REQUIRED whenever managed-mode
+     * storage is configured; pointer-only deployments still set it so
+     * the config gate is one consistent contract. Must be at least 64
+     * hex chars (32 bytes of entropy).
+     */
+    storageKeyHmacSecret: string;
+    port: number;
+    retrievalProfile: RetrievalProfileName;
+    retrievalProfileSettings: RetrievalProfile;
+    maxSearchResults: number;
+    similarityThreshold: number;
+    audnCandidateThreshold: number;
+    audnSafeReuseMinSimilarity: number;
+    crossAgentCandidateThreshold: number;
+    clarificationConflictThreshold: number;
+    adaptiveRetrievalEnabled: boolean;
+    adaptiveSimpleLimit: number;
+    adaptiveMediumLimit: number;
+    adaptiveComplexLimit: number;
+    adaptiveMultiHopLimit: number;
+    adaptiveAggregationLimit: number;
+    repairLoopEnabled: boolean;
+    hybridSearchEnabled: boolean;
+    repairLoopMinSimilarity: number;
+    repairSkipSimilarity: number;
+    mmrEnabled: boolean;
+    mmrLambda: number;
+    linkExpansionEnabled: boolean;
+    linkExpansionMax: number;
+    linkSimilarityThreshold: number;
+    scoringWeightSimilarity: number;
+    scoringWeightImportance: number;
+    scoringWeightRecency: number;
+    linkExpansionBeforeMMR: boolean;
+    pprEnabled: boolean;
+    pprDamping: number;
+    repairDeltaThreshold: number;
+    repairConfidenceFloor: number;
+    embeddingProvider: EmbeddingProviderName;
+    embeddingModel: string;
+    embeddingDimensions: number;
+    embeddingApiUrl?: string;
+    embeddingApiKey?: string;
+    voyageApiKey?: string;
+    voyageDocumentModel: string;
+    voyageQueryModel: string;
+    llmProvider: LLMProviderName;
+    llmModel: string;
+    llmApiUrl?: string;
+    llmApiKey?: string;
+    groqApiKey?: string;
+    ollamaBaseUrl: string;
+    vectorBackend: VectorBackendName;
+    skipVectorIndexes: boolean;
+    llmSeed?: number;
+    stagedLoadingEnabled: boolean;
+    retrievalTraceEnabled: boolean;
+    ingestTraceDir: string;
+    ingestTraceEnabled: boolean;
+    extractionCacheEnabled: boolean;
+    extractionCacheDir: string;
+    embeddingCacheEnabled: boolean;
+    chunkedExtractionEnabled: boolean;
+    chunkedExtractionFallbackEnabled: boolean;
+    chunkSizeTurns: number;
+    chunkOverlapTurns: number;
+    consensusExtractionEnabled: boolean;
+    consensusExtractionRuns: number;
+    observationDateExtractionEnabled: boolean;
+    quotedEntityExtractionEnabled: boolean;
+    entropyGateEnabled: boolean;
+    entropyGateThreshold: number;
+    entropyGateAlpha: number;
+    affinityClusteringThreshold: number;
+    affinityClusteringMinSize: number;
+    affinityClusteringBeta: number;
+    affinityClusteringTemporalLambda: number;
+    trustScoringEnabled: boolean;
+    trustScoreMinThreshold: number;
+    trustPenaltyEnabled: boolean;
+    auditLoggingEnabled: boolean;
+    decayCycleEnabled: boolean;
+    decayRetentionThreshold: number;
+    decayMinAgeDays: number;
+    memoryCapEnabled: boolean;
+    memoryCapMax: number;
+    memoryCapWarnRatio: number;
+    entityGraphEnabled: boolean;
+    entityResolutionThreshold: number;
+    entitySearchMinSimilarity: number;
+    lessonsEnabled: boolean;
+    lessonSimilarityThreshold: number;
+    consensusValidationEnabled: boolean;
+    consensusMinMemories: number;
+    queryExpansionEnabled: boolean;
+    queryExpansionMinSimilarity: number;
+    queryAugmentationEnabled: boolean;
+    queryAugmentationMaxEntities: number;
+    queryAugmentationMinSimilarity: number;
+    crossEncoderEnabled: boolean;
+    crossEncoderModel: string;
+    crossEncoderDtype: CrossEncoderDtype;
+    iterativeRetrievalEnabled: boolean;
+    namespaceClassificationEnabled: boolean;
+    fastAudnEnabled: boolean;
+    fastAudnDuplicateThreshold: number;
+    observationNetworkEnabled: boolean;
+    agenticRetrievalEnabled: boolean;
+    rerankSkipTopSimilarity: number;
+    rerankSkipMinGap: number;
+    literalListProtectionEnabled: boolean;
+    literalListProtectionMaxProtected: number;
+    temporalQueryConstraintEnabled: boolean;
+    temporalQueryConstraintBoost: number;
+    deferredAudnEnabled: boolean;
+    deferredAudnBatchSize: number;
+    compositeGroupingEnabled: boolean;
+    compositeMinClusterSize: number;
+    compositeMaxClusterSize: number;
+    compositeSimilarityThreshold: number;
+    anthropicApiKey?: string;
+    googleApiKey?: string;
+    costLoggingEnabled: boolean;
+    costLogDir: string;
+    costRunId: string;
+    conflictAutoResolveMs: number;
+    /**
+     * Typed Belief Calculus (TBC) gate. When true, the AUDN decision step
+     * defers to `decideBeliefOperator` from `services/typed-belief-calculus.ts`.
+     * Default false — Phase 1 ships only the type surface and stub resolver,
+     * so existing AUDN behavior is unchanged. See `docs/typed-belief-calculus.md`.
+     */
+    tbcEnabled: boolean;
+    /**
+     * Hierarchical retrieval (T2): adds a 5th RRF arm that searches over
+     * conversation/session summaries first, then expands to atomic facts within
+     * the matched sessions. Targets BEAM-10M scale (~14M tokens of context per
+     * system) where flat top-K retrieval loses signal.
+     * Default false. See `docs/hierarchical-retrieval.md`.
+     * Env var: HIERARCHICAL_RETRIEVAL_ENABLED=true
+     */
+    hierarchicalRetrievalEnabled: boolean;
+    /**
+     * Topic abstraction layer (Sprint 3 EO experiment): when true, ingest runs
+     * a second LLM pass per chunk to extract a 3-7 word conceptual topic, embeds
+     * it, and stores both alongside the raw fact. Retrieval fuses a topic-
+     * embedding similarity stream into RRF when topicSearchEnabled is also true.
+     * Default false. Design: benchmarks-sprint3/2026-05-10-am-baseline-and-rerank-design.md.
+     * Env var: TOPIC_ABSTRACTION_ENABLED=true
+     */
+    topicAbstractionEnabled: boolean;
+    /**
+     * Topic search arm: when true (and topic_embedding column populated), the
+     * search pipeline adds a topic-similarity RRF channel. Independent of the
+     * ingest-side flag so the retrieval lift can be measured against pre-existing
+     * topic-augmented memory state.
+     * Default false. Env var: TOPIC_SEARCH_ENABLED=true
+     */
+    topicSearchEnabled: boolean;
+    /**
+     * Cross-encoder reranker: when true, the search pipeline reranks the top-N
+     * RRF-fused candidates via an LLM-scored relevance pass. Adds ~50-150 ms
+     * p95 retrieve latency. Mirrors Hindsight's reranking layer.
+     * Default false. Env var: RERANKER_ENABLED=true
+     */
+    rerankerEnabled: boolean;
+    /** Top-N candidates fed into the reranker (default 20). Env: RERANKER_TOP_N */
+    rerankerTopN: number;
+    /**
+     * Recap layer (Sprint 3 v1, cross-session synthesis): when true, the
+     * post-write pipeline opportunistically synthesizes Recaps from clusters
+     * of memories sharing a topic_abstraction. Recaps are surfaced via their
+     * own RRF channel at retrieval. Cog-sci analogue: hippocampal consolidation.
+     * Requires topicAbstractionEnabled=true (clusters by topic field).
+     * Default false. Env var: RECAP_LAYER_ENABLED=true
+     */
+    recapLayerEnabled: boolean;
+    /** Min cluster size for recap building (default 4). Env: RECAP_MIN_CLUSTER_SIZE */
+    recapMinClusterSize: number;
+    /**
+     * Recap cluster pivot (Sprint 3 v1.1 — V2 backlog #2).
+     *   'topic'   — group by topic_abstraction (original; needs topic-abstraction
+     *               layer ON; empirically regressed fact abilities).
+     *   'session' — group by user_id + observed_at hour bucket (doesn't need
+     *               topic-abstraction; captures cross-turn aggregation in a
+     *               conversational window).
+     * Default 'topic' to preserve existing behavior. Env: RECAP_CLUSTER_PIVOT
+     */
+    recapClusterPivot: 'topic' | 'session';
+    /** When true, search pipeline adds a recap-similarity RRF channel.
+     * Independent of layer flag so retrieval can be measured against pre-existing
+     * recap state. Default false. Env: RECAP_SEARCH_ENABLED=true */
+    recapSearchEnabled: boolean;
+    /**
+     * Counter-evidence retrieval (Sprint 3 v1.1 — V2 backlog item 1): when
+     * true, the search pipeline expands the top-K result set with memories
+     * that COUNTER any retrieved memory via the belief_edges graph. Surfaces
+     * both sides of contradictions for CR-style queries.
+     * Requires TBC to have been ON at ingest (populates belief_edges).
+     * Default false. Env: COUNTER_EVIDENCE_ENABLED=true
+     */
+    counterEvidenceEnabled: boolean;
+    /**
+     * Temporal-aware packaging (Sprint 3 v1.2 — EO failure-mode fix).
+     * When true, retrieval-format.ts surfaces `observed_at` (the
+     * conversation timestamp captured during ingest) instead of
+     * `created_at` (the ingest wall-clock) for:
+     *   - chronological sort of the injection block
+     *   - the per-memory date attribute
+     *   - the Timeline summary
+     * This restores within-conversation turn order for BEAM-style
+     * backloaded ingestion where many turns share a single ingest time.
+     * Default false (preserves existing behavior). Env:
+     * PACKAGING_USE_OBSERVED_AT=true
+     */
+    packagingUseObservedAt: boolean;
+    /**
+     * Dual-date packaging (Sprint 3 v1.3 — companion to packagingUseObservedAt).
+     * When true, retrieval-format.ts emits BOTH `created_at` and `observed_at`
+     * attributes on every `<memory>` element when they differ. Lets the answer
+     * LLM see ingest time AND conversation time and decide which to weight
+     * per question, instead of forcing a global swap.
+     * Independent of `packagingUseObservedAt` (which controls sort + label
+     * date). Default false. Env: PACKAGING_DUAL_DATE=true
+     */
+    packagingDualDate: boolean;
+    /**
+     * Timeline channel (Sprint 3 v1.4 — H3 from haiku-080 master plan).
+     * When true, retrieval-format.ts emits an additional `## TIMELINE`
+     * section in the injection text. Dates are derived from observed_at
+     * across the retrieved set, sorted ascending, deduplicated.
+     * Independent of packagingUseObservedAt and packagingDualDate.
+     * Default false. Env: TIMELINE_CHANNEL_ENABLED=true
+     */
+    timelineChannelEnabled: boolean;
+    /**
+     * Answer-only retrieval filter (Sprint 4 iter 1). When true, drop
+     * advisory-only memories from the retrieved set before formatting the
+     * injection. Insight: Sprint 3 incorrect-case analysis showed
+     * retrieved contexts mixed verbose [context] snippets with specific
+     * [answer] facts, and Haiku weighted the former over the latter.
+     * Failsafe: if <3 memories survive the filter, falls back to the
+     * unfiltered set. Default false. Env: ANSWER_ONLY_RETRIEVAL_FILTER=true
+     */
+    answerOnlyRetrievalFilter: boolean;
+    /**
+     * Near-duplicate dedup at retrieval (Sprint 4 iter 2). When true,
+     * deduplicate retrieved memories by content fingerprint (lowercased
+     * alphanumeric prefix of first 80 chars). Sprint 3 showed retrieved
+     * contexts had same fact in 3-5 paraphrases per query; dedup makes
+     * room for diverse memories.
+     * Failsafe: if <3 memories survive, falls back to unfiltered set.
+     * Default false. Env: RETRIEVAL_DEDUP_ENABLED=true
+     */
+    retrievalDedupEnabled: boolean;
+    /**
+     * BM25 keyword RRF weight (Sprint 4 iter 3). Default 1.0 (existing
+     * behavior). Boosting to 1.5-2.0 prioritizes keyword/BM25 matches in
+     * the hybrid RRF fan-in. Useful for queries that ask for specific
+     * named facts ("how many X", "what is Y"). Only fires when
+     * hybridSearchEnabled is true. Env: KEYWORD_RRF_WEIGHT=1.5
+     */
+    keywordRrfWeight: number;
+    /**
+     * Entity-Attribute Index (EAI — Sprint 4). When true, ingest extracts
+     * (entity, attribute, value) triples into the `entity_attributes` table
+     * and retrieval queries that table for fact-specific lookups (e.g.
+     * "how many columns did I add?", "what's the API quota?"). Storage
+     * foundation lands first; extraction (Task B) and retrieval (Task C)
+     * activate the channel.
+     * Default false. Env var: ENTITY_ATTRIBUTES_ENABLED=true
+     */
+    entityAttributesEnabled: boolean;
+    /**
+     * Top-K EAI rows to fetch when the entity-attributes channel is enabled
+     * (Sprint 4 — Task C). Clamped to [5, 40] inside `fetchEntityFactsForInjection`
+     * — too few drops near-misses, too many bloats the `## FACTS` block.
+     * Default 20. Env: ENTITY_ATTRIBUTES_TOP_K=20
+     */
+    entityAttributesTopK: number;
+    /**
+     * User-profile channel (Sprint 3 v1.5 — H2 from haiku-080 master plan).
+     * When true, post-write synthesizes a per-user profile document
+     * (Honcho-style) after each ingest that stores >= 3 new memories.
+     * The search pipeline prepends the profile as a `## USER PROFILE`
+     * block at the head of every answer prompt.
+     * Default false. Env: USER_PROFILE_CHANNEL_ENABLED=true
+     */
+    userProfileChannelEnabled: boolean;
+    /**
+     * Episodes-as-separate-channel (Sprint 3 v1.6 — H4 from haiku-080 master
+     * plan). When true, the search pipeline fetches the top-K recap rows for
+     * the query embedding via `RecapStore.findRecapCandidates` and threads
+     * them through the injection builder as a dedicated `## EPISODES` block,
+     * INSTEAD OF routing recaps through the RRF fan-in. Sprint 3 v1.1
+     * documented that the RRF route displaced 3-5 atomic facts per recap in
+     * top-K and regressed fact-anchored abilities; this flag lets recap
+     * narrative surface to the answer LLM without paying that displacement
+     * cost. Independent of `recapSearchEnabled` (recap-via-RRF) — typical
+     * config has the layer ON, recap-search OFF, and episodes-channel ON.
+     * Default false. Env: EPISODES_CHANNEL_ENABLED=true
+     */
+    episodesChannelEnabled: boolean;
+    /**
+     * Top-K recap rows to fetch when the episodes channel is enabled.
+     * Default 2. Clamped to [1, 5] inside memory-search to bound prompt
+     * growth — large K dilutes the channel signal without lifting recall.
+     * Env: EPISODES_CHANNEL_TOP_K=2
+     */
+    episodesChannelTopK: number;
+    /**
+     * Verifier pass (Sprint 3 v1.7 — H5 from haiku-080 master plan).
+     * Informational flag from AM core's perspective — the AMB adapter
+     * inspects `ATOMICMEMORY_VERIFIER_ENABLED` to decide whether to call
+     * `/v1/memories/verify` between its answer-LLM call and scoring. The
+     * flag is surfaced in core config for symmetry with the other channel
+     * flags so iteration env files can request the verifier pass.
+     * Default false. Env: VERIFIER_PASS_ENABLED=true
+     */
+    verifierPassEnabled: boolean;
+    /**
+     * Layer 1 answer-format alignment (BEAM-0.85 Phase 0): when true,
+     * `buildInjection` prepends a per-question-type FORMAT hint to the
+     * injection prompt so the answer LLM produces structured output that
+     * matches the query shape (e.g. ordered lists, yes/no, prose).
+     * Default false. Env: ANSWER_FORMAT_ALIGNMENT_ENABLED=true
+     */
+    answerFormatAlignmentEnabled: boolean;
+    /**
+     * Event-chain packaging (EO fix — data-driven detector). When true,
+     * `buildInjection` prepends a `## EVENT_CHAIN` block listing the
+     * chronological chain with the highest score detected in the retrieved
+     * top-K. The detector fires regardless of query phrasing — it inspects
+     * the retrieved data for 3+ memories sharing an entity across 3+ distinct
+     * observed_at dates. Default false (ships behind flag for incremental
+     * validation). Env: EVENT_CHAIN_PACKAGING_ENABLED=true
+     */
+    eventChainPackagingEnabled: boolean;
+    /**
+     * Reflect channel — query-time reflection retrieval (BEAM-0.85 Phase 1,
+     * Task 1.9). When true, after RRF + reranking produce the selected memories,
+     * the search pipeline also embeds the query and fetches top-K reflections
+     * from session_reflections. The result is threaded downstream to
+     * retrieval-format as a parallel signal alongside chainResult.
+     * Gated by question type (SUMMARY, CONTRADICTION, PREFERENCE, NUMERIC_COUNT,
+     * EXACT_DATE, ORDERED_LIST — see reflect-retrieval.ts ROUTED_TYPES).
+     * Default false. Env: REFLECT_ENABLED=true
+     */
+    reflectEnabled: boolean;
+    /**
+     * Top-K reflections to fetch when reflect retrieval is enabled.
+     * Default 3. Env: REFLECT_RETRIEVAL_TOP_K=3
+     */
+    reflectRetrievalTopK: number;
+    /**
+     * Anthropic model used by the reflect worker for observation generation.
+     * Default 'claude-sonnet-4-5'. Env: REFLECT_MODEL=<model-id>
+     */
+    reflectModel: string;
+    /**
+     * Maximum observations per conversation the reflect worker will persist.
+     * Default 12. Env: REFLECT_MAX_OBSERVATIONS=12
+     */
+    reflectMaxObservations: number;
+    /**
+     * Polling interval (ms) for the reflect background worker.
+     * Default 5000. Env: REFLECT_JOB_POLL_MS=5000
+     */
+    reflectJobPollMs: number;
+    /**
+     * Debounce delay (ms) before a reflect job becomes eligible for processing.
+     * Not enforced in v1 worker but reserved for future use.
+     * Default 60000. Env: REFLECT_DEBOUNCE_MS=60000
+     */
+    reflectDebounceMs: number;
+    /**
+     * Dev/test-only: when true, PUT /v1/memories/config mutates the runtime
+     * singleton. Production deploys leave this unset (false) — the route
+     * returns 410 Gone. Startup-validated; routes read the memoized value
+     * through configRouteAdapter, never re-check at request time.
+     */
+    runtimeConfigMutationEnabled: boolean;
+    /**
+     * Phase 2 specialists gate (BEAM-0.85 Phase 2). When true, the specialist
+     * dispatcher runs after RRF + reranking produce top-K memories. The first
+     * specialist that matches the query pattern AND returns handled=true
+     * short-circuits the shared spine — its answer replaces the LLM output.
+     * Ingest-side: extractLiteralsFromFact runs fire-and-forget per new
+     * memory to populate entity_values for the IE/KU SQL lookup.
+     * Priority: CR → TR → MSR → IE/KU → shared spine.
+     * Default false. Env: PHASE2_SPECIALISTS_ENABLED=true
+     */
+    phase2SpecialistsEnabled: boolean;
+    /**
+     * Master gate for all three abstention-rescue interventions.
+     * Compensates for Haiku over-abstention: the model writes answers like
+     * "context does not contain information (March 10, 2024)" — citing the
+     * answer while claiming not to find it.
+     * Interventions (all gated here):
+     *   1. Confidence prefix — prepended to injectionText on every call.
+     *   2. Iterative retrieval — second retrieval pass with extracted keywords
+     *      when the first answer abstains and retrieval was non-empty.
+     *   3. Sonnet rescue — retry with Sonnet if Haiku still abstains.
+     * Default false. Env: ABSTENTION_RESCUE_ENABLED=true
+     */
+    abstentionRescueEnabled: boolean;
+    /** Top-K for the iterative-retrieval rescue pass. Default 8. Env: ABSTENTION_RESCUE_RETRIEVE_K */
+    abstentionRescueRetrieveK: number;
+    /** Model used for the Sonnet rescue step. Default 'claude-sonnet-4-5'. Env: ABSTENTION_RESCUE_SONNET_MODEL */
+    abstentionRescueSonnetModel: string;
+    /**
+     * Per-question-type adaptive confidence prefix (v36). When true, the forced
+     * FORBIDDEN-abstention prefix only applies to SUMMARY/PREFERENCE/
+     * NUMERIC_COUNT/EXACT_DATE (where v34 showed +0.09 to +0.27 lifts); a soft
+     * prefix (rubric phrasing + KU temporal anchor, no FORBIDDEN block) applies
+     * to ORDERED_LIST/CONTRADICTION/OTHER (where v34 regressed −0.13 to −0.22
+     * by fabricating); ABSTAIN passes through unchanged. Requires
+     * `abstentionRescueEnabled=true`. Default false. Env:
+     * CONFIDENCE_PREFIX_ADAPTIVE_ENABLED=true
+     */
+    confidencePrefixAdaptiveEnabled: boolean;
+    /**
+     * KU recency sort (v42). When true, NUMERIC_COUNT queries that ALSO match
+     * the KU-style framing pattern (isKuStyleQuery) reorder packaged retrieval
+     * by observed_at DESC before injection — so the answer LLM sees the most
+     * recent measurement first. Targets BEAM KU Mode B (wrong-value-forced)
+     * where Haiku picks the earlier of two competing values. Default false.
+     * Env: KU_RECENCY_SORT_ENABLED=true
+     */
+    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. Retrieved memories are
+     * grouped by `episode_id`; groups with >=2 memories are summarized via the
+     * configured chat LLM (default Haiku, ~30 tokens each); 1-memory groups
+     * pass through verbatim. Targets BEAM MSR (v36: 0.156/0.172) where gold
+     * facts span 2-4 conversations and the answer LLM cannot synthesize across
+     * them. Fail-closed on summary errors. Default false. Env:
+     * MSR_AGGREGATOR_ENABLED=true
+     */
+    msrAggregatorEnabled: boolean;
+    /**
+     * Always-on ENTITY_CARD channel (BEAM-0.85 — Honcho parity). When true,
+     * the Reflect worker synthesizes per-entity summary cards alongside the
+     * existing observations, and the search pipeline injects all cards for
+     * the active conversation under `## ENTITY_STATE` at the top of every
+     * answer-LLM prompt. Default false. Env: ENTITY_CARD_ENABLED=true
+     */
+    entityCardEnabled: boolean;
+    /** Max entity cards synthesized per Reflect run. Default 5. Env: ENTITY_CARD_MAX_PER_SESSION */
+    entityCardMaxPerSession: number;
+    /**
+     * Minimum observations an entity needs in a Reflect run before its card
+     * is synthesized. Default 3. Env: ENTITY_CARD_MIN_OBSERVATIONS
+     */
+    entityCardMinObservations: number;
+    /**
+     * AUDN bilateral preservation for contradictions (BEAM CR fix). When true,
+     * AUDN's DELETE and SUPERSEDE outcomes are replaced by a bilateral path
+     * that keeps BOTH the prior memory and the new memory in `memories`,
+     * marks both with `contradiction_active=true` and bidirectional
+     * `contradicts_memory_id`, and records the pair in
+     * `memory_contradictions`. Targets the BEAM `contradiction_resolution`
+     * rubric, which requires the answer to quote BOTH sides verbatim.
+     * Default false. Env: CONTRADICTION_PRESERVATION_ENABLED=true
+     */
+    contradictionPreservationEnabled: boolean;
+    /**
+     * Retrieval-side surfacing of contradictions (BEAM CR fix). When true,
+     * after top-K assembly the search pipeline enriches the result set:
+     *   - any memory in top-K with `contradiction_active=true` has its
+     *     counterpart (`contradicts_memory_id`) injected into the final set,
+     *   - a `## CONTRADICTIONS_DETECTED` section listing both sides verbatim
+     *     is prepended to the injection text.
+     * Independent of `contradictionPreservationEnabled` so the retrieval
+     * lift can be measured against pre-existing contradiction state.
+     * Default false. Env: CONTRADICTION_SURFACING_ENABLED=true
+     */
+    contradictionSurfacingEnabled: boolean;
+    /**
+     * BEAM v38: temporal state layer (focused Mem0 temporal-reasoning subset).
+     * When true:
+     *   - At ingest, an LLM classifier tags each stored memory with a stable
+     *     `state_key` for stateful facts (e.g. "user lives in Austin"); newly
+     *     stored stateful memories supersede prior memories with the same key
+     *     by setting their `event_end` to the new `event_start`.
+     *   - At read, a regex-based intent classifier flags CURRENT_STATE
+     *     queries; the retrieval pipeline reranks candidates so memories with
+     *     active state (`event_end IS NULL`) outrank superseded ones.
+     * Targets the KU rubric (currently 0.25). Fail-closed: supersede UPDATE
+     * failures abort the ingest. Default false. Env: TEMPORAL_STATE_ENABLED=true
+     */
+    temporalStateEnabled: boolean;
+    /**
+     * Document raw-content retention mode. `pointer_only` registers
+     * external references; `managed_blob` stores bytes through the
+     * configured raw-storage provider. `inline_small_text` is reserved.
+     */
+    rawStorageMode: RawStorageMode;
+    /**
+     * Adapter behind `rawStorageMode = 'managed_blob'`. NULL for the
+     * pointer-only path; required at startup when `rawStorageMode =
+     * 'managed_blob'`. No fallback — misconfigured setups fail closed.
+     */
+    rawStorageProvider: RawStorageProvider | null;
+    /** Optional global path prefix (e.g. `prod/core`) applied to every key. */
+    rawStoragePrefix: string;
+    /** Provider-specific options. Always populated, validated at startup. */
+    rawStorageLocalFsRoot: string | null;
+    rawStorageS3Bucket: string | null;
+    rawStorageS3Region: string | null;
+    rawStorageS3Endpoint: string | null;
+    rawStorageS3AccessKeyId: string | null;
+    rawStorageS3SecretAccessKey: string | null;
+    /** Per-request upload size cap for `PUT /v1/documents/:id/raw`. */
+    rawUploadMaxBytes: number;
+    /** Content codec applied between the upload service and the raw-content adapter. */
+    rawContentCodec: RawContentCodecName;
+    /**
+     * Parsed keyring entries keyed by operator-assigned id. Required and
+     * non-empty when `rawContentCodec='aes_gcm'`. Each value is a 32-byte
+     * key. Keys are kept in the ring so old rows stay decodable after
+     * rotation; new writes use `rawContentCodecActiveKeyId`.
+     */
+    rawContentCodecKeys: ReadonlyMap<string, Buffer>;
+    /** Key id chosen for NEW encode operations. Must reference an entry in the ring. */
+    rawContentCodecActiveKeyId: string | null;
+    /** Required at startup; drives fail-closed policy in cross-validation. */
+    rawStorageDeploymentEnv: RawStorageDeploymentEnv;
+    /**
+     * Parsed Synapse-shaped Filecoin provider config. Populated only
+     * when `rawStorageProvider === 'filecoin'`; `null` otherwise. The
+     * cross-provider guard in `validateRawStorageConfig` rejects any
+     * `RAW_STORAGE_FILECOIN_*` env var on non-filecoin deployments
+     * before this field is computed, so the operator cannot leave
+     * stale Filecoin knobs lying around.
+     */
+    filecoinProvider: FilecoinProviderConfig | null;
+    /**
+     * CSV of legacy providers kept registered as read-only stores so the
+     * cleanup-time registry can dispatch DELETEs against historical rows
+     * after the active provider has been switched. Validated for env-block
+     * completeness at startup. Never contains the active provider.
+     */
+    rawStorageLegacyProviders: ReadonlyArray<RawStorageProvider>;
+    /**
+     * Closed allowlist of pointer-mode URI schemes the direct storage
+     * API accepts. Defaults to the safe set `https://, s3://, gs://,
+     * ipfs://`. Operators can opt in `http://` and `local-fs://` via
+     * `RAW_STORAGE_POINTER_URI_SCHEMES` (csv). Unknown tokens fail
+     * closed at startup. The server NEVER fetches pointer URIs — this
+     * is downstream-consumer hygiene, not SSRF defence.
+     */
+    rawStoragePointerUriSchemes: ReadonlyArray<PointerUriScheme>;
+}
+/** Closed set of pointer-mode URI schemes operators can allowlist. */
+export type PointerUriScheme = 'https' | 's3' | 'gs' | 'ipfs' | 'http' | 'local-fs';
+/** Production providers backing `rawStorageMode='managed_blob'`. */
+export type RawStorageProvider = 'local_fs' | 's3' | 'filecoin';
+/**
+ * Fields accepted by `updateRuntimeConfig()`. Provider/model selection
+ * (embeddingProvider, embeddingModel, voyage*, llmProvider, llmModel) is
+ * intentionally absent: embedding.ts and llm.ts cache stateful provider
+ * instances at first call, so mid-flight mutation never took effect in v1.
+ * Freezing these as composition-time config is a bug fix. Server deployments
+ * still use env-backed startup config; isolated harnesses can pass an explicit
+ * RuntimeConfig to createCoreRuntime({ config }).
+ */
+export interface RuntimeConfigUpdates {
+    similarityThreshold?: number;
+    audnCandidateThreshold?: number;
+    clarificationConflictThreshold?: number;
+    maxSearchResults?: number;
+}
+/**
+ * Cross-field guard for the raw-storage knobs. Runs once at startup and
+ * fails closed when `managed_blob` is enabled without the provider
+ * fields the chosen adapter needs. No default values, no fallback
+ * provider — misconfiguration must surface deterministically per the
+ * Phase-3 plan.
+ */
+export interface RawStorageValidationInput {
+    mode: RawStorageMode;
+    provider: RawStorageProvider | null;
+    prefix: string;
+    localFsRoot: string | null;
+    s3Bucket: string | null;
+    s3Region: string | null;
+    s3AccessKeyId: string | null;
+    s3SecretAccessKey: string | null;
+    codec: RawContentCodecName;
+    codecKeys: ReadonlyMap<string, Buffer>;
+    codecActiveKeyId: string | null;
+    deploymentEnv: RawStorageDeploymentEnv;
+    legacyProviders: ReadonlyArray<RawStorageProvider>;
+    /**
+     * Names of `RAW_STORAGE_FILECOIN_*` env vars the operator set to a
+     * non-empty value, computed by
+     * `collectFilecoinProviderEnvKeys(process.env)` in `src/config.ts`.
+     * The cross-provider guard in `validateRawStorageConfig` rejects
+     * any non-empty list when `provider !== 'filecoin'`. Tests pass a
+     * fixed array directly.
+     */
+    filecoinEnvKeysSet: ReadonlyArray<string>;
+}
+export declare function validateRawStorageConfig(args: RawStorageValidationInput): void;
+export declare const config: RuntimeConfig;
+export declare function applyRuntimeConfigUpdates(target: RuntimeConfig, updates: RuntimeConfigUpdates): string[];
+export declare function updateRuntimeConfig(updates: RuntimeConfigUpdates): string[];
+/**
+ * Public/supported operator config surface. Fields listed here are part of
+ * v2's stable contract: consumers can rely on their semantics and presence,
+ * and changes go through a documented deprecation cycle.
+ *
+ * This is a documentation type — it does not constrain threading. The runtime
+ * still carries a single `RuntimeConfig` object; this array tags the public
+ * subset so docs, tests, and future config-split work have a single source of
+ * truth. See also: https://docs.atomicmemory.ai/platform/consuming-core.
+ */
+export declare const SUPPORTED_RUNTIME_CONFIG_FIELDS: readonly ["databaseUrl", "openaiApiKey", "coreApiKey", "storageKeyHmacSecret", "port", "embeddingProvider", "embeddingModel", "embeddingDimensions", "embeddingApiUrl", "embeddingApiKey", "voyageApiKey", "voyageDocumentModel", "voyageQueryModel", "llmProvider", "llmModel", "llmApiUrl", "llmApiKey", "groqApiKey", "anthropicApiKey", "googleApiKey", "ollamaBaseUrl", "vectorBackend", "skipVectorIndexes", "llmSeed", "crossEncoderModel", "crossEncoderDtype", "maxSearchResults", "retrievalProfile", "retrievalProfileSettings", "entityGraphEnabled", "lessonsEnabled", "agenticRetrievalEnabled", "iterativeRetrievalEnabled", "hybridSearchEnabled", "repairLoopEnabled", "crossEncoderEnabled", "auditLoggingEnabled", "adaptiveRetrievalEnabled", "consensusValidationEnabled", "namespaceClassificationEnabled", "extractionCacheDir", "costLogDir", "costRunId", "costLoggingEnabled", "runtimeConfigMutationEnabled"];
+/**
+ * Internal policy config — experimental / tuning flags. Fields here may
+ * change semantics, defaults, or be removed without notice. Consumers should
+ * NOT rely on these in production. Promoted into the supported contract when
+ * a field's behavior stabilizes.
+ */
+export declare const INTERNAL_POLICY_CONFIG_FIELDS: readonly ["similarityThreshold", "audnCandidateThreshold", "audnSafeReuseMinSimilarity", "crossAgentCandidateThreshold", "clarificationConflictThreshold", "repairLoopMinSimilarity", "repairSkipSimilarity", "repairDeltaThreshold", "repairConfidenceFloor", "adaptiveSimpleLimit", "adaptiveMediumLimit", "adaptiveComplexLimit", "adaptiveMultiHopLimit", "adaptiveAggregationLimit", "mmrEnabled", "mmrLambda", "linkExpansionEnabled", "linkExpansionMax", "linkSimilarityThreshold", "linkExpansionBeforeMMR", "scoringWeightSimilarity", "scoringWeightImportance", "scoringWeightRecency", "pprEnabled", "pprDamping", "stagedLoadingEnabled", "retrievalTraceEnabled", "ingestTraceDir", "ingestTraceEnabled", "extractionCacheEnabled", "embeddingCacheEnabled", "chunkedExtractionEnabled", "chunkedExtractionFallbackEnabled", "chunkSizeTurns", "chunkOverlapTurns", "consensusExtractionEnabled", "consensusExtractionRuns", "observationDateExtractionEnabled", "quotedEntityExtractionEnabled", "entropyGateEnabled", "entropyGateThreshold", "entropyGateAlpha", "affinityClusteringThreshold", "affinityClusteringMinSize", "affinityClusteringBeta", "affinityClusteringTemporalLambda", "trustScoringEnabled", "trustScoreMinThreshold", "trustPenaltyEnabled", "decayCycleEnabled", "decayRetentionThreshold", "decayMinAgeDays", "memoryCapEnabled", "memoryCapMax", "memoryCapWarnRatio", "entityResolutionThreshold", "entitySearchMinSimilarity", "lessonSimilarityThreshold", "consensusMinMemories", "queryExpansionEnabled", "queryExpansionMinSimilarity", "queryAugmentationEnabled", "queryAugmentationMaxEntities", "queryAugmentationMinSimilarity", "rerankSkipTopSimilarity", "rerankSkipMinGap", "literalListProtectionEnabled", "literalListProtectionMaxProtected", "temporalQueryConstraintEnabled", "temporalQueryConstraintBoost", "fastAudnEnabled", "fastAudnDuplicateThreshold", "observationNetworkEnabled", "deferredAudnEnabled", "deferredAudnBatchSize", "compositeGroupingEnabled", "compositeMinClusterSize", "compositeMaxClusterSize", "compositeSimilarityThreshold", "conflictAutoResolveMs", "tbcEnabled", "hierarchicalRetrievalEnabled", "topicAbstractionEnabled", "topicSearchEnabled", "rerankerEnabled", "rerankerTopN", "recapLayerEnabled", "recapMinClusterSize", "recapSearchEnabled", "recapClusterPivot", "counterEvidenceEnabled", "packagingUseObservedAt", "packagingDualDate", "timelineChannelEnabled", "answerOnlyRetrievalFilter", "retrievalDedupEnabled", "keywordRrfWeight", "entityAttributesEnabled", "entityAttributesTopK", "userProfileChannelEnabled", "episodesChannelEnabled", "episodesChannelTopK", "verifierPassEnabled", "answerFormatAlignmentEnabled", "eventChainPackagingEnabled", "reflectEnabled", "reflectRetrievalTopK", "reflectModel", "reflectMaxObservations", "reflectJobPollMs", "reflectDebounceMs", "phase2SpecialistsEnabled", "abstentionRescueEnabled", "abstentionRescueRetrieveK", "abstentionRescueSonnetModel", "confidencePrefixAdaptiveEnabled", "kuRecencySortEnabled", "msrAggregatorEnabled", "entityCardEnabled", "entityCardMaxPerSession", "entityCardMinObservations", "contradictionPreservationEnabled", "contradictionSurfacingEnabled", "temporalStateEnabled", "rawStorageMode", "rawStorageProvider", "rawStoragePrefix", "rawStorageLocalFsRoot", "rawStorageS3Bucket", "rawStorageS3Region", "rawStorageS3Endpoint", "rawStorageS3AccessKeyId", "rawStorageS3SecretAccessKey", "rawUploadMaxBytes", "rawContentCodec", "rawContentCodecKeys", "rawContentCodecActiveKeyId", "rawStorageDeploymentEnv", "filecoinProvider", "rawStorageLegacyProviders", "rawStoragePointerUriSchemes"];
+export type SupportedRuntimeConfigField = typeof SUPPORTED_RUNTIME_CONFIG_FIELDS[number];
+export type InternalPolicyConfigField = typeof INTERNAL_POLICY_CONFIG_FIELDS[number];
+export type SupportedRuntimeConfig = Pick<RuntimeConfig, SupportedRuntimeConfigField>;
+export type InternalPolicyConfig = Pick<RuntimeConfig, InternalPolicyConfigField>;