bridgebench 3.1.0-alpha.0 → 3.1.0-alpha.2

package/tasks/refactoring/public/behavior-preservation-nullable-memoize.yaml

@@ -0,0 +1,136 @@
+id: behavior-preservation-nullable-memoize
+version: 1.0.0
+category: refactoring
+cluster: behavior-preservation
+difficulty: expert
+title: memoize() Rewrite Equivalence — Falsy Values, Compute Timing, and the Prototype-Key Trap
+summary: >-
+  Four candidate rewrites of a single-slot memoizer are proposed. Exactly one preserves observable
+  behavior (loadSetting invoked once per distinct key, correct value returned for every key including
+  falsy ones). The others recompute falsy-valued keys, call loadSetting on every invocation, or use a
+  plain-object cache whose inherited 'constructor' key short-circuits computation. Classify each
+  rewrite and name the observable difference.
+prompt: |
+  Answer each deliverable using ONLY the supplied artifacts (memoize-original, load-note, rewrite-a,
+  rewrite-b, rewrite-c, rewrite-d). Cite artifact id(s) for every claim. Use the verdict vocabulary:
+  behavior-preserving / changes-behavior / meets-goal / fails-goal.
+
+  The transformation goal is to restructure memoize for readability WITHOUT changing observable
+  behavior: for the memoized function getSetting = memoize(loadSetting), each distinct key must
+  invoke loadSetting exactly once (loadSetting increments a disk_reads counter every call — see
+  load-note), and every key must return the same value memoize-original returns, including keys whose
+  value is falsy.
+
+  1. Classify rewrite-a relative to memoize-original. Justify by tracing what happens on a cache miss
+     and a cache hit, including for a key whose cached value is undefined.
+
+  2. Classify rewrite-b. If it changes behavior, name the observable difference and give a concrete
+     key from load-note that triggers it, stating how many disk_reads three sequential getSetting
+     calls with that key produce under memoize-original vs rewrite-b.
+
+  3. Classify rewrite-c. Name the observable difference, if any, over three sequential getSetting
+     calls with the same key, in terms of the disk_reads counter and the returned value.
+
+  4. Classify rewrite-d. If it changes behavior, give the concrete key from load-note that triggers
+     it, and state exactly what getSetting returns for that key and whether loadSetting is called.
+
+  5. Exactly one rewrite is the only behavior-preserving merge. Name it. Then, for memoize-original,
+     state the ground truth for three sequential getSetting('auth') calls: how many times loadSetting
+     is invoked (disk_reads delta) and what each call returns.
+artifacts:
+  - id: memoize-original
+    type: code
+    label: quill/memoize.ts — shipped memoize (the reference behavior)
+    content: |
+      // quill/memoize.ts — the shipped single-slot memoizer. This is the ONLY definition of memoize.
+      export function memoize<T>(fn: (key: string) => T): (key: string) => T {
+        const cache = new Map<string, T>();
+        return (key: string): T => {
+          if (cache.has(key)) return cache.get(key) as T; // membership by presence, not truthiness
+          const value = fn(key);
+          cache.set(key, value);
+          return value;
+        };
+      }
+  - id: load-note
+    type: note
+    label: quill settings — how memoize is used, side effects, and the complete key set
+    content: |
+      quill settings — how memoize is used (complete).
+
+      const getSetting = memoize(loadSetting) is the ONLY use of memoize in the codebase.
+
+      loadSetting(key):
+        - Increments a 'disk_reads' counter on EVERY call (an observable side effect) and reads the
+          setting from disk. It is expensive; memoize exists to run it once per distinct key.
+        - Returns the section object for a present setting, or undefined for an absent one.
+
+      Keys: getSetting is only ever called with keys from the frozen set
+        SECTION_NAMES = ['auth', 'render', 'constructor']
+      This is the complete set of keys; no other key is ever passed.
+
+      Fixed return values for this deployment:
+        - loadSetting('auth')        -> { token: 't-1' }   (a truthy object)
+        - loadSetting('render')      -> undefined          (this setting is absent)
+        - loadSetting('constructor') -> { mode: 'fast' }   ('constructor' is a real config section)
+
+      Reference semantics of memoize-original: keyed by Map.has, so EVERY distinct key — including
+      one whose value is undefined or otherwise falsy — is computed exactly once; later calls with
+      that key return the stored value without calling loadSetting. There is no eviction and no other
+      caller.
+  - id: rewrite-a
+    type: code
+    label: rewrite-a — "compute-if-absent, single return"
+    content: |
+      // rewrite-a — "compute-if-absent, one return statement."
+      export function memoize<T>(fn: (key: string) => T): (key: string) => T {
+        const cache = new Map<string, T>();
+        return (key: string): T => {
+          if (!cache.has(key)) cache.set(key, fn(key));
+          return cache.get(key) as T;
+        };
+      }
+  - id: rewrite-b
+    type: code
+    label: rewrite-b — "skip has(), reuse the get()"
+    content: |
+      // rewrite-b — "skip the has() lookup; reuse the value we already fetched."
+      export function memoize<T>(fn: (key: string) => T): (key: string) => T {
+        const cache = new Map<string, T>();
+        return (key: string): T => {
+          const cached = cache.get(key);
+          if (cached) return cached;    // return the cached value if we have one
+          const value = fn(key);
+          cache.set(key, value);
+          return value;
+        };
+      }
+  - id: rewrite-c
+    type: code
+    label: rewrite-c — "compute first, then decide"
+    content: |
+      // rewrite-c — "compute first, then decide whether to store."
+      export function memoize<T>(fn: (key: string) => T): (key: string) => T {
+        const cache = new Map<string, T>();
+        return (key: string): T => {
+          const value = fn(key);
+          if (cache.has(key)) return cache.get(key) as T;
+          cache.set(key, value);
+          return value;
+        };
+      }
+  - id: rewrite-d
+    type: code
+    label: rewrite-d — "plain object cache, `in` membership"
+    content: |
+      // rewrite-d — "use a plain object cache and the `in` operator."
+      export function memoize<T>(fn: (key: string) => T): (key: string) => T {
+        const cache: Record<string, T> = {};
+        return (key: string): T => {
+          if (key in cache) return cache[key];
+          const value = fn(key);
+          cache[key] = value;
+          return value;
+        };
+      }
+tags: [refactoring, behavior-preservation, memoization, edge-case, prototype]

