@remnic/core 1.1.31 → 9.3.516

package/src/plugin-id.ts

@@ -1,3 +1,5 @@
+import { resolvePluginEntry } from "./plugin-entry-resolver.js";
+
 /**
  * Canonical plugin id for @remnic/plugin-openclaw.
  *
@@ -8,77 +10,42 @@
 export const PLUGIN_ID = "openclaw-remnic" as const;
 export const LEGACY_PLUGIN_ID = "openclaw-engram" as const;
 
-/** The set of plugin ids that belong to Remnic (new canonical + legacy). */
-const REMNIC_PLUGIN_IDS: ReadonlySet<string> = new Set([PLUGIN_ID, LEGACY_PLUGIN_ID]);
+const REMNIC_PLUGIN_IDS = [PLUGIN_ID, LEGACY_PLUGIN_ID] as const;
 
 /**
  * Resolve the Remnic plugin entry from an OpenClaw-shaped config object.
  *
- * Lookup order:
- *   1. `plugins.slots.memory` — but **only** when it resolves to a known
- *      Remnic plugin id; foreign slots are ignored so mixed-plugin installs
- *      do not accidentally apply another plugin's config to Remnic.
- *   2. `preferredId` — the caller's own plugin id (e.g. `"openclaw-engram"` for
- *      the shim package); only consulted when no active slot overrides the choice.
- *   3. `plugins.entries["openclaw-remnic"]`
- *   4. `plugins.entries["openclaw-engram"]` (legacy backward-compat)
- *
- * Returns `undefined` when no Remnic entry is found.
- *
- * All five config-loader sites (loadPluginEntryFromFile, readPluginHooksPolicy,
- * loadPluginConfig in access-cli.ts, loadCliPluginConfig in operator-toolkit.ts,
- * and unwrapOpenClawEntry in materialize.cjs) delegate here so fallback order
- * and guard logic are defined in exactly one place.
- *
- * @param raw - The raw OpenClaw config object.
- * @param preferredId - The calling plugin's own id.  When present and no
- *   `plugins.slots.memory` slot is set, this id is tried before the hardcoded
- *   `PLUGIN_ID`/`LEGACY_PLUGIN_ID` fallbacks.  Ignored if it is not a known
- *   Remnic plugin id (safety guard against unexpected values).
+ * Kept as a compatibility subpath for consumers of @remnic/core/plugin-id while
+ * the shared resolver lives in plugin-entry-resolver.ts.
  */
 export function resolveRemnicPluginEntry(
   raw: unknown,
   preferredId?: string,
 ): Record<string, unknown> | undefined {
-  if (!raw || typeof raw !== "object") return undefined;
-  const r = raw as Record<string, unknown>;
-  const plugins =
-    r["plugins"] && typeof r["plugins"] === "object"
-      ? (r["plugins"] as Record<string, unknown>)
-      : undefined;
-  const entries =
-    plugins && plugins["entries"] && typeof plugins["entries"] === "object"
-      ? (plugins["entries"] as Record<string, unknown>)
-      : undefined;
-  if (!entries) return undefined;
-
-  const rawSlot =
-    plugins && plugins["slots"] && typeof plugins["slots"] === "object"
-      ? ((plugins["slots"] as Record<string, unknown>)["memory"] as string | undefined)
-      : undefined;
-  const activeId =
-    typeof rawSlot === "string" && REMNIC_PLUGIN_IDS.has(rawSlot)
-      ? rawSlot
-      : undefined;
-
-  // When no slot is set, honour the caller's own plugin id so shim installs
-  // (id="openclaw-engram") prefer their own entry over the canonical one.
-  const ownId =
-    !activeId &&
-    typeof preferredId === "string" &&
-    REMNIC_PLUGIN_IDS.has(preferredId)
-      ? preferredId
-      : undefined;
-
-  const candidateIds = [activeId, ownId, PLUGIN_ID, LEGACY_PLUGIN_ID].filter(
-    (id): id is string => typeof id === "string",
-  );
-
-  for (const id of candidateIds) {
-    const entry = entries[id];
-    if (entry !== undefined) {
-      return entry as Record<string, unknown>;
-    }
-  }
-  return undefined;
+  return resolvePluginEntry(raw, {
+    candidateIds: REMNIC_PLUGIN_IDS,
+    preferredId,
+    getEntries(candidate) {
+      const plugins = candidate["plugins"];
+      if (!plugins || typeof plugins !== "object" || Array.isArray(plugins)) {
+        return undefined;
+      }
+      const entries = (plugins as Record<string, unknown>)["entries"];
+      return entries && typeof entries === "object" && !Array.isArray(entries)
+        ? (entries as Record<string, unknown>)
+        : undefined;
+    },
+    getSlotId(candidate) {
+      const plugins = candidate["plugins"];
+      if (!plugins || typeof plugins !== "object" || Array.isArray(plugins)) {
+        return undefined;
+      }
+      const slots = (plugins as Record<string, unknown>)["slots"];
+      if (!slots || typeof slots !== "object" || Array.isArray(slots)) {
+        return undefined;
+      }
+      const slotId = (slots as Record<string, unknown>)["memory"];
+      return typeof slotId === "string" ? slotId : undefined;
+    },
+  });
 }

