cartethyia 2.5.4 → 2.5.7

package/src/persistence/shared-cache.ts

@@ -1,7 +1,6 @@
 // Cross-process cache coordination: a shared L2 in front of Postgres.
 //
-// Every hot read in the request path is cached in-process (see
-// `documentation/research/iomemory/01-request-path-census.md`). That is correct
+// Every hot read in the request path is cached in-process. That is correct
 // for one process and wrong for several: `main.ts` sets `reusePort: true`, so N
 // gateway processes each hold their own copy. With no shared layer, a key
 // revoked through the console stays valid for up to a full TTL in every other

package/src/persistence/stores/api-key-store.ts

@@ -187,6 +187,7 @@ export interface ApiKeyStore {
   reorder(tenantId: string, keyIds: readonly string[]): Promise<void>;
   update(tenantId: string, keyId: string, patch: ApiKeyPatch): Promise<ApiKeyRecord | undefined>;
   revoke(tenantId: string, keyId: string, revokedAt: Date): Promise<boolean>;
+  remove(tenantId: string, keyId: string): Promise<boolean>;
   findActiveByHash?(hash: string): Promise<typeof apiKeys.$inferSelect | undefined>;
   findActiveById?(keyId: string): Promise<typeof apiKeys.$inferSelect | undefined>;
   sumChildrenConsumed?(parentKeyId: string): Promise<number>;
@@ -380,10 +381,6 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
         .set({
           ...(patch.enabled !== undefined ? { enabled: patch.enabled } : {}),
           ...(patch.label !== undefined ? { label: patch.label } : {}),
-          // Promotes a legacy default key: `isDefaultGatewayApiKey` recognizes
-          // it by its canonical label, but recognition was never written back,
-          // so the row stayed unflagged and a later rename — which changes the
-          // only field that identifies it — dropped the default entirely.
           ...(patch.isDefault !== undefined ? { isDefault: patch.isDefault } : {}),
           ...(patch.keyHash !== undefined ? { keyHash: patch.keyHash } : {}),
           ...(patch.keyMode !== undefined ? { keyMode: patch.keyMode } : {}),
@@ -413,8 +410,8 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
             : {}),
           // Scopes are validated once, in `validateApiKeyRequest`, against the
           // tenant scope set; the store writes what it is handed. Omitting the
-          // field here meant an update was type-checked, accepted, and then
-          // silently dropped — a grant like `routing:cli_mapping` could be
+          // field here means an update is type-checked, accepted, and then
+          // silently dropped — a grant like `routing:cli_mapping` can be
           // turned on and never stick.
           ...(patch.scopes === undefined ? {} : { scopes: patch.scopes }),
         })
@@ -453,6 +450,21 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       return true;
     });
   }