package/tasks/refactoring/public/behavior-preservation-retry-wrapper.yaml

@@ -0,0 +1,187 @@
+id: behavior-preservation-retry-wrapper
+version: 1.0.0
+category: refactoring
+cluster: behavior-preservation
+difficulty: expert
+title: runWithRetry Rewrite Equivalence — Attempt Counts, Error Class, and onRetry Timing
+summary: >-
+  Four candidate rewrites of a transient-retry wrapper are proposed. Exactly one preserves
+  observable behavior (task-invocation count, which error classes retry vs rethrow, the error
+  object thrown, and how many times onRetry fires and with which attempt argument). The others
+  shift an attempt boundary, broaden the caught error class, or move onRetry across the exhaustion
+  check. Classify each rewrite and name the observable difference.
+prompt: |
+  Answer each deliverable using ONLY the supplied artifacts (retry-original, error-model,
+  rewrite-a, rewrite-b, rewrite-c, rewrite-d, usage-note). Cite artifact id(s) for every claim.
+  Use the verdict vocabulary: behavior-preserving / changes-behavior / meets-goal / fails-goal.
+
+  The transformation goal is to restructure runWithRetry for readability WITHOUT changing any
+  observable behavior: the number of times task() is invoked, which error classes are retried vs
+  rethrown immediately, the error object ultimately thrown, and the number of times and the attempt
+  argument with which opts.onRetry is called.
+
+  1. Classify rewrite-a relative to retry-original. Justify by tracing the attempt counter and the
+     retry/throw decision across every path.
+
+  2. Classify rewrite-b. If it changes behavior, name the exact observable difference. Use scenario
+     S1 in usage-note (task() throws a TransientError on every call, maxAttempts = 3): give the
+     number of task() invocations and the sequence of onRetry attempt arguments, and compare to
+     retry-original.
+
+  3. Classify rewrite-c. Use scenario S2 in usage-note (task() throws a PermanentError on its first
+     call, maxAttempts = 3): give the task() invocation count and onRetry behavior for BOTH
+     retry-original and rewrite-c, and name the observable difference if any.
+
+  4. Classify rewrite-d under scenario S1. State how many times opts.onRetry fires and with which
+     attempt arguments, and name the observable difference from retry-original, considering what
+     usage-note says onRetry is wired to.
+
+  5. Exactly one rewrite is the only behavior-preserving merge. Name it. Then, for retry-original
+     under scenario S1, state the ground-truth counts: how many times task() is invoked, how many
+     times onRetry fires and with which attempt values, and which error object is thrown.
+artifacts:
+  - id: retry-original
+    type: code
+    label: orchard/retry.ts — shipped runWithRetry (the reference behavior)
+    content: |
+      // orchard/retry.ts — the shipped helper. This file is the ONLY definition of runWithRetry
+      // in the codebase (see usage-note for call sites).
+      import { TransientError } from './errors';
+
+      export async function runWithRetry<T>(
+        task: () => Promise<T>,
+        opts: { maxAttempts: number; onRetry?: (err: unknown, attempt: number) => void },
+      ): Promise<T> {
+        let attempt = 0;
+        for (;;) {
+          attempt += 1;
+          try {
+            return await task();
+          } catch (err) {
+            if (!(err instanceof TransientError)) throw err; // permanent errors are never retried
+            if (attempt >= opts.maxAttempts) throw err;      // out of attempts: rethrow last error
+            opts.onRetry?.(err, attempt);                    // fires only for an attempt that RETRIES
+          }
+        }
+      }
+  - id: error-model
+    type: code
+    label: orchard/errors.ts — the complete error taxonomy
+    content: |
+      // orchard/errors.ts — the complete error taxonomy used with runWithRetry.
+      // TransientError and PermanentError are SIBLINGS; neither extends the other.
+      export class TransientError extends Error {} // e.g. network blip, 503
+      export class PermanentError extends Error {} // e.g. 400 bad request
+
+      // A PermanentError is NOT an instanceof TransientError. This is the entire set of error
+      // classes the retry helper distinguishes; there are no subclasses of TransientError.
+  - id: rewrite-a
+    type: code
+    label: rewrite-a — "same logic, tidier loop header"
+    content: |
+      // rewrite-a — proposed by engineer A. "Same logic, tidier loop header."
+      export async function runWithRetry<T>(
+        task: () => Promise<T>,
+        opts: { maxAttempts: number; onRetry?: (err: unknown, attempt: number) => void },
+      ): Promise<T> {
+        for (let attempt = 1; ; attempt++) {
+          try {
+            return await task();
+          } catch (err) {
+            if (!(err instanceof TransientError)) throw err;
+            if (attempt >= opts.maxAttempts) throw err;
+            opts.onRetry?.(err, attempt);
+          }
+        }
+      }
+  - id: rewrite-b
+    type: code
+    label: rewrite-b — "clearer exhaustion check"
+    content: |
+      // rewrite-b — proposed by engineer B. "Clearer exhaustion check."
+      export async function runWithRetry<T>(
+        task: () => Promise<T>,
+        opts: { maxAttempts: number; onRetry?: (err: unknown, attempt: number) => void },
+      ): Promise<T> {
+        let attempt = 0;
+        for (;;) {
+          attempt += 1;
+          try {
+            return await task();
+          } catch (err) {
+            if (!(err instanceof TransientError)) throw err;
+            if (attempt > opts.maxAttempts) throw err; // changed >= to >
+            opts.onRetry?.(err, attempt);
+          }
+        }
+      }
+  - id: rewrite-c
+    type: code
+    label: rewrite-c — "collapse the two guard lines"
+    content: |
+      // rewrite-c — proposed by engineer C. "Collapse the two guard lines."
+      export async function runWithRetry<T>(
+        task: () => Promise<T>,
+        opts: { maxAttempts: number; onRetry?: (err: unknown, attempt: number) => void },
+      ): Promise<T> {
+        let attempt = 0;
+        for (;;) {
+          attempt += 1;
+          try {
+            return await task();
+          } catch (err) {
+            if (attempt >= opts.maxAttempts) throw err;
+            opts.onRetry?.(err, attempt);
+          }
+        }
+        // note: the instanceof TransientError guard from retry-original is gone.
+      }
+  - id: rewrite-d
+    type: code
+    label: rewrite-d — "report the retry before deciding to give up"
+    content: |
+      // rewrite-d — proposed by engineer D. "Report the retry before deciding to give up."
+      export async function runWithRetry<T>(
+        task: () => Promise<T>,
+        opts: { maxAttempts: number; onRetry?: (err: unknown, attempt: number) => void },
+      ): Promise<T> {
+        let attempt = 0;
+        for (;;) {
+          attempt += 1;
+          try {
+            return await task();
+          } catch (err) {
+            if (!(err instanceof TransientError)) throw err;
+            opts.onRetry?.(err, attempt);              // moved ABOVE the exhaustion check
+            if (attempt >= opts.maxAttempts) throw err;
+          }
+        }
+      }
+  - id: usage-note
+    type: note
+    label: orchard retry — usage, observability, and canonical semantics (complete)
+    content: |
+      orchard retry — usage and observability (complete for the 2.x helper).
+
+      Call sites: runWithRetry is defined exactly once (retry-original) and called from exactly two
+      places: the queue worker and the webhook forwarder. Both pass an onRetry callback that does
+      one thing: metrics.increment('retries_total'). There is no other onRetry implementation and
+      nothing else reads the attempt argument. So the number of onRetry calls is directly
+      observable as the retries_total counter, and the attempt value is recorded as a metric label.
+
+      Canonical semantics of retry-original (authoritative):
+        - task() is invoked at most maxAttempts times.
+        - onRetry fires ONLY after a failed attempt that will be retried; it never fires on the
+          final (exhausting) attempt. So onRetry fires at most maxAttempts - 1 times, with
+          attempt = 1, 2, ..., up to maxAttempts - 1.
+        - A caught error that is not an instanceof TransientError is rethrown immediately, with no
+          retry and no onRetry call.
+        - On exhaustion, the LAST caught TransientError is rethrown.
+
+      Scenarios referenced by the deliverables:
+        S1: task() throws a TransientError on every invocation; maxAttempts = 3.
+        S2: task() throws a PermanentError on its first invocation; maxAttempts = 3.
+
+      This note plus retry-original and error-model are the complete behavioral contract: there is
+      no background auto-retry, no jitter/backoff timer, and no other caller to consider.
+tags: [refactoring, behavior-preservation, retry, error-handling, equivalence]

