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>

lib/fallback/engine.mjs

@@ -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
   };
 }