@hienlh/ppm 0.19.2 → 0.19.4

package/src/services/fs-credential-path-guard.ts

@@ -40,6 +40,28 @@ export function isChatUploadPath(resolved: string): boolean {
   return isInside(resolved, getUploadsDir());
 }
 
+/**
+ * Images the codex image-generation tool produced. Codex writes them under its
+ * own CODEX_HOME, which PPM places inside the PPM dir (one home per account),
+ * so `isPpmDirPath` covers them and the chat could not render a picture the
+ * assistant had just made.
+ *
+ * The match is structural rather than a lookup of the account table: the path
+ * must be `<ppmDir>/codex-accounts/<something>/generated_images/<at least one
+ * more segment>`. That keeps the exception to the one subtree codex fills with
+ * generated pictures and leaves the rest of an account home — `auth.json`
+ * above all, but equally the session, log, and memory databases beside it —
+ * refused, since none of those sit under a `generated_images` segment. Callers
+ * pass an already-resolved path, so `..` cannot walk back out of the subtree.
+ */
+export function isCodexGeneratedImagePath(resolved: string): boolean {
+  const root = resolve(getPpmDir(), "codex-accounts");
+  if (!isInside(resolved, root) || resolved === root) return false;
+  const rel = resolved.slice(root.length + 1).split(sep);
+  // [accountId, "generated_images", …at least one file segment]
+  return rel.length >= 3 && rel[1] === "generated_images";
+}
+
 /**
  * True when the path is `~/.cloudflared` or anything inside it. Real
  * `homedir()` is a deliberate exception to the getPpmDir()-only rule (see
@@ -79,16 +101,21 @@ export function isCredentialPath(resolved: string): boolean {
  * tokens; the latter stores the Cloudflare login cert. Neither may be
  * downloadable through a generic file route.
  *
- * Chat uploads are the one exception, and only for the PPM-dir branch — chat
- * uploads always live under `getPpmDir()`, never under `~/.cloudflared`, so
- * the exception is a no-op for the cloudflared branch. Every caller applies
- * this to the requested path *and* to its real path, so a symlink parked in
- * the uploads directory still fails on the second call and cannot reach the
- * rest of the PPM dir through the exception, and a symlink pointing at
- * `~/.cloudflared/cert.pem` fails the same way.
+ * Chat uploads and codex-generated images are the exceptions, and only for the
+ * PPM-dir branch — both always live under `getPpmDir()`, never under
+ * `~/.cloudflared`, so the exceptions are a no-op for the cloudflared branch.
+ * Every caller applies this to the requested path *and* to its real path, so a
+ * symlink parked in the uploads directory still fails on the second call and
+ * cannot reach the rest of the PPM dir through the exception, and a symlink
+ * pointing at `~/.cloudflared/cert.pem` fails the same way.
+ *
+ * Both exceptions are read-only on purpose: they are absent from
+ * `assertNotPpmSubtree`, so nothing can be copied, moved, or written INTO
+ * those directories through a generic file route.
  */
 export function assertNotPpmDir(resolved: string): void {
-  if (isCredentialPath(resolved) && !isChatUploadPath(resolved)) {
+  const allowed = isChatUploadPath(resolved) || isCodexGeneratedImagePath(resolved);
+  if (isCredentialPath(resolved) && !allowed) {
     throw Object.assign(new Error("Access denied"), { status: 403, code: "EDENIED" });
   }
 }

package/src/services/fs-path-guard.service.ts

@@ -14,6 +14,7 @@ export { realPathOrSelf, realPathOrSelfSync };
 export {
   isPpmDirPath,
   isChatUploadPath,
+  isCodexGeneratedImagePath,
   isCloudflaredDirPath,
   isCredentialPath,
   assertNotPpmDir,

package/src/services/postgres.service.ts

@@ -27,6 +27,39 @@ export interface PgQueryResult {
 /** Auto-close idle connections after 5 minutes */
 const IDLE_TIMEOUT_MS = 5 * 60 * 1000;
 
+/** Seconds allowed for DNS + TCP + TLS + auth before postgres.js gives up.
+ *  A healthy connect to a remote host over a VPN measures ~1s, so this only has to
+ *  cover the *first* attempt on a cold network path — the retry below is what
+ *  actually rescues that case, which is why this stays well under the library
+ *  default of 30 (a longer value just makes a genuinely dead host take longer to
+ *  report). */
+const CONNECT_TIMEOUT_SEC = 15;
+
+/** Extra attempts after a first attempt that failed before reaching the server. */
+const CONNECT_RETRIES = 1;
+
+/** Pause before re-attempting a connect-phase failure. */
+const RETRY_DELAY_MS = 250;
+
+/** Seconds to wait for a pool to drain before abandoning it, so evicting a wedged
+ *  connection can never hang the caller. */
+const END_TIMEOUT_SEC = 5;
+
+/** Error codes that prove the statement never reached the server, so replaying it
+ *  cannot double-apply a write. postgres.js holds a query until the startup
+ *  handshake completes, so all of these are raised before any SQL is written to the
+ *  socket. Ambiguous mid-query failures (CONNECTION_CLOSED, ECONNRESET) are
+ *  deliberately excluded — retrying those could re-run an INSERT or UPDATE. */
+const RETRYABLE_CONNECT_ERRORS = new Set([
+  "CONNECT_TIMEOUT",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+]);
+
 interface CachedConn {
   sql: postgres.Sql;
   timer: ReturnType<typeof setTimeout>;
@@ -49,7 +82,12 @@ class PostgresService {
     const sslOpts = sslmode === "no-verify" || sslmode === "require"
       ? { rejectUnauthorized: false }
       : sslmode === "disable" ? false : undefined;
-    const sql = postgres(connectionString, { max: 3, idle_timeout: 60, connect_timeout: 10, ssl: sslOpts as any });
+    const sql = postgres(connectionString, {
+      max: 3,
+      idle_timeout: 60,
+      connect_timeout: CONNECT_TIMEOUT_SEC,
+      ssl: sslOpts as any,
+    });
     const timer = setTimeout(() => this.disconnect(connectionString), IDLE_TIMEOUT_MS);
     this.cache.set(connectionString, { sql, timer });
     return sql;
@@ -60,15 +98,45 @@ class PostgresService {
     const cached = this.cache.get(connectionString);
     if (!cached) return;
     clearTimeout(cached.timer);
-    try { await cached.sql.end(); } catch { /* already closed */ }
+    // Drop the cache entry first: end() on a pool whose socket never came up can
+    // stall for the full drain timeout, and callers must not see it again meanwhile.
     this.cache.delete(connectionString);
+    try { await cached.sql.end({ timeout: END_TIMEOUT_SEC }); } catch { /* already closed */ }
+  }
+
+  /** True when the error happened before the query was written to the socket. */
+  private isRetryableConnectError(e: unknown): boolean {
+    const code = (e as { code?: unknown } | null)?.code;
+    return typeof code === "string" && RETRYABLE_CONNECT_ERRORS.has(code);
+  }
+
+  /** Run an operation against the cached pool, retrying if the connection never
+   *  got established. The first connect over a cold VPN path can burn ~20s on TCP
+   *  SYN retransmits and then fail outright, while an immediate second attempt
+   *  succeeds in about a second — without this, that first failure surfaces to the
+   *  user as a hard error. Only connect-phase failures are replayed, so a retried
+   *  write cannot be applied twice. */
+  private async withConnection<T>(
+    connectionString: string,
+    fn: (sql: postgres.Sql) => Promise<T>,
+  ): Promise<T> {
+    for (let attempt = 0; ; attempt++) {
+      const sql = this.connect(connectionString);
+      try {
+        return await fn(sql);
+      } catch (e) {
+        if (attempt >= CONNECT_RETRIES || !this.isRetryableConnectError(e)) throw e;
+        // Discard the pool that failed to connect so the retry starts clean.
+        await this.disconnect(connectionString);
+        await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
+      }
+    }
   }
 
   /** Test connection */
   async testConnection(connectionString: string): Promise<{ ok: boolean; error?: string }> {
     try {
-      const sql = this.connect(connectionString);
-      await sql`SELECT 1`;
+      await this.withConnection(connectionString, (sql) => sql`SELECT 1`);
       return { ok: true };
     } catch (e) {
       return { ok: false, error: (e as Error).message };
@@ -77,15 +145,14 @@ class PostgresService {
 
   /** List all user tables with row counts */
   async getTables(connectionString: string): Promise<PgTableInfo[]> {
-    const sql = this.connect(connectionString);
-    const tables = await sql`
+    const tables = await this.withConnection(connectionString, (sql) => sql`
       SELECT t.schemaname as schema, t.tablename as name,
              COALESCE(s.n_live_tup, 0)::int as row_count
       FROM pg_tables t
       LEFT JOIN pg_stat_user_tables s ON t.schemaname = s.schemaname AND t.tablename = s.relname
       WHERE t.schemaname NOT IN ('pg_catalog', 'information_schema')
       ORDER BY t.schemaname, t.tablename
-    `;
+    `);
     return tables.map((t) => ({
       name: t.name as string, schema: t.schema as string, rowCount: t.row_count as number,
     }));
@@ -93,33 +160,36 @@ class PostgresService {
 
   /** Get column schema for a table (with FK metadata) */
   async getTableSchema(connectionString: string, table: string, schema = "public"): Promise<PgColumnInfo[]> {
-    const sql = this.connect(connectionString);
-    const cols = await sql`
-      SELECT c.column_name as name, c.data_type as type,
-             c.is_nullable = 'YES' as nullable, c.column_default as default_value,
-             COALESCE(tc.constraint_type = 'PRIMARY KEY', false) as pk
-      FROM information_schema.columns c
-      LEFT JOIN information_schema.key_column_usage kcu
-        ON c.table_schema = kcu.table_schema AND c.table_name = kcu.table_name AND c.column_name = kcu.column_name
-      LEFT JOIN information_schema.table_constraints tc
-        ON kcu.constraint_name = tc.constraint_name AND tc.constraint_type = 'PRIMARY KEY'
-      WHERE c.table_schema = ${schema} AND c.table_name = ${table}
-      ORDER BY c.ordinal_position
-    `;
-
-    // Query FK references
-    const fkRows = await sql`
-      SELECT kcu.column_name as from_col,
-             ccu.table_name as ref_table,
-             ccu.column_name as ref_col
-      FROM information_schema.table_constraints tc
-      JOIN information_schema.key_column_usage kcu
-        ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
-      JOIN information_schema.constraint_column_usage ccu
-        ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
-      WHERE tc.constraint_type = 'FOREIGN KEY'
-        AND tc.table_schema = ${schema} AND tc.table_name = ${table}
-    `;
+    const { cols, fkRows } = await this.withConnection(connectionString, async (sql) => {
+      const cols = await sql`
+        SELECT c.column_name as name, c.data_type as type,
+               c.is_nullable = 'YES' as nullable, c.column_default as default_value,
+               COALESCE(tc.constraint_type = 'PRIMARY KEY', false) as pk
+        FROM information_schema.columns c
+        LEFT JOIN information_schema.key_column_usage kcu
+          ON c.table_schema = kcu.table_schema AND c.table_name = kcu.table_name AND c.column_name = kcu.column_name
+        LEFT JOIN information_schema.table_constraints tc
+          ON kcu.constraint_name = tc.constraint_name AND tc.constraint_type = 'PRIMARY KEY'
+        WHERE c.table_schema = ${schema} AND c.table_name = ${table}
+        ORDER BY c.ordinal_position
+      `;
+
+      // Query FK references
+      const fkRows = await sql`
+        SELECT kcu.column_name as from_col,
+               ccu.table_name as ref_table,
+               ccu.column_name as ref_col
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+          ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+        JOIN information_schema.constraint_column_usage ccu
+          ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
+        WHERE tc.constraint_type = 'FOREIGN KEY'
+          AND tc.table_schema = ${schema} AND tc.table_name = ${table}
+      `;
+      return { cols, fkRows };
+    });
+
     const fkMap = new Map<string, { table: string; column: string }>();
     for (const fk of fkRows) {
       fkMap.set(fk.from_col as string, { table: fk.ref_table as string, column: fk.ref_col as string });
@@ -140,22 +210,24 @@ class PostgresService {
     connectionString: string, table: string, schema = "public",
     page = 1, limit = 100, orderBy?: string, orderDir: "ASC" | "DESC" = "ASC",
   ): Promise<{ columns: string[]; rows: Record<string, unknown>[]; total: number; page: number; limit: number }> {
-    const sql = this.connect(connectionString);
-    const fullTable = sql(`${schema}.${table}`);
-
-    const [countRow] = await sql`SELECT COUNT(*)::int as cnt FROM ${fullTable}`;
-    const total = (countRow?.cnt as number) ?? 0;
     const offset = (page - 1) * limit;
+    const { rows, total } = await this.withConnection(connectionString, async (sql) => {
+      const fullTable = sql(`${schema}.${table}`);
 
-    let rows: postgres.RowList<postgres.Row[]>;
-    if (orderBy) {
-      const orderCol = sql(orderBy);
-      rows = orderDir === "DESC"
-        ? await sql`SELECT * FROM ${fullTable} ORDER BY ${orderCol} DESC LIMIT ${limit} OFFSET ${offset}`
-        : await sql`SELECT * FROM ${fullTable} ORDER BY ${orderCol} ASC LIMIT ${limit} OFFSET ${offset}`;
-    } else {
-      rows = await sql`SELECT * FROM ${fullTable} LIMIT ${limit} OFFSET ${offset}`;
-    }
+      const [countRow] = await sql`SELECT COUNT(*)::int as cnt FROM ${fullTable}`;
+      const total = (countRow?.cnt as number) ?? 0;
+
+      let rows: postgres.RowList<postgres.Row[]>;
+      if (orderBy) {
+        const orderCol = sql(orderBy);
+        rows = orderDir === "DESC"
+          ? await sql`SELECT * FROM ${fullTable} ORDER BY ${orderCol} DESC LIMIT ${limit} OFFSET ${offset}`
+          : await sql`SELECT * FROM ${fullTable} ORDER BY ${orderCol} ASC LIMIT ${limit} OFFSET ${offset}`;
+      } else {
+        rows = await sql`SELECT * FROM ${fullTable} LIMIT ${limit} OFFSET ${offset}`;
+      }
+      return { rows, total };
+    });
 
     const columns = rows.length > 0 ? Object.keys(rows[0]!) : [];
     return { columns, rows: rows as unknown as Record<string, unknown>[], total, page, limit };
@@ -163,7 +235,6 @@ class PostgresService {
 
   /** Execute arbitrary SQL */
   async executeQuery(connectionString: string, sqlText: string): Promise<PgQueryResult> {
-    const sql = this.connect(connectionString);
     const trimmed = sqlText.trim();
     const upper = trimmed.toUpperCase();
 
@@ -187,34 +258,37 @@ class PostgresService {
     const isSelect = upper.startsWith("SELECT") || upper.startsWith("WITH") ||
       upper.startsWith("EXPLAIN") || upper.startsWith("SHOW") || upper.startsWith("\\D");
 
-    const start = performance.now();
-    if (isSelect) {
-      const rows = await sql.unsafe(sqlText);
-      const executionTimeMs = Math.round(performance.now() - start);
-      const columns = rows.length > 0 ? Object.keys(rows[0]!) : [];
-      return { columns, rows: rows as unknown as Record<string, unknown>[], rowsAffected: 0, changeType: "select", executionTimeMs };
-    }
+    return this.withConnection(connectionString, async (sql) => {
+      const start = performance.now();
+      if (isSelect) {
+        const rows = await sql.unsafe(sqlText);
+        const executionTimeMs = Math.round(performance.now() - start);
+        const columns = rows.length > 0 ? Object.keys(rows[0]!) : [];
+        return { columns, rows: rows as unknown as Record<string, unknown>[], rowsAffected: 0, changeType: "select" as const, executionTimeMs };
+      }
 
-    const result = await sql.unsafe(sqlText);
-    const executionTimeMs = Math.round(performance.now() - start);
-    return { columns: [], rows: [], rowsAffected: result.count ?? 0, changeType: "modify", executionTimeMs };
+      const result = await sql.unsafe(sqlText);
+      const executionTimeMs = Math.round(performance.now() - start);
+      return { columns: [], rows: [], rowsAffected: result.count ?? 0, changeType: "modify" as const, executionTimeMs };
+    });
   }
 
   /** Execute multi-statement SQL script inside a transaction via sql.begin().
    *  Strips user-supplied BEGIN/COMMIT/ROLLBACK since sql.begin() manages the transaction. */
   async executeScript(connectionString: string, scriptText: string): Promise<{ statementsRun: number; executionTimeMs: number }> {
-    const sql = this.connect(connectionString);
     const txControl = /^(BEGIN|COMMIT|ROLLBACK|END)(;|\s|$)/i;
     const statements = splitSqlStatements(scriptText).filter((s) => !txControl.test(s));
     if (statements.length === 0) return { statementsRun: 0, executionTimeMs: 0 };
 
-    const start = performance.now();
-    await sql.begin(async (tx) => {
-      for (const stmt of statements) {
-        await tx.unsafe(stmt);
-      }
+    return this.withConnection(connectionString, async (sql) => {
+      const start = performance.now();
+      await sql.begin(async (tx) => {
+        for (const stmt of statements) {
+          await tx.unsafe(stmt);
+        }
+      });
+      return { statementsRun: statements.length, executionTimeMs: Math.round(performance.now() - start) };
     });
-    return { statementsRun: statements.length, executionTimeMs: Math.round(performance.now() - start) };
   }
 
   /** Update a single cell value */
@@ -222,11 +296,10 @@ class PostgresService {
     connectionString: string, table: string, schema = "public",
     pkColumn: string, pkValue: unknown, column: string, value: unknown,
   ): Promise<void> {
-    const sql = this.connect(connectionString);
-    await sql.unsafe(
+    await this.withConnection(connectionString, (sql) => sql.unsafe(
       `UPDATE "${schema}"."${table}" SET "${column}" = $1 WHERE "${pkColumn}" = $2`,
       [value as never, pkValue as never],
-    );
+    ));
   }
 
   /** Delete a row by primary key */
@@ -234,11 +307,10 @@ class PostgresService {
     connectionString: string, table: string, schema = "public",
     pkColumn: string, pkValue: unknown,
   ): Promise<void> {
-    const sql = this.connect(connectionString);
-    await sql.unsafe(
+    await this.withConnection(connectionString, (sql) => sql.unsafe(
       `DELETE FROM "${schema}"."${table}" WHERE "${pkColumn}" = $1`,
       [pkValue as never],
-    );
+    ));
   }
 
   /** Close all cached connections */

package/src/services/provider-usage/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared provider-usage layer.
+ *
+ * Adding a provider means writing a {@link ProviderUsageSource} — how to list
+ * its accounts and how to read one account's quota — and registering it. The
+ * background sweep, fetch timeout, in-memory cache, negative caching, snapshot
+ * persistence, and the synchronous read path all come with it.
+ *
+ * Registration lives in `register-usage-sources.ts` so this module stays free
+ * of imports from any particular provider.
+ */
+export {
+  AMBIENT_ACCOUNT_KEY,
+  DEFAULT_POLL_INTERVAL_MS,
+  FETCH_TIMEOUT_MS,
+  USAGE_CACHE_TTL_MS,
+  USAGE_FAILURE_TTL_MS,
+  type ProviderUsageSource,
+} from "./usage-source.ts";
+
+export {
+  registerUsageSource,
+  getUsageSource,
+  listUsageSources,
+  getUsage,
+  getOrFetchUsage,
+  refreshUsage,
+  invalidateUsage,
+  _clearUsageSources,
+} from "./usage-registry.ts";
+
+export {
+  startProviderUsagePolling,
+  stopProviderUsagePolling,
+  sweepUsageSource,
+  _isUsagePollingActive,
+} from "./usage-scheduler.ts";
+
+export {
+  snapshotToUsage,
+  readStoredUsage,
+  writeStoredUsage,
+} from "./usage-snapshot-store.ts";
+
+export { _clearUsageCache, invalidateCachedUsage } from "./usage-memory-cache.ts";
+
+import { _clearUsageCache } from "./usage-memory-cache.ts";
+import { _clearInflightUsage } from "./usage-registry.ts";
+import { _clearInflightSweeps, stopProviderUsagePolling } from "./usage-scheduler.ts";
+
+/**
+ * Drop every piece of live state the layer holds: timers, in-flight fetches and
+ * sweeps, and the memory cache. Stored snapshots are left alone — they are the
+ * caller's data, not this layer's state.
+ *
+ * Used by tests, and by the production path that has to abandon a stuck sweep.
+ */
+export function resetUsageRuntimeState(): void {
+  stopProviderUsagePolling();
+  _clearInflightSweeps();
+  _clearInflightUsage();
+  _clearUsageCache();
+}

package/src/services/provider-usage/register-usage-sources.ts

@@ -0,0 +1,18 @@
+import { registerUsageSource } from "./usage-registry.ts";
+import { claudeUsageSource } from "../claude-usage-source.ts";
+import { codexUsageSource } from "../../providers/codex-app-server/codex-usage-source.ts";
+
+/**
+ * Wires the concrete providers into the shared usage layer.
+ *
+ * Separate from `index.ts` so the layer itself imports no provider, and a
+ * provider importing the layer cannot create a cycle back through registration.
+ * Adding a provider is one line here plus its own source file.
+ *
+ * Idempotent: registration is keyed by provider id, so calling it again (a
+ * `bun --hot` reload, a test re-import) replaces rather than duplicates.
+ */
+export function registerAllUsageSources(): void {
+  registerUsageSource(claudeUsageSource);
+  registerUsageSource(codexUsageSource);
+}

package/src/services/provider-usage/usage-memory-cache.ts

@@ -0,0 +1,71 @@
+import type { UsageInfo } from "../../types/chat.ts";
+import { USAGE_CACHE_TTL_MS, USAGE_FAILURE_TTL_MS } from "./usage-source.ts";
+
+/**
+ * In-memory layer in front of the snapshot store, keyed by provider + account.
+ *
+ * Two things live here that the store cannot express. One is freshness: the
+ * store knows the last value but not whether it is worth re-reading yet. The
+ * other is failure — a rejected fetch has nothing to persist, yet must still be
+ * remembered, or every request that misses re-attempts it. For codex that meant
+ * spawning an app-server per request, and a spawn that hangs is never reaped.
+ */
+
+interface Entry {
+  /** Absent for a remembered failure. */
+  usage?: UsageInfo;
+  expiry: number;
+  failed: boolean;
+}
+
+const cache = new Map<string, Entry>();
+
+function key(providerId: string, accountId: string): string {
+  return `${providerId}\0${accountId}`;
+}
+
+/** Cached value if still fresh; `undefined` when absent, stale, or a failure. */
+export function getCachedUsageEntry(providerId: string, accountId: string): UsageInfo | undefined {
+  const hit = cache.get(key(providerId, accountId));
+  if (!hit || Date.now() >= hit.expiry || hit.failed) return undefined;
+  return hit.usage;
+}
+
+/**
+ * True while a recent failure is still remembered — the caller should neither
+ * re-fetch nor treat the absence as "never tried".
+ */
+export function isRecentlyFailed(providerId: string, accountId: string): boolean {
+  const hit = cache.get(key(providerId, accountId));
+  return !!hit && hit.failed && Date.now() < hit.expiry;
+}
+
+export function setCachedUsage(providerId: string, accountId: string, usage: UsageInfo): void {
+  cache.set(key(providerId, accountId), {
+    usage,
+    expiry: Date.now() + USAGE_CACHE_TTL_MS,
+    failed: false,
+  });
+}
+
+export function setCachedFailure(providerId: string, accountId: string): void {
+  cache.set(key(providerId, accountId), {
+    expiry: Date.now() + USAGE_FAILURE_TTL_MS,
+    failed: true,
+  });
+}
+
+/** Drop one entry so the next read re-fetches — used by an explicit refresh. */
+export function invalidateCachedUsage(providerId: string, accountId?: string): void {
+  if (accountId !== undefined) {
+    cache.delete(key(providerId, accountId));
+    return;
+  }
+  const prefix = `${providerId}\0`;
+  for (const k of cache.keys()) if (k.startsWith(prefix)) cache.delete(k);
+}
+
+/** Test seam: forget everything. */
+export function _clearUsageCache(): void {
+  cache.clear();
+}