@vzn/vx 0.0.630 → 0.0.632

package/src/cli/why.ts

@@ -9,12 +9,11 @@ import path from 'node:path'
 import { Cache } from '../cache/index.js'
 import { flagHint, formatValue, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
-import type { Database } from 'bun:sqlite'
 import {
-  type CacheKeyDiff,
   cacheKeyDiff,
   explainCacheKeyQuery as explainCacheKey,
   latestRunId,
+  rootCauses,
   whyDidThisRerunQuery as whyDidThisRerun,
   resolveRunId,
 } from '../orchestrator/index.js'
@@ -151,7 +150,10 @@ async function resolveTarget(
   const ids = pairs.map((p) => `${p.project}#${p.task}`)
   const invoked = ids.length === 0 && db.query('SELECT 1 FROM invocations LIMIT 1').get() !== null
   if (target.includes('#')) {
-    throw new UserError(`vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`)
+    throw new UserError(
+      `vx why: no recorded runs for "${target}"${suggest(target, ids, invoked)}`,
+      'VX_E_NO_HISTORY',
+    )
   }
   const matches = ids.filter((id) => id.endsWith(`#${target}`))
   if (matches.length === 1) return matches[0]!
@@ -161,10 +163,12 @@ async function resolveTarget(
     throw new UserError(
       `vx why: "${target}" ran in ${matches.length} projects — pick one:\n` +
         matches.map((m) => `  ${m}`).join('\n'),
+      'VX_E_AMBIGUOUS',
     )
   }
   throw new UserError(
     `vx why: no recorded runs for task "${target}"${suggest(target, ids, invoked)}`,
+    'VX_E_NO_HISTORY',
   )
 }
 
@@ -187,9 +191,12 @@ function restoredWord(r: { restored: boolean | null }): string {
 
 export async function whyCmd(args: readonly string[]): Promise<number> {
   const parsed = parseWhyArgs(args)
-  if (parsed.error !== undefined) throw new UserError(`vx why: ${parsed.error}`)
+  if (parsed.error !== undefined) throw new UserError(`vx why: ${parsed.error}`, 'VX_E_USAGE')
   if (parsed.target === undefined) {
-    throw new UserError('vx why: <task> required (e.g. vx why app#build, or vx why build)')
+    throw new UserError(
+      'vx why: <task> required (e.g. vx why app#build, or vx why build)',
+      'VX_E_USAGE',
+    )
   }
 
   const root = await findWorkspaceRoot(process.cwd())
@@ -206,6 +213,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       if (runId === null) {
         throw new UserError(
           `vx why: no recorded run ${parsed.runId} (vx last --list shows recent runs)`,
+          'VX_E_NO_HISTORY',
         )
       }
     } else runId = latestRunId(db, taskId)
@@ -231,6 +239,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     if (!why.found) {
       throw new UserError(
         `vx why: run ${runId} has no row for ${taskId}; \`vx last --list\` shows the recorded runs, \`vx last RUNID\` what one ran`,
+        'VX_E_NO_HISTORY',
       )
     }
     const diff = cacheKeyDiff(db, runId, taskId)
@@ -344,38 +353,3 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
 }
 
 const ROOTS_SHOWN = 5
-
-interface RootCause {
-  /** From the asked task down to the one whose own inputs moved. */
-  chain: string[]
-  entries: CacheKeyDiff['entries']
-}
-
-/**
- * The tasks under `taskId`'s moved upstreams whose OWN key components
- * moved in the same run, each with the chain that carried it up. A task
- * visited once is not walked again (a diamond names its root once).
- */
-function rootCauses(
-  db: Database,
-  runId: string,
-  taskId: string,
-  entries: CacheKeyDiff['entries'],
-): RootCause[] {
-  const roots: RootCause[] = []
-  const seen = new Set([taskId])
-  const walk = (chain: string[], moved: CacheKeyDiff['entries']): void => {
-    for (const e of moved) {
-      if (e.kind !== 'upstream' || seen.has(e.name)) continue
-      seen.add(e.name)
-      const next = [...chain, e.name]
-      const d = cacheKeyDiff(db, runId, e.name)
-      if (!d.found) continue
-      const own = d.entries.filter((x) => x.kind !== 'upstream')
-      if (own.length > 0) roots.push({ chain: next, entries: own })
-      walk(next, d.entries)
-    }
-  }
-  walk([taskId], entries)
-  return roots
-}

package/src/exec/runner.ts

@@ -849,7 +849,7 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
       }
     }
     const reader = stream.getReader()