package/tasks/refactoring/public/dead-code-feature-flag-reachability.yaml

@@ -0,0 +1,162 @@
+id: dead-code-feature-flag-reachability
+version: 1.1.0
+category: refactoring
+cluster: dead-code-elimination
+difficulty: expert
+title: Auditing a dead-code cleanup PR for the Nimbus notify module
+summary: A cleanup PR deletes seven items from the notify module, each claimed to be dead. Reachability runs through two live entry points, a string-keyed channel dispatcher, and a flag registry where one flag is active-but-off and another is permanently removed. Classify each removal as behavior-preserving or changes-behavior, and judge whether the PR meets the elimination goal.
+prompt: |
+  A cleanup PR (removal-pr) deletes seven items from the Nimbus `notify` module, each labelled
+  "dead code." Reachability is fully determined by three self-declared-complete artifacts: the
+  entry-manifest (the only entry points and the no-reflection guarantee), the flag-registry (every
+  flag and whether it is active or permanently removed), and the dispatch-registry (every channel
+  key the dispatcher is ever called with). The module source is in module-source.
+
+  Answer each deliverable using ONLY the supplied artifacts (entry-manifest, flag-registry,
+  dispatch-registry, module-source, removal-pr). Cite the artifact id(s) for every claim.
+
+  For removals R1..R7, classify each as exactly one of:
+    - behavior-preserving  (the item is truly unreachable; deleting it changes nothing observable)
+    - changes-behavior     (the item is reachable on some entry point / flag state / dispatch key;
+                            deleting it removes live behavior)
+
+  A code path guarded by a flag that is enabled, or that operators can still toggle ON, is
+  REACHABLE (not dead). A path guarded by a flag that has been permanently removed from the registry
+  is unreachable.
+
+  1. Classify R1 (remove sendPush).
+  2. Classify R2 (remove checkoutV2Path and its call in notifyUser).
+  3. Classify R3 (remove legacyExportPath and its dead guarded call in notifyUser).
+  4. Classify R4 (remove sendSms).
+  5. Classify R5 (remove formatLegacyReceipt).
+  6. Classify R6 (remove computeTax).
+  7. Classify R7 (remove the attachBanner call and function).
+  8. GOAL. Taking the elimination goal as "remove all and only truly-dead code," does this PR
+     meet-goal or fails-goal? If fails-goal, name every reachable item it wrongly removes AND any
+     truly-dead item it leaves behind.
+
+  Exactly one classification is defensible per deliverable; it is fully determined by the artifacts.
+  For every changes-behavior verdict, name the reachability path (entry point, flag state, or
+  dispatch key) that keeps the item alive.
+artifacts:
+  - id: entry-manifest
+    type: spec
+    label: notify module reachability manifest (complete)
+    content: |
+      Nimbus `notify` module — reachability surface. This manifest is COMPLETE.
+
+      Entry points (the ONLY ways execution enters this module):
+        - notifyUser(user)   — exported; called by the API controller on every send request.
+        - notifyBatch(users) — exported; called by the nightly cron job.
+      There are NO other exported functions and no other callers of this module.
+
+      Dynamic behavior: the module dispatches channel handlers by string key through the
+      dispatch-registry (see that artifact). Apart from that registry lookup, the module uses NO
+      reflection, NO eval, NO dynamic import, and NO string-to-symbol resolution. A function is
+      reachable ONLY if it can actually execute at runtime from notifyUser or notifyBatch — i.e. a
+      static call chain reaches it AND every feature-flag guard on that chain can be true per the
+      flag-registry — OR it is a channel handler registered in the dispatch-registry under a key in
+      CHANNELS. A call reached only through a guard whose flag is REMOVED (permanently false in the
+      flag-registry) is NOT a live chain.
+
+      Therefore: a defined function is truly dead if it has no static caller at all, OR its only
+      static callers sit behind a permanently-false (REMOVED) flag, AND it has no dispatch-registry
+      registration under a CHANNELS key.
+  - id: flag-registry
+    type: config
+    label: feature-flag registry (complete and authoritative)
+    content: |
+      # flags.registry.yaml — the COMPLETE set of flags. Any key not listed here does not exist,
+      # and flags.isEnabled(missingKey) returns false and can never be toggled true.
+
+      flags:
+        - key: promo.banner
+          enabled: true
+          status: active        # operators may toggle; currently ON
+        - key: checkout.v2
+          enabled: true
+          status: active        # currently ON; operators may toggle it either way
+        - key: legacy-export
+          enabled: false
+          status: REMOVED       # key was deleted from the registry service on 2026-03-14.
+                                # isEnabled('legacy-export') is permanently false and CANNOT be
+                                # toggled true again; the flag no longer exists operationally.
+
+      # No other flags exist. A branch guarded by an `active` flag is reachable (it is ON now, or
+      # can be turned ON); a branch guarded by a REMOVED flag is unreachable (permanently false).
+  - id: dispatch-registry
+    type: code
+    label: channel dispatch registry (complete key set)
+    content: |
+      // notify/dispatch.ts
+      // The dispatcher is invoked ONLY with keys from CHANNELS. This is the complete key set.
+      export const CHANNELS = ['email', 'sms'] as const;
+
+      const HANDLERS: Record<string, (u: User) => void> = {
+        email: sendEmail,
+        sms:   sendSms,
+        // NOTE: sendPush is intentionally NOT registered here and 'push' is not in CHANNELS.
+      };
+
+      export function dispatch(channel: string, u: User): void {
+        // channel is always one of CHANNELS (validated upstream by notifyUser).
+        HANDLERS[channel](u);
+      }
+  - id: module-source
+    type: code
+    label: notify module source
+    content: |
+      // notify/index.ts
+
+      export function notifyUser(user: User): void {
+        const amountDue = computeTax(user.subtotal);              // live, unconditional call
+        if (flags.isEnabled('promo.banner')) attachBanner(user);  // promo.banner is ON
+        if (flags.isEnabled('checkout.v2')) checkoutV2Path(user.cart);       // checkout.v2 is ON
+        if (flags.isEnabled('legacy-export')) legacyExportPath(user.order);  // legacy-export REMOVED
+        dispatch(user.channel, user);                             // user.channel in CHANNELS
+        record(user.id, amountDue);
+      }
+
+      export function notifyBatch(users: User[]): void {
+        for (const u of users) notifyUser(u);
+      }
+
+      // Called from notifyUser, guarded at the call site by checkout.v2 (flag-registry: enabled).
+      // No internal flag check.
+      function checkoutV2Path(cart: Cart): void {
+        const tax = computeTax(cart.subtotal);
+        finalizeCheckout(cart, tax);
+      }
+
+      // Called from notifyUser, guarded at the call site by legacy-export, which is REMOVED
+      // (permanently false), so this call never fires and this function is never reached.
+      function legacyExportPath(order: Order): void {
+        emit(formatLegacyReceipt(order));
+      }
+
+      function computeTax(subtotal: number): number { return Math.round(subtotal * 1.08); }
+      function attachBanner(user: User): void { user.banner = currentPromo(); }
+      function formatLegacyReceipt(order: Order): string { return `RECEIPT ${order.id}`; }
+
+      function sendEmail(u: User): void { mail.queue(u.email); }   // registered channel 'email'
+      function sendSms(u: User): void { sms.queue(u.phone); }      // registered channel 'sms'
+      function sendPush(u: User): void { push.queue(u.deviceId); } // NOT registered, no callers
+
+      // Defined long ago; no caller anywhere, not a channel handler, not touched by any flag.
+      function oldRetryHelper(fn: () => void): void { try { fn(); } catch { fn(); } }
+  - id: removal-pr
+    type: diff
+    label: proposed dead-code cleanup PR
+    content: |
+      PR #812 "remove dead code from notify module". Proposed deletions:
+
+      R1  delete function sendPush                                     (reason: "no callers")
+      R2  delete function checkoutV2Path and its call in notifyUser    (reason: "behind the checkout.v2 feature flag")
+      R3  delete function legacyExportPath and its dead guarded call in notifyUser (reason: "behind the legacy-export feature flag")
+      R4  delete function sendSms                                      (reason: "no direct callers found")
+      R5  delete function formatLegacyReceipt                          (reason: "only used by legacyExportPath")
+      R6  delete function computeTax                                   (reason: "only used by checkoutV2Path")
+      R7  delete function attachBanner and its call in notifyUser      (reason: "promo branch is dead")
+
+      The PR does NOT touch oldRetryHelper (the author did not notice it).
+tags: [dead-code-elimination, refactoring, feature-flags, reachability, dispatch]

