# Translation Attempt Correlation Contract

Audience: AI coding agents first.

- **Plan ID:** `IPZ-TRANSLATION-ATTEMPT-CORRELATION-CONTRACT-2026-08-14`
- **Task:** `#85 / TR-ATTEMPT-01`
- **Status:** IDLE
- **Outcome:** Publish a backward-compatible, dormant attempt-correlation token contract on the translation payload and result DTOs without activating runtime behavior.
- **Source request:** Add optional validated attempt-token state to both translation DTOs, result factories, getter, and serialization, with failure-first contract coverage and no runtime wiring.

## Acceptance criteria

1. `TranslationPayload` and `TranslationResult` accept a trailing optional `?string $attempt_token = null` constructor parameter.
2. `TranslationResult::success()` and `TranslationResult::failure()` accept trailing optional token parameters.
3. Calls that omit tokens remain valid and expose `null`.
4. Every non-null token is exactly 64 lowercase hexadecimal characters; invalid values throw `InvalidArgumentException`.
5. Only the new `TranslationResult::$attempt_token` property is public readonly; every legacy result property remains mutable.
6. `TranslationResult::get_attempt_token()` returns the token, and `to_array()` appends `attempt_token` after every existing key without changing existing key order.
7. Tests cover valid constructor/factory/getter/serialization round trips, null compatibility, malformed short/long/uppercase/whitespace/non-hex values, readonly token reassignment, and mutable legacy properties.
8. Focused PHPUnit, syntax checks, direct uncached PHPCS, candidate-aware baseline PHPCS, focused PHPStan, and `git diff --check` pass without warnings.
9. No generation, persistence, provider authority, callbacks, routes, hooks, jobs, Site Content wiring, feature activation, or WordPress/network request is added.

## Preserved WIP, ref, and path

- **Base ref:** refreshed `origin/master` at `4adee4c6e` after Task #86 publication.
- **Isolated worktree:** `/home/user/Projects/Press.zone/wordpress/wp-content/.claude/worktrees/agent-a3b877c2ac3741eef`.
- **Frozen production/test scope:**
  - `plugins/international-press-zone/includes/Translation/TranslationPayload.php`
  - `plugins/international-press-zone/includes/Translation/TranslationResult.php`
  - `plugins/international-press-zone/tests/Unit/Translation/TranslationResourceContractsTest.php`
- Plan registry edits are required bookkeeping outside frozen code scope.

## Constraints

- Work directly; do not delegate, invoke skills, or use external models.
- Preserve the candidate in one local commit; do not publish it.
- Do not contact WordPress or any network target.
- Preserve every existing parameter order/default, factory behavior, return value, and serialized key/order.
- Do not edit dispatchers, callbacks, persistence, Site Content classes, configuration, baselines, tooling, dependencies, or unrelated files.

## Execution steps

1. Verify Task #86 publication receipts and direct PHPCS on `TranslationResult.php`.
2. Add failure-first tests for the complete attempt-token contract.
3. Implement the minimal DTO changes.
4. Run every required focused verification and resolve all in-scope findings.
5. Record exact results, changed files, diff stat, receipts, blockers, and final status.

## Current receipt

- GitHub `origin/master` was refreshed to `4adee4c6e`; Task #86 implementation `25b4110d01358cfd184d0458aea53f09df8800f9`, controller receipt `7d5d6f47b690ebd5144bcb50b89c275f54589cfa`, normalization `fb13f6e9df012be96f834a7d300659ae24d92f75`, and normalization controller receipt `4adee4c6e` are published.
- Task #85 final rebased candidate commit `1eb3ce56c5bfb848e5eeb8a97d064fae26b2835c` retains upstream Task #86 formatting and plan records while integrating only attempt-token semantics, tests, and plan entries.
- Failure-first receipt: 20 tests ran; the new contract produced 3 errors and 5 failures before implementation. A temporary ignored vendor symlink was needed because isolated worktrees do not carry dependencies; the first attempt exposed this environment issue and was corrected without source/config changes.
- Final focused PHPUnit: `OK (20 tests, 59 assertions)` with no warnings.
- Final PHP syntax: all three changed PHP files report no syntax errors.
- Final direct uncached PHPCS: exit 0 with no output for all three changed PHP files after correcting six attempt-token documentation alignment errors found by the first rebased run.
- Final candidate-aware baseline PHPCS: exit 0 with no output for all three changed PHP files.
- Final focused PHPStan: `[OK] No errors` for both DTOs.
- Final `git diff --check`: exit 0 with no output.
- Independent correctness review: **APPROVED**.
- Independent adversarial security/correctness review: **APPROVED**.
- Nullable attempt tokens are compatibility plumbing only. No consumer treats token presence, absence, or value as authority.
- Task #84 remains blocked until non-null attempt tokens are persisted and enforced for replay protection.
- Diff against refreshed `origin/master` contains only the six Task #85 files and preserves every upstream plan.
- No WordPress/application network request, runtime wiring, persistence, callback, route, hook, job, provider authority, or feature activation was created.

## Next executable action

Immediate controller publication of the approved Task #85 candidate.