package/src/policy-runtime.test.ts

@@ -0,0 +1,75 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+
+import {
+  PolicyRuntimeManager,
+  readRuntimePolicySnapshot,
+} from "./policy-runtime.js";
+import type { BehaviorLoopPolicyState, PluginConfig } from "./types.js";
+
+function config(): PluginConfig {
+  return {
+    recencyWeight: 0.5,
+    lifecyclePromoteHeatThreshold: 0.7,
+    lifecycleStaleDecayThreshold: 0.2,
+    lifecycleArchiveDecayThreshold: 0.1,
+    cronRecallInstructionHeavyTokenCap: 4_000,
+    behaviorLoopProtectedParams: [],
+  } as unknown as PluginConfig;
+}
+
+function state(nextValue: number): BehaviorLoopPolicyState {
+  return {
+    version: 1,
+    windowDays: 7,
+    minSignalCount: 1,
+    maxDeltaPerCycle: 0.5,
+    protectedParams: [],
+    updatedAt: "2026-01-01T00:00:00.000Z",
+    adjustments: [
+      {
+        parameter: "recencyWeight",
+        previousValue: 0.5,
+        nextValue,
+        delta: nextValue - 0.5,
+        evidenceCount: 3,
+        confidence: 0.9,
+        reason: "test",
+        appliedAt: "2026-01-01T00:00:00.000Z",
+      },
+    ],
+  };
+}
+
+test("PolicyRuntimeManager serializes concurrent mutations without temp path races", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-policy-runtime-"));
+  try {
+    const manager = new PolicyRuntimeManager(dir, config());
+
+    const results = await Promise.all([
+      manager.applyFromBehaviorState(state(0.2)),
+      manager.applyFromBehaviorState(state(0.8)),
+      manager.applyFromBehaviorState(state(0.4)),
+    ]);
+
+    assert.deepEqual(results.map((result) => result.applied), [true, true, true]);
+
+    const snapshot = await readRuntimePolicySnapshot(
+      path.join(dir, "state", "policy-runtime.json"),
+    );
+    assert.ok(snapshot);
+    assert.ok([0.2, 0.8, 0.4].includes(snapshot.values.recencyWeight ?? -1));
+
+    const stateFiles = await readdir(path.join(dir, "state"));
+    assert.equal(
+      stateFiles.some((file) => file.includes(".tmp")),
+      false,
+      "successful concurrent mutations must not leave shared temp files behind",
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/policy-runtime.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { clamp01, clampLifecycleThreshold } from "./lifecycle.js";
 import { clampInstructionHeavyTokenCap } from "./recall-query-policy.js";
@@ -21,6 +22,7 @@ export interface RuntimePolicySnapshot {
 const RUNTIME_POLICY_VERSION = 1;
 const RUNTIME_POLICY_FILE = "policy-runtime.json";
 const RUNTIME_POLICY_PREV_FILE = "policy-runtime.prev.json";
+const mutationQueues = new Map<string, Promise<void>>();
 
 export function sanitizeRuntimePolicyValues(
   values: RuntimePolicyValues,
@@ -90,15 +92,31 @@ export async function readRuntimePolicySnapshot(
 }
 
 async function writeSnapshotAtomic(filePath: string, snapshot: RuntimePolicySnapshot): Promise<void> {
-  const tempPath = `${filePath}.tmp`;
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
   await mkdir(path.dirname(filePath), { recursive: true });
   await writeFile(tempPath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf-8");
   await rename(tempPath, filePath);
 }
 
+function enqueuePolicyMutation<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const previous = mutationQueues.get(key) ?? Promise.resolve();
+  const operation = previous
+    .catch(() => undefined)
+    .then(fn);
+  mutationQueues.set(
+    key,
+    operation.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return operation;
+}
+
 export class PolicyRuntimeManager {
   private readonly runtimePath: string;
   private readonly runtimePrevPath: string;
+  private readonly mutationKey: string;
 
   constructor(
     private readonly memoryDir: string,
@@ -107,6 +125,7 @@ export class PolicyRuntimeManager {
     const stateDir = path.join(memoryDir, "state");
     this.runtimePath = path.join(stateDir, RUNTIME_POLICY_FILE);
     this.runtimePrevPath = path.join(stateDir, RUNTIME_POLICY_PREV_FILE);
+    this.mutationKey = path.resolve(memoryDir);
   }
 
   async loadRuntimeValues(): Promise<RuntimePolicyValues | null> {
@@ -118,6 +137,10 @@ export class PolicyRuntimeManager {
   }
 
   async rollback(): Promise<boolean> {
+    return enqueuePolicyMutation(this.mutationKey, () => this.rollbackUnlocked());
+  }
+
+  private async rollbackUnlocked(): Promise<boolean> {
     const previous = await readRuntimePolicySnapshot(this.runtimePrevPath, {
       maxStaleDecayThreshold: this.config.lifecycleArchiveDecayThreshold,
     });
@@ -131,6 +154,12 @@ export class PolicyRuntimeManager {
 
   async applyFromBehaviorState(
     state: BehaviorLoopPolicyState,
+  ): Promise<{ applied: boolean; rolledBack: boolean; values: RuntimePolicyValues | null; reason: string }> {
+    return enqueuePolicyMutation(this.mutationKey, () => this.applyFromBehaviorStateUnlocked(state));
+  }
+
+  private async applyFromBehaviorStateUnlocked(
+    state: BehaviorLoopPolicyState,
   ): Promise<{ applied: boolean; rolledBack: boolean; values: RuntimePolicyValues | null; reason: string }> {
     const adjustmentCount = state.adjustments.length;
     if (adjustmentCount === 0) {
@@ -161,7 +190,7 @@ export class PolicyRuntimeManager {
           await writeSnapshotAtomic(this.runtimePath, existing);
           rolledBack = true;
         } else {
-          rolledBack = await this.rollback();
+          rolledBack = await this.rollbackUnlocked();
         }
         return {
           applied: false,
@@ -179,7 +208,7 @@ export class PolicyRuntimeManager {
           await writeSnapshotAtomic(this.runtimePath, existing);
           rolledBack = true;
         } else {
-          rolledBack = await this.rollback();
+          rolledBack = await this.rollbackUnlocked();
         }
         return {
           applied: false,

package/src/procedural/procedure-miner.test.ts

@@ -0,0 +1,152 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+
+import { recordCausalTrajectory, type CausalTrajectoryRecord } from "../causal-trajectory.js";
+import type { StorageManager } from "../storage.js";
+import type { PluginConfig } from "../types.js";
+import { runProcedureMining } from "./procedure-miner.js";
+
+function makeConfig(): PluginConfig {
+  return {
+    procedural: {
+      enabled: true,
+      minOccurrences: 2,
+      lookbackDays: 30,
+      successFloor: 1,
+      autoPromoteEnabled: false,
+      autoPromoteOccurrences: 10,
+    },
+  } as PluginConfig;
+}
+
+function makeTrajectory(
+  trajectoryId: string,
+  entityRef: string,
+): CausalTrajectoryRecord {
+  return {
+    schemaVersion: 1,
+    trajectoryId,
+    recordedAt: new Date().toISOString(),
+    sessionKey: "session-procedure-miner",
+    goal: "Build the same long-context workflow",
+    actionSummary: "Confirm the requirements and prepare the working plan.",
+    observationSummary: "The run produced a reusable sequence of actions.",
+    outcomeKind: "success",
+    outcomeSummary: "The workflow completed successfully with a reusable result.",
+    entityRefs: [entityRef],
+  };
+}
+
+test("procedure mining deduplicates by full cluster hash instead of truncated cluster text", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-procedure-miner-"));
+  const written: Array<{ structuredAttributes: Record<string, string> }> = [];
+  const storage = {
+    async readAllMemories() {
+      return written.map((entry, index) => ({
+        id: `procedure-${index}`,
+        content: "procedure body",
+        frontmatter: {
+          category: "procedure",
+          structuredAttributes: entry.structuredAttributes,
+        },
+      }));
+    },
+    async writeMemory(
+      _category: string,
+      _body: string,
+      options: { structuredAttributes?: Record<string, string> },
+    ) {
+      written.push({
+        structuredAttributes: options.structuredAttributes ?? {},
+      });
+      return `procedure-${written.length}`;
+    },
+  } as unknown as StorageManager;
+
+  try {
+    const sharedPrefix = "entity-".repeat(90);
+    await recordCausalTrajectory({
+      memoryDir,
+      record: makeTrajectory("cluster-a-1", `${sharedPrefix}alpha`),
+    });
+    await recordCausalTrajectory({
+      memoryDir,
+      record: makeTrajectory("cluster-a-2", `${sharedPrefix}alpha`),
+    });
+    await recordCausalTrajectory({
+      memoryDir,
+      record: makeTrajectory("cluster-b-1", `${sharedPrefix}bravo`),
+    });
+    await recordCausalTrajectory({
+      memoryDir,
+      record: makeTrajectory("cluster-b-2", `${sharedPrefix}bravo`),
+    });
+
+    const result = await runProcedureMining({
+      memoryDir,
+      storage,
+      config: makeConfig(),
+    });
+
+    assert.equal(result.clustersProcessed, 2);
+    assert.equal(result.proceduresWritten, 2);
+    assert.equal(new Set(written.map((entry) => entry.structuredAttributes.procedure_cluster)).size, 1);
+    assert.equal(new Set(written.map((entry) => entry.structuredAttributes.procedure_cluster_hash)).size, 2);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("procedure mining serializes concurrent writes for the same cluster", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-procedure-miner-concurrent-"));
+  const written: Array<{ structuredAttributes: Record<string, string> }> = [];
+  const storage = {
+    async readAllMemories() {
+      return written.map((entry, index) => ({
+        id: `procedure-${index}`,
+        content: "procedure body",
+        frontmatter: {
+          category: "procedure",
+          structuredAttributes: entry.structuredAttributes,
+        },
+      }));
+    },
+    async writeMemory(
+      _category: string,
+      _body: string,
+      options: { structuredAttributes?: Record<string, string> },
+    ) {
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      written.push({
+        structuredAttributes: options.structuredAttributes ?? {},
+      });
+      return `procedure-${written.length}`;
+    },
+  } as unknown as StorageManager;
+
+  try {
+    await recordCausalTrajectory({
+      memoryDir,
+      record: makeTrajectory("cluster-concurrent-1", "entity-concurrent"),
+    });
+    await recordCausalTrajectory({
+      memoryDir,
+      record: makeTrajectory("cluster-concurrent-2", "entity-concurrent"),
+    });
+
+    const [first, second] = await Promise.all([
+      runProcedureMining({ memoryDir, storage, config: makeConfig() }),
+      runProcedureMining({ memoryDir, storage, config: makeConfig() }),
+    ]);
+
+    assert.equal(written.length, 1);
+    assert.equal(first.clustersProcessed, 1);
+    assert.equal(second.clustersProcessed, 1);
+    assert.equal(first.proceduresWritten + second.proceduresWritten, 1);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/procedural/procedure-miner.ts

@@ -5,6 +5,9 @@
 import type { PluginConfig } from "../types.js";
 import type { StorageManager } from "../storage.js";
 import type { CausalTrajectoryRecord } from "../causal-trajectory.js";
+import { createHash } from "node:crypto";
+import { mkdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
 import {
   readCausalTrajectoryRecords,
   filterTrajectoriesByLookbackDays,
@@ -15,6 +18,10 @@ import { log } from "../logger.js";
 
 /** Must match truncation on `procedure_cluster` structured attribute (dedupe + storage). */
 const PROCEDURE_CLUSTER_ATTR_MAX = 500;
+const PROCEDURE_CLUSTER_LOCK_STALE_MS = 120_000;
+const PROCEDURE_CLUSTER_LOCK_TIMEOUT_MS = 30_000;
+
+const inProcessClusterWriteLocks = new Map<string, Promise<void>>();
 
 export interface ProcedureMiningResult {
   clustersProcessed: number;
@@ -28,6 +35,93 @@ function clusterKey(record: CausalTrajectoryRecord): string {
   return `${goal}|${refs.join(",")}`;
 }
 
+function clusterKeyHash(cluster: string): string {
+  return createHash("sha256").update(cluster).digest("hex");
+}
+
+function isErrnoCode(error: unknown, code: string): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === code
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function acquireClusterWriteLock(memoryDir: string, clusterHash: string): Promise<() => Promise<void>> {
+  const lockRoot = path.join(path.resolve(memoryDir), "state", "procedure-miner-locks");
+  const lockDir = path.join(lockRoot, `${clusterHash}.lock`);
+  await mkdir(lockRoot, { recursive: true });
+
+  const startedAt = Date.now();
+  let attempts = 0;
+  while (true) {
+    try {
+      await mkdir(lockDir);
+      return async () => {
+        await rm(lockDir, { recursive: true, force: true });
+      };
+    } catch (err) {
+      if (!isErrnoCode(err, "EEXIST")) throw err;
+    }
+
+    try {
+      const info = await stat(lockDir);
+      if (Date.now() - info.mtimeMs > PROCEDURE_CLUSTER_LOCK_STALE_MS) {
+        await rm(lockDir, { recursive: true, force: true });
+        continue;
+      }
+    } catch (err) {
+      if (isErrnoCode(err, "ENOENT")) continue;
+      throw err;
+    }
+
+    if (Date.now() - startedAt > PROCEDURE_CLUSTER_LOCK_TIMEOUT_MS) {
+      throw new Error(`Timed out waiting for procedure cluster write lock ${clusterHash}`);
+    }
+
+    attempts += 1;
+    await sleep(Math.min(250, 25 * attempts));
+  }
+}
+
+async function withClusterWriteLock<T>(
+  memoryDir: string,
+  clusterHash: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const inProcessKey = `${path.resolve(memoryDir)}:${clusterHash}`;
+  const previous = inProcessClusterWriteLocks.get(inProcessKey) ?? Promise.resolve();
+  let releaseInProcess!: () => void;
+  const current = previous.catch(() => undefined).then(
+    () =>
+      new Promise<void>((resolve) => {
+        releaseInProcess = resolve;
+      }),
+  );
+  inProcessClusterWriteLocks.set(inProcessKey, current);
+
+  await previous.catch(() => undefined);
+  let releaseDisk: (() => Promise<void>) | null = null;
+  try {
+    releaseDisk = await acquireClusterWriteLock(memoryDir, clusterHash);
+    return await fn();
+  } finally {
+    try {
+      if (releaseDisk) await releaseDisk();
+    } finally {
+      releaseInProcess();
+      if (inProcessClusterWriteLocks.get(inProcessKey) === current) {
+        inProcessClusterWriteLocks.delete(inProcessKey);
+      }
+    }
+  }
+}
+
 function successRate(group: CausalTrajectoryRecord[]): number {
   if (group.length === 0) return 0;
   const ok = group.filter((g) => g.outcomeKind === "success" || g.outcomeKind === "partial").length;
@@ -66,9 +160,15 @@ async function hasExistingClusterWrite(
   cluster: string,
 ): Promise<boolean> {
   const clusterKey = cluster.slice(0, PROCEDURE_CLUSTER_ATTR_MAX);
+  const clusterHash = clusterKeyHash(cluster);
   const memories = await storage.readAllMemories();
   for (const m of memories) {
     if (m.frontmatter.category !== "procedure") continue;
+    const h = m.frontmatter.structuredAttributes?.procedure_cluster_hash;
+    if (typeof h === "string") {
+      if (h === clusterHash) return true;
+      continue;
+    }
     const c = m.frontmatter.structuredAttributes?.procedure_cluster;
     if (c === clusterKey) return true;
   }
@@ -115,35 +215,40 @@ export async function runProcedureMining(options: {
 
     clustersProcessed += 1;
 
-    if (await hasExistingClusterWrite(options.storage, key)) {
-      log.debug(`procedure-miner: skip duplicate cluster key=${key.slice(0, 40)}…`);
-      continue;
-    }
-
     const steps = normalizeProcedureSteps(pseudoStepsFromCluster(group));
     if (steps.length < 2) continue;
 
     const title = `When you work on goals like: ${group[0].goal.trim().slice(0, 140)}`;
     const body = buildProcedurePersistBody(title, steps);
+    const clusterHash = clusterKeyHash(key);
 
     const promote =
       cfg.autoPromoteEnabled === true && group.length >= cfg.autoPromoteOccurrences && rate >= cfg.successFloor;
 
-    await options.storage.writeMemory("procedure", body, {
-      source: "procedure-miner",
-      status: promote ? "active" : "pending_review",
-      tags: ["procedure-miner", "causal-trajectory"],
-      structuredAttributes: {
-        procedure_cluster: key.slice(0, PROCEDURE_CLUSTER_ATTR_MAX),
-        trajectory_ids: group
-          .map((g) => g.trajectoryId)
-          .join(",")
-          .slice(0, 1900),
-        trajectory_count: String(group.length),
-        success_rate: rate.toFixed(4),
-      },
+    const wrote = await withClusterWriteLock(options.memoryDir, clusterHash, async () => {
+      if (await hasExistingClusterWrite(options.storage, key)) {
+        log.debug(`procedure-miner: skip duplicate cluster key=${key.slice(0, 40)}…`);
+        return false;
+      }
+
+      await options.storage.writeMemory("procedure", body, {
+        source: "procedure-miner",
+        status: promote ? "active" : "pending_review",
+        tags: ["procedure-miner", "causal-trajectory"],
+        structuredAttributes: {
+          procedure_cluster: key.slice(0, PROCEDURE_CLUSTER_ATTR_MAX),
+          procedure_cluster_hash: clusterHash,
+          trajectory_ids: group
+            .map((g) => g.trajectoryId)
+            .join(",")
+            .slice(0, 1900),
+          trajectory_count: String(group.length),
+          success_rate: rate.toFixed(4),
+        },
+      });
+      return true;
     });
-    proceduresWritten += 1;
+    if (wrote) proceduresWritten += 1;
   }
 
   return { clustersProcessed, proceduresWritten };

package/src/profiling.test.ts

@@ -139,6 +139,29 @@ describe("ProfilingCollector", () => {
     }
   });
 
+  test("getRecentTraces handles zero, positive, and omitted limits", () => {
+    const dir = tempDir();
+    try {
+      const collector = new ProfilingCollector({
+        enabled: true,
+        storageDir: dir,
+        maxTraces: 10,
+      });
+
+      const id1 = collector.startTrace("recall");
+      collector.endTrace(id1);
+      const id2 = collector.startTrace("extraction");
+      collector.endTrace(id2);
+
+      assert.deepEqual(collector.getRecentTraces(0), []);
+      assert.deepEqual(collector.getRecentTraces(-1), []);
+      assert.equal(collector.getRecentTraces(1).length, 1);
+      assert.equal(collector.getRecentTraces().length, 2);
+    } finally {
+      cleanup(dir);
+    }
+  });
+
   test("isolates concurrent traces — spans do not cross-contaminate", () => {
     const dir = tempDir();
     try {

package/src/profiling.ts

@@ -293,7 +293,16 @@ export class ProfilingCollector {
   // ---- Query methods -----------------------------------------------------
 
   getRecentTraces(limit?: number): ProfileTrace[] {
-    const n = limit ?? this.traces.length;
+    if (limit === undefined || limit === Infinity) {
+      return [...this.traces];
+    }
+    if (!Number.isFinite(limit)) {
+      return [];
+    }
+    const n = Math.floor(limit);
+    if (n <= 0) {
+      return [];
+    }
     return this.traces.slice(-n);
   }