cartethyia 2.5.4 → 2.5.7

package/src/console/routing/pools/probe-verdict.ts

@@ -1,132 +1,132 @@
-/**
- * What one provider-probe answer means about the egress.
- *
- * Extracted from the store so the console, the CLI probe
- * (`scripts/operations/probe-egress.ts`) and the tests cannot drift into three
- * readings of the same response. The rule that matters is not obvious:
- *
- * **The provider's IP gate runs before it validates the body.** So a `4xx`
- * complaint about the payload proves the address was accepted — it is the
- * probe's request that is wrong, not the proxy. Mapping that to `unreachable`
- * ("the probe could not complete") blamed the proxy for our own defect and hid
- * working egresses behind a verdict that said the pool was unusable.
- *
- * Only the free-tier refusal retires an address. Every other answer either says
- * the address works (`allowed`, `throttled`) or says nothing about it
- * (`unreachable`), and treating "says nothing" as "refused" would drop a usable
- * pool for good.
- */
-
-export type ProbeVerdict = "allowed" | "blocked" | "throttled" | "unreachable";
-
-export interface ProbeAnswer {
-  readonly status: ProbeVerdict;
-  /** Operator-facing reason; absent when the answer needs none. */
-  readonly reason?: string;
-}
-
-/** The upstream's own wording for "this address is retired". */
-const FREE_TIER_REFUSAL = /freetier|free tier can only be used/i;
-
-/**
- * Classifies one upstream response.
- *
- * `407` is separated from the generic 4xx branch on purpose: it comes from the
- * proxy front door, never from the provider, so it is a credential problem on
- * the tunnel and says nothing about whether the address is refused.
- */
-export function classifyProviderProbeAnswer(httpStatus: number, body: string): ProbeAnswer {
-  if (httpStatus === 403 && FREE_TIER_REFUSAL.test(body)) {
-    return { status: "blocked", reason: "Upstream refused this egress address" };
-  }
-  if (httpStatus === 407) {
-    return { status: "unreachable", reason: "Proxy requires authentication" };
-  }
-  if (httpStatus === 429) {
-    return { status: "throttled", reason: "Address accepted; rate limit spent" };
-  }
-  if (httpStatus >= 200 && httpStatus < 300) {
-    return { status: "allowed" };
-  }
-  if (httpStatus >= 500) {
-    return { status: "unreachable", reason: `Upstream answered ${httpStatus}` };
-  }
-  // Any other 4xx: the request reached the upstream's own validation, which
-  // only happens once the address is accepted.
-  return {
-    status: "allowed",
-    reason: `Reachable; upstream answered ${httpStatus} for the probe body`,
-  };
-}
-
-/**
- * Error codes that mean "this attempt never reached the upstream", not "the
- * upstream refused this address".
- *
- * Every one of them is worth a second attempt, and the reason is the same in
- * each case: the failure is a property of one socket, not of the egress. A
- * proxy that has just been dialled for the first time has to resolve, open a
- * tunnel, and complete a TLS handshake, and any of those steps can be refused
- * or reset by a middlebox that accepts the very next attempt — which is exactly
- * the "fails once, works on retry" report. Retiring the pool on the first one
- * blames the address for a cold-start race.
- */
-const RETRYABLE_TRANSPORT_CODES = new Set([
-  "ECONNREFUSED",
-  "ECONNRESET",
-  "ECONNABORTED",
-  "EHOSTUNREACH",
-  "ENETUNREACH",
-  "ENETRESET",
-  "EPIPE",
-  "ETIMEDOUT",
-  "EAI_AGAIN",
-  "UND_ERR_SOCKET",
-  "UND_ERR_CONNECT_TIMEOUT",
-  "ECONNECT_TIMEOUT",
-]);
-/** How many `cause` links to follow; wraps are shallow in practice. */
-const PROBE_ERROR_CAUSE_DEPTH = 5;
-
-/**
- * Whether one probe error should be retried before it becomes a verdict.
- *
- * Deliberately narrow: an abort is *our* deadline firing, so retrying it would
- * spend the whole probe budget on a slow egress, and an unknown error is left
- * alone rather than guessed at. Only transport codes that describe a single
- * dead connection qualify.
- */
-export function isRetryableProbeError(error: unknown): boolean {
-
-  // Walk the `cause` chain: a transport failure is routinely wrapped — the
-  // proxy layer raises `ProxyConnectHandshakeError` whose *message* carries the
-  // real code, with nothing on `code`. Checking only the top error would miss
-  // exactly the failure this exists for.
-  let current: unknown = error;
-  for (let depth = 0; depth < PROBE_ERROR_CAUSE_DEPTH && current !== undefined && current !== null; depth += 1) {
-    if (!(current instanceof Error)) break;
-    if (current.name === "AbortError" || current.name === "TimeoutError") return false;
-    // `code` is not on the base `Error`; narrow before reading it rather than
-    // asserting a shape the runtime may not have.
-    const code: string | undefined =
-      "code" in current && typeof current.code === "string" ? current.code : undefined;
-    if (code !== undefined && RETRYABLE_TRANSPORT_CODES.has(code.toUpperCase())) return true;
-    const message = String(current.message ?? "");
-    // The wrapped code is often only in the message, so match it there too.
-    for (const candidate of RETRYABLE_TRANSPORT_CODES) {
-      if (message.includes(candidate)) return true;
-    }
-    if (
-      message.includes("fetch failed") ||
-      message.includes("socket connection was closed unexpectedly") ||
-      message.includes("other side closed") ||
-      message.startsWith("terminated") ||
-      /connection (?:was|is) closed/i.test(message)
-    ) {
-      return true;
-    }
-    current = current.cause;
-  }
-  return false;
-}
-
+/**
+ * What one provider-probe answer means about the egress.
+ *
+ * Extracted from the store so the console, the CLI probe
+ * (`scripts/tools/probe-egress.ts`) and the tests cannot drift into three
+ * readings of the same response. The rule that matters is not obvious:
+ *
+ * **The provider's IP gate runs before it validates the body.** So a `4xx`
+ * complaint about the payload proves the address was accepted — it is the
+ * probe's request that is wrong, not the proxy. Mapping that to `unreachable`
+ * ("the probe could not complete") blamed the proxy for our own defect and hid
+ * working egresses behind a verdict that said the pool was unusable.
+ *
+ * Only the free-tier refusal retires an address. Every other answer either says
+ * the address works (`allowed`, `throttled`) or says nothing about it
+ * (`unreachable`), and treating "says nothing" as "refused" would drop a usable
+ * pool for good.
+ */
+
+export type ProbeVerdict = "allowed" | "blocked" | "throttled" | "unreachable";
+
+export interface ProbeAnswer {
+  readonly status: ProbeVerdict;
+  /** Operator-facing reason; absent when the answer needs none. */
+  readonly reason?: string;
+}
+
+/** The upstream's own wording for "this address is retired". */
+const FREE_TIER_REFUSAL = /freetier|free tier can only be used/i;
+
+/**
+ * Classifies one upstream response.
+ *
+ * `407` is separated from the generic 4xx branch on purpose: it comes from the
+ * proxy front door, never from the provider, so it is a credential problem on
+ * the tunnel and says nothing about whether the address is refused.
+ */
+export function classifyProviderProbeAnswer(httpStatus: number, body: string): ProbeAnswer {
+  if (httpStatus === 403 && FREE_TIER_REFUSAL.test(body)) {
+    return { status: "blocked", reason: "Upstream refused this egress address" };
+  }
+  if (httpStatus === 407) {
+    return { status: "unreachable", reason: "Proxy requires authentication" };
+  }
+  if (httpStatus === 429) {
+    return { status: "throttled", reason: "Address accepted; rate limit spent" };
+  }
+  if (httpStatus >= 200 && httpStatus < 300) {
+    return { status: "allowed" };
+  }
+  if (httpStatus >= 500) {
+    return { status: "unreachable", reason: `Upstream answered ${httpStatus}` };
+  }
+  // Any other 4xx: the request reached the upstream's own validation, which
+  // only happens once the address is accepted.
+  return {
+    status: "allowed",
+    reason: `Reachable; upstream answered ${httpStatus} for the probe body`,
+  };
+}
+
+/**
+ * Error codes that mean "this attempt never reached the upstream", not "the
+ * upstream refused this address".
+ *
+ * Every one of them is worth a second attempt, and the reason is the same in
+ * each case: the failure is a property of one socket, not of the egress. A
+ * proxy that has just been dialled for the first time has to resolve, open a
+ * tunnel, and complete a TLS handshake, and any of those steps can be refused
+ * or reset by a middlebox that accepts the very next attempt — which is exactly
+ * the "fails once, works on retry" report. Retiring the pool on the first one
+ * blames the address for a cold-start race.
+ */
+const RETRYABLE_TRANSPORT_CODES = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ECONNABORTED",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENETRESET",
+  "EPIPE",
+  "ETIMEDOUT",
+  "EAI_AGAIN",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "ECONNECT_TIMEOUT",
+]);
+/** How many `cause` links to follow; wraps are shallow in practice. */
+const PROBE_ERROR_CAUSE_DEPTH = 5;
+
+/**
+ * Whether one probe error should be retried before it becomes a verdict.
+ *
+ * Deliberately narrow: an abort is *our* deadline firing, so retrying it would
+ * spend the whole probe budget on a slow egress, and an unknown error is left
+ * alone rather than guessed at. Only transport codes that describe a single
+ * dead connection qualify.
+ */
+export function isRetryableProbeError(error: unknown): boolean {
+
+  // Walk the `cause` chain: a transport failure is routinely wrapped — the
+  // proxy layer raises `ProxyConnectHandshakeError` whose *message* carries the
+  // real code, with nothing on `code`. Checking only the top error would miss
+  // exactly the failure this exists for.
+  let current: unknown = error;
+  for (let depth = 0; depth < PROBE_ERROR_CAUSE_DEPTH && current !== undefined && current !== null; depth += 1) {
+    if (!(current instanceof Error)) break;
+    if (current.name === "AbortError" || current.name === "TimeoutError") return false;
+    // `code` is not on the base `Error`; narrow before reading it rather than
+    // asserting a shape the runtime may not have.
+    const code: string | undefined =
+      "code" in current && typeof current.code === "string" ? current.code : undefined;
+    if (code !== undefined && RETRYABLE_TRANSPORT_CODES.has(code.toUpperCase())) return true;
+    const message = String(current.message ?? "");
+    // The wrapped code is often only in the message, so match it there too.
+    for (const candidate of RETRYABLE_TRANSPORT_CODES) {
+      if (message.includes(candidate)) return true;
+    }
+    if (
+      message.includes("fetch failed") ||
+      message.includes("socket connection was closed unexpectedly") ||
+      message.includes("other side closed") ||
+      message.startsWith("terminated") ||
+      /connection (?:was|is) closed/i.test(message)
+    ) {
+      return true;
+    }
+    current = current.cause;
+  }
+  return false;
+}
+

