@remnic/core 9.7.14 → 9.8.0

package/src/write-quarantine.test.ts

@@ -0,0 +1,193 @@
+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 });
+    }
+  });
+});

package/src/write-quarantine.ts

@@ -0,0 +1,241 @@
+/**
+ * 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;
+}
+
+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. Expired records are deleted on read (lazy GC), so an inactive
+   * principal bucket with no follow-up write is still bounded by age.
+   */
+  async list(): Promise<QuarantinedRecord[]> {
+    const now = Date.now();
+    const records: QuarantinedRecord[] = [];
+    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)) records.push(parsed);
+      }
+    }
+    records.sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0));
+    return records;
+  }
+
+  /** 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;
+  }
+});

package/src/write-rate-limiter.ts

@@ -0,0 +1,135 @@
+/**
+ * Per-principal write rate limiter for the access HTTP surface
+ * (issues #1937 / #2029).
+ *
+ * Extracted from access-http.ts so the limiter is a cohesive unit. Each
+ * principal (authenticated caller identity) gets its own rolling-window
+ * bucket, so one chatty connector cannot starve writes for the others;
+ * requests with no resolved principal share a single global bucket.
+ *
+ * Deliberately transport-agnostic: it never throws `HttpError` — callers
+ * translate a refusal into their own 429. It logs a sampled warning when it
+ * refuses a write, so a sustained limit condition is diagnosable server-side
+ * (previously the refusal was a bare throw with no trace).
+ */
+
+import { log } from "./logger.js";
+
+// Defaults; overridable per instance via the constructor (config/env feed these
+// through the server's `writeRateLimit*` settings).
+const DEFAULT_WINDOW_MS = 60_000;
+const DEFAULT_MAX_REQUESTS = 30;
+// At most one rejection warning per this interval, carrying a rejected-count,
+// so a storm is visible without flooding the log.
+const LOG_INTERVAL_MS = 10_000;
+// Bucket key for requests with no resolved principal.
+const GLOBAL_BUCKET = "";
+
+type Slot = { readonly recordedAt: number };
+
+function sanitizePositiveInteger(value: number | undefined, fallback: number): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : fallback;
+}
+
+export class WriteRateLimiter {
+  readonly maxRequests: number;
+  readonly windowMs: number;
+  // One rolling window per principal. Empty buckets are pruned so the map does
+  // not grow without bound.
+  private readonly buckets = new Map<string, Slot[]>();
+  private lastLogAt = 0;
+  private suppressed = 0;
+
+  constructor(maxRequests?: number, windowMs?: number) {
+    this.maxRequests = sanitizePositiveInteger(maxRequests, DEFAULT_MAX_REQUESTS);
+    this.windowMs = sanitizePositiveInteger(windowMs, DEFAULT_WINDOW_MS);
+  }
+
+  private key(principal?: string): string {
+    return principal?.trim() ? principal.trim() : GLOBAL_BUCKET;
+  }
+
+  private prune(slots: Slot[], now: number): void {
+    while (slots.length > 0 && now - (slots[0]?.recordedAt ?? 0) >= this.windowMs) {
+      slots.shift();
+    }
+  }
+
+  /** Prune every bucket to the current window; drop buckets that go empty. */
+  private sweep(now: number): void {
+    for (const [key, slots] of this.buckets) {
+      this.prune(slots, now);
+      if (slots.length === 0) this.buckets.delete(key);
+    }
+  }
+
+  /** Live reservation/record count for a principal (test/introspection). */
+  slotsFor(principal?: string): ReadonlyArray<Slot> {
+    return this.buckets.get(this.key(principal)) ?? [];
+  }
+
+  /** Total live reservations across all principals (test/introspection). */
+  totalSlots(): number {
+    this.sweep(Date.now());
+    let total = 0;
+    for (const slots of this.buckets.values()) total += slots.length;
+    return total;
+  }
+
+  /** True if a write may proceed for the principal. Logs (sampled) when not. */
+  hasCapacity(principal?: string): boolean {
+    this.sweep(Date.now());
+    const key = this.key(principal);
+    const slots = this.buckets.get(key);
+    if (slots && slots.length >= this.maxRequests) {
+      this.logRejected(key);
+      return false;
+    }
+    return true;
+  }
+
+  /** Record a committed write against the principal's rolling window. */
+  record(principal?: string): void {
+    this.sweep(Date.now());
+    const key = this.key(principal);
+    const slots = this.buckets.get(key) ?? this.buckets.set(key, []).get(key)!;
+    slots.push({ recordedAt: Date.now() });
+  }
+
+  /**
+   * Reserve a slot for an in-flight write. Returns a release function, or
+   * `null` when the principal is already at the limit (caller raises its 429).
+   */
+  reserve(principal?: string): (() => void) | null {
+    if (!this.hasCapacity(principal)) return null;
+    const key = this.key(principal);
+    const slots = this.buckets.get(key) ?? this.buckets.set(key, []).get(key)!;
+    const slot: Slot = { recordedAt: Date.now() };
+    slots.push(slot);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const current = this.buckets.get(key);
+      if (!current) return;
+      const index = current.indexOf(slot);
+      if (index >= 0) current.splice(index, 1);
+      if (current.length === 0) this.buckets.delete(key);
+    };
+  }
+
+  private logRejected(principal: string): void {
+    const now = Date.now();
+    this.suppressed += 1;
+    if (now - this.lastLogAt < LOG_INTERVAL_MS) return;
+    const rejected = this.suppressed;
+    this.suppressed = 0;
+    this.lastLogAt = now;
+    const who = principal === GLOBAL_BUCKET ? "(no principal)" : principal;
+    log.warn(
+      `write_rate_limited: rejected ${rejected} write(s) for principal ${who}; ` +
+        `per-principal limit is ${this.maxRequests} per ${this.windowMs}ms. Raise ` +
+        `server.writeRateLimitMaxRequests (or REMNIC_WRITE_RATE_LIMIT_MAX_REQUESTS) if sustained.`,
+    );
+  }
+}