+  async remove(tenantId: string, keyId: string): Promise<boolean> {
+    return this.db.transaction(async (tx) => {
+      const rows = await tx
+        .delete(apiKeys)
+        .where(
+          and(
+            eq(apiKeys.tenantId, tenantId),
+            eq(apiKeys.id, keyId),
+            eq(apiKeys.isDefault, false),
+          ),
+        )
+        .returning({ id: apiKeys.id });
+      return rows.length > 0;
+    });
+  }
   async findActiveByHash(hash: string): Promise<typeof apiKeys.$inferSelect | undefined> {
     // The SQLite backend holds this lookup prepared. The builder path rebuilds
     // the query per call, which measured 60x the lookup itself, so the hot

package/src/persistence/stores/share-store.ts

@@ -308,9 +308,10 @@ export class DrizzleShareLinkStore implements ShareLinkStore {
           .set({
             tokenHash: input.tokenHash,
             tokenEncrypted: input.tokenEncrypted,
-            // The slug is the address and survives a rotate, so an operator who
-            // rotates does not invalidate every copy of the link they shared.
-            ...(current.slug === null ? { slug: input.slug } : {}),
+            // Rotating the slug changes the public URL, so the old link stops resolving.
+            // Callers always generate a fresh slug via generateShareSlug() before calling
+            // create() with rotate: true.
+            slug: input.slug,
             expiresAt: input.expiresAt,
             lastViewedAt: null,
           })

package/src/persistence/stores/telemetry-store.ts

@@ -1,237 +1,236 @@
-import { appendFile, mkdir, readdir, rm } from "node:fs/promises";
-import { join } from "node:path";
-import { sql } from "drizzle-orm";
-import { affectedRows, currentTimestamp, laterOf } from "../dialect";
-import type { CartethyiaDatabase } from "../db-handle";
-import {
-  telemetryEvents,
-  telemetryPayloads,
-  telemetryUsageTotals,
-  type TelemetryUsageIdentityType,
-} from "../schema";
-import { isGatewayError } from "../../observability/telemetry-status";
-import { TELEMETRY_EVENT_DIR } from "../../observability/event-log";
-import { dayEventFileName, utcDay } from "../../observability/event-day-index";
-
-interface UsageTotalDelta {
-  readonly tenantId: string;
-  readonly identityType: TelemetryUsageIdentityType;
-  readonly entityId: string;
-  requests: number;
-  errors: number;
-  inputTokens: number;
-  outputTokens: number;
-}
-
-function addUsageDelta(
-  deltas: Map<string, UsageTotalDelta>,
-  row: typeof telemetryEvents.$inferInsert,
-  identityType: TelemetryUsageIdentityType,
-  entityId: string | null | undefined,
-): void {
-  if (entityId == null) return;
-  const key = `${row.tenantId}\0${identityType}\0${entityId}`;
-  let delta = deltas.get(key);
-  if (!delta) {
-    delta = {
-      tenantId: row.tenantId,
-      identityType,
-      entityId,
-      requests: 0,
-      errors: 0,
-      inputTokens: 0,
-      outputTokens: 0,
-    };
-    deltas.set(key, delta);
-  }
-  delta.requests += 1;
-  // Same definition as every read-side error count, including the HTTP-status
-  // exclusions (404/499/503/504): this rollup is durable, so a request counted here
-  // stays counted after its raw row is pruned and cannot be corrected later.
-  if (isGatewayError(row.status, row.httpStatus)) delta.errors += 1;
-  delta.inputTokens += row.inputTokens ?? 0;
-  delta.outputTokens += row.outputTokens ?? 0;
-}
-
-function aggregateUsage(rows: readonly (typeof telemetryEvents.$inferInsert)[]) {
-  const deltas = new Map<string, UsageTotalDelta>();
-  for (const row of rows) {
-    addUsageDelta(deltas, row, "account", row.accountId);
-    addUsageDelta(deltas, row, "api_key", row.apiKeyId);
-  }
-  return [...deltas.values()];
-}
-
-/**
- * Database boundary for durable telemetry writes and bounded retention cleanup.
- * The observability buffer owns queueing and retry policy; this store owns table
- * operations, lifetime aggregates, and retention.
- */
-
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/**
- * Deletes whole days past the retention cutoff: the event file and its index
- * together.
- *
- * The day is the retention unit now, so both go at once. Removing one without
- * the other is the failure this avoids — an index with no events reports totals
- * for requests that no longer exist, and events with no index are invisible to
- * every usage read.
- *
- * The cutoff is a whole day, so today's file — still being appended to — is
- * never a candidate. It used to compare filenames hour by hour, which for a day
- * file compared the `.events` suffix against an hour stamp and could drop the
- * open file.
- */
-async function pruneEventFiles(before: Date): Promise<void> {
-  const files = await readdir(TELEMETRY_EVENT_DIR).catch(() => [] as string[]);
-  const cutoffDay = before.toISOString().slice(0, 10);
-  for (const file of files) {
-    const day = file.slice(0, 10);
-    if (day.length !== 10 || day >= cutoffDay) continue;
-    if (!file.endsWith(".events.jsonl") && !file.endsWith(".index.json")) continue;
-    await rm(join(TELEMETRY_EVENT_DIR, file), { force: true });
-  }
-}
-
-/**
- * Appends one JSON line per event to the day's event file.
- *
- * One file per UTC day, appended to and never rewritten while the day is open.
- * It used to be one file per `windowMinutes` window — 96 a day at the default —
- * which the reader then had to find, open and parse one by one on every usage
- * query. Which of those files was still being written had to be inferred from
- * the name, and that inference is what let the open one be deleted mid-write.
- *
- * A single growing file has no such ambiguity, and the day index tracks how much
- * of it has been counted by byte offset.
- */
-async function appendEvents(rows: readonly (typeof telemetryEvents.$inferInsert)[]): Promise<void> {
-  await mkdir(TELEMETRY_EVENT_DIR, { recursive: true });
-  const file = join(TELEMETRY_EVENT_DIR, dayEventFileName(utcDay(new Date())));
-  const newline = String.fromCharCode(10);
-  const body = rows.map((row) => JSON.stringify(row)).join(newline) + newline;
-  await appendFile(file, body, "utf8");
-}
-
-export class DrizzleTelemetryStore {
-  constructor(private readonly db: CartethyiaDatabase) {}
-
-  /** Inserts events and their durable identity aggregates atomically. */
-  async insertEvents(rows: Array<typeof telemetryEvents.$inferInsert>): Promise<void> {
-    if (rows.length === 0) return;
-    // The file accepts anything, so a malformed row would be written and then
-    // retried forever without ever failing. Rejecting it here keeps the buffer's
-    // drop-and-count contract: one bad row fails the batch, once.
-    for (const row of rows) {
-      if (!UUID_RE.test(row.tenantId)) {
-        throw new Error("telemetry event rejected: tenantId is not a uuid");
-      }
-    }
-    const deltas = aggregateUsage(rows);
-    // The per-request row goes to an append-only file, not to Postgres. The
-    // database keeps only the durable aggregate below, so a request never
-    // adds a row to the largest table. Readers of recent requests read the
-    // file; readers of long-term totals read the aggregate.
-    await this.db.transaction(async (tx) => {
-      if (deltas.length === 0) return;
-      const now = new Date();
-      await tx
-        .insert(telemetryUsageTotals)
-        .values(deltas.map((delta) => ({ ...delta, lastUsedAt: now })))
-        .onConflictDoUpdate({
-          target: [
-            telemetryUsageTotals.tenantId,
-            telemetryUsageTotals.identityType,
-            telemetryUsageTotals.entityId,
-          ],
-          set: {
-            requests: sql`${telemetryUsageTotals.requests} + excluded.requests`,
-            errors: sql`${telemetryUsageTotals.errors} + excluded.errors`,
-            inputTokens: sql`${telemetryUsageTotals.inputTokens} + excluded.input_tokens`,
-            outputTokens: sql`${telemetryUsageTotals.outputTokens} + excluded.output_tokens`,
-            lastUsedAt: laterOf(sql`${telemetryUsageTotals.lastUsedAt}`, sql`excluded.last_used_at`),
-            updatedAt: currentTimestamp(),
-          },
-        });
-    });
-    // After the aggregate commits, so a rejected batch is retried once, not
-    // appended once per attempt. The file is the record of requests whose
-    // totals were actually counted.
-    await appendEvents(rows);
-  }
-
-  /** Inserts one redacted payload and returns its generated identity. */
-  async insertPayload(
-    row: typeof telemetryPayloads.$inferInsert,
-  ): Promise<{ id: string; expiresAt: Date }> {
-    const [inserted] = await this.db
-      .insert(telemetryPayloads)
-      .values(row)
-      .returning({ id: telemetryPayloads.id, expiresAt: telemetryPayloads.expiresAt });
-    if (!inserted) throw new Error("payload capture insert returned no row");
-    return inserted;
-  }
-
-  /**
-   * Deletes at most one bounded batch of expired payloads in a single
-   * statement, so concurrent sweeps atomically claim disjoint rows and the
-   * returned count matches the rows actually deleted.
-   */
-  async deleteExpiredPayloads(batchSize = 5000, before = new Date()): Promise<number> {
-    const result = await this.db.execute(sql`
-      DELETE FROM ${telemetryPayloads}
-      WHERE ${telemetryPayloads.id} IN (
-        SELECT ${telemetryPayloads.id} FROM ${telemetryPayloads}
-        WHERE ${telemetryPayloads.expiresAt} < ${before}
-        ORDER BY ${telemetryPayloads.expiresAt}
-        LIMIT ${batchSize}
-      )
-    `);
-    return affectedRows(result);
-  }
-
-  /**
-   * Deletes at most one bounded batch of aged events in a single statement, so
-   * concurrent sweeps atomically claim disjoint rows and the returned count
-   * matches the rows actually deleted. Ordered by `created_at`, which
-   * `idx_telemetry_created_at` backs.
-   */
-  async deleteExpiredEvents(batchSize = 5000, before: Date): Promise<number> {
-    const result = await this.db.execute(sql`
-      DELETE FROM ${telemetryEvents}
-      WHERE ${telemetryEvents.id} IN (
-        SELECT ${telemetryEvents.id} FROM ${telemetryEvents}
-        WHERE ${telemetryEvents.createdAt} < ${before}
-        ORDER BY ${telemetryEvents.createdAt}
-        LIMIT ${batchSize}
-      )
-    `);
-    return affectedRows(result);
-  }
-
-  /**
-   * Deletes telemetry older than the supplied cutoff. Payloads follow their
-   * `expires_at` contract (15 minutes per row) rather than capture time.
-   *
-   * Events are pruned in bounded batches rather than one `DELETE`, because
-   * `telemetry_events` is the highest-volume table and a single statement
-   * covering every aged row grows without limit: it holds locks and WAL for the
-   * whole sweep, and on a deployment that has run for months it can exceed the
-   * pool's `statement_timeout` and be cancelled, so the sweep never converges
-   * and retention silently stops working. Each batch commits independently, so
-   * progress survives a cancel or a restart. The loop is bounded so one pass
-   * cannot run unbounded — a backlog drains over successive sweeps — mirroring
-   * the payload sweeper's `cleanupExpired`.
-   */
-  async pruneTelemetry(before: Date): Promise<void> {
-    await pruneEventFiles(before);
-    const MAX_BATCHES_PER_SWEEP = 40;
-    for (let batch = 0; batch < MAX_BATCHES_PER_SWEEP; batch += 1) {
-      const deleted = await this.deleteExpiredEvents(5000, before);
-      if (deleted < 5000) break;
-    }
-    await this.deleteExpiredPayloads(5000, before);
-  }
-}
+import { appendFile, mkdir, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { sql } from "drizzle-orm";
+import { affectedRows, currentTimestamp, laterOf } from "../dialect";
+import type { CartethyiaDatabase } from "../db-handle";
+import {
+  telemetryEvents,
+  telemetryPayloads,
+  telemetryUsageTotals,
+  type TelemetryUsageIdentityType,
+} from "../schema";
+import { isGatewayError } from "../../observability/telemetry-status";
+import { TELEMETRY_EVENT_DIR } from "../../observability/event-log";
+import { dayEventFileName, utcDay } from "../../observability/event-day-index";
+
+interface UsageTotalDelta {
+  readonly tenantId: string;
+  readonly identityType: TelemetryUsageIdentityType;
+  readonly entityId: string;
+  requests: number;
+  errors: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+function addUsageDelta(
+  deltas: Map<string, UsageTotalDelta>,
+  row: typeof telemetryEvents.$inferInsert,
+  identityType: TelemetryUsageIdentityType,
+  entityId: string | null | undefined,
+): void {
+  if (entityId == null) return;
+  const key = `${row.tenantId}\0${identityType}\0${entityId}`;
+  let delta = deltas.get(key);
+  if (!delta) {
+    delta = {
+      tenantId: row.tenantId,
+      identityType,
+      entityId,
+      requests: 0,
+      errors: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+    };
+    deltas.set(key, delta);
+  }
+  delta.requests += 1;
+  // Same definition as every read-side error count, including the HTTP-status
+  // exclusions (404/499/503/504): this rollup is durable, so a request counted here
+  // stays counted after its raw row is pruned and cannot be corrected later.
+  if (isGatewayError(row.status, row.httpStatus)) delta.errors += 1;
+  delta.inputTokens += row.inputTokens ?? 0;
+  delta.outputTokens += row.outputTokens ?? 0;
+}
+
+function aggregateUsage(rows: readonly (typeof telemetryEvents.$inferInsert)[]) {
+  const deltas = new Map<string, UsageTotalDelta>();
+  for (const row of rows) {
+    addUsageDelta(deltas, row, "account", row.accountId);
+    addUsageDelta(deltas, row, "api_key", row.apiKeyId);
+  }
+  return [...deltas.values()];
+}
+
+/**
+ * Database boundary for durable telemetry writes and bounded retention cleanup.
+ * The observability buffer owns queueing and retry policy; this store owns table
+ * operations, lifetime aggregates, and retention.
+ */
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Deletes whole days past the retention cutoff: the event file and its index
+ * together.
+ *
+ * The day is the retention unit now, so both go at once. Removing one without
+ * the other is the failure this avoids — an index with no events reports totals
+ * for requests that no longer exist, and events with no index are invisible to
+ * every usage read.
+ *
+ * The cutoff is a whole day, so today's file — still being appended to — is
+ * never a candidate. Comparing filenames hour by hour would match a day file's
+ * `.events` suffix against an hour stamp and could drop the open file.
+ */
+async function pruneEventFiles(before: Date): Promise<void> {
+  const files = await readdir(TELEMETRY_EVENT_DIR).catch(() => [] as string[]);
+  const cutoffDay = before.toISOString().slice(0, 10);
+  for (const file of files) {
+    const day = file.slice(0, 10);
+    if (day.length !== 10 || day >= cutoffDay) continue;
+    if (!file.endsWith(".events.jsonl") && !file.endsWith(".index.json")) continue;
+    await rm(join(TELEMETRY_EVENT_DIR, file), { force: true });
+  }
+}
+
+/**
+ * Appends one JSON line per event to the day's event file.
+ *
+ * One file per UTC day, appended to and never rewritten while the day is open.
+ * A file per `windowMinutes` window — 96 a day at the default — would have to be
+ * found, opened and parsed one by one on every usage query, and which of those
+ * files was still being written could only be inferred from the name, which is
+ * what lets the open one be deleted mid-write.
+ *
+ * A single growing file has no such ambiguity, and the day index tracks how much
+ * of it has been counted by byte offset.
+ */
+async function appendEvents(rows: readonly (typeof telemetryEvents.$inferInsert)[]): Promise<void> {
+  await mkdir(TELEMETRY_EVENT_DIR, { recursive: true });
+  const file = join(TELEMETRY_EVENT_DIR, dayEventFileName(utcDay(new Date())));
+  const newline = String.fromCharCode(10);
+  const body = rows.map((row) => JSON.stringify(row)).join(newline) + newline;
+  await appendFile(file, body, "utf8");
+}
+
+export class DrizzleTelemetryStore {
+  constructor(private readonly db: CartethyiaDatabase) {}
+
+  /** Inserts events and their durable identity aggregates atomically. */
+  async insertEvents(rows: Array<typeof telemetryEvents.$inferInsert>): Promise<void> {
+    if (rows.length === 0) return;
+    // The file accepts anything, so a malformed row would be written and then
+    // retried forever without ever failing. Rejecting it here keeps the buffer's
+    // drop-and-count contract: one bad row fails the batch, once.
+    for (const row of rows) {
+      if (!UUID_RE.test(row.tenantId)) {
+        throw new Error("telemetry event rejected: tenantId is not a uuid");
+      }
+    }
+    const deltas = aggregateUsage(rows);
+    // The per-request row goes to an append-only file, not to Postgres. The
+    // database keeps only the durable aggregate below, so a request never
+    // adds a row to the largest table. Readers of recent requests read the
+    // file; readers of long-term totals read the aggregate.
+    await this.db.transaction(async (tx) => {
+      if (deltas.length === 0) return;
+      const now = new Date();
+      await tx
+        .insert(telemetryUsageTotals)
+        .values(deltas.map((delta) => ({ ...delta, lastUsedAt: now })))
+        .onConflictDoUpdate({
+          target: [
+            telemetryUsageTotals.tenantId,
+            telemetryUsageTotals.identityType,
+            telemetryUsageTotals.entityId,
+          ],
+          set: {
+            requests: sql`${telemetryUsageTotals.requests} + excluded.requests`,
+            errors: sql`${telemetryUsageTotals.errors} + excluded.errors`,
+            inputTokens: sql`${telemetryUsageTotals.inputTokens} + excluded.input_tokens`,
+            outputTokens: sql`${telemetryUsageTotals.outputTokens} + excluded.output_tokens`,
+            lastUsedAt: laterOf(sql`${telemetryUsageTotals.lastUsedAt}`, sql`excluded.last_used_at`),
+            updatedAt: currentTimestamp(),
+          },
+        });
+    });
+    // After the aggregate commits, so a rejected batch is retried once, not
+    // appended once per attempt. The file is the record of requests whose
+    // totals were actually counted.
+    await appendEvents(rows);
+  }
+
+  /** Inserts one redacted payload and returns its generated identity. */
+  async insertPayload(
+    row: typeof telemetryPayloads.$inferInsert,
+  ): Promise<{ id: string; expiresAt: Date }> {
+    const [inserted] = await this.db
+      .insert(telemetryPayloads)
+      .values(row)
+      .returning({ id: telemetryPayloads.id, expiresAt: telemetryPayloads.expiresAt });
+    if (!inserted) throw new Error("payload capture insert returned no row");
+    return inserted;
+  }
+
+  /**
+   * Deletes at most one bounded batch of expired payloads in a single
+   * statement, so concurrent sweeps atomically claim disjoint rows and the
+   * returned count matches the rows actually deleted.
+   */
+  async deleteExpiredPayloads(batchSize = 5000, before = new Date()): Promise<number> {
+    const result = await this.db.execute(sql`
+      DELETE FROM ${telemetryPayloads}
+      WHERE ${telemetryPayloads.id} IN (
+        SELECT ${telemetryPayloads.id} FROM ${telemetryPayloads}
+        WHERE ${telemetryPayloads.expiresAt} < ${before}
+        ORDER BY ${telemetryPayloads.expiresAt}
+        LIMIT ${batchSize}
+      )
+    `);
+    return affectedRows(result);
+  }
+
+  /**
+   * Deletes at most one bounded batch of aged events in a single statement, so
+   * concurrent sweeps atomically claim disjoint rows and the returned count
+   * matches the rows actually deleted. Ordered by `created_at`, which
+   * `idx_telemetry_created_at` backs.
+   */
+  async deleteExpiredEvents(batchSize = 5000, before: Date): Promise<number> {
+    const result = await this.db.execute(sql`
+      DELETE FROM ${telemetryEvents}
+      WHERE ${telemetryEvents.id} IN (
+        SELECT ${telemetryEvents.id} FROM ${telemetryEvents}
+        WHERE ${telemetryEvents.createdAt} < ${before}
+        ORDER BY ${telemetryEvents.createdAt}
+        LIMIT ${batchSize}
+      )
+    `);
+    return affectedRows(result);
+  }
+
+  /**
+   * Deletes telemetry older than the supplied cutoff. Payloads follow their
+   * `expires_at` contract (15 minutes per row) rather than capture time.
+   *
+   * Events are pruned in bounded batches rather than one `DELETE`, because
+   * `telemetry_events` is the highest-volume table and a single statement
+   * covering every aged row grows without limit: it holds locks and WAL for the
+   * whole sweep, and on a deployment that has run for months it can exceed the
+   * pool's `statement_timeout` and be cancelled, so the sweep never converges
+   * and retention silently stops working. Each batch commits independently, so
+   * progress survives a cancel or a restart. The loop is bounded so one pass
+   * cannot run unbounded — a backlog drains over successive sweeps — mirroring
+   * the payload sweeper's `cleanupExpired`.
+   */
+  async pruneTelemetry(before: Date): Promise<void> {
+    await pruneEventFiles(before);
+    const MAX_BATCHES_PER_SWEEP = 40;
+    for (let batch = 0; batch < MAX_BATCHES_PER_SWEEP; batch += 1) {
+      const deleted = await this.deleteExpiredEvents(5000, before);
+      if (deleted < 5000) break;
+    }
+    await this.deleteExpiredPayloads(5000, before);
+  }
+}

package/src/protocol/canonical-model.ts

@@ -308,6 +308,13 @@ export type ContentPart =
       /** Responses reasoning summary block index, preserved across surfaces. */
       summary_index?: number;
       signature?: string;
+      /**
+       * Responses item id the `encrypted_content` was issued for. The upstream
+       * binds encrypted reasoning to its item and rejects a replay whose item
+       * id does not match, so the id travels with the payload it belongs to
+       * rather than being re-derived at request time.
+       */
+      item_id?: string;
       encrypted_content?: string;
     }
   | { kind: "extension"; name: string; payload: unknown };
@@ -596,9 +603,10 @@ export function hasEncryptedReasoning(parts: readonly ContentPart[]): boolean {
  * Single-pass summary of a request's content parts.
  *
  * `deriveRequiredCapabilities` + `assessTranslation` run on every candidate
- * preflight and previously each flattened the whole request (`allParts`) and
- * then scanned the copy up to ~6 times. This walks the messages once, builds
- * no intermediate array, and answers every predicate the pipeline needs.
+ * preflight, and flattening the whole request (`allParts`) in each and then
+ * scanning the copy up to ~6 times is the cost this avoids. It walks the
+ * messages once, builds no intermediate array, and answers every predicate the
+ * pipeline needs.
  * Results are memoized per request object in a `WeakMap`, so the preflight +
  * translate passes over one request share a single summary and entries are
  * collected with the request itself — no manual invalidation, no leak.