feat+docs+test: D40 — X-OLP-Fallback-Detail header (issue #7)

ADR 0004 § Decision § Chain advancement step 4 promised a per-hop failure detail debug header `X-OLP-Fallback-Detail`. From D9 through D39 the engine logged per-hop events (D28 added correlation fields) but never surfaced the failure trail on the response. D40 fulfills the promise via Option A — ungated v0.1 emission. Phase 2 will re-introduce owner-vs-non-owner gating when `lib/keys.mjs` lands. **Per-hop tuple collection** (lib/fallback/engine.mjs) executeWithFallback now collects `fallbackDetail` — an array of per-hop tuples — and returns it on EVERY return shape (success / client-error / AUTH_MISSING / non-trigger / chain-exhausted). Soft-trigger skipped hops are also recorded with `trigger_type: 'soft'` (currently dead- code-by-config per ADR 0004 Amendment 2; shape forward-compatible). Tuple shape (reuses D28 log-event field shapes so logs and the header pivot on the same keys): ``` { hop: <0-indexed hop number>, provider: <provider name>, model: <model name from IR>, code: <ProviderError code, engine-synthetic SOFT_TRIGGER, or 'UNKNOWN'>, error_message: <truncated to 200 chars with ellipsis on overflow>, trigger_type: 'hard' | 'soft' | 'client_error' | 'auth_missing' | 'unclassified' } ``` **Header serialiser** (server.mjs) - `FALLBACK_DETAIL_BYTE_CAP = 4096` (UTF-8 bytes). - `serializeFallbackDetailHeader(fallbackDetail)` exported. Returns `null` for empty/null/undefined → caller omits the header. - `jsonStringifyAscii` escapes every non-ASCII code point as `\uXXXX` to satisfy RFC 7230 §3.2.6 field-vchar (Node's HTTP header validator rejects multi-byte UTF-8). The D38 CONCURRENCY_LIMIT synthesised message contains a U+2014 em dash — without this escape, every CONCURRENCY_LIMIT response crashed at writeHead with "Invalid character in header content". The regression test pins this exact string. - 4KB cap algorithm: builds candidates as `[...slice(0, kept), sentinel]` and measures the FULL serialised length (including sentinel) before comparing against the cap, so the result is guaranteed under cap. Tail tuples dropped one at a time. Sentinel form: `{ truncated: true, omitted_hops: N }`. **Header emission** (server.mjs) - `withFallbackDetailHeader(base, fallbackDetail)` wraps the base header object; emits the header only when serialiser returns non-null. - Emitted on chain-exhausted, non-trigger-error, client-error, AUTH_MISSING, and success-with-prior-failure paths. - ABSENT on clean primary success — verified by a dedicated HTTP integration test. **Tests** (test-features.mjs): 452 → 468 (+16): - Engine-level tuple shape: 2-hop/exhausted, 2-hop/success-with-prior- failure, 1-hop/success (empty array), 1-hop/fail, non-ProviderError- yields-UNKNOWN, 500-char-message → 200-char-with-ellipsis, client error → 1 tuple + client_error trigger type - Serialiser: empty/null → null, small array round-trip, >4KB cap with `{truncated:true,omitted_hops:N}` sentinel, RFC 7230 newline/CR escaping, non-ASCII escaping (em dash regression guard for the D38 CONCURRENCY_LIMIT synthesised message) - HTTP integration: clean-1-hop-success (header absent), 2-hop- exhausted (2 tuples on the wire), 2-hop-success-with-prior-failure (1 tuple on the wire) Pre-commit fold-in (per evidence-first checkpoint #4): - **Reviewer Suggestion #2**: `jsonStringifyAscii` regex character class `[U+0080-U+FFFF]` contains an invisible U+0080 boundary marker that editors render as nothing, making the line easy to misread as the empty class `[-...]`. Folded in a 5-line comment block above the function body explaining the literal byte range and citing RFC 7230 §3.2.6. Two reviewer suggestions not folded: - **Suggestion #1**: AUTH_MISSING tuple path lacks a dedicated D40 test. Code is structurally correct (tuple pushed before early- return); low priority. Future polish. - **Suggestion #3**: defensive `err.code != null` guard. Extremely low priority — PROVIDER_ERROR_CODES is a closed enum with no falsy values. **ADR amendments** (docs/adr/0004-fallback-engine.md) - Amendment 5 added at top of amendments stack — full tuple schema, cap behavior, RFC 7230 hygiene, ungated v0.1 rationale, Phase 2 follow-up. - § Chain advancement step 4 updated to remove TBD / not-yet- implemented qualifiers and cross-reference Amendment 5. - § Observability headers section gains the X-OLP-Fallback-Detail schema as IMPLEMENTED at v0.1. **CHANGELOG.md** — D40 sub-entry appended under existing D38/D39 entries in Unreleased section. No package.json bump per phase_rolling_mode. Authority: - ADR 0004 § Decision § Chain advancement step 4 — D40 fulfils the promise - ADR 0004 Amendment 5 (this commit) — implementation contract - ADR 0004 § Observability headers — updated to IMPLEMENTED state - D18 (5 standard X-OLP-* headers) — D40 builds on this convention - D28 (per-hop structured log fields) — D40 reuses the field shapes - GitHub issue #7 — closed by this commit - CC 开发铁律 v1.6 § 10.x — fresh-context opus reviewer independent - CLAUDE.md release_kit_overlay phase_rolling_mode — no version bump Reviewer (Iron Rule v1.6 § 10.x Mode A, fresh-context opus, independent of drafter): APPROVE. Critical depth checks: - Tuple pushed once per hop, BEFORE client-error / AUTH_MISSING early-return branches — both paths include the failing tuple - fallbackDetail returned on all 5 return paths (verified line by line) - Cap algorithm measures FULL serialised length (with sentinel) before comparing — no overshoot - RFC 7230 compliance verified end-to-end: imported the function in Node, confirmed em-dash → —, unescaped form throws "Invalid character in header content" - Serialiser handles null / undefined / [] gracefully → header absent on clean primary success (HTTP test pins this) - Hygiene: 0 hits for personal markers, home paths, tokens - 468/468 tests pass in reviewer's independent npm test run Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-07-21 21:15:10 +00:00 · 2026-05-24 21:44:11 +10:00
parent bdfea6884b
commit 04f797f917
5 changed files with 683 additions and 10 deletions
@@ -227,6 +227,18 @@ export function evaluateSoftTriggers(triggerConfig, quotaSnapshot) {
 * @property {object|null} [quotaSnapshot] — optional pre-fetched quota snapshot
 */

+/**
+ * @typedef {Object} FallbackDetailTuple — per-hop failure detail tuple emitted in X-OLP-Fallback-Detail.
+ * D40 (issue #7) — Option A (ungated v0.1). Shapes reuse D28 log event fields so future readers
+ * can grep both surfaces consistently.
+ * @property {number} hop — 0-indexed hop number
+ * @property {string} provider — provider name at this hop
+ * @property {string} model — model string at this hop (from chain hop, which carries IR model)
+ * @property {string} code — ProviderError code, or 'UNKNOWN' for non-ProviderError exceptions
+ * @property {string} error_message — error message, truncated to 200 chars
+ * @property {string} trigger_type — classifyTrigger() output: 'hard' | 'auth_missing' | 'client_error' | 'non_trigger' | 'soft' for engine-synthesized soft skips
+ */
+
 /**
 * @typedef {Object} FallbackResult
 * @property {Array<object>|null} chunks — IR chunk array on success; null if exhausted
@@ -235,8 +247,65 @@ export function evaluateSoftTriggers(triggerConfig, quotaSnapshot) {
 * @property {number} fallbackHops — chain index of the serving hop (0=primary, 1=first fallback, etc.)
 * @property {Error|null} originalError — first-hop error if exhausted; null on success
 * @property {string[]} triedProviders — all providers tried, in chain order
+ * @property {FallbackDetailTuple[]} fallbackDetail — per-hop failure tuples (D40, issue #7).
+ *   On success, contains the failing hops before the serving hop (may be empty).
+ *   On exhausted/non-trigger/client-error/auth-missing return paths, contains every failed hop.
+ *   Server.mjs emits X-OLP-Fallback-Detail when this array is non-empty.
 */

+/**
+ * Truncates an error message to at most 200 characters. If truncation occurs,
+ * the result ends with a single-character ellipsis (U+2026 '…') to signal
+ * the cut. Used to keep X-OLP-Fallback-Detail tuples readable in dashboards.
+ *
+ * D40 (issue #7) — see ADR 0004 § Observability headers.
+ *
+ * @param {unknown} message
+ * @returns {string}
+ */
+function truncateErrorMessage(message) {
+  const s = typeof message === 'string' ? message : String(message ?? '');
+  if (s.length <= 200) return s;
+  return s.slice(0, 199) + '…';
+}
+
+/**
+ * Builds the per-hop failure tuple emitted in X-OLP-Fallback-Detail.
+ * Field shapes reuse D28's structured log event values so the header and
+ * the log line are pivotable on the same keys.
+ *
+ * D40 (issue #7) — see ADR 0004 § Observability headers.
+ *
+ * @param {number} hop
+ * @param {string} provider
+ * @param {string} model
+ * @param {Error} err
+ * @param {'hard'|'soft'|'auth_missing'|'client_error'|'non_trigger'|null} triggerType
+ * @returns {FallbackDetailTuple}
+ */
+function makeFallbackDetailTuple(hop, provider, model, err, triggerType) {
+  let code;
+  if (err instanceof ProviderError && err.code) {
+    code = err.code;
+  } else if (typeof err?.code === 'string') {
+    // Carries err.code from soft-trigger synthesized errors (code: 'SOFT_TRIGGER')
+    // or any custom error class that uses string codes. Non-string err.code
+    // falls through to 'UNKNOWN' so a numeric Node errno (e.g. ECONNREFUSED's
+    // numeric system errno) does not get mis-typed.
+    code = err.code;
+  } else {
+    code = 'UNKNOWN';
+  }
+  return {
+    hop,
+    provider,
+    model,
+    code,
+    error_message: truncateErrorMessage(err?.message),
+    trigger_type: triggerType ?? 'non_trigger',
+  };
+}
+
 /**
 * Executes a provider chain with fallback semantics.
 *
@@ -276,6 +345,12 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
  let originalError = null;  // Per ADR 0004: first-hop error is the canonical signal
  let firstErrorRecorded = false;

+  // D40 (issue #7) — per-hop failure tuples for X-OLP-Fallback-Detail.
+  // Reuses D28 log event field shapes; emitted by server.mjs on any response
+  // where this array is non-empty. ADR 0004 § Observability headers.
+  /** @type {FallbackDetailTuple[]} */
+  const fallbackDetail = [];
+
  for (let i = 0; i < chain.length; i++) {
    const hop = chain[i];
    const { provider, model, softTriggers = null, quotaSnapshot = null } = hop;
@@ -313,13 +388,17 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
      // should treat 'SOFT_TRIGGER' as engine-synthetic. D9 review-2 noted
      // this; documented here so future readers do not try to add SOFT_TRIGGER
      // to the PROVIDER_ERROR_CODES closed enum.
+      const softErr = Object.assign(
+        new Error(`Soft trigger fired for provider ${provider}: quota threshold exceeded`),
+        { code: 'SOFT_TRIGGER', provider },
+      );
      if (!firstErrorRecorded) {
-        originalError = Object.assign(
-          new Error(`Soft trigger fired for provider ${provider}: quota threshold exceeded`),
-          { code: 'SOFT_TRIGGER', provider },
-        );
+        originalError = softErr;
        firstErrorRecorded = true;
      }
+      // D40: record soft-skipped hop in fallbackDetail. trigger_type='soft' lets
+      // downstream readers distinguish a skipped hop from a spawned-and-failed one.
+      fallbackDetail.push(makeFallbackDetailTuple(i, provider, model, softErr, 'soft'));
      continue;
    }

@@ -348,6 +427,7 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
        fallbackHops: i,
        originalError: null,
        triedProviders,
+        fallbackDetail,  // D40: failing hops that came BEFORE this success
      };
    } catch (err) {
      // Record FIRST hop error as the canonical signal
@@ -357,6 +437,12 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
        firstErrorRecorded = true;
      }

+      // D40 (issue #7): classify once and record the per-hop tuple. The same
+      // trigger_type value flows into the log event below (consistency between
+      // logs and X-OLP-Fallback-Detail).
+      const errTriggerType = classifyTrigger(err);
+      fallbackDetail.push(makeFallbackDetailTuple(i, provider, model, err, errTriggerType));
+
      logEvent('warn', 'fallback_hop_error', {
        chain_id: chainId,
        hop: i,
@@ -364,7 +450,7 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
        model,
        error: err.message,
        code: err.code ?? null,
-        trigger_type: classifyTrigger(err),
+        trigger_type: errTriggerType,
        ir_request_hash: irRequestHash,
        next_provider: chain[i + 1]?.provider ?? null,
      });
@@ -389,6 +475,7 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
          fallbackHops: i,
          originalError: err,
          triedProviders,
+          fallbackDetail,  // D40
        };
      }

@@ -412,6 +499,7 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
          fallbackHops: i,
          originalError: err,
          triedProviders,
+          fallbackDetail,  // D40
        };
      }

@@ -428,7 +516,7 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
          error: err.message,
          code: err.code ?? null,
          advance_to_hop: i + 1,
-          trigger_type: classifyTrigger(err),
+          trigger_type: errTriggerType,
          ir_request_hash: irRequestHash,
          next_provider: chain[i + 1]?.provider ?? null,
        });
@@ -443,7 +531,7 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
        provider,
        error: err.message,
        code: err.code ?? null,
-        trigger_type: classifyTrigger(err),
+        trigger_type: errTriggerType,
        ir_request_hash: irRequestHash,
        next_provider: null,
      });
@@ -454,6 +542,7 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
        fallbackHops: i,
        originalError: err,
        triedProviders,
+        fallbackDetail,  // D40
      };
    }
  }
@@ -477,6 +566,7 @@ export async function executeWithFallback(chain, irRequest, executeHopFn, option
    fallbackHops: chain.length,
    originalError,
    triedProviders,
+    fallbackDetail,  // D40 (issue #7): per-hop failure tuples; every attempted hop on exhaustion
  };
 }