-    const decoder = new TextDecoder()
+    const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
     try {
       while (true) {
         const { value, done } = await reader.read()
@@ -1097,12 +1097,17 @@ export const CAPTURE_HEAD_CHARS = 8 * 1024 * 1024
 export const CAPTURE_TAIL_CHARS = 8 * 1024 * 1024
 
 const mib = (n: number): string => `${(n / (1024 * 1024)).toFixed(1)} MiB`
+const size = (n: number): string => (n < 1024 * 1024 ? `${n / 1024} KiB` : mib(n))
 
 /** The line that stands where the dropped middle was. */
-export function droppedOutputLine(dropped: number): string {
+export function droppedOutputLine(
+  dropped: number,
+  headChars = CAPTURE_HEAD_CHARS,
+  tailChars = CAPTURE_TAIL_CHARS,
+): string {
   return (
-    `\n[vx] ${mib(dropped)} of output not kept — vx keeps the first ${mib(CAPTURE_HEAD_CHARS)} ` +
-    `and the last ${mib(CAPTURE_TAIL_CHARS)} of a task's output for its cache entry and replay\n`
+    `\n[vx] ${mib(dropped)} of output not kept — vx keeps the first ${size(headChars)} ` +
+    `and the last ${size(tailChars)} of a task's output\n`
   )
 }
 
@@ -1145,12 +1150,17 @@ export class BoundedCapture {
   private tailLen = 0
   private dropped = 0
 
+  constructor(
+    private readonly headChars = CAPTURE_HEAD_CHARS,
+    private readonly tailChars = CAPTURE_TAIL_CHARS,
+  ) {}
+
   push(text: string, err = false): void {
     // Once the tail has begun the head is closed, even a unit short of its
     // bound (the surrogate case below): a later short chunk fit there and
     // was retained ahead of the chunk before it.
-    if (this.tailLen === 0 && this.headLen < CAPTURE_HEAD_CHARS) {
-      let room = CAPTURE_HEAD_CHARS - this.headLen
+    if (this.tailLen === 0 && this.headLen < this.headChars) {
+      let room = this.headChars - this.headLen
       if (text.length <= room) {
         this.head.push({ text, err })
         this.headLen += text.length
@@ -1165,9 +1175,9 @@ export class BoundedCapture {
     }
     this.tail.push({ text, err })
     this.tailLen += text.length
-    while (this.tailLen > CAPTURE_TAIL_CHARS) {
+    while (this.tailLen > this.tailChars) {
       const first = this.tail[0]!
-      const excess = this.tailLen - CAPTURE_TAIL_CHARS
+      const excess = this.tailLen - this.tailChars
       if (first.text.length <= excess) {
         this.tail.shift()
         this.tailLen -= first.text.length
@@ -1185,7 +1195,14 @@ export class BoundedCapture {
   chunks(): CapturedChunk[] {
     return this.dropped === 0
       ? [...this.head, ...this.tail]
-      : [...this.head, { text: droppedOutputLine(this.dropped), err: false }, ...this.tail]
+      : [
+          ...this.head,
+          {
+            text: droppedOutputLine(this.dropped, this.headChars, this.tailChars),
+            err: false,
+          },
+          ...this.tail,
+        ]
   }
 
   text(): string {
@@ -1213,7 +1230,7 @@ export async function streamToString(
   if (!stream || typeof stream === 'number') return ''
   const full = new BoundedCapture()
   const reader = stream.getReader()
-  const decoder = new TextDecoder()
+  const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
   // On abort, cancel the read so a pending `reader.read()` resolves
   // `done` and we return whatever we captured. Needed for the timeout
   // path: SIGTERMing `sh` doesn't close the pipe if an orphaned

package/src/graph/scheduler.ts

@@ -140,6 +140,12 @@ export interface TaskOutcome {
    * of reading it as a signal (item 268).
    */
   timedOut?: true
+  /**
+   * On a `failed` outcome of a command that ran: the final attempt's
+   * output, both streams, as `encodeOutputLog` stores it, secrets masked,
+   * bounded to its first 8 KiB and last 56 KiB. The run's history keeps it.
+   */
+  failedOutput?: string
   /**
    * On a failed persistent task: why it never became ready — the readiness
    * deadline fired, the child exited first (`exitCode` is then its own), or
@@ -255,6 +261,15 @@ export interface ScheduleOptions {
    * slot admits other work at once. Undefined: nothing owed.
    */
   settledOf?: (outcome: TaskOutcome) => Promise<Partial<TaskOutcome> | void> | undefined
+  /**
+   * The outcome of a task the caller settles in place, or undefined to
+   * dispatch it through `execute`. Asked of an exec-tier task the lane has
+   * room for, after the skip check; its outcome lands in the same tick, it
+   * holds no slot, and `onStart` / `onFinish` hear it as any other. An
+   * unkeyed group runs nothing, and the dispatch, the slot and the promise
+   * around it were ~10 µs of each of a warm run's 1,090 groups (X-192).
+   */
+  settleNow?: (node: TaskNode, upstream: TaskOutcome[]) => TaskOutcome | undefined
   /**
    * Optional priority override: callers pass their own per-node weight
    * (e.g. `computePredictedPriorities` from the orchestrator's history
@@ -749,6 +764,16 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       })
     }
 
+    // A throw falls back to the dispatch, whose `execute` reports it.
+    const settleInPlace = (node: TaskNode, upstream: TaskOutcome[]): TaskOutcome | undefined => {
+      if (options.settleNow === undefined) return undefined
+      try {
+        return options.settleNow(node, upstream)
+      } catch {
+        return undefined
+      }
+    }
+
     const tick = (): void => {
       if (resolved) return
       // Exec-tier tasks parked THIS tick on a refused admission. Within
@@ -844,6 +869,17 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
 
         const queuedMs = Date.now() - (readyAt.get(id) ?? Date.now())
         readyAt.delete(id)
+        const now = inRestoreTier(id) ? undefined : settleInPlace(node, upstream)
+        if (now !== undefined) {
+          try {
+            onStart?.(node)
+          } catch (err) {
+            const m = err instanceof Error ? err.message : String(err)
+            process.stderr.write(`[vx] onStart observer threw for ${id}: ${m}\n`)
+          }
+          finishOne(id, queuedMs === 0 ? now : { ...now, queuedMs })
+          continue
+        }
         const leave = admit(id)
         // Listed as running on dispatch, so the policy's next ask in this
         // tick sees it; the completion callbacks unlist it.

package/src/graph/task-graph.ts

@@ -1670,7 +1670,7 @@ function detectCycle(nodes: Map<string, TaskNode>): void {
           for (let i = 0; i < stack.length; i += 2) path.push(idsArr[stack[i]!]!)
           const startInPath = path.indexOf(idsArr[depIdx]!)
           const cycle = [...path.slice(startInPath), idsArr[depIdx]!].join(' -> ')
-          throw new UserError(`Cycle detected in task graph: ${cycle}`)
+          throw new UserError(`Cycle detected in task graph: ${cycle}`, 'VX_E_CYCLE')
         }
         color[depIdx] = GRAY
         stack.push(depIdx, 0)

package/src/index.ts

@@ -239,8 +239,25 @@ export type {
 // The serializable run result and its per-task views (what `run()` returns).
 export type { RunResult, TaskView, OutcomeView } from './orchestrator/index.js'
 
-// The one run-history query a reader outside the CLI takes today: `vx why`'s
-// answer, which `@vzn/vx-mcp` serves. The event bus / wire form and the
-// other history readers (`listRuns`, `getRun`, …) left the façade 2026-09-10
-// with no consumer; the telemetry seam above is the canonical export path.
-export { latestRunId, resolveRunId, whyDidThisRerunQuery } from './orchestrator/index.js'
+// The run-history queries a reader outside the CLI takes today: `vx why`'s
+// answer, a run's failures and a task's log, which `@vzn/vx-mcp` serves. The event bus /
+// wire form and the other history readers (`listRuns`, `getRun`, …) left the
+// façade 2026-09-10 with no consumer; the telemetry seam above is the
+// canonical export path.
+export {
+  cacheKeyDiff,
+  latestRunId,
+  resolveRunId,
+  rootCauses,
+  runFailures,
+  taskLog,
+  whyDidThisRerunQuery,
+} from './orchestrator/index.js'
+export type {
+  CacheKeyDiff,
+  OutputLocation,
+  RootCause,
+  RunFailures,
+  TaskFailure,
+  TaskLog,
+} from './orchestrator/index.js'

package/src/orchestrator/admission.ts

@@ -32,11 +32,21 @@ export interface TaintTracker {
    * bytes nothing vouches for. Its order-only deps count too.
    */
   judge: (node: TaskNode, upstream: TaskOutcome[]) => boolean
+  /**
+   * For a task `judge` called tainted: the task at the root of it, a
+   * failed one or a dependency `--exclude-dependencies` dropped. Its run
+   * row names it (`blocked_by`), so no reader counts the row on its key.
+   */
+  cause: (node: TaskNode, upstream: TaskOutcome[]) => string
   /** Every settled outcome, the scheduler's `onFinish`. */
   settled: (outcome: TaskOutcome) => void
 }
 
-const UNTAINTED: TaintTracker = { judge: () => false, settled: () => {} }
+const UNTAINTED: TaintTracker = {
+  judge: () => false,
+  cause: (node) => node.id,
+  settled: () => {},
+}
 
 /**
  * Records which tasks ran behind a failure, or on the key of a dependency
@@ -61,6 +71,7 @@ export function taintTracker(
   if (!continueAlways && seeds.size === 0) return UNTAINTED
   const outcomes = new Map<string, TaskOutcome>()
   const memo = new Map<string, boolean>()
+  const causes = new Map<string, string>()
   const failed = (u: TaskOutcome): boolean =>
     continueAlways && (u.status === 'failed' || u.status === 'aborted' || u.status === 'skipped')
   const through = (u: TaskOutcome | undefined): boolean =>
@@ -113,6 +124,23 @@ export function taintTracker(
       seeds.has(node.id) ||
       upstream.some(through) ||
       node.orderOnly?.some((d) => through(outcomes.get(d))) === true,
+    cause: (node, upstream) => {
+      // A restore-tier task's upstream holds holes (see `judge`).
+      const deps = upstream.filter((u) => u !== undefined)
+      for (const d of node.orderOnly ?? []) {
+        const u = outcomes.get(d)
+        if (u !== undefined) deps.push(u)
+      }
+      const root =
+        deps.find(failed) ?? deps.find((u) => taintOf(u.node.id)) ?? node.excludedUpstream?.[0]
+      let c: string
+      if (root === undefined) c = node.id
+      else if (failed(root))
+        c = root.status === 'skipped' ? (root.blockedBy ?? root.node.id) : root.node.id
+      else c = causes.get(root.node.id) ?? root.node.id
+      causes.set(node.id, c)
+      return c
+    },
     settled: (outcome) => {
       outcomes.set(outcome.node.id, outcome)
     },

package/src/orchestrator/affected-tasks.ts

@@ -4,6 +4,7 @@
 // behind `^build` runs when `ui#build` (or what it depends on) is reached,
 // and a spec edit `ui#build`'s inputs leave out stops at `ui`'s own tasks.
 
+import path from 'node:path'
 import type { WorkspaceRules } from '../config.js'
 import { declaresInput, workspaceFilesReachInto } from '../cache/index.js'
 import {
@@ -54,6 +55,30 @@ function wholeProjects(
   return whole
 }
 
+/**
+ * Why `--affected` kept a requested task (`vx run --affected --dry`):
+ * `input`, a changed `file` is one of its declared inputs; `project`, its
+ * project changed and the task reads it whole (an uncached task, a path no
+ * cached task declares, or no single `file`: a lockfile claim, a manifest
+ * edge, a config import); `package`, a `^` edge passes through `project`, a
+ * changed package with no such task; `named`, asked as `pkg#task`;
+ * `selected`, another filter selected its project outright. `via` is the
+ * `dependsOn` chain, nearest first, to the task the change seeded.
+ */
+export interface AffectedReason {
+  kind: 'input' | 'project' | 'package' | 'named' | 'selected'
+  /** Workspace-relative. */
+  file?: string
+  project?: string
+  via?: string[]
+}
+
+/** Collects each kept task's `AffectedReason` when given; a run without one pays nothing. */
+export interface AffectedExplain {
+  workspaceRoot: string
+  reasons: Map<string, AffectedReason>
+}
+
 /**
  * The task ids of `ids` whose closure the change reaches, in their order.
  * A group seeds nothing (it runs nothing) unless it is keyed, as the default
@@ -69,8 +94,16 @@ export function affectedRoots(
   changes: AffectedChanges,
   projects: ReadonlyMap<string, ProjectEntry>,
   packageGraph: PackageGraph,
+  explain?: AffectedExplain,
 ): string[] {
   const whole = wholeProjects(changes, projects)
+  const seeds = explain === undefined ? null : new Map<string, AffectedReason>()
+  const through = explain === undefined ? null : new Map<string, string>()
+  const inProject = (name: string, rel: string | undefined): AffectedReason => {
+    if (rel === undefined) return { kind: 'project' }
+    const dir = path.relative(explain!.workspaceRoot, projects.get(name)!.dir)
+    return { kind: 'project', file: dir === '' ? rel : path.posix.join(dir, rel) }
+  }
   // The builder's `^name` walk (task-graph.ts), keeping only the packages
   // it passes through: a holder's own node is already in `deps`.
   const passesChanged = (n: TaskNode): boolean => {
@@ -89,7 +122,10 @@ export function affectedRoots(
         if (visited.has(target)) continue
         visited.add(target)
         if (holds(target)) continue
-        if (changes.projects.has(target)) return true
+        if (changes.projects.has(target)) {
+          seeds?.set(n.id, { kind: 'package', project: target })
+          return true
+        }
         frontier.push(...packageGraph.directDeps(target))
       }
     }
@@ -99,22 +135,35 @@ export function affectedRoots(
     const cache = n.config.cache
     // Asked of every node, not only the changed projects' (the
     // `workspaceFiles` owners): a `graph` hook may have given the glob.
-    if (
-      cache !== undefined &&
-      (changes.changed.some((rel) => declaresInput(cache, null, rel)) ||
-        (changes.nested ?? []).some((dir) => workspaceFilesReachInto(cache, dir)))
-    ) {
-      return true
+    if (cache !== undefined) {
+      const file = changes.changed.find((rel) => declaresInput(cache, null, rel))
+      const dir =
+        file === undefined
+          ? (changes.nested ?? []).find((d) => workspaceFilesReachInto(cache, d))
+          : undefined
+      if (file !== undefined || dir !== undefined) {
+        seeds?.set(n.id, { kind: 'input', file: (file ?? dir)! })
+        return true
+      }
     }
     if (!changes.projects.has(n.projectName)) return false
+    const rels = changes.paths.get(n.projectName) ?? []
     // A group runs nothing; only the default `build` (projects.ts) is keyed.
     // An uncached task reads its project: a root file another task of it
     // declares (`workspaceFiles`) is no change there.
     if (cache === undefined) {
-      return !isGroupTask(n) && (whole.has(n.projectName) || changes.paths.has(n.projectName))
+      const hit = !isGroupTask(n) && (whole.has(n.projectName) || changes.paths.has(n.projectName))
+      if (hit) seeds?.set(n.id, inProject(n.projectName, rels[0]))
+      return hit
+    }
+    if (whole.has(n.projectName)) {
+      seeds?.set(n.id, inProject(n.projectName, undefined))
+      return true
     }
-    if (whole.has(n.projectName)) return true
-    return (changes.paths.get(n.projectName) ?? []).some((rel) => declaresInput(cache, rel, null))
+    const rel = rels.find((r) => declaresInput(cache, r, null))
+    if (rel === undefined) return false
+    if (seeds !== null) seeds.set(n.id, { ...inProject(n.projectName, rel), kind: 'input' })
+    return true
   }
   const reached = new Map<string, boolean>()
   // Post-order on an explicit stack: a closure is as deep as the graph, and
@@ -145,6 +194,7 @@ export function affectedRoots(
       frame[1] = i
       if (i === deps.length || reached.get(deps[i]!) === true) {
         reached.set(id, i < deps.length)
+        if (i < deps.length) through?.set(id, deps[i]!)
         stack.pop()
         continue
       }
@@ -152,7 +202,20 @@ export function affectedRoots(
     }
     return reached.get(root)!
   }
-  return ids.filter(reaches)
+  const kept = ids.filter(reaches)
+  if (explain !== undefined) {
+    for (const root of kept) {
+      const via: string[] = []
+      let id = root
+      for (let next = through!.get(id); next !== undefined; next = through!.get(id)) {
+        via.push(next)
+        id = next
+      }
+      const seed = seeds!.get(id)!
+      explain.reasons.set(root, via.length > 0 ? { ...seed, via } : seed)
+    }
+  }
+  return kept
 }
 
 /**
@@ -167,15 +230,21 @@ export function keptByAffected<R extends { project: string; task: string }>(
   projects: ReadonlyMap<string, ProjectEntry>,
   packageGraph: PackageGraph,
   keep: { named?: ReadonlySet<string>; outright?: ReadonlySet<string> } = {},
+  explain?: AffectedExplain,
 ): R[] {
   const ids = requested.map((r) => `${r.project}#${r.task}`)
-  const reached = new Set(affectedRoots(nodes, ids, changes, projects, packageGraph))
-  return requested.filter(
-    (r, i) =>
-      keep.named?.has(ids[i]!) === true ||
-      keep.outright?.has(r.project) === true ||
-      reached.has(ids[i]!),
-  )
+  const reached = new Set(affectedRoots(nodes, ids, changes, projects, packageGraph, explain))
+  return requested.filter((r, i) => {
+    const id = ids[i]!
+    const why: AffectedReason['kind'] | null =
+      keep.named?.has(id) === true
+        ? 'named'
+        : keep.outright?.has(r.project) === true
+          ? 'selected'
+          : null
+    if (why !== null) explain?.reasons.set(id, { kind: why })
+    return why !== null || reached.has(id)
+  })
 }
 
 /**

package/src/orchestrator/doctor.ts

@@ -8,7 +8,7 @@
 import os from 'node:os'
 import path from 'node:path'
 import { Cache, CACHE_VERSION, SCHEMA_VERSION } from '../cache/index.js'
-import { PLUGIN_HOOKS } from '../config.js'
+import { PLUGIN_HOOKS, type WorkspaceConfig } from '../config.js'
 import {
   cgroupCpuQuota,
   cgroupMemoryLimitBytes,
@@ -17,6 +17,7 @@ import {
   machineMemoryBytes,
   machineParallelism,
   maskedLine,
+  parseSize,
   relPosix,
 } from '../util/index.js'
 import { VERSION } from '../version.js'
@@ -93,6 +94,8 @@ export interface InfoFacts {
   schemaVersion: string
   cacheEntries: number
   cacheBytes: number
+  /** The workspace's `cacheRetention`, with `maxSize` in bytes; null when none is declared. */
+  cacheRetention: { olderThan?: string; maxSize?: string; maxBytes?: number } | null
   orphans: { artifacts: number; bytes: number }
   runs24h: number
   hits24h: number
@@ -250,6 +253,7 @@ async function collectWorkspaceInfo(
     schemaVersion: SCHEMA_VERSION,
     cacheEntries: stats.entryCount,
     cacheBytes: stats.totalBytes,
+    cacheRetention: retentionFact(workspaceConfig?.cacheRetention),
     // A row-less artifact is indexed again only when its task asks for its
     // key; the rest only `vx cache prune` reclaims (after an upgrade's
     // schema reset, most often).
@@ -407,3 +411,12 @@ async function countLoadableTasks(
   errors.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
   return { tasks, sandboxed, errors }
 }
+
+function retentionFact(r: WorkspaceConfig['cacheRetention']): InfoFacts['cacheRetention'] {
+  if (r === undefined) return null
+  return {
+    ...(r.olderThan !== undefined ? { olderThan: r.olderThan } : {}),
+    // Validated at load, so it parses.
+    ...(r.maxSize !== undefined ? { maxSize: r.maxSize, maxBytes: parseSize(r.maxSize)! } : {}),
+  }
+}