@remnic/core 9.7.15 → 9.9.0

package/src/write-quarantine.test.ts

@@ -0,0 +1,245 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readdir, rm, symlink, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { WriteQuarantineStore } from "./write-quarantine.js";
+
+async function withTempDir(fn: (dir: string) => Promise<void>): Promise<void> {
+  const dir = await mkdtemp(path.join(tmpdir(), "remnic-quarantine-"));
+  try {
+    await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+function isInside(root: string, child: string): boolean {
+  const rel = path.relative(path.resolve(root), path.resolve(child));
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+test("quarantine writes a record under state/quarantine and list() returns it", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir);
+    const written = await store.quarantine({
+      operation: "memory_store",
+      principal: "alice",
+      attemptedNamespace: "victim-secret",
+      payload: { content: "hello" },
+    });
+
+    assert.ok(isInside(path.join(dir, "state", "quarantine"), written));
+
+    const records = await store.list();
+    assert.equal(records.length, 1);
+    assert.equal(records[0]?.operation, "memory_store");
+    assert.equal(records[0]?.principal, "alice");
+    assert.equal(records[0]?.attemptedNamespace, "victim-secret");
+    assert.deepEqual(records[0]?.payload, { content: "hello" });
+  });
+});
+
+test("principal with path-traversal characters stays contained in the root", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir);
+    const written = await store.quarantine({
+      operation: "observe",
+      principal: "../../etc",
+      attemptedNamespace: "default",
+      payload: { messages: [] },
+    });
+
+    assert.ok(isInside(store.root, written), `escaped root: ${written}`);
+
+    // The principal is preserved verbatim in the record even though the
+    // on-disk segment is encoded.
+    const records = await store.list();
+    assert.equal(records.length, 1);
+    assert.equal(records[0]?.principal, "../../etc");
+  });
+});
+
+test("count reflects entries across principals", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir);
+    await store.quarantine({ operation: "memory_store", principal: "alice", attemptedNamespace: "ns", payload: 1 });
+    await store.quarantine({ operation: "observe", principal: "bob", attemptedNamespace: "ns", payload: 2 });
+    assert.equal(await store.count(), 2);
+  });
+});
+
+test("maxEntriesPerPrincipal caps a principal bucket", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir, { maxEntriesPerPrincipal: 2, maxAgeMs: 60 * 60 * 1000 });
+    for (let i = 0; i < 5; i++) {
+      await store.quarantine({ operation: "memory_store", principal: "alice", attemptedNamespace: "ns", payload: i });
+      await store.quarantine({ operation: "memory_store", principal: "bob", attemptedNamespace: "ns", payload: i });
+    }
+    const records = await store.list();
+    // The cap is per principal, not global: two survive for each.
+    assert.equal(records.length, 4);
+    assert.equal(records.filter((r) => r.principal === "alice").length, 2);
+    assert.equal(records.filter((r) => r.principal === "bob").length, 2);
+  });
+});
+
+test("age cap drops records older than maxAgeMs", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir, { maxEntriesPerPrincipal: 1000, maxAgeMs: 1_000 });
+    const oldPath = await store.quarantine({
+      operation: "memory_store",
+      principal: "alice",
+      attemptedNamespace: "ns",
+      payload: "old",
+    });
+    // Backdate the first record an hour into the past.
+    const hourAgo = new Date(Date.now() - 60 * 60 * 1000);
+    await utimes(oldPath, hourAgo, hourAgo);
+
+    // A fresh write into the same bucket triggers the prune.
+    await store.quarantine({
+      operation: "memory_store",
+      principal: "alice",
+      attemptedNamespace: "ns",
+      payload: "new",
+    });
+
+    const records = await store.list();
+    assert.equal(records.length, 1);
+    assert.equal(records[0]?.payload, "new");
+  });
+});
+
+test("list() skips malformed and wrong-shape JSON files", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir);
+    await store.quarantine({ operation: "memory_store", principal: "alice", attemptedNamespace: "ns", payload: "ok" });
+
+    // Drop a corrupt file and a valid-JSON-but-wrong-shape file beside the good
+    // record in the principal bucket.
+    const quarantineRoot = path.join(dir, "state", "quarantine");
+    const [principalName] = await readdir(quarantineRoot);
+    const principalDir = path.join(quarantineRoot, principalName ?? "");
+    await writeFile(path.join(principalDir, "corrupt.json"), "{ not json", "utf8");
+    await writeFile(path.join(principalDir, "wrong-shape.json"), "{}", "utf8");
+
+    const records = await store.list();
+    assert.equal(records.length, 1);
+    assert.equal(records[0]?.payload, "ok");
+    assert.equal(await store.count(), 1);
+  });
+});
+
+test("constructor rejects invalid retention caps", () => {
+  assert.throws(() => new WriteQuarantineStore("/tmp/x", { maxEntriesPerPrincipal: 0, maxAgeMs: 1000 }));
+  assert.throws(() => new WriteQuarantineStore("/tmp/x", { maxEntriesPerPrincipal: 1.5, maxAgeMs: 1000 }));
+  assert.throws(() => new WriteQuarantineStore("/tmp/x", { maxEntriesPerPrincipal: 10, maxAgeMs: Number.NaN }));
+  assert.throws(() => new WriteQuarantineStore("/tmp/x", { maxEntriesPerPrincipal: 10, maxAgeMs: 0 }));
+});
+
+test("expired records are dropped on read even without a follow-up write", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir, { maxEntriesPerPrincipal: 1000, maxAgeMs: 1_000 });
+    const only = await store.quarantine({
+      operation: "memory_store",
+      principal: "alice",
+      attemptedNamespace: "ns",
+      payload: "old",
+    });
+    const hourAgo = new Date(Date.now() - 60 * 60 * 1000);
+    await utimes(only, hourAgo, hourAgo);
+
+    // No further write; list()/count() must expire it and delete the file.
+    assert.equal(await store.count(), 0);
+    assert.deepEqual(await store.list(), []);
+  });
+});
+
+test("a symlinked state directory is not followed outside the memory dir", async () => {
+  await withTempDir(async (dir) => {
+    const external = await mkdtemp(path.join(tmpdir(), "remnic-quarantine-ext-"));
+    try {
+      // Replace <memoryDir>/state with a symlink to an external directory.
+      await symlink(external, path.join(dir, "state"), "dir");
+      const store = new WriteQuarantineStore(dir);
+
+      await assert.rejects(
+        store.quarantine({ operation: "memory_store", principal: "alice", attemptedNamespace: "ns", payload: "x" })
+      );
+      // Nothing was written into the external directory.
+      assert.deepEqual(await readdir(external), []);
+    } finally {
+      await rm(external, { recursive: true, force: true });
+    }
+  });
+});
+
+test("list() surfaces a symlink-escaping root instead of reporting empty", async () => {
+  await withTempDir(async (dir) => {
+    const external = await mkdtemp(path.join(tmpdir(), "remnic-quarantine-ext-"));
+    try {
+      // A symlinked `state` that escapes the memory dir must not read back as
+      // an empty (all-clear) store — the inspection failure has to surface.
+      await symlink(external, path.join(dir, "state"), "dir");
+      const store = new WriteQuarantineStore(dir);
+      await assert.rejects(store.list());
+      await assert.rejects(store.count());
+    } finally {
+      await rm(external, { recursive: true, force: true });
+    }
+  });
+});
+
+test("entries() pairs each record with its on-disk path and list() projects records", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir);
+    const written = await store.quarantine({
+      operation: "memory_store",
+      principal: "alice",
+      attemptedNamespace: "victim-secret",
+      payload: { content: "hi" },
+    });
+    const entries = await store.entries();
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0]?.path, written);
+    assert.ok(isInside(store.root, entries[0]?.path ?? ""));
+    assert.equal(entries[0]?.record.operation, "memory_store");
+    assert.deepEqual(entries[0]?.record.payload, { content: "hi" });
+    assert.deepEqual(
+      await store.list(),
+      entries.map((entry) => entry.record)
+    );
+  });
+});
+
+test("removeEntry deletes an entry by its path and is idempotent", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir);
+    await store.quarantine({ operation: "observe", principal: "alice", attemptedNamespace: "ns", payload: 1 });
+    const [entry] = await store.entries();
+    assert.ok(entry);
+    assert.equal(await store.removeEntry(entry.path), true);
+    assert.equal(await store.count(), 0);
+    // An already-absent path removes nothing.
+    assert.equal(await store.removeEntry(entry.path), false);
+  });
+});
+
+test("removeEntry refuses a path outside the quarantine root", async () => {
+  await withTempDir(async (dir) => {
+    const store = new WriteQuarantineStore(dir);
+    await store.quarantine({ operation: "observe", principal: "alice", attemptedNamespace: "ns", payload: 1 });
+    const outside = await mkdtemp(path.join(tmpdir(), "remnic-quarantine-outside-"));
+    const victim = path.join(outside, "keep.json");
+    await writeFile(victim, "{}", "utf8");
+    try {
+      assert.equal(await store.removeEntry(victim), false);
+      assert.equal((await readdir(outside)).length, 1, "file outside root must survive");
+      assert.equal(await store.count(), 1, "in-root entry untouched");
+    } finally {
+      await rm(outside, { recursive: true, force: true });
+    }
+  });
+});