package/src/console/routing/pools/store.ts

@@ -166,8 +166,8 @@ export class DrizzleNetworkPoolStore implements NetworkPoolStore {
       ...(row.lastSpeedtestAt ? { lastSpeedtestAt: row.lastSpeedtestAt.toISOString() } : {}),
       ...(() => {
         // A verdict describes the address recorded beside it. Once the pool is
-        // re-pointed, that address is gone and the verdict is a claim about a
-        // proxy that no longer exists — report "never probed" instead of
+        // re-pointed, that address is gone and the verdict is a claim about an
+        // address the pool no longer uses — report "never probed" instead of
         // showing a colour the operator cannot trust.
         const probe = storedProviderProbe(row, endpoint ?? "");
         return probe === undefined ? {} : { providerProbe: probe };
@@ -350,10 +350,10 @@ export class DrizzleNetworkPoolStore implements NetworkPoolStore {
   /**
    * Banks a probe verdict on the pool row.
    *
-   * The verdict used to live in the operator's browser, which made it
-   * decorative: another machine saw nothing, the gateway saw nothing, and
-   * admission kept choosing the pool the badge called blocked. Storing it here
-   * is what makes the badge a fact about the pool rather than about one tab.
+   * The verdict is stored here rather than per-viewer so every reader agrees:
+   * another machine, the gateway, and the operator alike. Otherwise admission
+   * keeps choosing the pool the badge calls blocked. Storing it here is what
+   * makes the badge a fact about the pool rather than about one tab.
    *
    * `poolId` is the pool row; `endpoint` is what the verdict was measured
    * against, so a later edit invalidates it on read. A probe against an unsaved
@@ -458,8 +458,8 @@ export class DrizzleNetworkPoolStore implements NetworkPoolStore {
       .set({
         endpointConfig,
         kind: effectiveKind === "https" ? "http" : effectiveKind,
-        // Fields default to `undefined` when omitted from the patch; that
-        // used to overwrite the current row with `undefined` and clobber
+        // Fields default to `undefined` when omitted from the patch, which
+        // would overwrite the current row with `undefined` and clobber
         // existing values. Fall back to the current record so a partial
         // PATCH truly leaves un-mentioned fields alone.
         maxInflight: patch.maxInflight ?? current.maxInflight,

package/src/console/settings/contracts.ts

@@ -7,6 +7,10 @@ import { t } from "elysia";
 import type { AccessDecision } from "../../security/access-control";
 import type { RedisBackend } from "../../persistence/redis";
 import type { ConsoleSettingsPreferences } from "../../persistence/schema";
+import { RTK_LEVELS } from "../../transport/request/rtk/rtk-constants";
+import { PONYTAIL_LEVELS } from "../../transport/request/rtk/ponytail-prompt";
+
+export { RTK_LEVELS, PONYTAIL_LEVELS };
 
 export interface RuntimeSettingsResponse {
   readonly redisBackendActual: RedisBackend;
@@ -17,6 +21,8 @@ export interface RuntimeSettingsResponse {
   readonly telemetryPayloads: TelemetryPayloadMode;
   /** Capture depth for `full` mode; `minimum` when unset. */
   readonly telemetryPayloadDepth: TelemetryPayloadDepth;
+  /** How long a captured frame is kept, in minutes; `null` means deployment default. */
+  readonly telemetryPayloadRetentionMinutes: number | null;
   readonly privacyMode: PrivacyMode;
   /** Compacts bulky tool-result text before dispatch (RTK prune). Default false. */
   readonly rtkPruneEnabled: boolean;
@@ -63,6 +69,17 @@ export interface RuntimeSettingsConfig {
   readonly store: RuntimeSettingsStore;
   readonly accessResolver: ConsoleAccessResolver;
   readonly auditSink?: AuditSink;
+  /**
+   * Structurally satisfied by `InMemoryRouteSnapshotService`.
+   *
+   * Two preferences here are read on the request path, not per request: the
+   * route snapshot reads `forceDisableCooldown` when it builds candidates, and
+   * the admission path reads `tenantConcurrencyLimit`. The snapshot is cached
+   * until something invalidates it, so without this a saved setting stays
+   * invisible to `/v1/*` until some unrelated console write happens to
+   * invalidate — the toggle looks broken while the row is already correct.
+   */
+  readonly snapshotInvalidator?: { invalidate(): unknown };
 }
 
 
@@ -75,13 +92,25 @@ export type TelemetryPayloadMode = (typeof TELEMETRY_PAYLOAD_MODES)[number];
 export const TELEMETRY_PAYLOAD_DEPTHS = ["minimum", "moderate", "maximum"] as const;
 /** Capture depth for `full` mode accepted by the runtime-settings PATCH. */
 export type TelemetryPayloadDepth = (typeof TELEMETRY_PAYLOAD_DEPTHS)[number];
+/**
+ * How long a captured payload frame is kept, in whole minutes, or `null` for
+ * the deployment default.
+ *
+ * Only the offered values are accepted, and a value off the list is *rejected*
+ * rather than clamped: clamping would answer a request for thirty days with
+ * seven and report success, and an operator who asked for the longer window
+ * would believe they got it.
+ */
+export const TELEMETRY_PAYLOAD_RETENTION_MINUTES = [15, 30, 60, 360, 720, 1440, 10080] as const;
+/** Payload retention in minutes accepted by the runtime-settings PATCH. */
+export type TelemetryPayloadRetentionMinutes =
+  | (typeof TELEMETRY_PAYLOAD_RETENTION_MINUTES)[number]
+  | null;
 export const PRIVACY_MODES = ["masked", "full"] as const;
 /** Provider/model label privacy accepted by the runtime-settings PATCH. */
 export type PrivacyMode = (typeof PRIVACY_MODES)[number];
-export const PONYTAIL_LEVELS = ["lite", "full", "ultra"] as const;
 /** PonyTail directive intensity accepted by the runtime-settings PATCH. */
 export type PonyTailLevel = (typeof PONYTAIL_LEVELS)[number];
-export const RTK_LEVELS = ["lite", "full", "ultra"] as const;
 /** RTK prune strength accepted by the runtime-settings PATCH. */
 export type RtkLevel = (typeof RTK_LEVELS)[number];
 
@@ -120,6 +149,19 @@ export function createRuntimeSettingsOperations(deps: RuntimeSettingsConfig) {
         if (patch.telemetryPayloadDepth !== undefined && !TELEMETRY_PAYLOAD_DEPTHS.includes(patch.telemetryPayloadDepth)) {
           throw new ConsoleDomainError("invalid_request", 400, "Invalid telemetryPayloadDepth");
         }
+        if (patch.telemetryPayloadRetentionMinutes !== undefined) {
+          const minutes = patch.telemetryPayloadRetentionMinutes;
+          if (
+            minutes !== null &&
+            !(TELEMETRY_PAYLOAD_RETENTION_MINUTES as readonly number[]).includes(minutes)
+          ) {
+            throw new ConsoleDomainError(
+              "invalid_request",
+              400,
+              "Invalid telemetryPayloadRetentionMinutes",
+            );
+          }
+        }
         if (patch.privacyMode !== undefined && !PRIVACY_MODES.includes(patch.privacyMode)) {
           throw new ConsoleDomainError("invalid_request", 400, "Invalid privacyMode");
         }
@@ -140,6 +182,14 @@ export function createRuntimeSettingsOperations(deps: RuntimeSettingsConfig) {
           target: a.tenantId,
           detail: patch as Record<string, unknown>,
         });
+        // Saved preferences are routing changes: `forceDisableCooldown` decides
+        // candidate eligibility and `tenantConcurrencyLimit` decides admission,
+        // and both are read from the cached route snapshot. Invalidate after the
+        // write commits so the next `/v1/*` request uses them instead of the
+        // revision that was built before the save. A failure here must not fail
+        // the save — the row is already correct, and the snapshot rebuilds on
+        // the next read anyway.
+        await Promise.resolve(deps.snapshotInvalidator?.invalidate()).catch(() => undefined);
         return updated;
       },
   };
@@ -156,6 +206,12 @@ export const runtimeUpdateBody = t.Object({
   responsesReasoningSummary: t.Optional(literalUnion(RESPONSES_REASONING_SUMMARIES)),
   telemetryPayloads: t.Optional(literalUnion(TELEMETRY_PAYLOAD_MODES)),
   telemetryPayloadDepth: t.Optional(literalUnion(TELEMETRY_PAYLOAD_DEPTHS)),
+  telemetryPayloadRetentionMinutes: t.Optional(
+    t.Union([
+      t.Null(),
+      t.Union(TELEMETRY_PAYLOAD_RETENTION_MINUTES.map((minutes) => t.Literal(minutes))),
+    ]),
+  ),
   privacyMode: t.Optional(literalUnion(PRIVACY_MODES)),
   tenantConcurrencyLimit: t.Optional(t.Union([t.Null(), t.Number()])),
   thinkingNormalizationEnabled: t.Optional(t.Boolean()),

package/src/console/settings/store.ts

@@ -11,6 +11,7 @@ import {
   RTK_LEVELS,
   TELEMETRY_PAYLOAD_DEPTHS,
   TELEMETRY_PAYLOAD_MODES,
+  TELEMETRY_PAYLOAD_RETENTION_MINUTES,
   type PonyTailLevel,
   type ResponsesReasoningSummary,
   type RtkLevel,
@@ -105,6 +106,25 @@ function normalizeImageClampMaxBytes(value: unknown): number | null {
   return normalizeBoundedNumber(value, 64 * 1024, 100 * 1024 * 1024);
 }
 
+/**
+ * How long a captured payload frame is kept, in whole minutes.
+ *
+ * Only one of the offered values survives; anything else reads as "deployment
+ * default" rather than being clamped to the nearest one. A stored value from
+ * before this list existed would otherwise be silently rewritten to a window
+ * the operator never chose, and dropping it to `null` is the same outcome the
+ * operator gets by never having set it.
+ */
+function normalizePayloadRetentionMinutes(value: unknown): number | null {
+  if (value === null || value === undefined) return null;
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed)) return null;
+  const minutes = Math.floor(parsed);
+  return (TELEMETRY_PAYLOAD_RETENTION_MINUTES as readonly number[]).includes(minutes)
+    ? minutes
+    : null;
+}
+
 function mapRuntimeSettingsRow(
   row: typeof consoleSettings.$inferSelect | undefined,
   redisBackend: RedisBackend,
@@ -120,6 +140,9 @@ function mapRuntimeSettingsRow(
       : "detailed",
     telemetryPayloads: normalizeTelemetryPayloadMode(prefs.telemetryPayloads),
     telemetryPayloadDepth: normalizeTelemetryPayloadDepth(prefs.telemetryPayloadDepth),
+    telemetryPayloadRetentionMinutes: normalizePayloadRetentionMinutes(
+      prefs.telemetryPayloadRetentionMinutes,
+    ),
     privacyMode: prefs.privacyMode === "full" ? "full" : "masked",
     rtkPruneEnabled: prefs.rtkPruneEnabled === true,
     rtkPruneLevel: normalizeRtkLevel(prefs.rtkPruneLevel),
@@ -127,9 +150,9 @@ function mapRuntimeSettingsRow(
     // RTK above works. `ponyTailLevel` selects the intensity and is kept while
     // the feature is off so a re-enable restores it, but a stored level is NOT
     // consent: the dashboard lets an operator choose a strength with the toggle
-    // still off, which writes a level and no flag. Reading that as enabled made
-    // the console report the directive as on while the dispatch gate — which
-    // requires the flag — never injected it.
+    // still off, which writes a level and no flag. Reading that as enabled
+    // would report the directive as on while the dispatch gate — which requires
+    // the flag — never injects it.
     ponyTailEnabled: prefs.ponyTailEnabled === true,
     ponyTailLevel: normalizePonyTailLevel(prefs.ponyTailLevel),
     forceDisableCooldown: prefs.forceDisableCooldown === true,
@@ -169,6 +192,10 @@ export class DrizzleRuntimeSettingsStore implements RuntimeSettingsStore {
       patchPrefs.responsesReasoningSummary = patch.responsesReasoningSummary;
     if (patch.telemetryPayloads !== undefined) patchPrefs.telemetryPayloads = patch.telemetryPayloads;
     if (patch.telemetryPayloadDepth !== undefined) patchPrefs.telemetryPayloadDepth = patch.telemetryPayloadDepth;
+    if (patch.telemetryPayloadRetentionMinutes !== undefined)
+      patchPrefs.telemetryPayloadRetentionMinutes = normalizePayloadRetentionMinutes(
+        patch.telemetryPayloadRetentionMinutes,
+      );
     if (patch.privacyMode !== undefined) patchPrefs.privacyMode = patch.privacyMode;
     if (patch.rtkPruneEnabled !== undefined) patchPrefs.rtkPruneEnabled = patch.rtkPruneEnabled;
     if (patch.rtkPruneLevel !== undefined) patchPrefs.rtkPruneLevel = patch.rtkPruneLevel;

package/src/console/shared/cursor.ts

@@ -13,8 +13,8 @@ const decodeCache = new Map<string, unknown>();
  * Maximum nesting depth a decoded cursor may have.
  *
  * `JSON.parse` accepts arbitrary nesting (it is iterative in this runtime), but
- * every traversal of the result is not: `deepFreeze` used to recurse once per
- * level, and `structuredClone` recurses again. A payload past the stack limit
+ * every traversal of the result is not: `structuredClone` recurses once per
+ * level. A payload past the stack limit
  * therefore threw `RangeError: Maximum call stack size exceeded` out of a function
  * that documents returning `undefined` for a malformed value — failing OPEN into a
  * 500 where the contract is "fall back to the first page", and leaving a partially
@@ -116,8 +116,8 @@ function copyDecoded<T>(value: unknown): T {
       // `structuredClone` recurses, so a value past its own budget throws. The
       // depth limit makes this unreachable for anything `decodeCursor` accepts, but
       // the documented contract is `undefined` for a value that cannot be decoded,
-      // and a cache hit on an entry written before the limit existed could still
-      // reach here.
+      // and the documented contract is `undefined` for a value that cannot be
+      // decoded.
       return undefined as T;
     }
   }
@@ -133,10 +133,10 @@ export interface DatedCursor {
 /**
  * Decodes a `(createdAt, id)` keyset cursor, rejecting anything malformed.
  *
- * Both the audit log and the telemetry event listing paginate on the same pair
- * and both had written the same validation locally — a shape check plus a
- * parseable timestamp. It lives here so the two listings cannot drift: a cursor
- * the audit store accepts must be one the stats store accepts.
+ * Both the audit log and the telemetry event listing paginate on the same pair,
+ * so the shape check plus parseable-timestamp validation lives here and the two
+ * listings cannot drift: a cursor the audit store accepts must be one the stats
+ * store accepts.
  *
  * Deliberately not generic over `T extends DatedCursor`: a caller could then
  * instantiate it with a wider type and read fields that were never validated.

package/src/console/shared/errors.ts

@@ -141,9 +141,7 @@ export function requireGlobalAdmin(access: AccessDecision | undefined): AccessDe
 /**
  * Builds the console's catch-all error handler for an Elysia route group.
  *
- * Every console route group used to wrap each handler in its own try/catch
- * calling `errorResponse` with a group-specific fallback message — 95 copies,
- * 22 of them in one file. Elysia's global `error(handler)` hook receives any
+ * Elysia's global `error(handler)` hook receives any
  * throw from the group (including a `.use()`d child), so one hook per group
  * produces the identical envelope with the identical fallback text.
  *

package/src/network/http2-bidi.ts

@@ -73,10 +73,8 @@ export interface Http2BidiOpenOptions {
  * The dialer contract a provider adapter is handed.
  *
  * Declared here rather than in the provider layer so the dependency runs one
- * way: `provider-contracts` imports this module, never the reverse. It used to
- * be declared there and re-exported from here, which made the two import each
- * other — type-only, so it never deadlocked, but it meant this
- * transport-neutral contract had to know about providers.
+ * way: `provider-contracts` imports this module, never the reverse, and this
+ * transport-neutral contract stays free of any knowledge of providers.
  */
 export type ValidatedOutboundHttp2Bidi = (
   url: URL,