@remnic/core 9.7.15 → 9.9.0

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);
+}

package/src/contradiction/contradiction.test.ts

@@ -24,6 +24,7 @@ import { executeResolution, isValidResolutionVerb } from "./resolution.js";
 import { ACTIVE_STATUSES, runContradictionScan } from "./contradiction-scan.js";
 import { parseConfig } from "../config.js";
 import type { StorageManager } from "../storage.js";
+import { sealedWriteToLegacyArgs, type SealedMemoryEnvelope } from "../write-envelope.js";
 import type { MemoryCategory, MemoryFile, MemoryFrontmatter } from "../types.js";
 
 type FrontmatterLifecycleOptions = Parameters<StorageManager["writeMemoryFrontmatter"]>[2];
@@ -117,12 +118,15 @@ function makeResolutionStorage(options: {
       const memory = memories.get(id);
       return memory ? cloneMemory(memory) : null;
     },
-    async writeMemory(category: MemoryCategory, content: string, writeOptions: {
-      lineage?: string[];
-      derivedFrom?: string[];
-      derivedVia?: string;
-      tags?: string[];
-    }) {
+    // Production mapper keeps this legacy-shaped double faithful (§21).
+    async writeSealedMemory(envelope: SealedMemoryEnvelope, extras: Record<string, unknown>) {
+      const { category, content, options } = sealedWriteToLegacyArgs(envelope, extras);
+      const writeOptions = options as {
+        lineage?: string[];
+        derivedFrom?: string[];
+        derivedVia?: string;
+        tags?: string[];
+      };
       const id = `merged-created-${memories.size}`;
       const memory = makeMemory(id, category);
       memory.content = content;

package/src/contradiction/resolution.ts

@@ -6,6 +6,7 @@
  */
 
 import { log } from "../logger.js";
+import { composeMemoryEnvelope } from "../write-envelope.js";
 import type { StorageManager } from "../storage.js";
 import type { MemoryCategory, MemoryFile } from "../types.js";
 import type { ResolutionVerb } from "./contradiction-review.js";
@@ -386,11 +387,23 @@ async function prepareMergeReplacement(
   const category = options.mergedCategory ?? mergedMemoryCategory(sourceA, sourceB);
   let mergedId: string;
   try {
-    const mergeResult = await storage.writeMemory(category, mergedContent, {
+    // Sealed-envelope write (issue #1989 PR4): merged content is
+    // LLM-produced — salvage; drops are warn-logged.
+    const mergeEnvelope = composeMemoryEnvelope(
+      {
+        content: mergedContent,
+        category,
+        confidence: Math.min(sourceA.frontmatter.confidence ?? 0.8, sourceB.frontmatter.confidence ?? 0.8),
+        tags: ["contradiction-resolution", "merge"],
+      },
+      { source: "contradiction-resolution" },
+      { salvage: true },
+    );
+    if (mergeEnvelope.salvageNotes.length > 0) {
+      log.warn(`contradiction-resolution write salvaged invalid fields: ${mergeEnvelope.salvageNotes.join("; ")}`);
+    }
+    const mergeResult = await storage.writeSealedMemory(mergeEnvelope, {
       actor: "contradiction-resolution",
-      confidence: Math.min(sourceA.frontmatter.confidence ?? 0.8, sourceB.frontmatter.confidence ?? 0.8),
-      tags: ["contradiction-resolution", "merge"],
-      source: "contradiction-resolution",
       lineage: [idA, idB],
       derivedVia: "merge",
     });

package/src/correction/correction-access-wiring.ts

@@ -21,6 +21,8 @@
  */
 
 import path from "node:path";
+import { composeMemoryEnvelope, isMemoryCategory } from "../write-envelope.js";
+import { log } from "../logger.js";
 import { createHash } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import type { Orchestrator } from "../orchestrator.js";
@@ -402,20 +404,39 @@ async function writeReplacementMemory(
   // writeMemory is the single storage chokepoint — catalog/dedup/reindex fire
   // here (rule 43). Tombstone blocking also fires here (#1579), so a
   // resurrected fact lands as pending_review rather than silently overwriting.
-  const { id, tombstoneBlocked } = await storage.writeMemory(
-    (draft.category ?? "fact") as Parameters<typeof storage.writeMemory>[0],
-    draft.content,
+  // Sealed-envelope write (issue #1989 PR4): correction drafts carry
+  // plan-derived (machine) field values — salvage so one malformed optional
+  // field cannot make a correction unapplicable; drops are warn-logged.
+  // Category is IDENTITY and stays fatal (#2022 review): default to "fact"
+  // only when ABSENT (the legacy default); an explicit unrecognized value
+  // must surface as a contract error, not silently change the correction's
+  // meaning before it supersedes the target.
+  if (draft.category !== undefined && !isMemoryCategory(draft.category)) {
+    throw new CorrectionContractError(
+      `correction draft carries unrecognized category ${JSON.stringify(draft.category)} — expected a valid memory category`,
+    );
+  }
+  const draftCategory = draft.category ?? ("fact" as const);
+  const draftEnvelope = composeMemoryEnvelope(
     {
-      source: "correction",
+      content: draft.content,
+      category: draftCategory,
       confidence: draft.confidence ?? 0.9,
       tags: draft.tags ?? [],
       ...(draft.entityRef ? { entityRef: draft.entityRef } : {}),
       ...(draft.validAt ? { validAt: draft.validAt } : {}),
-      ...(draft.observedAt ? { observedAt: draft.observedAt } : {}),
       ...(draft.structuredAttributes ? { structuredAttributes: draft.structuredAttributes } : {}),
-      ...(draft.supersedes ? { supersedes: draft.supersedes } : {}),
     },
+    { source: "correction" },
+    { salvage: true },
   );
+  if (draftEnvelope.salvageNotes.length > 0) {
+    log.warn(`correction write salvaged invalid fields: ${draftEnvelope.salvageNotes.join("; ")}`);
+  }
+  const { id, tombstoneBlocked } = await storage.writeSealedMemory(draftEnvelope, {
+    ...(draft.observedAt ? { observedAt: draft.observedAt } : {}),
+    ...(draft.supersedes ? { supersedes: draft.supersedes } : {}),
+  });
   if (tombstoneBlocked) {
     // #1645 (review thread): the replacement content matched a tombstone, so it
     // landed pending_review (non-active). Returning the id would let the
@@ -516,13 +537,27 @@ async function rescopeMemoryFn(
   const destContent = fm.structuredAttributes
     ? stripAttributesSuffix(memory.content)
     : memory.content;
-  const { id: destId, tombstoneBlocked: destBlocked } = await destStorage.writeMemory(fm.category, destContent, {
-    source: `correction:rescope:${namespace}`,
-    ...(typeof fm.confidence === "number" ? { confidence: fm.confidence } : {}),
-    ...(Array.isArray(fm.tags) ? { tags: fm.tags } : {}),
-    ...(fm.entityRef ? { entityRef: fm.entityRef } : {}),
-    ...(fm.structuredAttributes ? { structuredAttributes: fm.structuredAttributes } : {}),
-    ...(fm.valid_at ? { validAt: fm.valid_at } : {}),
+  // Sealed-envelope write (issue #1989 PR4): a rescope REPLAYS stored
+  // frontmatter — legacy rows may predate current field limits, and a
+  // rescope must never be impossible for data already in the store, so
+  // compose in salvage mode (drops warn-logged).
+  const rescopeEnvelope = composeMemoryEnvelope(
+    {
+      content: destContent,
+      category: fm.category,
+      ...(typeof fm.confidence === "number" ? { confidence: fm.confidence } : {}),
+      ...(Array.isArray(fm.tags) ? { tags: fm.tags } : {}),
+      ...(fm.entityRef ? { entityRef: fm.entityRef } : {}),
+      ...(fm.structuredAttributes ? { structuredAttributes: fm.structuredAttributes } : {}),
+      ...(fm.valid_at ? { validAt: fm.valid_at } : {}),
+    },
+    { source: `correction:rescope:${namespace}` },
+    { salvage: true },
+  );
+  if (rescopeEnvelope.salvageNotes.length > 0) {
+    log.warn(`rescope write salvaged invalid fields: ${rescopeEnvelope.salvageNotes.join("; ")}`);
+  }
+  const { id: destId, tombstoneBlocked: destBlocked } = await destStorage.writeSealedMemory(rescopeEnvelope, {
     ...(fm.observedAt ? { observedAt: fm.observedAt } : {}),
     ...(fm.memoryKind ? { memoryKind: fm.memoryKind } : {}),
     ...(Array.isArray(fm.links) ? { links: fm.links } : {}),
@@ -669,11 +704,20 @@ async function appendAuditRecordFn(
   // Corrections are themselves memories, searchable and namespaced (issue
   // #1580 design §4). Write a correction-category memory capturing the
   // plan + outcome as the audit trail.
-  const { id: id } = await storage.writeMemory("correction", buildAuditBody(record), {
-    source: "correction-contract",
-    confidence: 1.0,
-    tags: ["correction-audit", `plan:${record.planId}`, `classification:${record.classification}`],
-  });
+  // Sealed-envelope write (issue #1989 PR4): system-built audit body —
+  // strict compose; an invalid audit record is a code bug.
+  const { id: id } = await storage.writeSealedMemory(
+    composeMemoryEnvelope(
+      {
+        content: buildAuditBody(record),
+        category: "correction",
+        confidence: 1.0,
+        tags: ["correction-audit", `plan:${record.planId}`, `classification:${record.classification}`],
+      },
+      { source: "correction-contract" },
+    ),
+    {},
+  );
   return id;
 }
 

package/src/cross-namespace-budget.test.ts

@@ -355,3 +355,38 @@ test("inverted soft/hard limits clamp soft <= hard", () => {
   const cfg = limiter.getConfig();
   assert.equal(cfg.softLimit, cfg.hardLimit);
 });
+
+test("release(token) removes the EXACT reserved entry, not the newest (issue #1906 review #4)", () => {
+  const limiter = new CrossNamespaceBudget({
+    enabled: true,
+    softLimit: 0,
+    hardLimit: 10,
+    windowMs: 60_000,
+  });
+
+  // A reserves first (older), B reserves later (newer).
+  const a = limiter.record("p1", 0);
+  const b = limiter.record("p1", 1_000);
+  assert.ok(a.reservation, "an allowed record returns a reservation token");
+  assert.ok(b.reservation);
+  assert.equal(a.count, 1);
+  assert.equal(b.count, 2);
+
+  // A fails and releases ITS token. A naive pop-newest would drop B's entry.
+  limiter.release(a.reservation);
+
+  // Advance so A's original timestamp (t=0) would have expired but B's (t=1000)
+  // is still live. A fresh record counts only B + itself => 2. If B had been
+  // wrongly removed, only the fresh entry would remain => 1.
+  const after = limiter.record("p1", 60_500);
+  assert.equal(
+    after.count,
+    2,
+    "B's newer reservation survives A's release (A's exact entry was removed)",
+  );
+
+  // release() is idempotent and a no-op for an unknown/already-freed token.
+  limiter.release(a.reservation);
+  limiter.release(undefined);
+  assert.equal(limiter.bucketCount(), 1);
+});