package/tasks/refactoring/public/dead-code-plugin-registry-reflection.yaml

@@ -0,0 +1,125 @@
+id: dead-code-plugin-registry-reflection
+version: 1.0.0
+category: refactoring
+cluster: dead-code-elimination
+difficulty: expert
+title: Auditing a plugin cleanup PR where classes are constructed by name at Solstice Export
+summary: A cleanup PR deletes six items from an export service whose plugins are constructed by string name from a registry. One exporter is enabled at startup, one is reachable only through a request-format allow-list, one is truly dead, and a core plugin is constructed directly. Classify each removal as behavior-preserving or changes-behavior, and judge whether the PR meets the elimination goal.
+prompt: |
+  Solstice Export constructs its plugins by string name from REGISTRY. A cleanup PR (removal-pr)
+  deletes six items, each labelled "unused." Reachability is fully determined by three
+  self-declared-complete artifacts: plugin-config (the exact enabled plugins and allowed request
+  formats), the registry (every class the loader can resolve), and the bootstrap manifest (the only
+  three plugin-construction sites and the no-other-reflection guarantee). The classes and helpers
+  are in module-source.
+
+  Answer each deliverable using ONLY the supplied artifacts (plugin-config, registry, bootstrap,
+  module-source, removal-pr). Cite the artifact id(s) for every claim. Note that a class with no
+  literal `new ClassName()` anywhere can still be constructed via REGISTRY[name]; grepping for
+  direct constructor calls is not sufficient.
+
+  For removals P1..P6, classify each as exactly one of:
+    - behavior-preserving  (the item is never constructed / never called on any path; deleting it
+                            changes nothing observable)
+    - changes-behavior     (the item is constructed or called on some path — startup, a request
+                            format, or a core site; deleting it removes live behavior)
+
+  1. Classify P1 (remove AuthPlugin).
+  2. Classify P2 (remove YamlExporter and its registry entry).
+  3. Classify P3 (remove XmlExporter and its registry entry).
+  4. Classify P4 (remove deprecatedThumbnailer).
+  5. Classify P5 (remove JsonExporter and its registry entry).
+  6. Classify P6 (remove warmCache).
+  7. GOAL. Taking the elimination goal as "remove all and only truly-dead code," does this PR
+     meet-goal or fails-goal? If fails-goal, name every reachable item it wrongly removes AND any
+     truly-dead item it leaves behind.
+
+  Exactly one classification is defensible per deliverable; it is fully determined by the artifacts.
+  For every changes-behavior verdict, name the construction/call path (startup, request format, or
+  core) that keeps the item alive.
+artifacts:
+  - id: plugin-config
+    type: config
+    label: plugin configuration (baked at build, complete, immutable at runtime)
+    content: |
+      # plugins.config.yaml — baked at build time; COMPLETE and immutable at runtime.
+
+      enabledPlugins: [JsonExporter, CsvExporter]   # exactly these are constructed at startup
+      allowedFormats: [json, csv, yaml]             # the request path accepts exactly these formats
+
+      # A request's format is validated against allowedFormats BEFORE any plugin is constructed;
+      # a format outside this list is rejected and never reaches the registry.
+      # A class is constructed ONLY IF its name is in enabledPlugins, OR its name equals
+      # <Capitalized-format>Exporter for some format in allowedFormats (e.g. yaml -> YamlExporter).
+      # No other plugin is enabled and no other format is accepted.
+  - id: registry
+    type: code
+    label: plugin registry (every resolvable class)
+    content: |
+      // plugins/registry.ts
+      import { JsonExporter, CsvExporter, YamlExporter, XmlExporter } from './exporters';
+
+      // The loader resolves classes by name from this object; these are all it can resolve.
+      export const REGISTRY = { JsonExporter, CsvExporter, YamlExporter, XmlExporter };
+
+      // AuthPlugin is NOT in REGISTRY: it is constructed directly by bootstrap (see that artifact),
+      // not resolved by name.
+  - id: bootstrap
+    type: spec
+    label: plugin construction sites (complete)
+    content: |
+      // plugins/bootstrap.ts — the COMPLETE set of plugin construction sites. There are exactly
+      // three, and no other code constructs a plugin.
+
+      // (core) constructed directly at startup, unconditionally:
+      new AuthPlugin().init();
+
+      // (startup) one instance per enabled plugin name:
+      for (const name of config.enabledPlugins) new REGISTRY[name]().run(seed);
+
+      // (request) per export request, chosen by the already-validated format:
+      export function handleExport(req: ExportReq) {
+        // req.format has already been checked to be in config.allowedFormats.
+        const cls = REGISTRY[capitalize(req.format) + 'Exporter'];  // e.g. 'yaml' -> YamlExporter
+        return new cls().run(req.data);
+      }
+
+      // REGISTRY is indexed ONLY by (a) a name in config.enabledPlugins or (b)
+      // <Capitalized-format>Exporter for a format in config.allowedFormats. Apart from these
+      // sites there is NO `new` of any plugin, NO eval, and NO dynamic import in the service.
+  - id: module-source
+    type: code
+    label: plugin classes and helper functions
+    content: |
+      // plugins/exporters.ts
+
+      export class AuthPlugin { init() { session.attach(); } }         // core plugin
+
+      export class JsonExporter { run(d: Data) { return JSON.stringify(d); } }
+      export class CsvExporter  { run(d: Data) { return toCsv(d); } }
+      export class YamlExporter { run(d: Data) { return toYaml(d); } }
+      export class XmlExporter  { run(d: Data) { warmCache(); return toXml(d); } }
+
+      // Called ONLY from XmlExporter.run above; no other caller.
+      function warmCache(): void { cache.preload(); }
+
+      // No caller anywhere; not in REGISTRY; not a core plugin.
+      function deprecatedThumbnailer(img: Image): Buffer { return render(img, 64); }
+
+      // No caller anywhere; not in REGISTRY; not a core plugin.
+      function legacyManifestWriter(pkg: Pkg): string { return `MANIFEST ${pkg.id}`; }
+  - id: removal-pr
+    type: diff
+    label: proposed cleanup PR
+    content: |
+      PR #440 "delete unused plugin code". Proposed deletions:
+
+      P1  delete class AuthPlugin                       (reason: "not in plugins.config enabledPlugins")
+      P2  delete class YamlExporter + its registry entry (reason: "no `new YamlExporter()` anywhere")
+      P3  delete class XmlExporter + its registry entry   (reason: "no `new XmlExporter()` anywhere")
+      P4  delete function deprecatedThumbnailer           (reason: "no callers")
+      P5  delete class JsonExporter + its registry entry  (reason: "no `new JsonExporter()` anywhere")
+      P6  delete function warmCache                       (reason: "only used by XmlExporter")
+
+      The PR does NOT touch legacyManifestWriter (the author did not notice it).
+tags: [dead-code-elimination, refactoring, plugin-registry, reflection, reachability]