feat: establish versioned UI translation ledger foundation

[seonghobae]

Scope / owner boundary

PostgreSQL-authoritative versioned UI translation ledger for #922 plus the first authenticated translation API slice. LineageWeave owns product UI copy/presentation read-model behavior only; ontology/concept labels and semantic truth remain with canonical owners. Product contract: ko/en/ja/zh/vi/es/de/fr, exact screen-key completeness, immutable published versions, no cross-locale fallback, product/screen/version/locale cache identity.

Current product lineage

Ledger rollback/publication/TRUNCATE, immutable projection, cache-integrity, typed validation, optional-cache timeout, independent real-wire recursion evidence, and exact-version cache query-budget repairs remain adopted. The valid-hit path uses PostgreSQL digest/key-set admission without transferring the full localized projection; true cache misses use one complete authoritative PostgreSQL projection after bounded Valkey I/O. Synthetic RecursionError injection remains supplemental only.

Current exact head is 2a8ed5d02f4a3082b346d923d754c1ff37ebff52. Its latest intervening delta is test-quality cleanup only: direct dependency-override callables, narrower Exception capture, awaited task-result consumption, and documented best-effort teardown. No ledger/API/DB semantic authority changed.

Protected main remains 83eba56149eb802cd63642c507c324c9976ec78e; this branch contains that line and stays open/Ready/mechanically mergeable. Ready is validation admission only.

Exact-head verification

• Tests 33943899031: success
• PROV-O 33943898948: success
• Ontology Pages 33943898956: success
• SAST 33943899021: success
• coverage-source-tree 101308656500: success
• coverage-evidence 101321891041: success
• Security 33943898985: failure only at central Dependency Review support preflight 101279669944; exact checkout succeeded and OSV/Trivy/Scorecard succeeded, but they are not substitutes
• CodeQL 33943899007: failure after successful exact-head shard dispatch with no authenticated terminal codeql-dispatch/<language> verdict
• required opencode-review check 101333611414: failure after successfully validating live PR/head, obtaining GitHub OIDC and a repository-scoped OpenCode App token, and POSTing the canonical opencode-review repository dispatch; the leaf check then found no current-head APPROVED/CHANGES_REQUESTED receipt and failed closed as designed
• qualifying independent exact-head approval: none

The previous body’s coverage-source-tree queued statement is obsolete; it is now terminal GREEN. The remaining model-backed failures are not LineageWeave-local provider implementations. Canonical owner evidence identifies the shared dispatch authorization defect: trusted OpenCode dispatches use opencode-agent[bot], while the organization variable still admits only github-actions[bot]. .github#1932 already merged uniform comma-separated allowlist parsing; .github#1927 remains open for the owner/admin variable update to github-actions[bot],opencode-agent[bot]. .github#1902 remains Draft for evidence-driven redispatch after pre-runner/failed earlier attempts. Do not churn this leaf head, substitute a local provider, or synthesize review/status receipts.

The repeated Dependency Review HTTP-403/support incident remains owned by ContextualWisdomLab/.github#810; no local scanner replaces that required gate.

Remaining #922 buyer work

This ledger/API is foundation, not completion of the material UI. After normal landing, a real material screen must consume a published eight-locale resource with reviewed product copy. Acceptance still requires normal/loading/empty/error/permission/responsive states, keyboard/focus/screen-reader behavior, CJK/text expansion/font fallback, and fresh desktop/mobile browser evidence on one exact head. PRD/TRD/ARCHITECTURE/UX/OPERABILITY/TEST_STRATEGY/CHANGELOG and docs/product-technical-gap-baseline.md must converge with that cutover.

Direct descendant #932 remains Draft on this exact parent, but its secondary-auth RED is no longer pending. Isolated run 33999658012 completed GREEN and the verified clean tree was promoted non-force as #932 product head 846ec4700666188a281940b99ac4edf776e904ca. That child clears Customer Master secondary projections on token transition and rejects stale async completions by captured-token identity. #932 still lacks fresh full required exact-product-head/browser/a11y evidence and independent approval; none of its GREEN or product evidence transfers to this parent.

Do not self-approve, force-push, bypass product gates, weaken evidence, or transfer predecessor/child check or review results.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

8개 로케일 번역 원장과 읽기 경로를 추가했습니다. 인증된 HTTP 조회, 캐시 검증과 폴백, 게시 후 변경 차단, TRUNCATE 가드, 롤백 경로, 기준선 문서와 검증 테스트도 갱신했습니다.

Changes

UI 번역 원장

Layer / File(s)	Summary
원장 스키마와 게시 계약 docs/adr/0362-versioned-ui-translation-ledger.md, migrations/0246_ui_translation_ledger.sql, tests/test_translation_ledger_contract.py, tests/test_translation_ledger_postgres.py, tests/test_translation_ledger_unicode_whitespace.py	8개 로케일, 리소스 identity, 번역 완전성, Unicode 공백 검증, 게시 timestamp와 게시 후 불변성을 정의하고 검증합니다.
번역 읽기 모델과 캐시 검증 backend/app/translation_ledger.py, tests/test_translation_ledger_read_model.py, tests/test_translation_screen_value_object.py, tests/test_translation_ledger_cache_*.py, tests/test_translation_cache_timeout.py, tests/test_translation_exact_version_query_budget.py	캐시 후보가 없으면 단일 PostgreSQL projection을 조회합니다. 후보가 있으면 키와 digest만 검증하고, 실패 시 authoritative projection으로 폴백합니다.
인증된 번역 조회 API backend/app/main.py, tests/test_translation_api_http.py, tests/test_translation_api_driver_boundary.py	인증이 필요한 GET /api/translations/{screen_key}를 제공합니다. 입력 오류는 분리된 422 응답으로, 리소스 없음과 불완전한 번역은 404와 409로 변환합니다.
TRUNCATE 보호와 롤백 검증 migrations/0247_ui_translation_truncate_guard.sql, migrations/rollback/*.sql, tests/test_translation_ledger_rollback*.py, tests/test_translation_ledger_truncate*.py	게시된 원장의 TRUNCATE를 잠금으로 보호합니다. 리소스 존재, 회원 로케일, 롤백 재실행과 동시성 동작을 검증합니다.
기술 기준선과 런타임 지원 docs/product-technical-gap-baseline.md, docs/product-technical-gap-baseline-history-2026-09-04.md, docs/product-technical-gap-baseline-history-2026-09-04.raw.txt, lineageweave/observability.py, pyproject.toml, tests/test_translation_documentation_alignment.py, tests/test_translation_wire_evidence_contract.py	ADR와 기술 기준선을 갱신합니다. 로깅 계측 의존성과 JSON 재귀 소진 증거 검증을 갱신합니다.

Estimated code review effort: 5 (Critical) | ~120 minutes

Merge Risk: 🔵 Low · up to 9a189

This change adds a versioned translation ledger and authenticated read API. Runtime behavior is covered by the supplied contract evidence, but release-status documentation checks can still miss contradictory status text and should be tightened before relying on them for readiness claims.

Sequence Diagram(s)

sequenceDiagram
  participant AuthenticatedClient
  participant FastAPI
  participant translation_ledger
  participant PostgreSQL
  participant Valkey

  AuthenticatedClient->>FastAPI: GET /api/translations/{screen_key}
  FastAPI->>translation_ledger: read_ui_translations(...)
  translation_ledger->>Valkey: exact-version cache candidate
  Valkey-->>translation_ledger: cache payload or miss
  translation_ledger->>PostgreSQL: validate digest / fetch projection
  PostgreSQL-->>translation_ledger: TranslationScreen
  translation_ledger-->>FastAPI: immutable translations
  FastAPI-->>AuthenticatedClient: 200 / 404 / 409 / 422

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 80.56% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 216 functions across 27 files. (1 skipped: …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 버전 관리형 UI 번역 원장 기반을 구축하는 주요 변경 사항을 정확하고 간결하게 설명합니다.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/i18n-versioned-translation-ledger

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Valid finding: the explicit-version Valkey fast path can make a structurally valid but incomplete cache payload authoritative. _decode_cached_screen() validates identity and nonblank values, but it has no independent knowledge of the published resource's required key set. A payload for the exact product/screen/version/locale containing only title therefore bypasses PostgreSQL and returns an incomplete screen, contradicting this PR's fail-closed completeness contract and its statement that PostgreSQL remains authoritative. Add a realistic RED for a correct-identity/partial-key cache payload, then make cache acceptance depend on authoritative published key-set evidence (without cross-locale fallback).

[seonghobae]

Review finding on current head 7df347874ae26b95947be14b0cb97d7789b8d07a: application reads canonicalize product_key and screen_key with .strip(), but migration 0246 only checks btrim(key) <> ''; it does not require btrim(key) = key. PostgreSQL can persist lineageweave and lineageweave as distinct resource identities while the reader/cache boundary collapses both inputs to lineageweave, leaving a padded published resource unreachable through the canonical reader. Repair should make the DB reject leading/trailing whitespace so aggregate, API, and cache identities agree.

[seonghobae]

Review finding on 0e307531d97e71346835dc059f6c3db46956abbc: publication provenance is caller-controlled. guard_ui_translation_resource_mutation() currently does new.published_at := coalesce(new.published_at, now()), so a caller can submit an arbitrary non-null published_at while transitioning a draft to published; the trigger preserves that value and the row becomes immutable. Because publication time is release/audit evidence, the state transition must stamp database time itself rather than admit a caller-supplied timestamp. Add RED coverage for server-owned publication time, then assign now() unconditionally on the publish transition.

[seonghobae]

Application/DB identity semantics are not actually aligned yet. ADR 0362 says leading/trailing-whitespace product_key and screen_key forms are rejected consistently at PostgreSQL and the application boundary, and migration 0246 rejects them with btrim equality. _validate_identity_segment() instead strips caller input and accepts it, so lineageweave aliases lineageweave before DB/cache lookup. That silently normalizes an ambiguous external identity while the persisted aggregate forbids that spelling. Add a RED covering padded product/screen inputs failing before I/O, then make the application boundary reject rather than normalize.