Harden PerfTrace privacy fence, snapshot immutability, open-span cap

Accept parentId only as opaque span ids (known open/ring or OPAQUE_ID_RE);
return shallow snapshot copies; cap open spans with oldest-first eviction;
mark() takes StartOptions; cover double-end, clear, and overflow paths.

Author: TheGreatAxios

src/perf/index.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import {
+  OPEN_SPAN_CAPACITY,
   RING_CAPACITY,
   clear,
   end,
@@ -43,7 +44,7 @@ describe("start / end / mark", () => {
   });
 
   test("mark is a completed point-in-time span", () => {
-    const id = mark("adapter.transport", { transport: "http_sse" });
+    const id = mark("adapter.transport", { tags: { transport: "http_sse" } });
     expect(id.length).toBeGreaterThan(0);
 
     const spans = snapshot();
@@ -52,6 +53,17 @@ describe("start / end / mark", () => {
     expect(spans[0]!.tags).toEqual({ transport: "http_sse" });
   });
 
+  test("mark accepts optional parentId like start", () => {
+    const turnId = start("turn");
+    mark("adapter.transport", { parentId: turnId, tags: { transport: "ws" } });
+    end(turnId);
+
+    const spans = snapshot();
+    const marked = spans.find((s) => s.name === "adapter.transport")!;
+    expect(marked.parentId).toBe(turnId);
+    expect(marked.tags).toEqual({ transport: "ws" });
+  });
+
   test("open spans appear in snapshot without endNs", () => {
     const id = start("session");
     const spans = snapshot();
@@ -72,6 +84,20 @@ describe("start / end / mark", () => {
     expect(snapshot()).toHaveLength(0);
   });
 
+  test("double-end is a no-op", () => {
+    const id = start("tool");
+    end(id);
+    end(id);
+    expect(snapshot()).toHaveLength(1);
+  });
+
+  test("end after clear is a no-op", () => {
+    const id = start("tool");
+    clear();
+    end(id, { count: 1 });
+    expect(snapshot()).toHaveLength(0);
+  });
+
   test("end merges sanitized tags onto the span", () => {
     const id = start("tool", { tags: { tool_id: "t1" } });
     end(id, { count: 3, prompt: "secret" });
@@ -80,11 +106,93 @@ describe("start / end / mark", () => {
   });
 });
 
+describe("parentId privacy fence", () => {
+  test("strips path-like parentId", () => {
+    const id = start("inference", { parentId: "/Users/me/secret/repo/src/main.ts" });
+    end(id);
+    expect(snapshot()[0]!.parentId).toBeUndefined();
+  });
+
+  test("strips free-text and path-separator parentIds", () => {
+    const a = start("tool", { parentId: "has spaces and free text" });
+    end(a);
+    const b = start("tool", { parentId: "../../etc/passwd" });
+    end(b);
+    const c = start("tool", { parentId: "C:\\Windows\\System32" });
+    end(c);
+
+    for (const span of snapshot()) {
+      expect(span.parentId).toBeUndefined();
+    }
+  });
+
+  test("accepts known open span ids and opaque ids", () => {
+    const parent = start("turn");
+    const child = start("inference", { parentId: parent });
+    end(child);
+    end(parent);
+
+    // Opaque id that matches OPAQUE_ID_RE but is not currently open/ring-known
+    // after clear of only that id — still accepted when pattern matches.
+    const orphan = start("tool", { parentId: "parent1" });
+    end(orphan);
+
+    const spans = snapshot();
+    expect(spans.find((s) => s.name === "inference")!.parentId).toBe(parent);
+    expect(spans.find((s) => s.name === "tool")!.parentId).toBe("parent1");
+  });
+
+  test("accepts parentId of a completed (ring) span", () => {
+    const parent = start("turn");
+    end(parent);
+    const child = start("inference", { parentId: parent });
+    end(child);
+    expect(snapshot().find((s) => s.name === "inference")!.parentId).toBe(parent);
+  });
+});
+
+describe("snapshot immutability", () => {
+  test("mutating a snapshot does not poison the next snapshot", () => {
+    const id = start("tool", { tags: { tool_id: "t1", count: 1 } });
+    end(id);
+
+    const first = snapshot();
+    expect(first).toHaveLength(1);
+    first[0]!.name = "session";
+    first[0]!.tags!.tool_id = "POISON";
+    first[0]!.tags!.count = 999;
+    first[0]!.parentId = "injected";
+    first.push({
+      id: "fake",
+      name: "session",
+      startNs: 0n,
+      endNs: 0n,
+    });
+
+    const second = snapshot();
+    expect(second).toHaveLength(1);
+    expect(second[0]!.name).toBe("tool");
+    expect(second[0]!.tags).toEqual({ tool_id: "t1", count: 1 });
+    expect(second[0]!.parentId).toBeUndefined();
+  });
+
+  test("mutating an open-span snapshot does not poison open state", () => {
+    start("session", { tags: { provider_id: "openai" } });
+    const first = snapshot();
+    first[0]!.tags!.provider_id = "POISON";
+    first[0]!.endNs = 1n;
+
+    const second = snapshot();
+    expect(second[0]!.tags).toEqual({ provider_id: "openai" });
+    expect(second[0]!.endNs).toBeUndefined();
+  });
+});
+
 describe("ring overflow", () => {
   test("drops oldest completed spans when capacity is exceeded", () => {
     // Fill past capacity with marks (cheap completed spans).
     for (let i = 0; i < RING_CAPACITY + 10; i += 1) {
-      mark("tool", { count: i });
+      mark("tool", { tags: { count: i } });
     }
 
     const spans = snapshot();
@@ -105,6 +213,30 @@ describe("ring overflow", () => {
   });
 });
 
+describe("open span capacity", () => {
+  test("evicts oldest open span when over OPEN_SPAN_CAPACITY", () => {
+    const ids: string[] = [];
+    for (let i = 0; i < OPEN_SPAN_CAPACITY + 5; i += 1) {
+      ids.push(start("tool", { tags: { count: i } }));
+    }
+
+    const open = snapshot().filter((s) => s.endNs === undefined);
+    expect(open).toHaveLength(OPEN_SPAN_CAPACITY);
+
+    // Oldest five (count 0..4) were evicted; survivors start at count 5.
+    const counts = open.map((s) => s.tags?.count).sort((a, b) => (a ?? 0) - (b ?? 0));
+    expect(counts[0]).toBe(5);
+    expect(counts[counts.length - 1]).toBe(OPEN_SPAN_CAPACITY + 4);
+
+    // Ending an evicted id is a no-op; ending a survivor still works.
+    end(ids[0]!);
+    end(ids[ids.length - 1]!);
+    const completed = snapshot().filter((s) => s.endNs !== undefined);
+    expect(completed).toHaveLength(1);
+    expect(completed[0]!.tags?.count).toBe(OPEN_SPAN_CAPACITY + 4);
+  });
+});
+
 describe("sanitizeTags", () => {
   test("keeps allowlisted enums, numbers, and opaque ids", () => {
     const tags = sanitizeTags({

src/perf/index.ts

@@ -3,12 +3,19 @@
  *
  * Fixed-size ring buffer, monotonic high-res clocks, privacy-sanitized tags.
  * No network, no PostHog, no export side effects.
+ *
+ * Memory policy (fixed, not settings):
+ * - RING_CAPACITY completed spans (oldest completed dropped on overflow)
+ * - OPEN_SPAN_CAPACITY concurrent open spans (oldest open dropped on overflow)
+ * - snapshot() returns shallow copies so consumers cannot poison internal state
  */
 
-import { sanitizeTags, type PerfTags, type TransportKind } from "./sanitize.js";
+import { isOpaqueId, sanitizeTags, type PerfTags } from "./sanitize.js";
 
 export {
   sanitizeTags,
+  isOpaqueId,
+  OPAQUE_ID_RE,
   ALLOWED_TAG_KEYS,
   type AllowedTagKey,
   type PerfTags,
@@ -48,9 +55,15 @@ export type StartOptions = {
   tags?: Record<string, unknown>;
 };
 
-/** Fixed ring capacity — constant, not a settings UI. */
+/** Fixed ring capacity for completed spans — constant, not a settings UI. */
 export const RING_CAPACITY = 4096;
 
+/**
+ * Max concurrent open (un-ended) spans. Fixed memory: when exceeded, the
+ * oldest open span is dropped so a leaked start() cannot grow without bound.
+ */
+export const OPEN_SPAN_CAPACITY = 1024;
+
 // Module state: one process-wide ring. Tests call clear() between cases.
 let nextId = 0;
 const openSpans = new Map<string, PerfSpan>();
@@ -80,33 +93,77 @@ function pushRing(span: PerfSpan): void {
   }
 }
 
+function ringHasId(id: string): boolean {
+  if (ringCount === 0) return false;
+  const startIdx = ringCount < RING_CAPACITY ? 0 : ringWrite;
+  for (let i = 0; i < ringCount; i += 1) {
+    const span = ring[(startIdx + i) % RING_CAPACITY];
+    if (span !== undefined && span.id === id) return true;
+  }
+  return false;
+}
+
+/**
+ * Privacy fence for parentId: only opaque span ids (known open/ring ids, or
+ * OPAQUE_ID_RE). Free text, paths, and long strings are stripped.
+ */
+function sanitizeParentId(parentId: string | undefined): string | undefined {
+  if (parentId === undefined || parentId.length === 0) return undefined;
+  if (openSpans.has(parentId) || ringHasId(parentId)) return parentId;
+  if (isOpaqueId(parentId)) return parentId;
+  return undefined;
+}
+
+/** Shallow copy so snapshot consumers cannot mutate the ring / open map. */
+function cloneSpan(span: PerfSpan): PerfSpan {
+  const copy: PerfSpan = {
+    id: span.id,
+    name: span.name,
+    startNs: span.startNs,
+  };
+  if (span.parentId !== undefined) copy.parentId = span.parentId;
+  if (span.endNs !== undefined) copy.endNs = span.endNs;
+  if (span.tags !== undefined) copy.tags = { ...span.tags };
+  return copy;
+}
+
+/** Drop the oldest open span when at capacity (Map iteration is insertion order). */
+function evictOldestOpenIfFull(): void {
+  if (openSpans.size < OPEN_SPAN_CAPACITY) return;
+  const oldest = openSpans.keys().next().value;
+  if (oldest !== undefined) openSpans.delete(oldest);
+}
+
 /**
  * Open a timed span. Returns an opaque id for `end`.
  * Unknown span names are ignored (returns empty string; end is a no-op).
+ * When open capacity is full, the oldest open span is dropped first.
  */
 export function start(name: SpanName | string, opts?: StartOptions): string {
   if (!isSpanName(name)) return "";
 
   const id = allocId();
   const tags = sanitizeTags(opts?.tags);
+  const parentId = sanitizeParentId(opts?.parentId);
   const span: PerfSpan = {
     id,
     name,
     startNs: nowNs(),
   };
-  if (opts?.parentId !== undefined && opts.parentId.length > 0) {
-    span.parentId = opts.parentId;
+  if (parentId !== undefined) {
+    span.parentId = parentId;
   }
   if (tags !== undefined) {
     span.tags = tags;
   }
+  evictOldestOpenIfFull();
   openSpans.set(id, span);
   return id;
 }
 
 /**
  * Close a span opened by `start`. Merges optional end tags (sanitized).
- * Unknown or already-ended ids are ignored.
+ * Unknown or already-ended ids are ignored (double-end is a no-op).
  */
 export function end(id: string, tags?: Record<string, unknown>): void {
   if (id.length === 0) return;
@@ -126,20 +183,25 @@ export function end(id: string, tags?: Record<string, unknown>): void {
 
 /**
  * Point-in-time event: recorded as a completed span with startNs === endNs.
- * Unknown span names are ignored.
+ * Unknown span names are ignored. Accepts the same options shape as `start`
+ * (optional parentId + tags).
  */
-export function mark(name: SpanName | string, tags?: Record<string, unknown>): string {
+export function mark(name: SpanName | string, opts?: StartOptions): string {
   if (!isSpanName(name)) return "";
 
   const id = allocId();
   const ns = nowNs();
-  const sanitized = sanitizeTags(tags);
+  const sanitized = sanitizeTags(opts?.tags);
+  const parentId = sanitizeParentId(opts?.parentId);
   const span: PerfSpan = {
     id,
     name,
     startNs: ns,
     endNs: ns,
   };
+  if (parentId !== undefined) {
+    span.parentId = parentId;
+  }
   if (sanitized !== undefined) {
     span.tags = sanitized;
   }
@@ -150,20 +212,23 @@ export function mark(name: SpanName | string, tags?: Record<string, unknown>): s
 /**
  * Snapshot of completed spans in chronological order (oldest first),
  * plus any still-open spans (endNs unset) appended after completed ones.
+ *
+ * Returns shallow copies of each span (and of tags) so callers cannot
+ * mutate the ring buffer or open-span map through the returned objects.
  */
 export function snapshot(): PerfSpan[] {
   const completed: PerfSpan[] = [];
   if (ringCount > 0) {
     const startIdx = ringCount < RING_CAPACITY ? 0 : ringWrite;
     for (let i = 0; i < ringCount; i += 1) {
       const span = ring[(startIdx + i) % RING_CAPACITY];
-      if (span !== undefined) completed.push(span);
+      if (span !== undefined) completed.push(cloneSpan(span));
     }
   }
 
   if (openSpans.size === 0) return completed;
 
-  const open = [...openSpans.values()];
+  const open = [...openSpans.values()].map(cloneSpan);
   // Stable order by start time so tests and dumps are deterministic.
   open.sort((a, b) => (a.startNs < b.startNs ? -1 : a.startNs > b.startNs ? 1 : 0));
   return completed.concat(open);

src/perf/sanitize.ts

@@ -72,13 +72,14 @@ const MAX_ID_LENGTH = 64;
 
 // Opaque ids / model ids: alphanumerics, dots, underscores, hyphens, colons, @.
 // No spaces, slashes, backslashes, or control characters.
-const OPAQUE_ID_RE = /^[A-Za-z0-9._:@-]{1,64}$/;
+export const OPAQUE_ID_RE = /^[A-Za-z0-9._:@-]{1,64}$/;
 
 function isFiniteNumber(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value);
 }
 
-function isOpaqueId(value: unknown): value is string {
+/** True for short opaque id strings (no paths, whitespace, or free text). */
+export function isOpaqueId(value: unknown): value is string {
   return typeof value === "string" && value.length <= MAX_ID_LENGTH && OPAQUE_ID_RE.test(value);
 }