Merge pull request #542 from ndycode/claude/audit-24-error-contracts-request

docs(errors): record typed-error adoption in the contracts reference

Author: ndycode

docs/reference/error-contracts.md

@@ -62,6 +62,14 @@ Compatibility guarantees:
 - Error responses are normalized to JSON error payloads with a stable `error.message` field.
 - Diagnostics may include request/correlation IDs when available.
 
+### Typed Errors
+
+The request layer's thrown errors are backed by the typed hierarchy in `lib/errors.ts` (base class `CodexError`, which extends `Error` and carries a stable `code` string):
+
+- `refreshAndUpdateToken` throws `CodexAuthError` (`code: "CODEX_AUTH_ERROR"`) with the message `Failed to refresh token, authentication required` on any refresh failure. The error carries a `retryable` boolean (transient network/lock failures are retryable; invalid-grant style failures are not) and, where available, `cause` and `context` (`refreshFailureReason`, `statusCode`).
+- Catch sites may rely on `instanceof CodexAuthError` (or the structural `code` property) plus `retryable` to decide whether to re-attempt or force re-authentication.
+- HTTP error responses are returned as normalized `Response` payloads (see above), not thrown, so they intentionally have no `Error` class.
+
 ---
 
 ## Runtime Rotation Proxy Error Contract
@@ -94,6 +102,8 @@ Supported dual-call forms include:
 - `getRateLimitBackoffWithReason(...)` and `getRateLimitBackoffWithReason({ ... })`
 - `transformRequestBody(...)` and `transformRequestBody({ ... })`
 
+Invalid named-parameter calls (missing or wrongly typed required fields, or unknown keys) throw a native `TypeError` with a `<helper> requires ...` message — for example, `createCodexHeaders` throws `TypeError: createCodexHeaders requires accountId and accessToken`. This is a deliberate, shared convention across the dual-call helpers and is not wrapped in a `CodexError` subclass.
+
 ---
 
 ## Related

lib/request/token-refresh.ts

@@ -90,6 +90,16 @@ function isRetryableAuthSetterError(error: unknown): boolean {
 
 /**
  * Refreshes the OAuth token and updates stored credentials
+ *
+ * Mutation contract: on success the passed `currentAuth` object is updated
+ * IN PLACE (access/refresh/expires) after the persistence await, and the same
+ * reference is returned. Same-account refreshes are serialized by
+ * `queuedRefresh`, so two concurrent calls for one account coalesce rather
+ * than race; callers must still not share one Auth object across calls for
+ * DIFFERENT accounts, and must not read token fields from a shared reference
+ * while a refresh for it is in flight (the window between the persistence
+ * await and the mutation block exposes the pre-refresh values).
+ *
  * @param currentAuth - Current auth state
  * @param client - Codex client for updating stored credentials
  * @returns Updated auth (throws on failure)