# Translation Resource Contracts

Audience: AI coding agents first.

- **ID:** IPZ-TRANSLATION-RESOURCE-CONTRACTS-2026-08-14
- **Status:** IDLE
- **Task:** Translation resource contract extraction
- **Source request:** Identify, isolate, and land only dormant shared translation-resource contracts required by `SiteContentTranslationResourceHandler`.

## Outcome

Add compatible dormant definitions for `TranslationResourceHandler`, `TranslationPayload`, and `FinalizeResult`, with exact focused contract tests. No handler implementation, dispatch or finalization behavior, registration, routes, hooks, writes, UI, or activation changes.

## Acceptance Criteria

- Contract signatures exactly match read-only preserved source and satisfy `SiteContentTranslationResourceHandler` requirements.
- `TranslationPayload` and `FinalizeResult` validate invalid construction state and reject mutation while preserving canonical read access.
- Contract filenames meet the project PSR-4 autoload convention; the candidate-aware PHPCS gate exempts `WordPress.Files.FileName` via `phpcs.xml.dist`, so no suppression or baseline entry is needed.
- `TranslationResourceHandler` uses snake_case parameter names without PHPCS suppressions; PHP parameter names are not part of its type signature and no current consumer uses named arguments.
- Payload/result fields are public readonly properties, replacing magic read/write APIs; callers retain canonical property reads and mutation fails natively.
- Only three contract definitions, matching focused tests, and this plan/index change.
- `TranslationResult` remains unchanged because its existing target definition directly satisfies the interface type reference.
- Focused PHPUnit, PHP syntax, candidate-aware PHPCS/PHPStan, `git diff --check`, and commit hooks pass without unaddressed signals.

## Preserved WIP

Read-only source: `/home/user/Projects/Press.zone/wordpress/wp-content/.worktrees/remaining-release-orchestration`.

## Execution

1. Read source contracts, handler, every consumer, tests, Composer PSR-4 autoload, naming convention, and candidate gate.
2. Make `TranslationPayload` and `FinalizeResult` immutable; validate trust-boundary state without normalizing preserved values.
3. Add focused negative and mutation tests.
4. Run syntax, focused PHPUnit, exact/candidate-aware PHPCS, PHPStan, `git diff --check`, and commit hook.
5. Amend `df33872667de88f0816ac630f91bdc05d6d0b148`.

## Current Receipt

Blocker A root: `TranslationFinalizerJobIdentityStandaloneTest` came from the preserved `Bind finalization to canonical jobs` commit and expects an experimental `resource_handlers` property. Current `origin/master` production `TranslationFinalizer` never has that property and finalizes canonical database jobs directly. The stale test fails before it can observe an invariant and requires runtime dependencies outside this contract slice; no test-only correction can preserve meaningful coverage within owned scope. Baseline proof: current and `origin/master` both have zero `resource_handlers` references, while preserved source has the removed property. It is unrelated to this commit and remains unmodified.

Blocker B root: `TranslationResourceHandler` carried obsolete camelCase public parameter names with inline PHPCS suppressions. Renamed parameters to snake_case; PHP interface compatibility is type/signature based, and no current consumer uses named arguments. All suppressions removed.

Intelephense root: private fields were accessed only through `__get`; `__set` parameters were intentionally unused. Replaced magic mutation/access APIs with public readonly constructor-promoted fields. Canonical reads remain compatible; native readonly errors enforce immutability.

PHPCS blocker reproduction found 32 errors and 3 warnings in the focused test: file/class/method docblocks, namespace form, `ABSPATH`/`WP_Error` test stubs, camelCase parameters, and array alignment. Removed global namespace/stub declarations, uses the existing test bootstrap, added compliant test docblocks and snake_case parameters, and lazily aliases an anonymous local WP error contract only for the two error assertions. Test behavior remains 12 tests and 23 assertions. Passed: syntax for all four owned PHP files; focused PHPUnit (12 tests, 23 assertions); exact PHPCS for all three contracts plus test; candidate-aware `php tools/phpcs-baseline.php check` with all four paths; PHPStan using `phpstan.neon.dist`; `git diff --check`. No suppressions, baselines, or warning-ignore entries added. Standalone finalizer baseline proof: exact `origin/master` test `tests/unit/Translation/TranslationFinalizerJobIdentityStandaloneTest.php` fataled with `Property InternationalPressZone\Translation\TranslationFinalizer::$resource_handlers does not exist` at line 69. It is pre-existing and unrelated; runtime remains unmodified. Candidate is rebased unnecessary: `origin/master` is not an ancestor of this deliberately isolated slice. Pending amend after plan receipt update.

## Next Executable Action

None. Amended contract slice is clean; stale standalone finalizer test remains a separate baseline repair.