# Site Content Translation Resource Handler

Audience: AI coding agents first.

- **ID:** IPZ-SITE-CONTENT-TRANSLATION-RESOURCE-HANDLER-2026-08-14
- **Status:** DONE
- **Task:** SC-HANDLER-01
- **Source request:** Complete every remaining multilingual Site Content slice through session end. Synced-pattern resolution is published; recover the next dependency-correct dormant resource-handler slice without duplicating old work.
- **Execution owner:** Current main coordinator only; no implementation delegation.

## Outcome

Publish a dormant `SiteContentTranslationResourceHandler` implementing `TranslationResourceHandler` for exact `site_content`. Prepare bounded segmented provider payloads from current catalog source and atomically finalize reviewed results through persisted attempt authority. Add no construction, registration, route, job, UI, or visible behavior.

## Acceptance

- `supports(string $content_type): bool` accepts only exact `site_content`.
- `prepare(int $content_id, string $target_language): TranslationPayload|WP_Error` treats `content_id` as a Site Content translation-row ID.
- Resolve an active exact-language row and current canonical source through `SiteContentRepository`, `SiteContentCatalog::lookup_source()`, and `BlockSegmentCodec`.
- Validate exact canonical identity, language, source revision, positive translation revision, bounded current source, payload size at most 1 MiB, at most 1,000 exact ordered segments, per-segment text, total characters, and exact JSON object/list shape.
- Generate a cryptographically random attempt token only after all preparation validation. Begin translation only through token-bound repository compare-and-swap.
- `finalize()` requires the exact authenticated attempt. Provider failure consumes only that attempt through `mark_failed()` without fallible live-source lookup. Stale callbacks never consume newer attempts.
- Successful finalization re-resolves current source, validates exact provider languages/resource/segment IDs/order/context/types, compiles through `BlockSegmentCodec::apply()`, and saves only through token-bound `save_review()`.
- Authenticated malformed result or codec failure consumes only that attempt and returns a bounded error. Pre-authentication validation never writes.
- Errors expose no source, translated content, token, database detail, or exception text.
- Preserve PHP 8.0 and WordPress 6.0 compatibility. No `array_is_list()`.
- Focused tests cover support; preparation/finalization; malformed/missing/inactive/mismatched/stale state; source lookup and codec failures; payload/count/character limits; exact JSON shape/types/order/context; attempt correlation; provider failure; compare-and-swap failures; safe errors; and zero writes before validation.
- Add no bootstrap registration, handler construction, dispatcher/finalizer registration, route, hook, schedule, feature activation, UI, runtime consumer, migration, or WordPress request.
- Run every applicable test, lint, static-analysis, security, smoke, diagnostic, and related gate only through canonical remote execution on registry-selected `debian1`/`debian2`/`debian3`. Never run a local gate or fallback.

## Preserved WIP / ref / path

- Active worktree: `/home/user/Projects/Press.zone/wordpress/wp-content/.worktrees/site-content-handler-recovery`
- Branch: `wt/site-content-handler-recovery`
- Exact base: `4681d9e07e6b2b9fec8a3897b2efcc1d9e2f25ba`
- Preserved candidate worktree: `/home/user/Projects/Press.zone/wordpress/wp-content/.worktrees/task-84-site-content-handler`
- Preserved candidate commits: implementation `8b3fcec80`; umbrella receipt `8e238100d`.
- Recover candidate semantics, fixtures, and tests. Do not overwrite newer published catalog, codec, adapter, fixture, or plan-index work wholesale.

## Allowed paths

- `includes/Translation/SiteContentTranslationResourceHandler.php`
- handler-only fixtures under `tests/Fixtures/Translation/`
- `tests/Unit/Translation/SiteContentTranslationResourceHandlerTest.php`
- `phpunit.xml.dist` only if normal-suite registration is valid and warning-free
- this plan, `docs/plans/INDEX.md`, and `2026-08-09-multilingual-site-entry-and-layout.md`
- Existing catalog/codec/adapter sources or tests only for a proven missing prerequisite not already present on current master; record and verify any such expansion before editing.
- Proven prerequisite expansion: `includes/SiteContent/class-blocksegmentcodec.php`. Current master uses PHP 8.1-only `array_is_list()` in both translation-list paths, so handler finalization would fail on supported PHP 8.0. Restore the codec-local exact-list helper already verified in preserved Task #84; make no other codec change.

## Execution

1. Compare preserved candidate prerequisites and contracts against exact current master.
2. Recover only the handler, focused fixtures/tests, and any proven minimal prerequisite delta.
3. Correct stale assumptions, PHP compatibility, suite composition, and warning behavior before claiming reuse.
4. Run focused and full applicable gates remotely only; address every signal.
5. Review correctness/security directly; rerun affected remote gates.
6. Normal-commit through installed warning-free enforcement, land, fetch, verify exact `origin/master`, and prove dormancy remotely.
7. Publish final receipt and continue the next uncovered multilingual slice.

## Current receipt

Implementation commit `097a5f64b078078896f88de326278d2101263094` passed mandatory exact-tree remote pre-commit enforcement: PHPCS, PHPStan, and slopgate completed on registry-selected Debian infrastructure; focused PHPUnit had already passed `28 tests, 119 assertions`. The serialized isolated publisher merged that exact commit with then-current `origin/master` and published merge `aa56fce307a2c02aa34f36c37b5ef006755ea34f` with tree `2349585a8fd2d982cf5307b317a633253f58a4c8`. A final merged-candidate focused PHPUnit gate ran remotely before publication. Fresh fetch proves `097a5f64b` is an ancestor of exact `origin/master`. Remote dormancy proof on registry-selected `debian2` found exactly one production reference—the handler declaration itself—and one test reference; no runtime construction or registration exists.

The candidate remains standalone in PHPUnit because current shared fixtures still collide on `wp_is_block_theme()` when composed. The broad registered suite’s pre-existing duplicate REST-support warning is unchanged and outside this slice; this plan added no warning suppression or suite-wide fixture churn.

## Next executable action

None. Continue through `2026-08-15-segmented-site-content-backend.md`; do not reopen this published dormant slice unless a current-contract regression is reproduced.