Cloud 0.2.5: public failure sanitizer

Cloud patch release @timazed/codexkit@0.2.5, distributed through GitHub Packages. Swift's version is unchanged.

Public failure normalization

Export sanitizeCodexFailure(value: unknown): SanitizedCodexFailure | undefined for parsed, flat serialized SDK failures, including CodexKitCloudError.toJSON() and JSON round trips. A recognized SDK code returns a fresh explicitly allowlisted object; missing/unknown codes return undefined, and invalid optional diagnostics are omitted. Messages always regenerate from static SDK labels.

The sanitizer shares the SDK's category, parameter, identifier, Retry-After and image reset validators with error construction and serialization. It is synchronous, deterministic for JSON data, non-mutating, and independent of network access or credentials. Optional diagnostics retain their public names. requestId continues to mean the provider request ID.

Manual and stream-terminal failures now also omit unknown optional categories and unsupported correlation formats. Existing SDK error codes, requests, models, retries, and successful results are unchanged.

Consumer migration

Pin the exact version in a separately authorized application change:

npm install --save-exact @timazed/codexkit@0.2.5

Replace mp-api's duplicate SDK validation with one call while retaining its own field projection and fallback:

import { sanitizeCodexFailure, type SanitizedCodexFailure } from "@timazed/codexkit";

function parseStoredFailure(stored: unknown) {
  const safe: SanitizedCodexFailure | undefined = sanitizeCodexFailure(stored);
  return safe ? projectApplicationFields(safe) : applicationFailureFallback();
}

The projection and fallback above are application-owned placeholders. See the contract and sanitized JSON example and compiled projection example.

Persisted JSON remains untrusted. Without original request/credential context, format validation cannot identify private values disguised as valid provider IDs or recover missing diagnostics. Applications with insufficient historical provenance can omit IDs in their projection. Application-specific codes, job persistence, API envelopes and consuming HTTP request IDs remain outside the SDK.

Verification

• 253 offline Cloud tests, including HTTP 400 fixtures through actual text/image SDK execution, JSON round trips, legacy failures, unsafe fields and values, static messages, idempotence/immutability, stream and image-quota failures, and unchanged success paths.
• Packed CommonJS/ESM imports and strict TypeScript CommonJS/NodeNext consumers, including the migration example.
• Shared source-size check (356 production files) and 46 verification-harness tests.
• Cloud CI runs the package suite on Node 22 and 24. Cloud Release installs this exact published version and checks CommonJS/ESM client and sanitizer exports against GitHub Packages.

Verification links: merged PR #21, main repository CI, main Cloud CI, and Cloud Release / published-registry checks.

This release does not change or deploy mp-api, replay production jobs, or establish/fix the original generation defect.