@remnic/core 9.7.14 → 9.8.0

package/src/config.ts

@@ -35,14 +35,24 @@ import { expandTildePath } from "./utils/path.js";
 // boolean-coercion logic that connectors/index.ts already exports. The helper
 // lives in connectors/coerce.ts (a tiny, dependency-free module) so neither
 // config.ts → connectors/index.ts nor the reverse circular import arises.
-import { coerceBool, coerceInstallExtension, coerceNumber } from "./connectors/coerce.js";
+import { coerceBool, coerceBooleanLike, coerceInstallExtension, coerceNumber } from "./connectors/coerce.js";
+import { parseRecallConcurrencyConfig } from "./recall-concurrency-config.js";
 import { hasLegacyConnectorEntries } from "./connectors/paths.js";
+import {
+  parseQmdChunkStrategy,
+  parseQmdDaemonTimeoutMs,
+  parseQmdGpuBackend,
+  parseQmdSearchStrategy,
+  parseQmdSubprocessStrategy,
+  parseQmdSupportedVersion,
+} from "./config-qmd.js";
 import {
   resolveEmitLegacyTools,
   resolveNamespaceCatalogEnabled,
 } from "./emit-legacy-tools.js";
 import { parseWearablesConfig } from "./wearables/config.js";
 import { parseProvenanceConfig } from "./provenance.js";
+import { parseBoundedJsonlStateConfig } from "./bounded-jsonl-state.js";
 import { parseCodingKnowledgeConfig } from "./coding/coding-knowledge-config.js";
 import { parseChatConfig } from "./chat/chat-config.js";
 import { parseCorrectionIntentConfig, parseFaithfulnessGateConfig } from "./faithfulness-config.js";
@@ -188,92 +198,35 @@ function parseBoundedPositiveInteger(
   return Math.max(min, Math.min(max, parsed));
 }
 
