From 317d244753c1e0daa93fb6e6bc1778ec8074dc27 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 9 Sep 2026 15:15:11 +0000
Subject: [PATCH] docs(kernel): reduce the 429/503 details fences to what
 producers emit

The two 429 fences taught `limit`, `window` and `quota_reset`, none of which
any producer emits, and omitted `resetAt`, which both of them do. Both 429
emitters build the same exhaustive two-member bag:

  packages/runtime/src/endpoint-policy.ts:356
  packages/runtime/src/security/inbound-rate-limit.ts:359
    details: { retryAfterSeconds, resetAt }

so anything else those fences name is not in the bag by construction. The
503 fence taught a `details` bag with `reason` / `retryAfterSeconds` /
`estimated_completion`; no 503 producer on this tree emits a `details` bag
at all, so the bag is dropped rather than re-spelled.

The `QUOTA_EXCEEDED` fence is deliberately untouched: that code has no
producer anywhere on the tree, so there is no emitted shape to reduce it to.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012GKcPZbMoGq7WPzKLfRBTU
---
 content/docs/protocol/kernel/error-handling.mdx | 16 +++-------------
 1 file changed, 3 insertions(+), 13 deletions(-)

diff --git a/content/docs/protocol/kernel/error-handling.mdx b/content/docs/protocol/kernel/error-handling.mdx
index 1bb2360754..530b221220 100644
--- a/content/docs/protocol/kernel/error-handling.mdx
+++ b/content/docs/protocol/kernel/error-handling.mdx
@@ -418,10 +418,8 @@ never crosses HTTP. The refusal is emitted as the flat body shown above, and
     "code": "RATE_LIMIT_EXCEEDED",
     "message": "Rate limit exceeded",
     "details": {
-      "limit": 1000,
-      "window": "1m",
       "retryAfterSeconds": 45,
-      "quota_reset": "2024-01-16T14:31:00Z"
+      "resetAt": "2024-01-16T14:31:00Z"
     }
   }
 }
@@ -525,12 +523,7 @@ async function fetchWithRetry(url, options = {}, maxRetries = 3) {
   "success": false,
   "error": {
     "code": "SERVICE_UNAVAILABLE",
-    "message": "Service temporarily unavailable",
-    "details": {
-      "reason": "database_maintenance",
-      "retryAfterSeconds": 300,
-      "estimated_completion": "2024-01-16T15:00:00Z"
-    }
+    "message": "Service temporarily unavailable"
   }
 }
 ```
@@ -650,11 +643,8 @@ Content-Type: application/json
     "code": "RATE_LIMIT_EXCEEDED",
     "message": "Rate limit exceeded: 1000 requests per minute",
     "details": {
-      "limit": 1000,
-      "window": "1m",
       "retryAfterSeconds": 45,
-      "quota_reset": "2024-01-16T14:31:00Z",
-      "upgrade_url": "https://app.acme.com/billing/upgrade"
+      "resetAt": "2024-01-16T14:31:00Z"
     },
     "requestId": "req_ghi789",
     "timestamp": "2024-01-16T14:30:15Z"