package/src/write-quarantine.ts

@@ -0,0 +1,290 @@
+/**
+ * Dead-letter quarantine for writes rejected by the namespace write-ACL
+ * (issue #1888).
+ *
+ * When `observe` / `memory_store` / `suggestion_submit` fail namespace
+ * authorization, the payload used to be dropped with no recoverable copy: a
+ * client configured with a namespace that matches no policy (and is not the
+ * default/shared namespace) had every write in the window silently destroyed.
+ * The ACL rejection is CORRECT and stays fail-closed; this store only
+ * preserves the payload so it can be replayed after the config is fixed,
+ * following the AGENTS.md "reject loudly but never destroy state" posture
+ * (patterns 14/42).
+ *
+ * Records live OUTSIDE any memory namespace at
+ * `<memoryDir>/state/quarantine/<principalSafe>/<timestamp>-<id>.json`, keyed
+ * by the encoded principal, and are bounded per principal by count and age.
+ * Every path is resolved from `memoryDir` through `resolveSafeStoragePath`, so
+ * a symlinked `state`/`quarantine` cannot redirect writes outside the memory
+ * directory. The store never re-routes a payload into a writable namespace.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { Dirent } from "node:fs";
+import { lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { encodeStoragePathSegment, resolveSafeStoragePath } from "./storage-paths.js";
+
+export type QuarantineOperation = "observe" | "memory_store" | "suggestion_submit";
+
+export interface QuarantineEntryInput {
+  operation: QuarantineOperation;
+  /** Authenticated principal the write was attributed to, if any. */
+  principal: string | undefined;
+  /** Namespace the caller attempted to write and was denied. */
+  attemptedNamespace: string;
+  /** The original request payload, preserved verbatim for replay. */
+  payload: unknown;
+  /** ISO timestamp; defaults to now. Injectable for deterministic tests. */
+  timestamp?: string;
+}
+
+export interface QuarantinedRecord {
+  operation: QuarantineOperation;
+  principal: string | null;
+  attemptedNamespace: string;
+  timestamp: string;
+  payload: unknown;
+}
+
+/** A quarantined record paired with the absolute on-disk path it was read from. */
+export interface QuarantineEntry {
+  record: QuarantinedRecord;
+  path: string;
+}
+
+export interface QuarantineCaps {
+  /** Keep at most this many records per principal (newest win). */
+  maxEntriesPerPrincipal: number;
+  /** Drop records older than this many milliseconds. */
+  maxAgeMs: number;
+}
+
+export const DEFAULT_QUARANTINE_CAPS: QuarantineCaps = {
+  maxEntriesPerPrincipal: 500,
+  maxAgeMs: 14 * 24 * 60 * 60 * 1000,
+};
+
+const QUARANTINE_DIRNAME = "quarantine";
+
+function validateCaps(caps: QuarantineCaps): void {
+  if (!Number.isInteger(caps.maxEntriesPerPrincipal) || caps.maxEntriesPerPrincipal < 1) {
+    throw new Error(
+      `WriteQuarantineStore: maxEntriesPerPrincipal must be a positive integer (got ${caps.maxEntriesPerPrincipal})`
+    );
+  }
+  if (!Number.isFinite(caps.maxAgeMs) || caps.maxAgeMs <= 0) {
+    throw new Error(
+      `WriteQuarantineStore: maxAgeMs must be a positive finite number of milliseconds (got ${caps.maxAgeMs})`
+    );
+  }
+}
+
+function isQuarantinedRecord(value: unknown): value is QuarantinedRecord {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  return (
+    (record.operation === "observe" ||
+      record.operation === "memory_store" ||
+      record.operation === "suggestion_submit") &&
+    (record.principal === null || typeof record.principal === "string") &&
+    typeof record.attemptedNamespace === "string" &&
+    typeof record.timestamp === "string" &&
+    "payload" in record
+  );
+}
+
+export class WriteQuarantineStore {
+  private readonly memoryDir: string;
+
+  constructor(
+    memoryDir: string,
+    private readonly caps: QuarantineCaps = DEFAULT_QUARANTINE_CAPS
+  ) {
+    validateCaps(caps);
+    this.memoryDir = path.resolve(memoryDir);
+  }
+
+  /** Absolute quarantine root (`<memoryDir>/state/quarantine`). */
+  get root(): string {
+    return path.join(this.memoryDir, "state", QUARANTINE_DIRNAME);
+  }
+
+  /**
+   * Resolve a path under the quarantine root, checked for containment and
+   * symlink traversal from `memoryDir` down — so a symlinked `state` or
+   * `quarantine` component that escapes the memory directory is rejected.
+   */
+  private safeDir(...segments: string[]): Promise<string> {
+    return resolveSafeStoragePath(this.memoryDir, "state", QUARANTINE_DIRNAME, ...segments);
+  }
+
+  /**
+   * Park a rejected write. Returns the absolute path of the record written.
+   * Prunes the principal's bucket to the configured caps afterward.
+   */
+  async quarantine(input: QuarantineEntryInput): Promise<string> {
+    const timestamp = input.timestamp ?? new Date().toISOString();
+    const record: QuarantinedRecord = {
+      operation: input.operation,
+      principal: input.principal ?? null,
+      attemptedNamespace: input.attemptedNamespace,
+      timestamp,
+      payload: input.payload,
+    };
+    const principalSegment = encodeStoragePathSegment(input.principal ?? "unknown");
+    const fileName = `${timestamp.replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}.json`;
+
+    const dir = await this.safeDir(principalSegment);
+    await mkdir(dir, { recursive: true });
+    // The temp write uses the exclusive `wx` flag so a pre-planted symlink at
+    // the temp name can never be followed (O_EXCL); rename is atomic (rule 42).
+    const finalPath = await this.safeDir(principalSegment, fileName);
+    const tmpPath = await this.safeDir(principalSegment, `${fileName}.tmp`);
+    await writeFile(tmpPath, JSON.stringify(record, null, 2), { encoding: "utf8", flag: "wx" });
+    await rename(tmpPath, finalPath);
+
+    await this.pruneDir(dir);
+    return finalPath;
+  }
+
+  /**
+   * All valid, non-expired quarantined records across every principal, oldest
+   * first, each paired with its absolute on-disk path. Expired records are
+   * deleted on read (lazy GC), so an inactive principal bucket with no
+   * follow-up write is still bounded by age.
+   */
+  async entries(): Promise<QuarantineEntry[]> {
+    const now = Date.now();
+    const entries: QuarantineEntry[] = [];
+    for (const dir of await this.principalDirs()) {
+      for (const file of await this.entryFiles(dir)) {
+        const info = await stat(file).catch(() => null);
+        if (!info) continue;
+        if (now - info.mtimeMs > this.caps.maxAgeMs) {
+          await rm(file, { force: true }).catch(() => {});
+          continue;
+        }
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(await readFile(file, "utf8"));
+        } catch {
+          continue;
+        }
+        if (isQuarantinedRecord(parsed)) entries.push({ record: parsed, path: file });
+      }
+    }
+    entries.sort((a, b) => {
+      const at = a.record.timestamp;
+      const bt = b.record.timestamp;
+      return at < bt ? -1 : at > bt ? 1 : 0;
+    });
+    return entries;
+  }
+
+  /** As {@link entries} but projected to records only (backward-compatible view). */
+  async list(): Promise<QuarantinedRecord[]> {
+    return (await this.entries()).map((entry) => entry.record);
+  }
+
+  /**
+   * Delete one quarantined entry by its absolute on-disk path (as returned by
+   * {@link entries}). The path MUST resolve inside the quarantine root, mirroring
+   * the store's containment posture; a path outside the root — or one already
+   * absent — removes nothing. Returns true only when a file was actually deleted.
+   */
+  async removeEntry(entryPath: string): Promise<boolean> {
+    const rootAbs = path.resolve(this.root);
+    const rel = path.relative(rootAbs, path.resolve(entryPath));
+    if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+      return false;
+    }
+    // Symlink-race-safe resolution (issue #1888): resolveSafeStoragePath rejects
+    // any symlinked path component and verifies the REAL path stays inside the
+    // real quarantine root before we touch it, so a swapped component cannot
+    // redirect the deletion outside the store — lexical containment alone is not
+    // sufficient against a TOCTOU symlink swap.
+    let safe: string;
+    try {
+      safe = await resolveSafeStoragePath(rootAbs, rel);
+    } catch {
+      return false;
+    }
+    try {
+      await rm(safe, { force: false });
+      return true;
+    } catch (err) {
+      const errno = err as NodeJS.ErrnoException;
+      if (errno?.code === "ENOENT") return false;
+      throw err;
+    }
+  }
+
+  /** Total valid, non-expired quarantined record count across every principal. */
+  async count(): Promise<number> {
+    return (await this.list()).length;
+  }
+
+  /** lstat (no symlink follow): true only for a real directory. */
+  private async isRealDir(dir: string): Promise<boolean> {
+    const info = await lstat(dir).catch(() => null);
+    return info?.isDirectory() === true;
+  }
+
+  private async principalDirs(): Promise<string[]> {
+    // safeDir() rejects a symlinked/containment-escaping root — let that
+    // propagate instead of masquerading as an empty store.
+    const root = await this.safeDir();
+    if (!(await this.isRealDir(root))) return [];
+    let entries: Dirent[];
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch (err) {
+      // Root vanished mid-scan → legitimately empty. Any other failure
+      // (permissions, IO) is a genuine inspection failure and must surface.
+      if ((err as NodeJS.ErrnoException)?.code === "ENOENT") return [];
+      throw err;
+    }
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(root, entry.name))
+      .sort();
+  }
+
+  private async entryFiles(dir: string): Promise<string[]> {
+    if (!(await this.isRealDir(dir))) return [];
+    let entries: Dirent[];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException)?.code === "ENOENT") return [];
+      throw err;
+    }
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => path.join(dir, entry.name))
+      .sort();
+  }
+
+  private async pruneDir(dir: string): Promise<void> {
+    const files = await this.entryFiles(dir);
+    const now = Date.now();
+    const survivors: Array<{ path: string; mtimeMs: number }> = [];
+    for (const file of files) {
+      const info = await stat(file).catch(() => null);
+      if (!info) continue;
+      if (now - info.mtimeMs > this.caps.maxAgeMs) {
+        await rm(file, { force: true }).catch(() => {});
+        continue;
+      }
+      survivors.push({ path: file, mtimeMs: info.mtimeMs });
+    }
+    const surplus = survivors.length - this.caps.maxEntriesPerPrincipal;
+    if (surplus <= 0) return;
+    survivors.sort((a, b) => a.mtimeMs - b.mtimeMs || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    for (const victim of survivors.slice(0, surplus)) {
+      await rm(victim.path, { force: true }).catch(() => {});
+    }
+  }
+}

