@spendgraph/harness 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# @spendgraph/harness
+
+Pull a stored prompt, render it, report what it cost. Zero dependencies.
+
+Your prompt lives in spendgraph, not in your codebase. This client fetches it,
+substitutes its typed fields, and records what the call cost — without sitting
+in your request path.
+
+```sh
+npm install @spendgraph/harness
+```
+
+## The production path
+
+```ts
+import { Harness } from "@spendgraph/harness";
+
+const harness = new Harness({
+  apiKey: process.env.SPENDGRAPH_API_KEY,
+  baseUrl: "https://your-spendgraph.example.com",
+});
+
+export async function handle(request) {
+  const prompt = await harness.pull("billing-explainer-k3f9x2");
+
+  const values = { question: "why was I charged twice?" };
+  const messages = prompt.render(values);
+
+  // Call the provider yourself. spendgraph is never between you and the model.
+  const startedAt = Date.now();
+  const completion = await yourModelCall(messages);
+
+  await harness.report(prompt.id, {
+    versionId: prompt.versionId,
+    model: "anthropic/claude-sonnet-5",
+    fields: prompt.serialize(values),
+    rendered: messages,
+    output: completion.text,
+    inputTokens: completion.usage.inputTokens,
+    outputTokens: completion.usage.outputTokens,
+    cacheReadTokens: completion.usage.cacheReadTokens ?? 0,
+    cacheWriteTokens: completion.usage.cacheWriteTokens ?? 0,
+    latencyMs: Date.now() - startedAt,
+  });
+
+  return completion.text;
+}
+```
+
+Call `pull` inside the handler, not at module scope. It refreshes as a side
+effect of being called, so a service that pulls once at boot serves that wording
+for the life of the process. Called per request it is a cache read, not a round
+trip.
+
+`report` never throws and never rejects — it sits beside a request that has
+already been answered, and telemetry that can break the thing it measures is
+worse than no telemetry. Pass `onReportError` if you want to know when one is
+dropped.
+
+## Handles
+
+`pull`, `run` and the rest take a prompt's uuid or its slug.
+
+A slug is derived from the prompt's name, so **renaming the prompt mints a new
+one and the old stops resolving**. The uuid never changes. Pull by slug for
+something readable; pull by id where the handle has to outlive an edit to the
+name.
+
+When a handle stops resolving, the client keeps serving the wording it last saw
+rather than failing your request — and backs off rather than retrying on every
+call. Pass `onPullError` to be told, because otherwise that is silent:
+
+```ts
+new Harness({
+  apiKey,
+  baseUrl,
+  onPullError: (err, handle) => log.warn({ err, handle }, "prompt refresh failed"),
+});
+```
+
+## Caching
+
+`pull` is stale-while-revalidate. A fresh entry is returned outright, a stale
+one is returned *now* and refreshed behind you, and only a cold miss waits on
+the network. So an edit in the dashboard reaches production within a TTL without
+any request paying for the fetch.
+
+```ts
+new Harness({ apiKey, baseUrl, cache: { ttlSeconds: 300, maxSize: 100 } });
+```
+
+`harness.invalidate(promptId)` drops it immediately — `promote()` does this for
+you, including for entries cached under the other handle.
+
+## The batch path
+
+`run`, `sample` and `runAll` execute the prompt server-side and record the
+rollout in one call. That adds a hop and makes spendgraph a dependency of your
+uptime, which is the right trade for evaluation and the wrong one for a user
+waiting on a response.
+
+```ts
+const result = await harness.run("billing-explainer-k3f9x2", values);
+const k = await harness.sample(promptId, values, { k: 5 }); // pass^k
+const across = await harness.runAll(promptId, values);      // one per model
+```
+
+Cap what a client can spend:
+
+```ts
+new Harness({ apiKey, baseUrl, maxCostMicros: 5_000_000 }); // $5
+harness.spent();      // micro-dollars used
+harness.remaining();  // what is left
+```
+
+Omit `maxCostMicros` and it warns once that it is unbounded. Pass `null` to say
+you meant it.
+
+## Typed fields
+
+A prompt declares its placeholders — `string`, `text`, `number`, `boolean`,
+`enum`, `list`, `json` — and `render` validates before anything is sent, so a
+missing required field is an exception rather than a `{placeholder}` reaching
+the model.
+
+`harness codegen` turns those declarations into types:
+
+```sh
+npx harness codegen --url https://your-spendgraph.example.com
+# usage: harness codegen [--out <file>] [--project <id>] [--module <specifier>]
+```
+
+It reads `SPENDGRAPH_API_KEY` and `SPENDGRAPH_URL` from the environment and
+writes `src/harness.generated.d.ts`. Include that file and the values argument
+is checked per prompt, by id and by slug. Delete it and calls fall back to a
+loose `Record<string, unknown>` — the runtime validation is unchanged either
+way.
+
+## Versions
+
+```ts
+const { versions, currentVersionId } = await harness.versions(promptId);
+await harness.promote(promptId, versionId);
+```
+
+Promoting changes what every `pull` serves from that moment, and invalidates the
+cache so the change is visible immediately rather than after a TTL.
+
+## Datasets
+
+```ts
+const { cases, counts } = await harness.cases(promptId);
+await harness.setCases(promptId, cases);
+```
+
+`setCases` replaces the whole set. A dataset answers "what am I evaluating
+against" with one answer at a time, and a merge would leave no way to remove a
+case.
+
+## License
+
+MIT

