@atomicmemory/core 1.0.0

package/dist/config.js

@@ -0,0 +1,808 @@
+/**
+ * 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 { getRetrievalProfile, parseRetrievalProfile, } from './services/retrieval-profiles.js';
+import { parsePointerUriSchemes } from './storage/pointer-uri-allowlist.js';
+import { collectFilecoinProviderEnvKeys, parseFilecoinProviderConfig, } from './storage/providers/filecoin/config.js';
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+function optionalEnv(name) {
+    return process.env[name] || undefined;
+}
+function parseEmbeddingProvider(value, fallback) {
+    if (!value)
+        return fallback;
+    const valid = ['openai', 'ollama', 'openai-compatible', 'transformers', 'voyage'];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid provider "${value}". Must be one of: ${valid.join(', ')}`);
+    }
+    return value;
+}
+function parseLlmProvider(value, fallback) {
+    if (!value)
+        return fallback;
+    const valid = [
+        'openai',
+        'ollama',
+        'openai-compatible',
+        'groq',
+        'anthropic',
+        'google-genai',
+        'claude-code',
+    ];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid provider "${value}". Must be one of: ${valid.join(', ')}`);
+    }
+    return value;
+}
+function defaultLlmModel(provider) {
+    if (provider === 'claude-code')
+        return '';
+    return 'gpt-4o-mini';
+}
+function requireFiniteNumber(value, field) {
+    if (!Number.isFinite(value)) {
+        throw new Error(`${field} must be a finite number`);
+    }
+    return value;
+}
+function parseCrossEncoderDtype(value) {
+    const dtype = value ?? 'auto';
+    const valid = ['auto', 'fp32', 'fp16', 'q8', 'int8', 'uint8', 'q4', 'bnb4', 'q4f16'];
+    if (!valid.includes(dtype)) {
+        throw new Error(`Invalid CROSS_ENCODER_DTYPE "${dtype}". Must be one of: ${valid.join(', ')}`);
+    }
+    return dtype;
+}
+function parseLlmSeed(value) {
+    if (!value)
+        return undefined;
+    const parsed = parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function parsePositiveIntEnv(name, fallback) {
+    const raw = optionalEnv(name);
+    if (!raw)
+        return fallback;
+    const parsed = parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return parsed;
+}
+function parseVectorBackend(value) {
+    if (!value)
+        return 'pgvector';
+    if (value === 'pgvector' || value === 'ruvector-mock' || value === 'zvec-mock')
+        return value;
+    throw new Error('Invalid VECTOR_BACKEND. Must be "pgvector", "ruvector-mock", or "zvec-mock"');
+}
+/**
+ * Phases 1 + 3 of the large-file ingestion plan accept `pointer_only`
+ * and `managed_blob` respectively. `inline_small_text` is reserved for
+ * a later phase — fail closed rather than silently downgrading if an
+ * operator sets it now.
+ */
+function parseRawStorageMode(value) {
+    if (!value || value === 'pointer_only')
+        return 'pointer_only';
+    if (value === 'managed_blob')
+        return 'managed_blob';
+    if (value === 'inline_small_text') {
+        throw new Error("RAW_STORAGE_MODE='inline_small_text' is not yet supported. Use " +
+            "'pointer_only' or 'managed_blob'.");
+    }
+    throw new Error(`Invalid RAW_STORAGE_MODE '${value}'. Must be 'pointer_only' or 'managed_blob'.`);
+}
+/** Parse + validate RAW_STORAGE_PROVIDER for `managed_blob` mode. */
+function parseRawStorageProvider(value) {
+    if (!value)
+        return null;
+    if (value === 'local_fs' || value === 's3' || value === 'filecoin')
+        return value;
+    throw new Error(`Invalid RAW_STORAGE_PROVIDER '${value}'. Must be 'local_fs', 's3', or 'filecoin'.`);
+}
+/** Parse `RAW_CONTENT_CODEC` env var. Defaults to `'none'`. */
+function parseRawContentCodec(value) {
+    if (!value)
+        return 'none';
+    if (value === 'none' || value === 'aes_gcm')
+        return value;
+    throw new Error(`Invalid RAW_CONTENT_CODEC '${value}'. Must be 'none' or 'aes_gcm'.`);
+}
+/**
+ * Parse `RAW_CONTENT_CODEC_KEYS` env var: comma-separated `keyId:base64Url`
+ * pairs. Each decoded key MUST be exactly 32 bytes (AES-256). Empty
+ * input returns an empty ring (validation runs separately).
+ */
+function parseRawContentCodecKeys(value) {
+    const ring = new Map();
+    if (!value)
+        return ring;
+    const entries = value.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+    for (const entry of entries) {
+        const colon = entry.indexOf(':');
+        if (colon <= 0) {
+            throw new Error(`RAW_CONTENT_CODEC_KEYS entry '${entry}' must be '<keyId>:<base64Url-32B>'.`);
+        }
+        const keyId = entry.slice(0, colon);
+        const encoded = entry.slice(colon + 1);
+        let key;
+        try {
+            key = Buffer.from(encoded, 'base64url');
+        }
+        catch {
+            throw new Error(`RAW_CONTENT_CODEC_KEYS entry for '${keyId}' is not valid base64url.`);
+        }
+        if (key.length !== 32) {
+            throw new Error(`RAW_CONTENT_CODEC_KEYS entry for '${keyId}' decoded to ${key.length} bytes; expected 32.`);
+        }
+        if (ring.has(keyId)) {
+            throw new Error(`Duplicate keyId '${keyId}' in RAW_CONTENT_CODEC_KEYS.`);
+        }
+        ring.set(keyId, key);
+    }
+    return ring;
+}
+/** Parse the required `RAW_STORAGE_DEPLOYMENT_ENV` knob. */
+function parseRawStorageDeploymentEnv(value) {
+    if (!value) {
+        throw new Error("RAW_STORAGE_DEPLOYMENT_ENV is required. Set 'production', 'staging', or 'local'.");
+    }
+    if (value === 'production' || value === 'staging' || value === 'local')
+        return value;
+    throw new Error(`Invalid RAW_STORAGE_DEPLOYMENT_ENV '${value}'. Must be 'production', 'staging', or 'local'.`);
+}
+/**
+ * Parse `RAW_STORAGE_LEGACY_PROVIDERS` (csv). The active provider is
+ * NEVER allowed in this list — that check happens in
+ * `validateRawStorageConfig` since it requires knowing which provider
+ * is active. Unknown values fail closed here so typos surface.
+ */
+function parseLegacyProviders(value) {
+    if (!value)
+        return [];
+    const entries = value.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+    const out = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        if (entry !== 'local_fs' && entry !== 's3' && entry !== 'filecoin') {
+            throw new Error(`Invalid RAW_STORAGE_LEGACY_PROVIDERS entry '${entry}'. ` +
+                "Each item must be 'local_fs', 's3', or 'filecoin'.");
+        }
+        if (seen.has(entry)) {
+            throw new Error(`Duplicate provider '${entry}' in RAW_STORAGE_LEGACY_PROVIDERS.`);
+        }
+        seen.add(entry);
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Phase-3 plan requires every managed blob to live under a namespaced
+ * path including environment, user, and document ids. The user/doc
+ * portion is generated per-upload; the environment portion is the
+ * `RAW_STORAGE_PREFIX` operator-supplied namespace. Validate that the
+ * prefix is a non-empty *relative* path with no `..` segments before
+ * it gets joined with caller-controlled key fragments.
+ */
+function validateRawStoragePrefix(prefix) {
+    if (!prefix || prefix.trim().length === 0) {
+        throw new Error("RAW_STORAGE_MODE='managed_blob' requires RAW_STORAGE_PREFIX " +
+            '(a relative namespace path, e.g. `prod/core`).');
+    }
+    if (prefix.startsWith('/')) {
+        throw new Error("RAW_STORAGE_PREFIX must be a relative path (no leading '/').");
+    }
+    const segments = prefix.split('/').filter((s) => s.length > 0);
+    if (segments.some((s) => s === '..')) {
+        throw new Error("RAW_STORAGE_PREFIX must not contain '..' segments.");
+    }
+}
+export function validateRawStorageConfig(args) {
+    validateCodecConfig(args);
+    validateLegacyProviders(args);
+    rejectFilecoinEnvOnNonFilecoinProvider(args);
+    if (args.mode !== 'managed_blob') {
+        if (args.provider !== null) {
+            throw new Error("RAW_STORAGE_PROVIDER is set but RAW_STORAGE_MODE is not 'managed_blob'. " +
+                "Either set RAW_STORAGE_MODE='managed_blob' or unset RAW_STORAGE_PROVIDER.");
+        }
+        return;
+    }
+    if (!args.provider) {
+        throw new Error("RAW_STORAGE_MODE='managed_blob' requires RAW_STORAGE_PROVIDER " +
+            "('local_fs', 's3', or 'filecoin').");
+    }
+    validateRawStoragePrefix(args.prefix);
+    if (args.provider === 'local_fs') {
+        if (!args.localFsRoot) {
+            throw new Error("RAW_STORAGE_PROVIDER='local_fs' requires RAW_STORAGE_LOCAL_FS_ROOT.");
+        }
+        return;
+    }
+    if (args.provider === 's3') {
+        const missing = collectMissingS3Fields(args);
+        if (missing.length > 0) {
+            throw new Error(`RAW_STORAGE_PROVIDER='s3' requires: ${missing.join(', ')}.`);
+        }
+        return;
+    }
+    // provider === 'filecoin'. Synapse-shaped env validation lives in
+    // `parseFilecoinProviderConfig` (called from this file's config
+    // init block below) so the provider module is the single source
+    // of truth for its own field shape. The cross-provider guard fires
+    // BEFORE this branch so a misconfigured non-filecoin deployment
+    // carrying stray Filecoin vars fails fast.
+}
+/**
+ * Reject any `RAW_STORAGE_FILECOIN_*` environment variable that is
+ * set when `RAW_STORAGE_PROVIDER` is not `'filecoin'`. The provider
+ * module's parser is only invoked on the filecoin branch, so this
+ * central guard is the only seam that catches "operator left stale
+ * Filecoin config on an S3 deployment" misconfigurations.
+ */
+function rejectFilecoinEnvOnNonFilecoinProvider(args) {
+    if (args.provider === 'filecoin')
+        return;
+    if (args.filecoinEnvKeysSet.length === 0)
+        return;
+    throw new Error(`RAW_STORAGE_FILECOIN_* environment variables are set but ` +
+        `RAW_STORAGE_PROVIDER='${args.provider ?? '<unset>'}'. ` +
+        `Filecoin provider configuration is only valid when ` +
+        `RAW_STORAGE_PROVIDER=filecoin. Unset: ${args.filecoinEnvKeysSet.join(', ')}.`);
+}
+function collectMissingS3Fields(args) {
+    return [
+        !args.s3Bucket && 'RAW_STORAGE_S3_BUCKET',
+        !args.s3Region && 'RAW_STORAGE_S3_REGION',
+        !args.s3AccessKeyId && 'RAW_STORAGE_S3_ACCESS_KEY_ID',
+        !args.s3SecretAccessKey && 'RAW_STORAGE_S3_SECRET_ACCESS_KEY',
+    ].filter((x) => Boolean(x));
+}
+function collectMissingLocalFsFields(args) {
+    return args.localFsRoot ? [] : ['RAW_STORAGE_LOCAL_FS_ROOT'];
+}
+/**
+ * Codec-level validation independent of the active provider: if the
+ * operator selected `aes_gcm`, they MUST configure a non-empty keyring
+ * and an active key id present in that ring. Misconfiguration fails
+ * closed at startup rather than at first encode.
+ */
+function validateCodecConfig(args) {
+    if (args.codec !== 'aes_gcm') {
+        if (args.codecKeys.size > 0 || args.codecActiveKeyId !== null) {
+            throw new Error("RAW_CONTENT_CODEC is not 'aes_gcm' but codec keyring fields are set. " +
+                "Either set RAW_CONTENT_CODEC='aes_gcm' or unset RAW_CONTENT_CODEC_KEYS/_ACTIVE_KEY_ID.");
+        }
+        return;
+    }
+    if (args.codecKeys.size === 0) {
+        throw new Error("RAW_CONTENT_CODEC='aes_gcm' requires RAW_CONTENT_CODEC_KEYS (non-empty).");
+    }
+    if (!args.codecActiveKeyId) {
+        throw new Error("RAW_CONTENT_CODEC='aes_gcm' requires RAW_CONTENT_CODEC_ACTIVE_KEY_ID.");
+    }
+    if (!args.codecKeys.has(args.codecActiveKeyId)) {
+        throw new Error(`RAW_CONTENT_CODEC_ACTIVE_KEY_ID='${args.codecActiveKeyId}' is not present in RAW_CONTENT_CODEC_KEYS.`);
+    }
+}
+/**
+ * `RAW_STORAGE_LEGACY_PROVIDERS` validation: every named provider must
+ * have its full env block configured, must NOT equal the active
+ * provider, and cannot include `'filecoin'` (which is the canonical
+ * active-only provider for this iteration; legacy Filecoin rows are
+ * handled by the active store directly).
+ */
+function validateLegacyProviders(args) {
+    for (const provider of args.legacyProviders) {
+        if (provider === args.provider) {
+            throw new Error(`RAW_STORAGE_LEGACY_PROVIDERS lists '${provider}', but that is the active provider. ` +
+                'A provider cannot be both active and legacy.');
+        }
+        if (provider === 'filecoin') {
+            throw new Error(`RAW_STORAGE_LEGACY_PROVIDERS cannot include '${provider}'. ` +
+                'Filecoin-family rows are served by the active store, not via legacy registration.');
+        }
+        const missing = provider === 'local_fs'
+            ? collectMissingLocalFsFields(args)
+            : collectMissingS3Fields(args);
+        if (missing.length > 0) {
+            throw new Error(`RAW_STORAGE_LEGACY_PROVIDERS='${provider}' requires its full env block: ${missing.join(', ')}.`);
+        }
+    }
+}
+const embeddingProvider = parseEmbeddingProvider(optionalEnv('EMBEDDING_PROVIDER'), 'openai');
+const llmProvider = parseLlmProvider(optionalEnv('LLM_PROVIDER'), 'openai');
+const retrievalProfile = parseRetrievalProfile(optionalEnv('RETRIEVAL_PROFILE'));
+const retrievalProfileSettings = getRetrievalProfile(retrievalProfile);
+const DEFAULT_SIMILARITY_THRESHOLD = 0.3;
+/** Require OpenAI key only when at least one provider uses it. */
+const needsOpenAIKey = embeddingProvider === 'openai' || llmProvider === 'openai';
+const needsGroqKey = llmProvider === 'groq';
+const needsAnthropicKey = llmProvider === 'anthropic';
+const needsGoogleKey = llmProvider === 'google-genai';
+const needsVoyageKey = embeddingProvider === 'voyage';
+const groqApiKey = needsGroqKey ? requireEnv('GROQ_API_KEY') : optionalEnv('GROQ_API_KEY');
+const openaiApiKey = needsOpenAIKey ? requireEnv('OPENAI_API_KEY') : (optionalEnv('OPENAI_API_KEY') ?? '');
+const anthropicApiKey = needsAnthropicKey ? requireEnv('ANTHROPIC_API_KEY') : optionalEnv('ANTHROPIC_API_KEY');
+const googleApiKey = needsGoogleKey ? requireEnv('GOOGLE_API_KEY') : optionalEnv('GOOGLE_API_KEY');
+const voyageApiKey = needsVoyageKey ? requireEnv('VOYAGE_API_KEY') : optionalEnv('VOYAGE_API_KEY');
+/**
+ * Validate the hex-encoded HMAC secret used for storage-key prefix
+ * derivation. Rejects values shorter than 64 hex chars (32 bytes) or
+ * containing non-hex characters. Empty / missing values are caught
+ * by `requireEnv` before this function runs.
+ */
+function parseStorageKeyHmacSecret(raw) {
+    const value = raw.trim();
+    if (value.length < 64) {
+        throw new Error('STORAGE_KEY_HMAC_SECRET must be at least 64 hex chars (32 bytes of entropy).');
+    }
+    if (!/^[0-9a-fA-F]+$/.test(value)) {
+        throw new Error('STORAGE_KEY_HMAC_SECRET must be hex-encoded.');
+    }
+    return value.toLowerCase();
+}
+function parseUnitNumberEnv(name, fallback) {
+    const raw = optionalEnv(name);
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        throw new Error(`${name} must be a finite number between 0 and 1`);
+    }
+    return parsed;
+}
+export const config = {
+    databaseUrl: requireEnv('DATABASE_URL'),
+    openaiApiKey,
+    coreApiKey: requireEnv('CORE_API_KEY'),
+    storageKeyHmacSecret: parseStorageKeyHmacSecret(requireEnv('STORAGE_KEY_HMAC_SECRET')),
+    port: parseInt(process.env.PORT ?? '3050', 10),
+    retrievalProfile,
+    retrievalProfileSettings,
+    maxSearchResults: retrievalProfileSettings.maxSearchResults,
+    similarityThreshold: parseUnitNumberEnv('SIMILARITY_THRESHOLD', DEFAULT_SIMILARITY_THRESHOLD),
+    audnCandidateThreshold: parseFloat(optionalEnv('AUDN_CANDIDATE_THRESHOLD') ?? '0.7'),
+    audnSafeReuseMinSimilarity: parseFloat(optionalEnv('AUDN_SAFE_REUSE_MIN_SIMILARITY') ?? '0.95'),
+    crossAgentCandidateThreshold: parseFloat(optionalEnv('CROSS_AGENT_CANDIDATE_THRESHOLD') ?? '0.75'),
+    clarificationConflictThreshold: 0.8,
+    adaptiveRetrievalEnabled: (process.env.ADAPTIVE_RETRIEVAL_ENABLED ?? String(retrievalProfileSettings.adaptiveRetrievalEnabled)) === 'true',
+    adaptiveSimpleLimit: parsePositiveIntEnv('ADAPTIVE_SIMPLE_LIMIT', 5),
+    adaptiveMediumLimit: parsePositiveIntEnv('ADAPTIVE_MEDIUM_LIMIT', 5),
+    adaptiveComplexLimit: parsePositiveIntEnv('ADAPTIVE_COMPLEX_LIMIT', 8),
+    adaptiveMultiHopLimit: parsePositiveIntEnv('ADAPTIVE_MULTI_HOP_LIMIT', 12),
+    adaptiveAggregationLimit: parsePositiveIntEnv('ADAPTIVE_AGGREGATION_LIMIT', 25),
+    repairLoopEnabled: (process.env.REPAIR_LOOP_ENABLED ?? String(retrievalProfileSettings.repairLoopEnabled)) === 'true',
+    hybridSearchEnabled: (process.env.HYBRID_SEARCH_ENABLED ?? String(retrievalProfileSettings.hybridSearchEnabled)) === 'true',
+    repairLoopMinSimilarity: parseFloat(process.env.REPAIR_LOOP_MIN_SIMILARITY ?? String(retrievalProfileSettings.repairLoopMinSimilarity)),
+    repairSkipSimilarity: parseFloat(process.env.REPAIR_SKIP_SIMILARITY ?? String(retrievalProfileSettings.repairSkipSimilarity ?? 0.55)),
+    mmrEnabled: (process.env.MMR_ENABLED ?? String(retrievalProfileSettings.mmrEnabled)) === 'true',
+    mmrLambda: parseFloat(process.env.MMR_LAMBDA ?? String(retrievalProfileSettings.mmrLambda)),
+    linkExpansionEnabled: (process.env.LINK_EXPANSION_ENABLED ?? String(retrievalProfileSettings.linkExpansionEnabled)) === 'true',
+    linkExpansionMax: parseInt(process.env.LINK_EXPANSION_MAX ?? String(retrievalProfileSettings.linkExpansionMax), 10),
+    linkSimilarityThreshold: parseFloat(process.env.LINK_SIMILARITY_THRESHOLD ?? String(retrievalProfileSettings.linkSimilarityThreshold)),
+    scoringWeightSimilarity: parseFloat(process.env.SCORING_WEIGHT_SIMILARITY ?? String(retrievalProfileSettings.scoringWeightSimilarity)),
+    scoringWeightImportance: parseFloat(process.env.SCORING_WEIGHT_IMPORTANCE ?? String(retrievalProfileSettings.scoringWeightImportance)),
+    scoringWeightRecency: parseFloat(process.env.SCORING_WEIGHT_RECENCY ?? String(retrievalProfileSettings.scoringWeightRecency)),
+    linkExpansionBeforeMMR: (process.env.LINK_EXPANSION_BEFORE_MMR ?? String(retrievalProfileSettings.linkExpansionBeforeMMR)) === 'true',
+    pprEnabled: (process.env.PPR_ENABLED ?? 'false') === 'true',
+    pprDamping: parseFloat(process.env.PPR_DAMPING ?? '0.5'),
+    repairDeltaThreshold: parseFloat(process.env.REPAIR_DELTA_THRESHOLD ?? String(retrievalProfileSettings.repairDeltaThreshold)),
+    repairConfidenceFloor: parseFloat(process.env.REPAIR_CONFIDENCE_FLOOR ?? String(retrievalProfileSettings.repairConfidenceFloor)),
+    // Embedding provider
+    embeddingProvider,
+    embeddingModel: optionalEnv('EMBEDDING_MODEL') ?? 'text-embedding-3-small',
+    embeddingDimensions: parseInt(requireEnv('EMBEDDING_DIMENSIONS'), 10),
+    embeddingApiUrl: optionalEnv('EMBEDDING_API_URL'),
+    embeddingApiKey: optionalEnv('EMBEDDING_API_KEY'),
+    voyageApiKey: voyageApiKey ?? undefined,
+    voyageDocumentModel: optionalEnv('VOYAGE_DOCUMENT_MODEL') ?? 'voyage-4-large',
+    voyageQueryModel: optionalEnv('VOYAGE_QUERY_MODEL') ?? 'voyage-4-lite',
+    // LLM provider
+    llmProvider,
+    llmModel: optionalEnv('LLM_MODEL') ?? defaultLlmModel(llmProvider),
+    llmApiUrl: optionalEnv('LLM_API_URL'),
+    llmApiKey: optionalEnv('LLM_API_KEY'),
+    // Groq
+    groqApiKey: groqApiKey ?? undefined,
+    anthropicApiKey: anthropicApiKey ?? undefined,
+    googleApiKey: googleApiKey ?? undefined,
+    // Ollama
+    ollamaBaseUrl: optionalEnv('OLLAMA_BASE_URL') ?? 'http://localhost:11434',
+    vectorBackend: parseVectorBackend(optionalEnv('VECTOR_BACKEND')),
+    skipVectorIndexes: (optionalEnv('SKIP_VECTOR_INDEXES') ?? 'false') === 'true',
+    llmSeed: parseLlmSeed(optionalEnv('LLM_SEED')),
+    stagedLoadingEnabled: (optionalEnv('STAGED_LOADING_ENABLED') ?? 'false') === 'true',
+    retrievalTraceEnabled: (optionalEnv('RETRIEVAL_TRACE_ENABLED') ?? 'false') === 'true',
+    ingestTraceDir: optionalEnv('INGEST_TRACE_DIR') ?? './.traces/ingest',
+    ingestTraceEnabled: (optionalEnv('INGEST_TRACE_ENABLED') ?? 'false') === 'true',
+    extractionCacheEnabled: (optionalEnv('EXTRACTION_CACHE_ENABLED') ?? 'false') === 'true',
+    extractionCacheDir: optionalEnv('EXTRACTION_CACHE_DIR') ?? './.eval-cache',
+    embeddingCacheEnabled: (optionalEnv('EMBEDDING_CACHE_ENABLED') ?? 'false') === 'true',
+    chunkedExtractionEnabled: (optionalEnv('CHUNKED_EXTRACTION_ENABLED') ?? 'false') === 'true',
+    chunkedExtractionFallbackEnabled: (optionalEnv('CHUNKED_EXTRACTION_FALLBACK_ENABLED') ?? 'false') === 'true',
+    chunkSizeTurns: parseInt(optionalEnv('CHUNK_SIZE_TURNS') ?? '4', 10),
+    chunkOverlapTurns: parseInt(optionalEnv('CHUNK_OVERLAP_TURNS') ?? '1', 10),
+    consensusExtractionEnabled: (optionalEnv('CONSENSUS_EXTRACTION_ENABLED') ?? 'false') === 'true',
+    consensusExtractionRuns: parseInt(optionalEnv('CONSENSUS_EXTRACTION_RUNS') ?? '3', 10),
+    observationDateExtractionEnabled: (optionalEnv('OBSERVATION_DATE_EXTRACTION_ENABLED') ?? 'false') === 'true',
+    quotedEntityExtractionEnabled: (optionalEnv('QUOTED_ENTITY_EXTRACTION_ENABLED') ?? 'false') === 'true',
+    entropyGateEnabled: (optionalEnv('ENTROPY_GATE_ENABLED') ?? 'false') === 'true',
+    entropyGateThreshold: parseFloat(optionalEnv('ENTROPY_GATE_THRESHOLD') ?? '0.35'),
+    entropyGateAlpha: parseFloat(optionalEnv('ENTROPY_GATE_ALPHA') ?? '0.5'),
+    affinityClusteringThreshold: parseFloat(optionalEnv('AFFINITY_CLUSTERING_THRESHOLD') ?? '0.85'),
+    affinityClusteringMinSize: parseInt(optionalEnv('AFFINITY_CLUSTERING_MIN_SIZE') ?? '3', 10),
+    affinityClusteringBeta: parseFloat(optionalEnv('AFFINITY_CLUSTERING_BETA') ?? '0.5'),
+    affinityClusteringTemporalLambda: parseFloat(optionalEnv('AFFINITY_CLUSTERING_TEMPORAL_LAMBDA') ?? '0.1'),
+    trustScoringEnabled: (optionalEnv('TRUST_SCORING_ENABLED') ?? 'false') === 'true',
+    trustScoreMinThreshold: parseFloat(optionalEnv('TRUST_SCORE_MIN_THRESHOLD') ?? '0.3'),
+    trustPenaltyEnabled: (optionalEnv('TRUST_PENALTY_ENABLED') ?? 'false') === 'true',
+    auditLoggingEnabled: (optionalEnv('AUDIT_LOGGING_ENABLED') ?? 'false') === 'true',
+    decayCycleEnabled: (optionalEnv('DECAY_CYCLE_ENABLED') ?? 'false') === 'true',
+    decayRetentionThreshold: parseFloat(optionalEnv('DECAY_RETENTION_THRESHOLD') ?? '0.2'),
+    decayMinAgeDays: parseInt(optionalEnv('DECAY_MIN_AGE_DAYS') ?? '7', 10),
+    memoryCapEnabled: (optionalEnv('MEMORY_CAP_ENABLED') ?? 'false') === 'true',
+    memoryCapMax: parseInt(optionalEnv('MEMORY_CAP_MAX') ?? '5000', 10),
+    memoryCapWarnRatio: parseFloat(optionalEnv('MEMORY_CAP_WARN_RATIO') ?? '0.8'),
+    entityGraphEnabled: (optionalEnv('ENTITY_GRAPH_ENABLED') ?? 'false') === 'true',
+    entityResolutionThreshold: parseFloat(optionalEnv('ENTITY_RESOLUTION_THRESHOLD') ?? '0.92'),
+    entitySearchMinSimilarity: parseFloat(optionalEnv('ENTITY_SEARCH_MIN_SIMILARITY') ?? '0.7'),
+    lessonsEnabled: (optionalEnv('LESSONS_ENABLED') ?? 'false') === 'true',
+    lessonSimilarityThreshold: parseFloat(optionalEnv('LESSON_SIMILARITY_THRESHOLD') ?? '0.75'),
+    consensusValidationEnabled: (optionalEnv('CONSENSUS_VALIDATION_ENABLED') ?? 'false') === 'true',
+    consensusMinMemories: parseInt(optionalEnv('CONSENSUS_MIN_MEMORIES') ?? '3', 10),
+    queryExpansionEnabled: (optionalEnv('QUERY_EXPANSION_ENABLED') ?? 'false') === 'true',
+    queryExpansionMinSimilarity: parseFloat(optionalEnv('QUERY_EXPANSION_MIN_SIMILARITY') ?? '0.5'),
+    queryAugmentationEnabled: (optionalEnv('QUERY_AUGMENTATION_ENABLED') ?? 'false') === 'true',
+    queryAugmentationMaxEntities: parseInt(optionalEnv('QUERY_AUGMENTATION_MAX_ENTITIES') ?? '5', 10),
+    queryAugmentationMinSimilarity: parseFloat(optionalEnv('QUERY_AUGMENTATION_MIN_SIMILARITY') ?? '0.4'),
+    crossEncoderEnabled: (optionalEnv('CROSS_ENCODER_ENABLED') ?? 'false') === 'true', // ms-marco hurts temporal queries; keep disabled until better model
+    crossEncoderModel: optionalEnv('CROSS_ENCODER_MODEL') ?? 'Xenova/ms-marco-MiniLM-L-6-v2',
+    crossEncoderDtype: parseCrossEncoderDtype(optionalEnv('CROSS_ENCODER_DTYPE')),
+    iterativeRetrievalEnabled: (optionalEnv('ITERATIVE_RETRIEVAL_ENABLED') ?? 'false') === 'true',
+    namespaceClassificationEnabled: (optionalEnv('NAMESPACE_CLASSIFICATION_ENABLED') ?? 'false') === 'true',
+    fastAudnEnabled: (optionalEnv('FAST_AUDN_ENABLED') ?? 'true') === 'true',
+    fastAudnDuplicateThreshold: parseFloat(optionalEnv('FAST_AUDN_DUPLICATE_THRESHOLD') ?? '0.95'),
+    observationNetworkEnabled: (optionalEnv('OBSERVATION_NETWORK_ENABLED') ?? 'true') === 'true',
+    agenticRetrievalEnabled: (optionalEnv('AGENTIC_RETRIEVAL_ENABLED') ?? 'false') === 'true',
+    rerankSkipTopSimilarity: parseFloat(optionalEnv('RERANK_SKIP_TOP_SIMILARITY') ?? '0.85'),
+    rerankSkipMinGap: parseFloat(optionalEnv('RERANK_SKIP_MIN_GAP') ?? '0.05'),
+    literalListProtectionEnabled: (optionalEnv('LITERAL_LIST_PROTECTION_ENABLED') ?? 'false') === 'true',
+    literalListProtectionMaxProtected: parsePositiveIntEnv('LITERAL_LIST_PROTECTION_MAX_PROTECTED', 3),
+    temporalQueryConstraintEnabled: (optionalEnv('TEMPORAL_QUERY_CONSTRAINT_ENABLED') ?? 'false') === 'true',
+    temporalQueryConstraintBoost: parseFloat(optionalEnv('TEMPORAL_QUERY_CONSTRAINT_BOOST') ?? '2'),
+    deferredAudnEnabled: (optionalEnv('DEFERRED_AUDN_ENABLED') ?? 'false') === 'true',
+    deferredAudnBatchSize: parseInt(optionalEnv('DEFERRED_AUDN_BATCH_SIZE') ?? '20', 10),
+    compositeGroupingEnabled: (optionalEnv('COMPOSITE_GROUPING_ENABLED') ?? 'true') === 'true',
+    compositeMinClusterSize: parseInt(optionalEnv('COMPOSITE_MIN_CLUSTER_SIZE') ?? '2', 10),
+    compositeMaxClusterSize: parseInt(optionalEnv('COMPOSITE_MAX_CLUSTER_SIZE') ?? '3', 10),
+    compositeSimilarityThreshold: parseFloat(optionalEnv('COMPOSITE_SIMILARITY_THRESHOLD') ?? '0.55'),
+    costLoggingEnabled: (optionalEnv('COST_LOGGING_ENABLED') ?? 'false') === 'true',
+    costLogDir: optionalEnv('COST_LOG_DIR') ?? 'data/cost-logs',
+    costRunId: optionalEnv('COST_RUN_ID') ?? '',
+    conflictAutoResolveMs: parseInt(optionalEnv('CONFLICT_AUTO_RESOLVE_MS') ?? '86400000', 10),
+    tbcEnabled: (optionalEnv('TBC_ENABLED') ?? 'false') === 'true',
+    hierarchicalRetrievalEnabled: (optionalEnv('HIERARCHICAL_RETRIEVAL_ENABLED') ?? 'false') === 'true',
+    topicAbstractionEnabled: (optionalEnv('TOPIC_ABSTRACTION_ENABLED') ?? 'false') === 'true',
+    topicSearchEnabled: (optionalEnv('TOPIC_SEARCH_ENABLED') ?? 'false') === 'true',
+    rerankerEnabled: (optionalEnv('RERANKER_ENABLED') ?? 'false') === 'true',
+    rerankerTopN: parseInt(optionalEnv('RERANKER_TOP_N') ?? '20', 10),
+    recapLayerEnabled: (optionalEnv('RECAP_LAYER_ENABLED') ?? 'false') === 'true',
+    recapMinClusterSize: parseInt(optionalEnv('RECAP_MIN_CLUSTER_SIZE') ?? '4', 10),
+    recapSearchEnabled: (optionalEnv('RECAP_SEARCH_ENABLED') ?? 'false') === 'true',
+    recapClusterPivot: (optionalEnv('RECAP_CLUSTER_PIVOT') === 'session' ? 'session' : 'topic'),
+    counterEvidenceEnabled: (optionalEnv('COUNTER_EVIDENCE_ENABLED') ?? 'false') === 'true',
+    packagingUseObservedAt: (optionalEnv('PACKAGING_USE_OBSERVED_AT') ?? 'false') === 'true',
+    packagingDualDate: (optionalEnv('PACKAGING_DUAL_DATE') ?? 'false') === 'true',
+    timelineChannelEnabled: (optionalEnv('TIMELINE_CHANNEL_ENABLED') ?? 'false') === 'true',
+    answerOnlyRetrievalFilter: (optionalEnv('ANSWER_ONLY_RETRIEVAL_FILTER') ?? 'false') === 'true',
+    retrievalDedupEnabled: (optionalEnv('RETRIEVAL_DEDUP_ENABLED') ?? 'false') === 'true',
+    keywordRrfWeight: parseFloat(optionalEnv('KEYWORD_RRF_WEIGHT') ?? '1.0'),
+    entityAttributesEnabled: (optionalEnv('ENTITY_ATTRIBUTES_ENABLED') ?? 'false') === 'true',
+    entityAttributesTopK: parsePositiveIntEnv('ENTITY_ATTRIBUTES_TOP_K', 20),
+    userProfileChannelEnabled: (optionalEnv('USER_PROFILE_CHANNEL_ENABLED') ?? 'false') === 'true',
+    episodesChannelEnabled: (optionalEnv('EPISODES_CHANNEL_ENABLED') ?? 'false') === 'true',
+    episodesChannelTopK: parseInt(optionalEnv('EPISODES_CHANNEL_TOP_K') ?? '2', 10),
+    verifierPassEnabled: (optionalEnv('VERIFIER_PASS_ENABLED') ?? 'false') === 'true',
+    answerFormatAlignmentEnabled: (optionalEnv('ANSWER_FORMAT_ALIGNMENT_ENABLED') ?? 'false') === 'true',
+    eventChainPackagingEnabled: (optionalEnv('EVENT_CHAIN_PACKAGING_ENABLED') ?? 'false') === 'true',
+    reflectEnabled: (optionalEnv('REFLECT_ENABLED') ?? 'false') === 'true',
+    reflectRetrievalTopK: parsePositiveIntEnv('REFLECT_RETRIEVAL_TOP_K', 3),
+    reflectModel: optionalEnv('REFLECT_MODEL') ?? 'claude-sonnet-4-5',
+    reflectMaxObservations: parsePositiveIntEnv('REFLECT_MAX_OBSERVATIONS', 12),
+    reflectJobPollMs: parsePositiveIntEnv('REFLECT_JOB_POLL_MS', 5000),
+    reflectDebounceMs: parsePositiveIntEnv('REFLECT_DEBOUNCE_MS', 60000),
+    runtimeConfigMutationEnabled: (process.env.CORE_RUNTIME_CONFIG_MUTATION_ENABLED ?? 'false') === 'true',
+    phase2SpecialistsEnabled: (optionalEnv('PHASE2_SPECIALISTS_ENABLED') ?? 'false') === 'true',
+    abstentionRescueEnabled: (optionalEnv('ABSTENTION_RESCUE_ENABLED') ?? 'false') === 'true',
+    abstentionRescueRetrieveK: parseInt(optionalEnv('ABSTENTION_RESCUE_RETRIEVE_K') ?? '8', 10),
+    abstentionRescueSonnetModel: optionalEnv('ABSTENTION_RESCUE_SONNET_MODEL') ?? 'claude-sonnet-4-5',
+    confidencePrefixAdaptiveEnabled: (optionalEnv('CONFIDENCE_PREFIX_ADAPTIVE_ENABLED') ?? 'false') === 'true',
+    kuRecencySortEnabled: (optionalEnv('KU_RECENCY_SORT_ENABLED') ?? 'false') === 'true',
+    msrAggregatorEnabled: (optionalEnv('MSR_AGGREGATOR_ENABLED') ?? 'false') === 'true',
+    entityCardEnabled: (optionalEnv('ENTITY_CARD_ENABLED') ?? 'false') === 'true',
+    entityCardMaxPerSession: parsePositiveIntEnv('ENTITY_CARD_MAX_PER_SESSION', 5),
+    entityCardMinObservations: parsePositiveIntEnv('ENTITY_CARD_MIN_OBSERVATIONS', 3),
+    contradictionPreservationEnabled: (optionalEnv('CONTRADICTION_PRESERVATION_ENABLED') ?? 'false') === 'true',
+    contradictionSurfacingEnabled: (optionalEnv('CONTRADICTION_SURFACING_ENABLED') ?? 'false') === 'true',
+    temporalStateEnabled: (optionalEnv('TEMPORAL_STATE_ENABLED') ?? 'false') === 'true',
+    rawStorageMode: parseRawStorageMode(optionalEnv('RAW_STORAGE_MODE')),
+    rawStorageProvider: parseRawStorageProvider(optionalEnv('RAW_STORAGE_PROVIDER')),
+    rawStoragePrefix: optionalEnv('RAW_STORAGE_PREFIX') ?? '',
+    rawStorageLocalFsRoot: optionalEnv('RAW_STORAGE_LOCAL_FS_ROOT') ?? null,
+    rawStorageS3Bucket: optionalEnv('RAW_STORAGE_S3_BUCKET') ?? null,
+    rawStorageS3Region: optionalEnv('RAW_STORAGE_S3_REGION') ?? null,
+    rawStorageS3Endpoint: optionalEnv('RAW_STORAGE_S3_ENDPOINT') ?? null,
+    rawStorageS3AccessKeyId: optionalEnv('RAW_STORAGE_S3_ACCESS_KEY_ID') ?? null,
+    rawStorageS3SecretAccessKey: optionalEnv('RAW_STORAGE_S3_SECRET_ACCESS_KEY') ?? null,
+    rawUploadMaxBytes: parsePositiveIntEnv('RAW_UPLOAD_MAX_BYTES', 26214400 /* 25 MiB */),
+    rawContentCodec: parseRawContentCodec(optionalEnv('RAW_CONTENT_CODEC')),
+    rawContentCodecKeys: parseRawContentCodecKeys(optionalEnv('RAW_CONTENT_CODEC_KEYS')),
+    rawContentCodecActiveKeyId: optionalEnv('RAW_CONTENT_CODEC_ACTIVE_KEY_ID') ?? null,
+    rawStorageDeploymentEnv: parseRawStorageDeploymentEnv(optionalEnv('RAW_STORAGE_DEPLOYMENT_ENV')),
+    filecoinProvider: null,
+    rawStorageLegacyProviders: parseLegacyProviders(optionalEnv('RAW_STORAGE_LEGACY_PROVIDERS')),
+    rawStoragePointerUriSchemes: parsePointerUriSchemes(optionalEnv('RAW_STORAGE_POINTER_URI_SCHEMES')),
+};
+const filecoinEnvKeysSet = collectFilecoinProviderEnvKeys(process.env);
+validateRawStorageConfig({
+    mode: config.rawStorageMode,
+    provider: config.rawStorageProvider,
+    prefix: config.rawStoragePrefix,
+    localFsRoot: config.rawStorageLocalFsRoot,
+    s3Bucket: config.rawStorageS3Bucket,
+    s3Region: config.rawStorageS3Region,
+    s3AccessKeyId: config.rawStorageS3AccessKeyId,
+    s3SecretAccessKey: config.rawStorageS3SecretAccessKey,
+    codec: config.rawContentCodec,
+    codecKeys: config.rawContentCodecKeys,
+    codecActiveKeyId: config.rawContentCodecActiveKeyId,
+    deploymentEnv: config.rawStorageDeploymentEnv,
+    legacyProviders: config.rawStorageLegacyProviders,
+    filecoinEnvKeysSet,
+});
+if (config.rawStorageProvider === 'filecoin') {
+    // Cross-provider guard above has already fired for non-filecoin
+    // deployments carrying stray RAW_STORAGE_FILECOIN_* vars; this
+    // branch validates the full Synapse-shaped block and fails closed
+    // on missing / malformed values.
+    config.filecoinProvider = parseFilecoinProviderConfig(process.env);
+}
+export function applyRuntimeConfigUpdates(target, updates) {
+    const applied = [];
+    if (updates.similarityThreshold !== undefined) {
+        target.similarityThreshold = requireFiniteNumber(updates.similarityThreshold, 'similarityThreshold');
+        applied.push('similarityThreshold');
+    }
+    if (updates.audnCandidateThreshold !== undefined) {
+        target.audnCandidateThreshold = requireFiniteNumber(updates.audnCandidateThreshold, 'audnCandidateThreshold');
+        applied.push('audnCandidateThreshold');
+    }
+    if (updates.clarificationConflictThreshold !== undefined) {
+        target.clarificationConflictThreshold = requireFiniteNumber(updates.clarificationConflictThreshold, 'clarificationConflictThreshold');
+        applied.push('clarificationConflictThreshold');
+    }
+    if (updates.maxSearchResults !== undefined) {
+        target.maxSearchResults = Math.max(1, Math.floor(requireFiniteNumber(updates.maxSearchResults, 'maxSearchResults')));
+        applied.push('maxSearchResults');
+    }
+    return applied;
+}
+export function updateRuntimeConfig(updates) {
+    return applyRuntimeConfigUpdates(config, updates);
+}
+/**
+ * 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 const SUPPORTED_RUNTIME_CONFIG_FIELDS = [
+    // Infrastructure
+    'databaseUrl', 'openaiApiKey', 'coreApiKey', 'storageKeyHmacSecret', 'port',
+    // Provider / model selection (startup config)
+    'embeddingProvider', 'embeddingModel', 'embeddingDimensions',
+    'embeddingApiUrl', 'embeddingApiKey',
+    'voyageApiKey', 'voyageDocumentModel', 'voyageQueryModel',
+    'llmProvider', 'llmModel', 'llmApiUrl', 'llmApiKey',
+    'groqApiKey', 'anthropicApiKey', 'googleApiKey',
+    'ollamaBaseUrl', 'vectorBackend', 'skipVectorIndexes', 'llmSeed',
+    'crossEncoderModel', 'crossEncoderDtype',
+    // Operator-visible runtime
+    'maxSearchResults', 'retrievalProfile', 'retrievalProfileSettings',
+    // Major feature toggles (surfaced in GET /v1/memories/health)
+    'entityGraphEnabled', 'lessonsEnabled', 'agenticRetrievalEnabled',
+    'iterativeRetrievalEnabled', 'hybridSearchEnabled', 'repairLoopEnabled',
+    'crossEncoderEnabled', 'auditLoggingEnabled', 'adaptiveRetrievalEnabled',
+    'consensusValidationEnabled', 'namespaceClassificationEnabled',
+    // Cost / cache ops
+    'extractionCacheDir', 'costLogDir', 'costRunId', 'costLoggingEnabled',
+    // Dev/test-only mutation gate for PUT /v1/memories/config
+    // (see https://docs.atomicmemory.ai/platform/consuming-core)
+    '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 const INTERNAL_POLICY_CONFIG_FIELDS = [
+    // Retrieval thresholds
+    'similarityThreshold', 'audnCandidateThreshold', 'audnSafeReuseMinSimilarity',
+    'crossAgentCandidateThreshold', 'clarificationConflictThreshold',
+    // Repair loop tuning
+    'repairLoopMinSimilarity', 'repairSkipSimilarity',
+    'repairDeltaThreshold', 'repairConfidenceFloor',
+    // Adaptive retrieval tuning
+    'adaptiveSimpleLimit', 'adaptiveMediumLimit', 'adaptiveComplexLimit',
+    'adaptiveMultiHopLimit', 'adaptiveAggregationLimit',
+    // MMR
+    'mmrEnabled', 'mmrLambda',
+    // Link expansion
+    'linkExpansionEnabled', 'linkExpansionMax',
+    'linkSimilarityThreshold', 'linkExpansionBeforeMMR',
+    // Scoring weights
+    'scoringWeightSimilarity', 'scoringWeightImportance', 'scoringWeightRecency',
+    // PPR
+    'pprEnabled', 'pprDamping',
+    // Staging / tracing
+    'stagedLoadingEnabled', 'retrievalTraceEnabled', 'ingestTraceDir', 'ingestTraceEnabled',
+    // Extraction internals
+    'extractionCacheEnabled', 'embeddingCacheEnabled',
+    'chunkedExtractionEnabled', 'chunkedExtractionFallbackEnabled',
+    'chunkSizeTurns', 'chunkOverlapTurns',
+    'consensusExtractionEnabled', 'consensusExtractionRuns',
+    'observationDateExtractionEnabled', 'quotedEntityExtractionEnabled',
+    'entropyGateEnabled', 'entropyGateThreshold', 'entropyGateAlpha',
+    // Affinity clustering
+    'affinityClusteringThreshold', 'affinityClusteringMinSize',
+    'affinityClusteringBeta', 'affinityClusteringTemporalLambda',
+    // Trust
+    'trustScoringEnabled', 'trustScoreMinThreshold', 'trustPenaltyEnabled',
+    // Decay / caps
+    'decayCycleEnabled', 'decayRetentionThreshold', 'decayMinAgeDays',
+    'memoryCapEnabled', 'memoryCapMax', 'memoryCapWarnRatio',
+    // Entity tuning
+    'entityResolutionThreshold', 'entitySearchMinSimilarity',
+    // Lesson tuning
+    'lessonSimilarityThreshold',
+    // Consensus tuning
+    'consensusMinMemories',
+    // Query expansion / augmentation
+    'queryExpansionEnabled', 'queryExpansionMinSimilarity',
+    'queryAugmentationEnabled', 'queryAugmentationMaxEntities',
+    'queryAugmentationMinSimilarity',
+    // Rerank tuning
+    'rerankSkipTopSimilarity', 'rerankSkipMinGap',
+    // Literal/list answer selection
+    'literalListProtectionEnabled', 'literalListProtectionMaxProtected',
+    // Temporal query selection
+    'temporalQueryConstraintEnabled', 'temporalQueryConstraintBoost',
+    // Fast AUDN
+    'fastAudnEnabled', 'fastAudnDuplicateThreshold',
+    // Observation / deferred
+    'observationNetworkEnabled', 'deferredAudnEnabled', 'deferredAudnBatchSize',
+    // Composite grouping
+    'compositeGroupingEnabled', 'compositeMinClusterSize',
+    'compositeMaxClusterSize', 'compositeSimilarityThreshold',
+    // Conflict handling
+    'conflictAutoResolveMs',
+    // Typed Belief Calculus (Phase 1 scaffold; gates future TBC behavior)
+    'tbcEnabled',
+    // Hierarchical Retrieval (T2; gates 5th RRF arm + summary table writes)
+    'hierarchicalRetrievalEnabled',
+    // Sprint 3 EO experiment: topic-abstraction ingest layer + retrieval channel
+    'topicAbstractionEnabled',
+    'topicSearchEnabled',
+    // Sprint 3 v1: cross-encoder reranker on RRF top-N
+    'rerankerEnabled',
+    'rerankerTopN',
+    // Sprint 3 v1: Recap (cross-session synthesis) layer
+    'recapLayerEnabled',
+    'recapMinClusterSize',
+    'recapSearchEnabled',
+    'recapClusterPivot',
+    // Sprint 3 v1.1: counter-evidence retrieval via belief_edges graph
+    'counterEvidenceEnabled',
+    // Sprint 3 v1.2: temporal-aware packaging — surface observed_at not created_at
+    'packagingUseObservedAt',
+    // Sprint 3 v1.3: dual-date packaging — emit both created_at and observed_at
+    'packagingDualDate',
+    // Sprint 3 v1.4: timeline channel — dedicated ## TIMELINE prompt section
+    'timelineChannelEnabled',
+    // Sprint 4 iter 1: drop advisory-only memories from injection
+    'answerOnlyRetrievalFilter',
+    // Sprint 4 iter 2: dedup near-duplicates by content fingerprint
+    'retrievalDedupEnabled',
+    // Sprint 4 iter 3: BM25 keyword RRF weight (default 1.0; boost 1.5-2.0)
+    'keywordRrfWeight',
+    // Sprint 4: Entity-Attribute Index (EAI) — (entity, attribute, value) lookups
+    'entityAttributesEnabled',
+    'entityAttributesTopK',
+    // Sprint 3 v1.5: user-profile channel — pinned `## USER PROFILE` block
+    'userProfileChannelEnabled',
+    // Sprint 3 v1.6: episodes-as-separate-channel — `## EPISODES` block sourced
+    // from RecapStore candidates instead of RRF fan-in.
+    'episodesChannelEnabled',
+    'episodesChannelTopK',
+    // Sprint 3 v1.7: verifier-pass — second LLM call re-grounds candidate answer.
+    // Read by the AMB adapter via ATOMICMEMORY_VERIFIER_ENABLED; surfaced in
+    // core config so iteration env files can request it for symmetry.
+    'verifierPassEnabled',
+    // BEAM-0.85 Phase 0 L1: answer-format alignment — prepends per-question-type
+    // FORMAT hint to the injection prompt to shape answer-LLM output structure.
+    'answerFormatAlignmentEnabled',
+    // EO fix — data-driven event-chain detector: prepends ## EVENT_CHAIN channel
+    // when retrieved top-K contains 3+ memories for same entity across 3+ dates.
+    'eventChainPackagingEnabled',
+    // BEAM-0.85 Phase 1: async reflection worker + retrieval channel.
+    'reflectEnabled',
+    'reflectRetrievalTopK',
+    'reflectModel',
+    'reflectMaxObservations',
+    'reflectJobPollMs',
+    'reflectDebounceMs',
+    // BEAM-0.85 Phase 2: specialist dispatcher gate (CR, TR, MSR, IE/KU).
+    'phase2SpecialistsEnabled',
+    // Abstention-rescue: confidence prefix + iterative retrieval + Sonnet fallback.
+    'abstentionRescueEnabled',
+    'abstentionRescueRetrieveK',
+    'abstentionRescueSonnetModel',
+    // BEAM v36: per-question-type adaptive confidence prefix (forced vs soft vs none).
+    'confidencePrefixAdaptiveEnabled',
+    // BEAM v42: KU recency sort (NUMERIC_COUNT + KU-style queries → observed_at DESC).
+    'kuRecencySortEnabled',
+    // BEAM v39-multihop: MSR cross-conversation aggregator (retrieval-side channel).
+    'msrAggregatorEnabled',
+    // BEAM-0.85: always-on per-entity ENTITY_CARD channel (Honcho parity).
+    'entityCardEnabled',
+    'entityCardMaxPerSession',
+    'entityCardMinObservations',
+    // BEAM CR fix (2026-05-12): AUDN bilateral preservation for contradictions.
+    'contradictionPreservationEnabled',
+    'contradictionSurfacingEnabled',
+    // BEAM v38 (2026-05-12): temporal state layer (write/read for KU).
+    'temporalStateEnabled',
+    // Document pipeline (Phases 1 + 3). The raw-storage knobs are
+    // operator-visible at startup and intentionally NOT mutable at
+    // runtime — moving the storage backend mid-process would orphan
+    // already-persisted blobs.
+    'rawStorageMode',
+    'rawStorageProvider',
+    'rawStoragePrefix',
+    'rawStorageLocalFsRoot',
+    'rawStorageS3Bucket',
+    'rawStorageS3Region',
+    'rawStorageS3Endpoint',
+    'rawStorageS3AccessKeyId',
+    'rawStorageS3SecretAccessKey',
+    'rawUploadMaxBytes',
+    // Filecoin raw storage: content codec + deployment env. Same
+    // operator-visible-at-startup, not-runtime-mutable contract as the
+    // raw-storage block above.
+    'rawContentCodec',
+    'rawContentCodecKeys',
+    'rawContentCodecActiveKeyId',
+    'rawStorageDeploymentEnv',
+    // Synapse-shaped Filecoin provider config. Single grouped field on
+    // `RuntimeConfig`; the underlying env var surface is
+    // `RAW_STORAGE_FILECOIN_*` and the parser lives in
+    // `src/storage/providers/filecoin/config.ts`.
+    'filecoinProvider',
+    'rawStorageLegacyProviders',
+    'rawStoragePointerUriSchemes',
+];