-function parseQmdSupportedVersion(value: unknown): string {
-  if (value === undefined || value === null) return "2.5.3";
-  if (typeof value !== "string") {
-    throw new Error(`qmdSupportedVersion must be a semantic version string; got ${JSON.stringify(value)}`);
-  }
-  const normalized = value.trim();
-  if (!/^\d+\.\d+\.\d+$/.test(normalized)) {
-    throw new Error(
-      `qmdSupportedVersion must be a semantic version string like "2.5.3"; got ${JSON.stringify(value)}`,
-    );
-  }
-  return normalized;
-}
-
-function parseQmdGpuBackend(value: unknown): "auto" | "metal" | "cuda" | "vulkan" | "false" | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (value === false) return "false";
-  if (typeof value !== "string") {
-    throw new Error(`qmdGpuBackend must be one of "auto", "metal", "cuda", "vulkan", or false; got ${JSON.stringify(value)}`);
-  }
-  const normalized = value.trim().toLowerCase();
+/**
+ * Validate a closed-range integer config knob, coercing CLI numeric strings
+ * first (issue #1909 review round 8). `undefined`/`null` → `fallback`. Anything
+ * provided must coerce to a FINITE INTEGER in `[min, max]`; otherwise THROW
+ * (AGENTS.md #1/#39: reject invalid user input, never silently floor/clamp).
+ */
+function parseIntegerInClosedRange(
+  value: unknown,
+  min: number,
+  max: number,
+  fallback: number,
+  keyName: string,
+): number {
+  // Only an absent key (undefined) falls back to the default; an explicit `null`
+  // is invalid input and proceeds to validation → throw (round 9 finding 1).
+  if (value === undefined) return fallback;
+  const coerced = coerceNumber(value);
   if (
-    normalized === "auto" ||
-    normalized === "metal" ||
-    normalized === "cuda" ||
-    normalized === "vulkan" ||
-    normalized === "false"
+    coerced === undefined ||
+    !Number.isFinite(coerced) ||
+    !Number.isInteger(coerced) ||
+    coerced < min ||
+    coerced > max
   ) {
-    return normalized;
-  }
-  throw new Error(`qmdGpuBackend must be one of "auto", "metal", "cuda", "vulkan", or false; got ${JSON.stringify(value)}`);
-}
-
-function parseQmdChunkStrategy(value: unknown): "auto" | "regex" {
-  if (value === undefined || value === null) return "auto";
-  if (typeof value !== "string") {
-    throw new Error(`qmdChunkStrategy must be "auto" or "regex"; got ${JSON.stringify(value)}`);
-  }
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "auto" || normalized === "regex") return normalized;
-  throw new Error(`qmdChunkStrategy must be "auto" or "regex"; got ${JSON.stringify(value)}`);
-}
-
-// Issue #1335. Default "hybrid" preserves the historical lex+vec+hyde daemon plan.
-function parseQmdSearchStrategy(value: unknown): "hybrid" | "lex-vec" | "lex" {
-  if (value === undefined || value === null) return "hybrid";
-  if (typeof value !== "string") {
-    throw new Error(
-      `qmdSearchStrategy must be one of "hybrid", "lex-vec", or "lex"; got ${JSON.stringify(value)}`,
-    );
-  }
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "hybrid" || normalized === "lex-vec" || normalized === "lex") {
-    return normalized;
-  }
-  throw new Error(
-    `qmdSearchStrategy must be one of "hybrid", "lex-vec", or "lex"; got ${JSON.stringify(value)}`,
-  );
-}
-
-// Issue #1335. Reject non-numeric / non-integer timeouts rather than silently
-// coercing them (gotcha #51), then clamp valid integers to the documented bounds.
-function parseQmdDaemonTimeoutMs(value: unknown): number {
-  if (value === undefined || value === null) return 8_000;
-  const coerced = coerceNumber(value);
-  if (coerced === undefined || !Number.isInteger(coerced)) {
     throw new Error(
-      `qmdDaemonTimeoutMs must be an integer number of milliseconds between 1000 and 120000; got ${JSON.stringify(value)}`,
+      `${keyName} must be an integer in [${min}, ${max}]; got ${JSON.stringify(value)}`,
     );
   }
-  return Math.min(120_000, Math.max(1_000, coerced));
-}
-
-// Issue #1335. Default "query" keeps `qmd query` (LLM expansion + rerank) per gotcha #7.
-function parseQmdSubprocessStrategy(value: unknown): "query" | "search" {
-  if (value === undefined || value === null) return "query";
-  if (typeof value !== "string") {
-    throw new Error(
-      `qmdSubprocessStrategy must be one of "query" or "search"; got ${JSON.stringify(value)}`,
-    );
-  }
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "query" || normalized === "search") return normalized;
-  throw new Error(
-    `qmdSubprocessStrategy must be one of "query" or "search"; got ${JSON.stringify(value)}`,
-  );
+  return coerced;
 }
 
 function parseOptionalNonEmptyString(value: unknown): string | undefined {
@@ -343,30 +296,6 @@ function parsePortNumber(
   return coerced;
 }
 
-// Coerce common string/number representations of a boolean to a real boolean.
-// Returns `undefined` when the value cannot be interpreted, so callers can
-// fall back to their own default. Guards against the "string `false` is
-// truthy" footgun (CLAUDE.md gotcha #36) when config values arrive from
-// CLI/env/JSON sources where booleans are sometimes string-typed.
-function coerceBooleanLike(value: unknown): boolean | undefined {
-  if (typeof value === "boolean") return value;
-  if (typeof value === "number") {
-    if (value === 1) return true;
-    if (value === 0) return false;
-    return undefined;
-  }
-  if (typeof value === "string") {
-    const normalized = value.trim().toLowerCase();
-    if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
-      return true;
-    }
-    if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
-      return false;
-    }
-  }
-  return undefined;
-}
-
 function readNestedConfig(
   cfg: Record<string, unknown>,
   blockName: string,
@@ -658,6 +587,7 @@ const DEFAULT_BEHAVIOR_LOOP_PROTECTED_PARAMS = [
   "maxMemoryTokens",
   "qmdMaxResults",
   "qmdColdMaxResults",
+  "qmdEmbeddingBacklogThreshold",
   "recallPlannerMaxQmdResultsMinimal",
   "verbatimArtifactsMaxRecall",
 ];
@@ -1683,6 +1613,15 @@ export function parseConfig(
         : "openclaw-engram",
     qmdMaxResults:
       typeof cfg.qmdMaxResults === "number" ? cfg.qmdMaxResults : 8,
+    qmdEmbeddingBacklogThreshold: (() => {
+      const raw = cfg.qmdEmbeddingBacklogThreshold;
+      const n = typeof raw === "number"
+        ? raw
+        : typeof raw === "string" && raw.trim() !== ""
+          ? Number(raw)
+          : NaN;
+      return Number.isFinite(n) && Number.isInteger(n) && n >= 0 ? n : 1000;
+    })(),
     qmdColdTierEnabled: cfg.qmdColdTierEnabled === true,
     qmdColdCollection:
       typeof cfg.qmdColdCollection === "string" && cfg.qmdColdCollection.length > 0
@@ -1780,6 +1719,16 @@ export function parseConfig(
       typeof cfg.sessionObserverDebounceMs === "number"
         ? Math.max(0, Math.floor(cfg.sessionObserverDebounceMs))
         : 120_000,
+    // Explicit validation (issue #1909 review round 8): reject invalid input
+    // rather than flooring/clamping. Must be an integer in [0, 2^31-1] (Node's
+    // setTimeout ceiling); 0 = save every turn; undefined → 3000.
+    bufferSaveDebounceMs: parseIntegerInClosedRange(
+      cfg.bufferSaveDebounceMs,
+      0,
+      2_147_483_647,
+      3_000,
+      "bufferSaveDebounceMs",
+    ),
     sessionObserverBands,
     injectQuestions: cfg.injectQuestions === true,
     commitmentDecayDays: parseIntegerAtLeast(
@@ -2061,10 +2010,8 @@ export function parseConfig(
           (v): v is string => typeof v === "string" && v.length > 0,
         )
       : ["decisions", "principles", "conventions", "runbooks", "entities"],
-    // Cross-namespace query-budget limiter (issue #565 PR 4/5).
-    // Defaults to false — ships disabled so existing deployments are
-    // unaffected. When enabled, the read path throttles a principal that
-    // issues a burst of recalls against namespaces other than their own.
+    // Cross-namespace query-budget limiter (issue #565 PR 4/5). Defaults to
+    // false — ships disabled; when enabled, throttles cross-namespace recall bursts.
     recallCrossNamespaceBudgetEnabled:
       coerceBool(cfg.recallCrossNamespaceBudgetEnabled) ?? false,
     recallCrossNamespaceBudgetWindowMs: (() => {
@@ -2079,6 +2026,7 @@ export function parseConfig(
       const n = coerceNumber(cfg.recallCrossNamespaceBudgetHardLimit);
       return n !== undefined && n > 0 ? Math.floor(n) : 30;
     })(),
+    ...parseRecallConcurrencyConfig(cfg),
     // Recall-audit anomaly detector (issue #565 PR 5/5). Defaults off so
     // existing deployments are unaffected; enable explicitly to let the
     // access surfaces flag suspicious query patterns derived from the
@@ -2126,10 +2074,23 @@ export function parseConfig(
     // opt out with recallMemoryWorthFilterEnabled=false.
     recallMemoryWorthFilterEnabled:
       coerceBool(cfg.recallMemoryWorthFilterEnabled) ?? true,
+    // Trust/Memory-Worth recall stage corpus-level fallback (issue #1905).
+    // Default true: when a candidate is missing from the frontmatter already
+    // loaded on the hot recall path, the stage may fall back to a per-namespace
+    // corpus counter/signal map (version-keyed, so it hits in steady state).
+    // Set false to disable that O(corpus) fallback entirely — the stage then
+    // uses only the preloaded frontmatter plus a bounded-parallel per-candidate
+    // direct read (fully O(candidates)). coerceBool handles "false"/"0" forms.
+    recallTrustStageCorpusFallbackEnabled:
+      coerceBool(cfg.recallTrustStageCorpusFallbackEnabled) ?? true,
     // Hot-memories result cache (issue #1902). Default on: readAllMemories()
     // serves from the version-keyed in-process corpus cache. coerceBool
     // handles "false"/"0" string forms; set false to force disk scans.
     hotMemoriesCacheEnabled: coerceBool(cfg.hotMemoriesCacheEnabled) ?? true,
+    // Scope-aware cache invalidation (issue #1904). Default on: a plain fact
+    // create no longer nukes the QMD/entity caches it can't affect. coerceBool
+    // handles "false"/"0" string forms; set false to restore full-clear-per-write.
+    scopedCacheInvalidationEnabled: coerceBool(cfg.scopedCacheInvalidationEnabled) ?? true,
     // External-edit safety net (issue #1902): the version sentinel gives
     // immediate coherence for cooperating writers, but direct user/git/editor
     // writes to memory files (which the project supports) don't bump it. Bound
@@ -2270,15 +2231,31 @@ export function parseConfig(
         ? cfg.activeRecallPromptStyle
         : "balanced",
     activeRecallCustomInstruction: (() => {
-      const customInstruction =
+      const raw =
         typeof cfg.activeRecallCustomInstruction === "string"
           ? cfg.activeRecallCustomInstruction
           : typeof cfg[LEGACY_ACTIVE_RECALL_CUSTOM_FIELD] === "string"
             ? cfg[LEGACY_ACTIVE_RECALL_CUSTOM_FIELD]
             : "";
-      return customInstruction.trim().length > 0
-        ? customInstruction.trim()
-        : null;
+      return raw.trim().length > 0 ? raw.trim() : null;
+    })(),
+    activeRecallPromptReplacement: (() => {
+      const raw = cfg.activeRecallPromptReplacement;
+      if (raw !== undefined && raw !== null && typeof raw !== "string") {
+        throw new Error(
+          `activeRecallPromptReplacement must be a string; got ${JSON.stringify(raw)}`,
+        );
+      }
+      return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : null;
+    })(),
+    activeRecallPromptOverride: (() => {
+      const raw = cfg.activeRecallPromptOverride;
+      if (raw !== undefined && raw !== null && typeof raw !== "string") {
+        throw new Error(
+          `activeRecallPromptOverride must be a string; got ${JSON.stringify(raw)}`,
+        );
+      }
+      return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : null;
     })(),
     activeRecallPromptAppend:
       typeof cfg.activeRecallPromptAppend === "string" &&
@@ -3127,6 +3104,7 @@ export function parseConfig(
       typeof cfg.entityRetrievalRecentTurns === "number" ? cfg.entityRetrievalRecentTurns : 6,
     entitySchemas,
     recallBudgetChars: recallPipelineConfig.recallBudgetChars,
+    recallProfileMaxRatio: parseRecallProfileMaxRatio(cfg.recallProfileMaxRatio),
     recallOuterTimeoutMs:
       typeof cfg.recallOuterTimeoutMs === "number" ? Math.max(0, Math.floor(cfg.recallOuterTimeoutMs)) : 75_000,
     recallCoreDeadlineMs:
@@ -3301,6 +3279,17 @@ export function parseConfig(
       typeof cfg.proactiveExtractionTimeoutMs === "number"
         ? Math.max(0, Math.floor(cfg.proactiveExtractionTimeoutMs))
         : 2500,
+    proactiveExtractionSkipWhenLocalLlmBusy: ((): boolean => {
+      const raw = cfg.proactiveExtractionSkipWhenLocalLlmBusy;
+      if (raw === undefined || raw === null) return true;
+      const value = coerceBooleanLike(raw, "proactiveExtractionSkipWhenLocalLlmBusy");
+      if (value === undefined) {
+        throw new Error(
+          `proactiveExtractionSkipWhenLocalLlmBusy must be boolean-like (true|false|1|0|yes|no|on|off); got ${JSON.stringify(raw)}`,
+        );
+      }
+      return value;
+    })(),
     proactiveExtractionMaxTokens:
       typeof cfg.proactiveExtractionMaxTokens === "number"
         ? Math.max(0, Math.floor(cfg.proactiveExtractionMaxTokens))
@@ -3531,6 +3520,11 @@ export function parseConfig(
     memoryReconstructionMaxExpansions:
       typeof cfg.memoryReconstructionMaxExpansions === "number" ? Math.max(0, Math.round(cfg.memoryReconstructionMaxExpansions)) : 3,
     graphLateralInhibitionEnabled: cfg.graphLateralInhibitionEnabled !== false,
+    // Incremental GraphIndex edge cache (issue #1904). Default on: single-writer
+    // edge appends are pushed into the warm cache in place (size-revalidated for
+    // cross-process coherence) instead of nulling + re-reading the 6 MB edge
+    // file. coerceBool handles string forms; set false to null the cache per write.
+    graphEdgeCacheIncrementalEnabled: coerceBool(cfg.graphEdgeCacheIncrementalEnabled) ?? true,
     graphLateralInhibitionBeta:
       typeof cfg.graphLateralInhibitionBeta === "number"
         ? Math.max(0, Math.min(1, cfg.graphLateralInhibitionBeta))
@@ -3563,10 +3557,9 @@ export function parseConfig(
       Number.isFinite(cfg.graphEdgeDecayVisibilityThreshold)
         ? Math.max(0, Math.min(1, cfg.graphEdgeDecayVisibilityThreshold))
         : 0.2,
-    // Issue #681 PR 3/3 — confidence-aware traversal & PageRank refinement.
-    // Floor clamps to [0, 1] so misconfigured input cannot accept negative
-    // confidences or reject every edge. Iterations floors at 0 so a
-    // documented 0 disables PageRank refinement and BFS scores pass through.
+    ...parseBoundedJsonlStateConfig(cfg, parseIntegerAtLeast),
+    // Issue #681 PR 3/3 — confidence-aware traversal. Floor clamps to [0,1]; a
+    // documented 0 iterations disables PageRank refinement (BFS scores pass through).
     graphTraversalConfidenceFloor:
       typeof cfg.graphTraversalConfidenceFloor === "number" &&
       Number.isFinite(cfg.graphTraversalConfidenceFloor)
@@ -4127,6 +4120,17 @@ function clampNonNegativeNumber(value: unknown): number | undefined {
   return Math.max(0, Math.floor(value));
 }
 
+function parseRecallProfileMaxRatio(value: unknown): number {
+  if (value === undefined) return 0.3;
+  const ratio = coerceNumber(value);
+  if (ratio === undefined || ratio < 0 || ratio > 1) {
+    throw new Error(
+      `recallProfileMaxRatio must be a finite number in [0, 1]; got ${JSON.stringify(value)}`,
+    );
+  }
+  return ratio;
+}
+
 /**
  * Cursor L on PR #736: numeric config keys must accept BOTH numbers
  * and CLI-string forms (`--config peerProfileReasonerMinInteractions=10`

package/src/connector-provenance-lifecycle.test.ts

@@ -295,9 +295,9 @@ test("runExtraction: mixed tagged+untagged turns → persistExtraction receives
             validAt?: string;
             sourceConnector?: string;
           }
-        ): Promise<string[]> => {
+        ): Promise<{ persistedIds: string[]; memoryPathById: Map<string, string> }> => {
           spy(sourceContext);
-          return ["fact-1"];
+          return { persistedIds: ["fact-1"], memoryPathById: new Map() };
         },
         maybeCapturePassiveCorrections: async () => {},
         resolveSelfNamespace: () => "default",
@@ -397,9 +397,9 @@ test("runExtraction: context-only turns without sourceConnector do not affect at
           validAt?: string;
           sourceConnector?: string;
         }
-      ): Promise<string[]> => {
+      ): Promise<{ persistedIds: string[]; memoryPathById: Map<string, string> }> => {
         capturedConnector = sourceContext?.sourceConnector;
-        return ["fact-1"];
+        return { persistedIds: ["fact-1"], memoryPathById: new Map() };
       },
       maybeCapturePassiveCorrections: async () => {},
       resolveSelfNamespace: () => "default",

package/src/connectors/coerce.test.ts

@@ -0,0 +1,131 @@
+import { strict as assert } from "node:assert";
+import { afterEach, beforeEach, test } from "node:test";
+
+import { coerceBool, coerceNumber } from "./coerce.js";
+import { initLogger, resetLogger } from "../logger.js";
+
+let warnings: string[];
+
+beforeEach(() => {
+  warnings = [];
+  initLogger(
+    {
+      info() {},
+      warn(msg: string) {
+        warnings.push(msg);
+      },
+      error() {},
+      debug() {},
+    },
+    false,
+    { timestamps: false },
+  );
+});
+
+afterEach(() => {
+  // Restore the no-op backend so later suites do not inherit this capture sink.
+  initLogger({ info() {}, warn() {}, error() {}, debug() {} });
+});
+
+test("coerceBool recognizes canonical true/false spellings without warning", () => {
+  for (const t of ["true", "1", "yes", "on", "TRUE", " On "]) {
+    assert.equal(coerceBool(t), true, `${t} → true`);
+  }
+  for (const f of ["false", "0", "no", "off", "FALSE", " Off "]) {
+    assert.equal(coerceBool(f), false, `${f} → false`);
+  }
+  assert.equal(coerceBool(true), true);
+  assert.equal(coerceBool(false), false);
+  assert.deepEqual(warnings, [], "recognized values must not warn");
+});
+
+test("coerceBool returns undefined silently for absent values", () => {
+  assert.equal(coerceBool(undefined), undefined);
+  assert.equal(coerceBool(null), undefined);
+  assert.equal(coerceBool(""), undefined);
+  assert.equal(coerceBool("   "), undefined);
+  assert.deepEqual(warnings, [], "absent/empty must be treated as 'use default', no warning");
+});
+
+test("coerceBool warns on a present-but-unrecognized string and returns undefined", () => {
+  assert.equal(coerceBool("disabled"), undefined);
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /unrecognized boolean value "disabled"/);
+  assert.match(warnings[0], /using default/);
+});
+
+test("coerceBool includes the label in the warning when provided", () => {
+  assert.equal(coerceBool("fales", "qmdForceCpu"), undefined);
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /for qmdForceCpu/);
+});
+
+test("coerceBool does not warn on inherited Object keys (prototype safety)", () => {
+  assert.equal(coerceBool("constructor"), undefined);
+  assert.equal(coerceBool("toString"), undefined);
+  assert.equal(coerceBool("hasOwnProperty"), undefined);
+  // These are unrecognized strings, so each warns exactly once — never matched
+  // as a truthy/falsy token via the prototype chain.
+  assert.equal(warnings.length, 3);
+});
+
+test("coerceBool returns undefined without warning for non-string, non-boolean inputs", () => {
+  assert.equal(coerceBool(2), undefined);
+  assert.equal(coerceBool({}), undefined);
+  assert.equal(coerceBool([]), undefined);
+  assert.deepEqual(warnings, []);
+});
+
+test("coerceNumber accepts finite numbers and numeric strings without warning", () => {
+  assert.equal(coerceNumber(5), 5);
+  assert.equal(coerceNumber(0), 0);
+  assert.equal(coerceNumber(-3.5), -3.5);
+  assert.equal(coerceNumber("42"), 42);
+  assert.equal(coerceNumber(" 7 "), 7);
+  assert.deepEqual(warnings, []);
+});
+
+test("coerceNumber returns undefined silently for absent inputs", () => {
+  assert.equal(coerceNumber(undefined), undefined);
+  assert.equal(coerceNumber(null), undefined);
+  assert.equal(coerceNumber(""), undefined);
+  assert.equal(coerceNumber("   "), undefined);
+  assert.deepEqual(warnings, [], "absent numeric inputs do not warn");
+});
+
+test("coerceNumber warns on present non-finite number inputs and returns undefined", () => {
+  assert.equal(coerceNumber(Number.NaN), undefined);
+  assert.equal(coerceNumber(Number.POSITIVE_INFINITY), undefined);
+  assert.equal(coerceNumber(Number.NEGATIVE_INFINITY, "ttlMs"), undefined);
+  assert.equal(warnings.length, 3);
+  assert.match(warnings[0], /non-finite numeric value/);
+  assert.match(warnings[2], /for ttlMs/);
+});
+
+test("coerceNumber warns on a present-but-unparseable string and returns undefined", () => {
+  assert.equal(coerceNumber("abc"), undefined);
+  assert.equal(coerceNumber("NaN"), undefined);
+  assert.equal(coerceNumber("Infinity"), undefined);
+  assert.equal(coerceNumber("12px", "maxResults"), undefined);
+  assert.equal(warnings.length, 4);
+  assert.match(warnings[0], /unrecognized numeric value "abc"/);
+  assert.match(warnings[3], /for maxResults/);
+});
+
+test("warns via console when no logger backend is installed (standalone-core path)", () => {
+  resetLogger();
+  const originalWarn = console.warn;
+  const captured: string[] = [];
+  console.warn = (msg?: unknown) => {
+    captured.push(String(msg));
+  };
+  try {
+    assert.equal(coerceBool("disabled"), undefined);
+    assert.equal(coerceNumber("abc"), undefined);
+  } finally {
+    console.warn = originalWarn;
+  }
+  assert.equal(captured.length, 2);
+  assert.match(captured[0], /^remnic: ignoring unrecognized boolean value "disabled"/);
+  assert.match(captured[1], /^remnic: ignoring unrecognized numeric value "abc"/);
+});

package/src/connectors/coerce.ts

@@ -5,6 +5,28 @@
  * connectors/index.ts can import them without creating a circular dependency.
  */
 
+import { isLoggerInitialized, log } from "../logger.js";
+
+const BOOL_TOKENS: Record<string, boolean> = {
+  true: true, "1": true, yes: true, on: true,
+  false: false, "0": false, no: false, off: false,
+};
+
+/**
+ * Surface a "present but unrecognized config value" diagnostic. Routes through
+ * the installed logger when a host has called `initLogger`, and otherwise falls
+ * back to `console.warn` so the standalone `@remnic/core` path (documented to
+ * call `parseConfig()` without a logger) does not silently discard the warning
+ * and re-introduce the fail-open default this whole change exists to prevent.
+ */
+export function warnUnrecognizedConfig(message: string): void {
+  if (isLoggerInitialized()) {
+    log.warn(message);
+  } else {
+    console.warn(`remnic: ${message}`);
+  }
+}
+
 /**
  * Generic boolean coercion: converts string representations of booleans
  * (e.g. from CLI `--config someFlag=false`) to proper boolean values.
@@ -13,15 +35,28 @@
  * Returns `undefined` when the value is neither a boolean nor a recognised
  * string, so callers can fall back to a default.
  *
+ * A value that is PRESENT but unrecognised (a non-empty string like `"disabled"`
+ * or a typo like `"fales"`) is logged at warn level before returning `undefined`,
+ * so an operator typo does not silently take the caller's default — which is
+ * frequently a fail-open `?? true`. Absent values (`undefined`/`null`/empty
+ * string) fall through silently: absence legitimately means "use the default".
+ * Pass `label` (the config key) to make the warning actionable.
+ *
  * CLAUDE.md gotcha #36: String "false" is truthy in JavaScript.
  * CLAUDE.md gotcha #28: Coerce CLI values to expected types at input boundaries.
+ * CLAUDE.md gotcha #51: Reject/flag present-but-unrecognized values; don't
+ * silently default them.
  */
-export function coerceBool(value: unknown): boolean | undefined {
+export function coerceBool(value: unknown, label?: string): boolean | undefined {
   if (typeof value === "boolean") return value;
   if (typeof value === "string") {
     const v = value.trim().toLowerCase();
-    if (["false", "0", "no", "off"].includes(v)) return false;
-    if (["true", "1", "yes", "on"].includes(v)) return true;
+    if (v === "") return undefined;
+    if (Object.hasOwn(BOOL_TOKENS, v)) return BOOL_TOKENS[v];
+    warnUnrecognizedConfig(
+      `ignoring unrecognized boolean value ${JSON.stringify(value)}${label ? ` for ${label}` : ""}; ` +
+        `expected true|false|1|0|yes|no|on|off — using default`,
+    );
   }
   return undefined;
 }
@@ -33,7 +68,7 @@ export function coerceBool(value: unknown): boolean | undefined {
  * Delegates to the generic `coerceBool` helper. Kept for backward compatibility.
  */
 export function coerceInstallExtension(value: unknown): boolean | undefined {
-  return coerceBool(value);
+  return coerceBool(value, "installExtension");
 }
 
 /**
@@ -46,17 +81,55 @@ export function coerceInstallExtension(value: unknown): boolean | undefined {
  * - string: trimmed, parsed with `Number()`. Returns `undefined` on
  *   empty, NaN, or Infinity.
  *
+ * A PRESENT but unparseable string (a non-empty value that is not a finite
+ * number) is logged at warn level before returning `undefined`, for the same
+ * reason as `coerceBool`: a typo must not silently take the caller's default.
+ * Absent values (`undefined`/`null`/empty string) fall through silently.
+ * Pass `label` (the config key) to make the warning actionable.
+ *
  * CLAUDE.md gotcha #28: Coerce CLI values to expected types at input boundaries.
+ * CLAUDE.md gotcha #51: Flag present-but-unrecognized values.
  */
-export function coerceNumber(value: unknown): number | undefined {
+export function coerceNumber(value: unknown, label?: string): number | undefined {
   if (typeof value === "number") {
-    return Number.isFinite(value) ? value : undefined;
+    if (Number.isFinite(value)) return value;
+    warnUnrecognizedConfig(
+      `ignoring non-finite numeric value ${JSON.stringify(value)}${label ? ` for ${label}` : ""}; ` +
+        `expected a finite number — using default`,
+    );
+    return undefined;
   }
   if (typeof value === "string") {
     const trimmed = value.trim();
     if (trimmed.length === 0) return undefined;
     const n = Number(trimmed);
-    return Number.isFinite(n) ? n : undefined;
+    if (Number.isFinite(n)) return n;
+    warnUnrecognizedConfig(
+      `ignoring unrecognized numeric value ${JSON.stringify(value)}${label ? ` for ${label}` : ""}; ` +
+        `expected a finite number — using default`,
+    );
   }
   return undefined;
 }
+
+/**
+ * Config-layer boolean coercion. Adds numeric 1/0 handling on top of the
+ * canonical `coerceBool` because config values can arrive as JSON numbers,
+ * which `coerceBool` intentionally does not accept. Any other present-but-
+ * unrecognized value (string typo or out-of-range number) warns and returns
+ * `undefined` so a caller's fail-open `?? true` default is not taken silently.
+ *
+ * CLAUDE.md gotcha #36: string "false" is truthy in JavaScript.
+ */
+export function coerceBooleanLike(value: unknown, label?: string): boolean | undefined {
+  if (typeof value === "number") {
+    if (value === 1) return true;
+    if (value === 0) return false;
+    warnUnrecognizedConfig(
+      `ignoring unrecognized boolean value ${JSON.stringify(value)}${label ? ` for ${label}` : ""}; ` +
+        `expected true|false|1|0|yes|no|on|off — using default`,
+    );
+    return undefined;
+  }
+  return coerceBool(value, label);
+}