package/src/write-rate-limiter.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { log } from "./logger.js";
+import { WriteRateLimiter } from "./write-rate-limiter.js";
+
+test("WriteRateLimiter: defaults applied when unset or invalid (issue #1937)", () => {
+  assert.equal(new WriteRateLimiter().maxRequests, 30);
+  assert.equal(new WriteRateLimiter().windowMs, 60_000);
+  assert.equal(new WriteRateLimiter(0).maxRequests, 30, "0 is invalid -> default");
+  assert.equal(new WriteRateLimiter(1.5).maxRequests, 30, "non-integer -> default");
+  const custom = new WriteRateLimiter(120, 30_000);
+  assert.equal(custom.maxRequests, 120);
+  assert.equal(custom.windowMs, 30_000);
+});
+
+test("WriteRateLimiter: capacity check, record, and sampled rejection logging (issue #2029)", () => {
+  const limiter = new WriteRateLimiter(1, 60_000);
+  const warnings: string[] = [];
+  const originalWarn = log.warn;
+  log.warn = (msg: string) => {
+    warnings.push(msg);
+  };
+  try {
+    assert.equal(limiter.hasCapacity(), true);
+    limiter.record();
+    assert.equal(limiter.hasCapacity(), false, "over the limit after one recorded write");
+    assert.equal(limiter.hasCapacity(), false);
+    assert.ok(
+      warnings.some((w) => w.includes("write_rate_limited")),
+      "a refused write is logged server-side",
+    );
+    assert.equal(warnings.length, 1, "logging is sampled within the interval, not per-refusal");
+  } finally {
+    log.warn = originalWarn;
+  }
+});
+
+test("WriteRateLimiter: reserve returns a release, refuses at the limit, frees on release", () => {
+  const limiter = new WriteRateLimiter(1, 60_000);
+  const release = limiter.reserve();
+  assert.ok(release, "first reservation succeeds");
+  assert.equal(limiter.slotsFor().length, 1);
+  assert.equal(limiter.reserve(), null, "second reservation refused at the limit");
+  release?.();
+  assert.equal(limiter.slotsFor().length, 0, "release frees the reserved slot");
+  assert.ok(limiter.reserve(), "capacity restored after release");
+});
+
+test("WriteRateLimiter: old slots pruned after the rolling window", () => {
+  const realNow = Date.now;
+  try {
+    let now = 1_000_000;
+    Date.now = () => now;
+    const limiter = new WriteRateLimiter(1, 1000);
+    limiter.record();
+    assert.equal(limiter.hasCapacity(), false, "at the limit within the window");
+    now += 1001;
+    assert.equal(limiter.hasCapacity(), true, "slot pruned once older than the window");
+  } finally {
+    Date.now = realNow;
+  }
+});
+
+test("WriteRateLimiter: buckets are isolated per principal (issue #2029)", () => {
+  const limiter = new WriteRateLimiter(1, 60_000);
+  limiter.record("alice");
+  assert.equal(limiter.hasCapacity("alice"), false, "alice is at her own limit");
+  assert.equal(limiter.hasCapacity("bob"), true, "bob is unaffected by alice");
+  assert.equal(limiter.hasCapacity(), true, "the no-principal global bucket is separate");
+  limiter.record("bob");
+  assert.equal(limiter.slotsFor("alice").length, 1);
+  assert.equal(limiter.slotsFor("bob").length, 1);
+  assert.equal(limiter.totalSlots(), 2, "each principal keeps its own window");
+});
+
+test("WriteRateLimiter: rolling-window end is exclusive (issue #2029 review)", () => {
+  const realNow = Date.now;
+  try {
+    let now = 1_000_000;
+    Date.now = () => now;
+    const limiter = new WriteRateLimiter(1, 1000);
+    limiter.record();
+    now += 1000; // exactly at recordedAt + windowMs
+    assert.equal(limiter.hasCapacity(), true, "a slot at the exact window end is expired");
+  } finally {
+    Date.now = realNow;
+  }
+});
+
+test("WriteRateLimiter: expired buckets from transient principals are swept globally (issue #2029 review)", () => {
+  const realNow = Date.now;
+  try {
+    let now = 1_000_000;
+    Date.now = () => now;
+    const limiter = new WriteRateLimiter(5, 1000);
+    limiter.record("ephemeral-1");
+    limiter.record("ephemeral-2");
+    assert.equal(limiter.totalSlots(), 2);
+    now += 1001; // both windows expire
+    assert.equal(limiter.totalSlots(), 0, "expired buckets are swept, not reported as live");
+  } finally {
+    Date.now = realNow;
+  }
+});