[sidneyswift]

Shared Context HTTP and MCP operations currently collapse failures into a blanket 409 or fixed message. This candidate returns authored code, retryable and action-aware guidance consistently across both transports while preserving HTTP error, MCP message/success: false, and MCP isError: true.

Draft and held for Docs #31 native/content acceptance and release order. Docs31 remains pinned to b09baf719f09249e2d65b391167fcddd1df05c1b; its protected-preview/native gate is unchanged. This PR must remain unmerged until that acceptance and ordering are resolved. Legacy docs-legacy#361 does not satisfy the prerequisite. Source-only progress toward recoupable/app#2125, without hosted/account/workspace acceptance.

Supersedes the bounded typed-error work of #1005. Current source includes main f38a86bf36f9691e1e84da13725835196d9634dc through a normal merge retaining candidate 4977dce3fe6320031bf09209d83240e85b2005de as first parent. All accepted main changes are preserved; the README retains both appended sections. Two newer ownership fixtures use the exact authored denial message with private details in cause, preserving conservative unknown-error classification.

• Nine codes map to 403/404/409/422/503/402/500; budget exhaustion is reserved, with no spend-path producer or assertion that nothing was charged.
• Exact, separate API/storage message allowlists replace broad substring inference. Stored Zod shape failures remain internal; generic SQL no-row errors remain opaque storage failures without lookup provenance. Unknown storage rejection is non-retryable, not proof of caller conflict. Recognized transient messages are retry-eligible; disabled capabilities require availability before retry.
• No raw exception/cause/identifier logging. Existing enum-only diagnostic logging, private/no-store headers, authorization, delegated OAuth catalog exclusion and material-evidence policy remain unchanged.
• Read/list/plan/verify guidance does not require write keys. Uncertain writes retain their key and unchanged input; attachments retain exact source version/targets. Existing RPC/execution paths still own idempotency. Partial successful results remain successful.

Validation: 380 integrated tests pass across 14 focused suites, including typed transports/classification/published examples and the newer ownership, guest-routing and terminal-workflow regressions. Scoped TypeScript, ESLint, formatting and diff checks pass. Independent merged-source review PASS. No whole-repository typecheck or runtime acceptance claim.

All six Docs31-bound pure module files remain byte-identical to 4977dce3 and match the existing Docs fixture hashes. No contract or Docs fixture changed. The Docs checker still requires exact HEAD 4977dce3; this source-byte compatibility proof does not bypass that checker or satisfy native/content acceptance.

Required Docs changes: current Context OpenAPI error schema and status responses; HTTP/MCP envelopes; operation-level unsupported URL descriptions (422 where applicable, retaining schema 400); conditional retry guidance; URL-only/reconnect/partial examples; explicit auth/schema exceptions, conservative stored-data classification, reserved budget status and no paid-work guarantees. Details in the pending-contract README section.

No action/schema/migration/provider implementation, database operation, build, server, browser, login, credentials or production data access. Guest endpoint behavior is unchanged. Merge and hosted qualification remain separate.

---

Summary by cubic

Replaces the blanket 409/fixed-message Context failures with authored code, retryable, and guidance errors that are identical across HTTP and MCP, while preserving existing HTTP error, MCP message/success: false, and isError: true fields.

This is a source-only draft held for the owning Docs contract; legacy docs-legacy#361 does not satisfy the prerequisite and the current contract must be accepted before merging. Supersedes the typed-error work in #1005.

Error contract

• Nine codes map to 403/404/409/422/503/402/500; budget_exhausted is reserved with no spend-path producer.
• Classification uses exact API and storage message allowlists; unknown API messages are internal, unknown storage rejections are opaque storage_failed, and disabled capabilities return 503 unavailable with contract examples aligned.
• Stored-data schema failures and generic SQL no-row errors remain internal/opaque without lookup provenance.
• Retry guidance is action-aware: read/list/plan/verify never asks for a write key; uncertain writes keep the same key and unchanged input; attachment retries keep exact source version and targets.
• No raw exception messages, causes, or identifiers are returned or logged; existing enum-only diagnostics and private/no-store headers are unchanged.

^{Written for commit 4977dce. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
api	Ready	Preview	Nov 2, 2026 8:54pm UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn