# Block Template Translation Adapter

Audience: AI coding agents first.

- **ID:** IPZ-BLOCK-TEMPLATE-TRANSLATION-ADAPTER-2026-08-14
- **Status:** ACTIVE
- **Task:** #81 / SC-ADAPTER-01
- **Source request:** Continue dormant Site Content in dependency order after publishing Task #80: repository, block-template translation adapter, then translation resource-handler integration. Keep every slice unreachable until later runtime/API/UI work.
- **Execution owner:** Current isolated worktree session.
- **Blocker limit:** One complete preserved-to-published contract comparison and 45 minutes. Stop on an incompatible final-class test seam or unavailable deterministic gate; NEVER alter published dependencies, runtime bootstrap, test configuration, or delivery infrastructure.

## Outcome

Publish dormant `BlockTemplateTranslationAdapter` library code that applies ready, current Site Content overlays to `wp_template` and `wp_template_part` objects only for an eligible request context. Add no bootstrap registration or visible behavior.

## Dependencies

Consume unchanged published `SiteContentRequestContext`, `SiteContentCatalog`, `SiteContentRepository`, `SiteEntityIdentity`, and `BlockSegmentCodec`. Task #80 repository, Task #83 canonical request-context validation, and the separate package-verification hardening prerequisite are published on `origin/master`.

## Acceptance

- Accept only `wp_template` and `wp_template_part` identities.
- Always return a clone. NEVER mutate supplied or cached `WP_Block_Template` instances.
- Deny overlays when request context does not permit one or requested language differs from context language.
- Resolve source from current catalog. Missing identity/source MUST return the unchanged clone.
- Require active `ready` translation with matching source revision; stale, missing, malformed, oversized, or codec-failed data MUST return current catalog source.
- Accept only valid JSON lists of translation segment arrays. Maximum payload: 1 MiB. Maximum translated segments: 1,000.
- Cache by identity, target language, source revision, positive translation revision, and request-context key. Return a fresh clone on every call.
- Bound diagnostics to reason, entity type/key, and language. NEVER expose content, translated segments, provider data, database errors, or exception details.
- No route, endpoint, hook registration, construction, dispatch/finalization registration, scheduled work, feature flag, UI, write path, runtime consumer, or visible behavior.

## Allowed paths

- `plugins/international-press-zone/includes/SiteContent/class-blocktemplatetranslationadapter.php`
- `plugins/international-press-zone/includes/SiteContent/class-sitecontentcatalog.php` — complete template-type snapshot seam required to prevent repeated full scans.
- `plugins/international-press-zone/tests/Unit/SiteContent/BlockTemplateTranslationAdapterTest.php`
- Adapter-only fixtures under `plugins/international-press-zone/tests/Fixtures/SiteContent/`
- This plan, `docs/plans/2026-08-14-ipz-delivery-and-site-content-continuation.md`, and both plan indexes.

## Execution

1. Reconcile implementation against current published dependency contracts.
2. Run syntax, focused PHPUnit, direct uncached and candidate-aware PHPCS, PHPStan, `git diff --check`, and dormant-consumer search.
3. Obtain independent adversarial correctness and security review; repair confirmed Task #81 findings only.
4. Commit and publish through repository delivery controller. Record exact publication proof.

## Rollback

Revert adapter, focused test, and adapter-only fixtures together. Keep published Site Content schema, domain contracts, request contexts, catalog, and repository unchanged. No data rollback or feature flag applies because this slice has no runtime effect.

## Current receipt

Implementation remains dormant. It uses published snake_case APIs, clone-safe output, fail-closed catalog fallback, untrusted template-property checks, bounded diagnostics, a 1 MiB payload cap, and a 1,000-segment cap. Focused fixtures avoid broad PHPCS suppression and record required seam inputs. Before synchronization, focused adapter PHPUnit passed 13 tests / 50 assertions and focused catalog PHPUnit passed 7 tests / 28 assertions. Syntax, direct uncached and candidate-aware PHPCS, PHPStan, `git diff --check`, and dormancy checks passed without warnings. Independent correctness and security reviews approved the candidate after repairs for malformed identity handling, payload and segment limits, repeated whole-catalog parsing, and bounded diagnostics. No WordPress site was contacted.

A concurrent smaller adapter implementation reached `origin/master` during serialized publication. Conflict review rejected it because it omitted payload and segment limits, accepted decoded arrays instead of the repository JSON contract, repeated catalog scans, exposed premature filter APIs, and lacked most fail-closed coverage. The reviewed candidate retains the complete per-template-type snapshot seam and stronger focused tests. Final conflict review also found that integer translation revisions could be zero or negative; validation and a focused regression now require every revision to be positive. Independent security review then reproduced a diagnostic-hook exception escaping fail-closed resolution; `diagnose()` now contains callback failures, and its failure-first regression passes. Focused adapter PHPUnit passes 14 tests / 53 assertions. Direct and candidate-aware PHPCS, PHPStan, `git diff --check`, and dormancy checks are clean. Independent security re-review approved the repaired candidate with no remaining blocking correctness or security findings.

## Next executable action

Amend the approved candidate and rerun the repository delivery controller.