package/bin/harness.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * harness codegen — writes a .d.ts describing every stored prompt's fields.
+ *
+ *   SPENDGRAPH_API_KEY=sg_… SPENDGRAPH_URL=https://costs.example.com \
+ *     npx harness codegen --out src/harness.generated.d.ts
+ *
+ * Reads through the paginated list endpoint, so a project with hundreds of
+ * prompts is many small requests rather than one enormous response.
+ */
+import { writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { emitPromptTypes } from "../dist/index.js";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function flag(name, fallback) {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+}
+
+function fail(message) {
+  console.error(`harness: ${message}`);
+  process.exit(1);
+}
+
+if (command !== "codegen") {
+  console.log("usage: harness codegen [--out <file>] [--project <id>] [--module <specifier>]");
+  process.exit(command ? 1 : 0);
+}
+
+const apiKey = process.env.SPENDGRAPH_API_KEY;
+const baseUrl = (process.env.SPENDGRAPH_URL ?? flag("url", "")).replace(/\/+$/, "");
+if (!apiKey) fail("set SPENDGRAPH_API_KEY");
+if (!baseUrl) fail("set SPENDGRAPH_URL, or pass --url");
+
+const out = resolve(flag("out", "src/harness.generated.d.ts"));
+const project = flag("project", "");
+const moduleName = flag("module", "@spendgraph/harness");
+
+const prompts = [];
+let cursor = null;
+
+// Bounded: a server that kept handing back a cursor must not spin forever.
+for (let page = 0; page < 200; page++) {
+  // Archived prompts included on purpose. The dashboard hides them, but a
+  // generated type disappearing because somebody tidied a list would break the
+  // build of code that still pulls the prompt — archiving does not stop it
+  // serving, so it must not stop it type-checking either.
+  const params = new URLSearchParams({ limit: "200", archived: "all" });
+  if (project) params.set("project", project);
+  if (cursor) params.set("cursor", cursor);
+
+  const res = await fetch(`${baseUrl}/api/v1/prompts?${params}`, {
+    headers: { "x-api-key": apiKey },
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    fail(`${res.status} listing prompts — ${body.slice(0, 200)}`);
+  }
+
+  const body = await res.json();
+  prompts.push(...(body.prompts ?? []));
+  cursor = body.nextCursor;
+  if (!cursor) break;
+}
+
+await mkdir(dirname(out), { recursive: true });
+await writeFile(out, emitPromptTypes(prompts, { module: moduleName }));
+
+const named = prompts.filter((p) => (p.fieldSpec ?? []).some((f) => f.required)).length;
+console.log(
+  `harness: wrote ${prompts.length} prompt${prompts.length === 1 ? "" : "s"} to ${out}` +
+    (named ? ` (${named} with required fields)` : "")
+);

package/dist/core/budget.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Thrown when a client has spent its ceiling.
+ *
+ * Deliberately not a `HarnessError`: nothing was refused by the server, so a
+ * caller inspecting `status` or `retryable` would be told a story about HTTP
+ * that never happened.
+ */
+export declare class BudgetExceededError extends Error {
+    readonly spentMicros: number;
+    readonly limitMicros: number;
+    constructor(spentMicros: number, limitMicros: number);
+}
+/**
+ * What this client has spent, and whether it may spend more.
+ *
+ * A loop that samples k rollouts across a dataset is the shape of an expensive
+ * accident: one bad `k`, one dataset larger than expected, and the bill arrives
+ * before anyone notices. The guard is a counter and a comparison, and a cost
+ * meter that shipped without one would be embarrassing.
+ *
+ * Governs spending this client *initiates* — `run`, `sample`, `runAll`. It does
+ * not gate `report`, which records money the caller already spent elsewhere;
+ * counting that would make the ceiling mean two different things at once.
+ */
+export declare class Budget {
+    private used;
+    private readonly limit;
+    /**
+     * `undefined` means no ceiling and warns once — an unbounded client in a
+     * scheduled script is how a surprise bill happens. `null` means the same
+     * thing deliberately, and says nothing.
+     */
+    constructor(maxCostMicros?: number | null);
+    spent(): number;
+    remaining(): number;
+    add(costMicros: number): void;
+    /**
+     * Throws if the ceiling is already reached.
+     *
+     * Checked before a request rather than after: stopping once the bill has been
+     * incurred is a report, not a limit.
+     */
+    assertAffordable(): void;
+}
+/** Test seam: lets the once-only warning be exercised more than once. */
+export declare function resetBudgetWarning(): void;

package/dist/core/budget.js

@@ -0,0 +1,72 @@
+/**
+ * Thrown when a client has spent its ceiling.
+ *
+ * Deliberately not a `HarnessError`: nothing was refused by the server, so a
+ * caller inspecting `status` or `retryable` would be told a story about HTTP
+ * that never happened.
+ */
+export class BudgetExceededError extends Error {
+    spentMicros;
+    limitMicros;
+    constructor(spentMicros, limitMicros) {
+        super(`Cost ceiling reached: spent $${(spentMicros / 1e6).toFixed(4)} of ` +
+            `$${(limitMicros / 1e6).toFixed(4)}. Raise maxCostMicros or start a new client.`);
+        this.name = "BudgetExceededError";
+        this.spentMicros = spentMicros;
+        this.limitMicros = limitMicros;
+    }
+}
+let warned = false;
+/**
+ * What this client has spent, and whether it may spend more.
+ *
+ * A loop that samples k rollouts across a dataset is the shape of an expensive
+ * accident: one bad `k`, one dataset larger than expected, and the bill arrives
+ * before anyone notices. The guard is a counter and a comparison, and a cost
+ * meter that shipped without one would be embarrassing.
+ *
+ * Governs spending this client *initiates* — `run`, `sample`, `runAll`. It does
+ * not gate `report`, which records money the caller already spent elsewhere;
+ * counting that would make the ceiling mean two different things at once.
+ */
+export class Budget {
+    used = 0;
+    limit;
+    /**
+     * `undefined` means no ceiling and warns once — an unbounded client in a
+     * scheduled script is how a surprise bill happens. `null` means the same
+     * thing deliberately, and says nothing.
+     */
+    constructor(maxCostMicros) {
+        this.limit = maxCostMicros ?? Infinity;
+        if (maxCostMicros === undefined && !warned) {
+            warned = true;
+            console.warn("[harness] No maxCostMicros set — this client can spend without limit. " +
+                "Pass maxCostMicros, or null to say you meant it.");
+        }
+    }
+    spent() {
+        return this.used;
+    }
+    remaining() {
+        return this.limit === Infinity ? Infinity : Math.max(0, this.limit - this.used);
+    }
+    add(costMicros) {
+        if (Number.isFinite(costMicros) && costMicros > 0)
+            this.used += costMicros;
+    }
+    /**
+     * Throws if the ceiling is already reached.
+     *
+     * Checked before a request rather than after: stopping once the bill has been
+     * incurred is a report, not a limit.
+     */
+    assertAffordable() {
+        if (this.used >= this.limit)
+            throw new BudgetExceededError(this.used, this.limit);
+    }
+}
+/** Test seam: lets the once-only warning be exercised more than once. */
+export function resetBudgetWarning() {
+    warned = false;
+}

package/dist/core/cache.d.ts

@@ -0,0 +1,119 @@
+/**
+ * LRU with a TTL, and staleness reported rather than enforced.
+ *
+ * `get` returning a stale entry instead of dropping it is what lets `pull`
+ * serve immediately and refresh behind the request. The alternative — evict on
+ * expiry — puts an HTTP round trip on the critical path of whichever unlucky
+ * request arrives one millisecond after the TTL lapses.
+ */
+export interface CacheOptions<T = unknown> {
+    /** Entries older than this are stale, not gone. Default 300 (5 minutes). */
+    ttlSeconds?: number;
+    /** Default 100. */
+    maxSize?: number;
+    /** Injectable clock, so tests do not sleep. */
+    now?: () => number;
+    /**
+     * How long to leave a key alone after its refresh failed. Default 60.
+     *
+     * A handle that has stopped resolving is served from cache and retried on a
+     * schedule, rather than on every call.
+     */
+    retryAfterSeconds?: number;
+    /**
+     * Called when a background refresh throws.
+     *
+     * `report` has `onReportError` because silence there loses spend data; the
+     * same argument applies here, where silence means serving a wording that can
+     * never update. Without it a rename on the dashboard freezes a running
+     * service with nothing anywhere saying so.
+     */
+    onRefreshError?: (err: unknown, key: string) => void;
+    /**
+     * Every name a cached value answers to — for a prompt, its id and its slug.
+     *
+     * The cache is keyed on whatever handle the caller passed, which is why
+     * invalidation kept missing: a promotion knows the uuid, production pulled by
+     * the slug, and a fetch still in flight carries no payload to connect them.
+     * With this, an invalidation is recorded against the prompt rather than
+     * against one string, and a fetch is dropped when the thing it fetched was
+     * invalidated — not when some unrelated key was.
+     */
+    identify?: (value: T) => string[];
+}
+export interface CacheHit<T> {
+    value: T;
+    stale: boolean;
+    ageMs: number;
+}
+export declare class PullCache<T> {
+    private readonly store;
+    private readonly ttlMs;
+    private readonly maxSize;
+    private readonly now;
+    /** Keys with a refresh in flight, so N concurrent readers cause one fetch. */
+    private readonly refreshing;
+    /** When a key's refresh last failed, so a dead handle is not retried per call. */
+    private readonly failures;
+    private readonly retryAfterMs;
+    private readonly onRefreshError?;
+    private readonly identify?;
+    /**
+     * A monotonic counter and the tick at which each name was last invalidated.
+     *
+     * A fetch records the counter when it starts and, when it lands, asks whether
+     * anything it turned out to be — its key, its id, its slug — has been
+     * invalidated since. That is the whole protocol, and it holds for the cold
+     * path, the background refresh, and a handle nobody has seen before, none of
+     * which the previous per-key epoch could cover.
+     */
+    private tick;
+    private readonly invalidatedAt;
+    /**
+     * The tick of the last `clear()`.
+     *
+     * `clear` cannot name a fetch it has never seen — a cold one is in neither
+     * `store` nor `refreshing` — so it raises a floor instead: anything that
+     * started before it is out of date whatever it turns out to be.
+     */
+    private clearedAt;
+    /** Fetches outstanding, so the log above can be dropped when none remain. */
+    private outstanding;
+    constructor(opts?: CacheOptions<T>);
+    get(key: string): CacheHit<T> | undefined;
+    set(key: string, value: T): void;
+    /**
+     * Runs `refresh` unless one is already in flight for this key.
+     *
+     * Without the guard, a burst of requests arriving just after the TTL lapses
+     * each start their own refresh — the stampede the cache exists to prevent.
+     * Failures are swallowed on purpose: a background refresh that throws must not
+     * surface in a request that was already answered from cache.
+     */
+    refreshInBackground(key: string, refresh: () => Promise<T>): void;
+    /** Records a fetch starting, and the tick it must be judged against. */
+    beginFetch(): number;
+    /** Stores a landed fetch unless what it fetched was invalidated meanwhile. */
+    settle(key: string, value: T, startedAt: number): void;
+    /** Ends a fetch that threw, and backs the handle off. */
+    abandon(key: string): void;
+    /** Records that everything under this name is out of date. */
+    invalidate(name: string): void;
+    /** The log only matters while a fetch could still be judged against it. */
+    private forgetLogIfIdle;
+    /** Keeps `failures` inside the same bound as the entries themselves. */
+    private boundFailures;
+    /** Every key whose entry satisfies `match`. */
+    keysWhere(match: (value: T) => boolean): string[];
+    delete(key: string): void;
+    clear(): void;
+    get size(): number;
+    /**
+     * How many keys the cache holds bookkeeping for, entries aside.
+     *
+     * Exposed for the test that this stays bounded: `epochs` and `failures` are
+     * private and grow on paths `size` cannot see, so a test written against
+     * `size` passes whether or not they leak — which is what the first one did.
+     */
+    get trackedKeys(): number;
+}

package/dist/core/cache.js

@@ -0,0 +1,206 @@
+export class PullCache {
+    store = new Map();
+    ttlMs;
+    maxSize;
+    now;
+    /** Keys with a refresh in flight, so N concurrent readers cause one fetch. */
+    refreshing = new Set();
+    /** When a key's refresh last failed, so a dead handle is not retried per call. */
+    failures = new Map();
+    retryAfterMs;
+    onRefreshError;
+    identify;
+    /**
+     * A monotonic counter and the tick at which each name was last invalidated.
+     *
+     * A fetch records the counter when it starts and, when it lands, asks whether
+     * anything it turned out to be — its key, its id, its slug — has been
+     * invalidated since. That is the whole protocol, and it holds for the cold
+     * path, the background refresh, and a handle nobody has seen before, none of
+     * which the previous per-key epoch could cover.
+     */
+    tick = 0;
+    invalidatedAt = new Map();
+    /**
+     * The tick of the last `clear()`.
+     *
+     * `clear` cannot name a fetch it has never seen — a cold one is in neither
+     * `store` nor `refreshing` — so it raises a floor instead: anything that
+     * started before it is out of date whatever it turns out to be.
+     */
+    clearedAt = -1;
+    /** Fetches outstanding, so the log above can be dropped when none remain. */
+    outstanding = 0;
+    constructor(opts = {}) {
+        // A TTL of 0 means "always stale", which is a legitimate way to disable
+        // caching without a separate flag; only undefined falls back to the default.
+        this.ttlMs = (opts.ttlSeconds ?? 300) * 1000;
+        this.maxSize = Math.max(1, opts.maxSize ?? 100);
+        this.now = opts.now ?? (() => Date.now());
+        this.retryAfterMs = (opts.retryAfterSeconds ?? 60) * 1000;
+        this.onRefreshError = opts.onRefreshError;
+        this.identify = opts.identify;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        // Re-insert to mark most-recently-used: Map iterates in insertion order, so
+        // deleting and re-setting moves the key to the end.
+        this.store.delete(key);
+        this.store.set(key, entry);
+        const ageMs = this.now() - entry.at;
+        return { value: entry.value, stale: ageMs > this.ttlMs, ageMs };
+    }
+    set(key, value) {
+        this.store.delete(key);
+        this.store.set(key, { value, at: this.now() });
+        while (this.store.size > this.maxSize) {
+            const oldest = this.store.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.store.delete(oldest);
+            // The bookkeeping goes with the entry unless a fetch for it is still
+            // running, otherwise these grow forever in a class whose contract is a
+            // bounded LRU — one permanent entry per distinct key ever seen.
+            if (!this.refreshing.has(oldest))
+                this.failures.delete(oldest);
+        }
+    }
+    /**
+     * Runs `refresh` unless one is already in flight for this key.
+     *
+     * Without the guard, a burst of requests arriving just after the TTL lapses
+     * each start their own refresh — the stampede the cache exists to prevent.
+     * Failures are swallowed on purpose: a background refresh that throws must not
+     * surface in a request that was already answered from cache.
+     */
+    refreshInBackground(key, refresh) {
+        if (this.refreshing.has(key))
+            return;
+        // Backed off after a failure. A handle that has stopped resolving — which a
+        // rename now makes routine, since it re-mints the slug — otherwise fires a
+        // fresh doomed request on every single pull, forever, while serving wording
+        // that can never update. The entry stays (stale is better than nothing);
+        // what stops is the stampede.
+        const failedAt = this.failures.get(key);
+        if (failedAt !== undefined && this.now() - failedAt < this.retryAfterMs)
+            return;
+        this.refreshing.add(key);
+        const startedAt = this.beginFetch();
+        void refresh()
+            .then((value) => this.settle(key, value, startedAt))
+            .catch((err) => {
+            this.abandon(key);
+            // Surfaced rather than swallowed. `report` has onReportError for exactly
+            // this reason; without a counterpart here a service can serve a frozen
+            // prompt indefinitely with nothing anywhere saying so.
+            //
+            // Wrapped, because nobody is holding this promise: `pullWithCache` has
+            // already returned the stale value, so a callback that throws would be
+            // an unhandled rejection — process exit in Node, isolate abort in a
+            // Worker.
+            try {
+                this.onRefreshError?.(err, key);
+            }
+            catch {
+                /* a reporter that cannot report is not worth an outage */
+            }
+        })
+            .finally(() => {
+            this.refreshing.delete(key);
+            this.forgetLogIfIdle();
+        });
+    }
+    /** Records a fetch starting, and the tick it must be judged against. */
+    beginFetch() {
+        this.outstanding++;
+        return this.tick;
+    }
+    /** Stores a landed fetch unless what it fetched was invalidated meanwhile. */
+    settle(key, value, startedAt) {
+        this.outstanding--;
+        const names = [key, ...(this.identify?.(value) ?? [])];
+        const overtaken = startedAt < this.clearedAt ||
+            names.some((n) => (this.invalidatedAt.get(n) ?? -1) > startedAt);
+        if (!overtaken) {
+            // Only once the value is kept: clearing first meant a fetch that lost the
+            // race still wiped a live backoff, turning bounded retry into a retry on
+            // every call.
+            this.failures.delete(key);
+            this.set(key, value);
+        }
+        this.forgetLogIfIdle();
+    }
+    /** Ends a fetch that threw, and backs the handle off. */
+    abandon(key) {
+        this.outstanding--;
+        // Recorded here too, not only on the background path. The cold path is the
+        // one a fresh isolate takes, so without this a permanently 404ing handle —
+        // which a rename now makes routine — issued one upstream request per pull,
+        // forever.
+        this.failures.set(key, this.now());
+        this.boundFailures();
+        this.forgetLogIfIdle();
+    }
+    /** Records that everything under this name is out of date. */
+    invalidate(name) {
+        this.invalidatedAt.set(name, ++this.tick);
+    }
+    /** The log only matters while a fetch could still be judged against it. */
+    forgetLogIfIdle() {
+        if (this.outstanding === 0 && this.refreshing.size === 0)
+            this.invalidatedAt.clear();
+    }
+    /** Keeps `failures` inside the same bound as the entries themselves. */
+    boundFailures() {
+        while (this.failures.size > this.maxSize) {
+            const oldest = this.failures.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.failures.delete(oldest);
+        }
+    }
+    /** Every key whose entry satisfies `match`. */
+    keysWhere(match) {
+        const out = [];
+        for (const [key, entry] of this.store)
+            if (match(entry.value))
+                out.push(key);
+        return out;
+    }
+    delete(key) {
+        this.store.delete(key);
+        // The backoff goes with it. Otherwise invalidate() could not clear a
+        // backoff, and a handle that has demonstrably recovered kept skipping its
+        // refresh for the whole retry window — which `retryAfterSeconds` being a
+        // public option makes arbitrarily long.
+        this.failures.delete(key);
+        this.invalidate(key);
+        // Nothing outstanding means nothing can be judged against the log, so it is
+        // residue — which is what made it grow by one per prompt ever invalidated.
+        this.forgetLogIfIdle();
+    }
+    clear() {
+        // Every key the cache has an opinion about, not only the ones with an entry:
+        // a cold-isolate fetch is in flight under a key that is not in `store` yet,
+        // and bumping only stored keys let it land after the invalidation.
+        this.clearedAt = ++this.tick;
+        this.store.clear();
+        this.failures.clear();
+        this.forgetLogIfIdle();
+    }
+    get size() {
+        return this.store.size;
+    }
+    /**
+     * How many keys the cache holds bookkeeping for, entries aside.
+     *
+     * Exposed for the test that this stays bounded: `epochs` and `failures` are
+     * private and grow on paths `size` cannot see, so a test written against
+     * `size` passes whether or not they leak — which is what the first one did.
+     */
+    get trackedKeys() {
+        return new Set([...this.invalidatedAt.keys(), ...this.failures.keys()]).size;
+    }
+}