Deferred AJAX contract

Bounded candidate reference — 2026-10-20: 0.2.0-rc.1 is committed locally through 84f415b3098af5653577b2c65eea31fca21df79c, unpublished and not production-approved; stable PHP >=8.5.11 <8.6.0 is required. This is documentation, not adoption: this knowledge base retains its installed 0.1.0-rc.1 dependency and PHP 8.2.11 local profile. Dated PHP 8.2 evidence is historical; earlier dirty-source reports retain their original test provenance, not retroactive clean-commit proof. Candidate examples are illustrative: API signatures were reviewed, but candidate code was not executed by this editorial update. See current checkpoint, open criteria and adoption boundary.

Status

DEFERRED — reference contract only. No AJAX JavaScript, DOM replacement runtime, or AJAX-specific server module is implemented in this extraction. The core can already read JSON/form/multipart requests and return JSON, but that does not constitute the feature described below. Adoption requires a separate approved implementation and browser test phase.

Proposed opt-in contract

Enhancement would apply only to elements explicitly marked by an application, for example data-ajax. Ordinary links/forms must retain normal navigation and submission. The client would construct requests from the element method/action, preserve FormData for multipart/file forms, use JSON only when the endpoint declares it, send Accept: application/json, and include CSRF headers from a document-owned current token.

A proposed success envelope is:

{
  "success": true,
  "message": "Optional safe summary",
  "data": {},
  "html": "Optional application-rendered fragment",
  "destination": "/optional-safe-path",
  "csrf": "optional-rotated-token"
}

A proposed failure envelope is:

{
  "success": false,
  "message": "Safe user-facing summary",
  "errors": { "field": ["Validation message"] },
  "csrf": "optional-rotated-token"
}

Expected statuses: 200/201 for represented success, 204 for no body, 303 for normal form fallback, 400 malformed input, 401 unauthenticated, 403 forbidden, 409 state conflict, 419 stale CSRF, 422 validation, 429 rate limited, and 500 safe server failure. Validation must be application-owned and errors keyed by stable field names.

Proposed browser behavior

• Retrieve destination only from a same-origin validated response/header.
• Replace only an explicitly targeted container; parse response safely and do not execute arbitrary returned scripts.
• Update document.title, history.pushState, and focus after successful page replacement; popstate must restore/refetch a canonical URL.
• Replace the current CSRF token when a response supplies a rotated value.
• Mark the initiating control busy/disabled, expose progress through ARIA, and restore it in every completion/failure path.
• On 401, preserve a safe return path and perform normal authentication navigation. On 419, refresh once only when an application endpoint explicitly supports token refresh; otherwise show a safe retry instruction.
• Do not automatically retry unsafe requests. GET may use bounded retry with backoff. POST retries require an application idempotency key and server-side idempotency contract.
• Network/parse failures fall back to ordinary navigation/submission when it is safe and no mutation may already have completed; otherwise show an explicit uncertain-state message.

Verification required before implementation may be called supported

Browser tests must cover opt-in/out, link/form/multipart/JSON bodies, envelope validation, all status branches, same-origin destinations, DOM/title/history, popstate, CSRF rotation, focus/busy/ARIA, session failure, retry/idempotency, double submission, malformed JSON, and ordinary non-JavaScript fallback.

Editorial provenance

Source: docs/AJAX_CONTRACT.md. Source SHA-256: 60281b97aed457a70a9f0d0290c504d364f9db561f36700659775ab5a993f7de.

Framework candidate reference; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.