feat: establish versioned UI translation ledger foundation - #929
feat: establish versioned UI translation ledger foundation#929seonghobae wants to merge 188 commits into
Conversation
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthrough8개 로케일 번역 원장과 읽기 경로를 추가했습니다. 인증된 HTTP 조회, 캐시 검증과 폴백, 게시 후 변경 차단, TRUNCATE 가드, 롤백 경로, 기준선 문서와 검증 테스트도 갱신했습니다. ChangesUI 번역 원장
Estimated code review effort: 5 (Critical) | ~120 minutes Merge Risk: 🔵 Low · up to 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
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
seonghobae
left a comment
seonghobae
left a comment
There was a problem hiding this comment.
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).
|
Review finding on current head |
|
Review finding on |
seonghobae
left a comment
seonghobae
left a comment
There was a problem hiding this comment.
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.
seonghobae
added
enhancement
ChatGPT Codex Connector
Record current protected main, ready/draft split, pending hosted jobs, and the leftover-pair a11y single-writer wait without claiming independent review or terminal GREEN.
![opencode-agent[bot]](https://avatars.githubusercontent.com/in/1549082?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
OpenCode reviewed the current-head product diff. Coverage is a separate gate.
Changed files
backend/app/main.py— API and service runtimebackend/app/translation_ledger.py— API and service runtimedocs/adr/0362-versioned-ui-translation-ledger.md— operator or user guidancedocs/product-technical-gap-baseline-history-2026-09-04.md— operator or user guidancedocs/product-technical-gap-baseline-history-2026-09-04.raw.txt— operator or user guidancedocs/product-technical-gap-baseline.md— operator or user guidancelineageweave/observability.py— Python module behaviormigrations/0246_ui_translation_ledger.sql— repository behaviormigrations/0247_ui_translation_truncate_guard.sql— repository behaviormigrations/rollback/0246_ui_translation_ledger.sql— repository behaviormigrations/rollback/0247_ui_translation_truncate_guard.sql— repository behaviorpyproject.toml— repository behaviortests/test_translation_api_driver_boundary.py— regression suitetests/test_translation_api_http.py— regression suitetests/test_translation_cache_recursion_real_payload.py— regression suitetests/test_translation_cache_timeout.py— regression suitetests/test_translation_documentation_alignment.py— regression suitetests/test_translation_exact_version_query_budget.py— regression suitetests/test_translation_ledger_cache_duplicate_members.py— regression suitetests/test_translation_ledger_cache_recursion.py— regression suitetests/test_translation_ledger_cache_surrogate.py— regression suitetests/test_translation_ledger_cache_version_type.py— regression suitetests/test_translation_ledger_contract.py— regression suitetests/test_translation_ledger_identity_type.py— regression suitetests/test_translation_ledger_postgres.py— regression suitetests/test_translation_ledger_read_model.py— regression suitetests/test_translation_ledger_resource_version.py— regression suitetests/test_translation_ledger_rollback.py— regression suitetests/test_translation_ledger_rollback_locale_guard.py— regression suitetests/test_translation_ledger_rollback_lock_contract.py— regression suitetests/test_translation_ledger_truncate_guard.py— regression suitetests/test_translation_ledger_truncate_publication_lock_contract.py— regression suitetests/test_translation_ledger_truncate_publication_race.py— regression suitetests/test_translation_ledger_unicode_whitespace.py— regression suitetests/test_translation_screen_value_object.py— regression suitetests/test_translation_wire_evidence_contract.py— regression suiteuv.lock— repository behavior
Changed behavior
flowchart LR
PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
Evidence --> S1["Backend: main.py (2 files)"]
S1 --> I1["API and service runtime"]
I1 --> R1["Review risk: Backend: main.py (2 files)"]
R1 --> V1["backend tests"]
Evidence --> S2["Docs: 0362-versioned-ui-translation-ledger.md (4 files)"]
S2 --> I2["operator or user guidance"]
I2 --> R2["Review risk: Docs: 0362-versioned-ui-translation-ledger.md (4 files)"]
R2 --> V2["docs review"]
Evidence --> S3["Python: observability.py"]
S3 --> I3["Python module behavior"]
I3 --> R3["Review risk: Python: observability.py"]
R3 --> V3["pytest plus coverage"]
Evidence --> S4["Repository file: 0246_ui_translation_ledger.sql"]
S4 --> I4["repository behavior"]
I4 --> R4["Review risk: Repository file: 0246_ui_translation_ledger.sql"]
R4 --> V4["required checks"]
Evidence --> S5["Repository file: 0247_ui_translation_truncate_guard.sql"]
S5 --> I5["repository behavior"]
I5 --> R5["Review risk: Repository file: 0247_ui_translation_truncate_guard.sql"]
R5 --> V5["required checks"]
Evidence --> S6["Repository file: 0246_ui_translation_ledger.sql"]
S6 --> I6["repository behavior"]
I6 --> R6["Review risk: Repository file: 0246_ui_translation_ledger.sql"]
R6 --> V6["required checks"]
Evidence --> S7["Repository file: 0247_ui_translation_truncate_guard.sql"]
S7 --> I7["repository behavior"]
I7 --> R7["Review risk: Repository file: 0247_ui_translation_truncate_guard.sql"]
R7 --> V7["required checks"]
Evidence --> S8["Repository file: pyproject.toml"]
S8 --> I8["repository behavior"]
I8 --> R8["Review risk: Repository file: pyproject.toml"]
R8 --> V8["required checks"]
Evidence --> S9["Test: test_translation_api_driver_boundary.py (24 files)"]
S9 --> I9["regression suite"]
I9 --> R9["Review risk: Test: test_translation_api_driver_boundary.py (24 files)"]
R9 --> V9["targeted test run"]
Evidence --> S10["Repository file: uv.lock"]
S10 --> I10["repository behavior"]
I10 --> R10["Review risk: Repository file: uv.lock"]
R10 --> V10["required checks"]
Findings
No source-backed product finding is synthesized from the coverage gate. A coverage miss belongs in the status comment.
- Head SHA:
0f4fd26a5f0fcf26932d0945188aefb2143d6605 - Workflow run: 34124343793
- Workflow attempt: 1
- Coverage gate:
failure
Review outcome
Coverage is a gate, not the review. This body reviews the changed product files.
Changed-File Evidence Map
flowchart LR
PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
Evidence --> S1["Backend: main.py (2 files)"]
S1 --> I1["API and service runtime"]
I1 --> R1["Review risk: Backend: main.py (2 files)"]
R1 --> V1["backend tests"]
Evidence --> S2["Docs: 0362-versioned-ui-translation-ledger.md (4 files)"]
S2 --> I2["operator or user guidance"]
I2 --> R2["Review risk: Docs: 0362-versioned-ui-translation-ledger.md (4 files)"]
R2 --> V2["docs review"]
Evidence --> S3["Python: observability.py"]
S3 --> I3["Python module behavior"]
I3 --> R3["Review risk: Python: observability.py"]
R3 --> V3["pytest plus coverage"]
Evidence --> S4["Repository file: 0246_ui_translation_ledger.sql"]
S4 --> I4["repository behavior"]
I4 --> R4["Review risk: Repository file: 0246_ui_translation_ledger.sql"]
R4 --> V4["required checks"]
Evidence --> S5["Repository file: 0247_ui_translation_truncate_guard.sql"]
S5 --> I5["repository behavior"]
I5 --> R5["Review risk: Repository file: 0247_ui_translation_truncate_guard.sql"]
R5 --> V5["required checks"]
Evidence --> S6["Repository file: 0246_ui_translation_ledger.sql"]
S6 --> I6["repository behavior"]
I6 --> R6["Review risk: Repository file: 0246_ui_translation_ledger.sql"]
R6 --> V6["required checks"]
Evidence --> S7["Repository file: 0247_ui_translation_truncate_guard.sql"]
S7 --> I7["repository behavior"]
I7 --> R7["Review risk: Repository file: 0247_ui_translation_truncate_guard.sql"]
R7 --> V7["required checks"]
Evidence --> S8["Repository file: pyproject.toml"]
S8 --> I8["repository behavior"]
I8 --> R8["Review risk: Repository file: pyproject.toml"]
R8 --> V8["required checks"]
Evidence --> S9["Test: test_translation_api_driver_boundary.py (24 files)"]
S9 --> I9["regression suite"]
I9 --> R9["Review risk: Test: test_translation_api_driver_boundary.py (24 files)"]
R9 --> V9["targeted test run"]
Evidence --> S10["Repository file: uv.lock"]
S10 --> I10["repository behavior"]
I10 --> R10["Review risk: Repository file: uv.lock"]
R10 --> V10["required checks"]
OpenCode Review Overview
Coverage evidence did not pass, so approval is blocked. The formal pull-request review is the source-backed diff review, not this status comment. |
1 participant
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
RecursionErrorinjection remains supplemental only.Current exact head is
0f4fd26a5f0fcf26932d0945188aefb2143d6605. Concurrent commit0f4fd26...is docs-only ondocs/product-technical-gap-baseline.md, directly after previously validated2a8ed5d02f4a3082b346d923d754c1ff37ebff52; it refreshed the dated live queue snapshot and did not change ledger/API/DB semantics. Exact-head evidence is evaluated independently rather than inherited.Protected
mainremains the direct base line for this PR. Ready is validation admission only.Fresh exact-head validation
Exact-head Tests
34102663992, PROV-O34102663856, Ontology Pages34102664095, and SAST Semgrep34102663989are now terminal GREEN on0f4fd26....Security
34102663880is terminal fail-closed, not a product vulnerability finding. Scorecard, OSV, and Trivy all completed GREEN. Dependency Review job101708140170checked out exact head0f4fd26...and failed its support preflight because GitHub returned HTTP 403 fordependency-graph/compare/83eba56149eb802cd63642c507c324c9976ec78e...0f4fd26a5f0fcf26932d0945188aefb2143d6605; the dependency-review action itself was therefore skipped. This reproduces the canonical support incident already tracked byContextualWisdomLab/.github#810; do not add a LineageWeave-local shim or substitute the successful scanners.CodeQL PR
34102664003is also terminal fail-closed. Language detection succeeded; actions/javascript-typescript/python compatibility jobs found no authenticated current-head dispatch verdict and failed atRelease runner or enforce current-head CodeQL verdict. The later dispatch job completed successfully, but the exact commit still has nocodeql-dispatch/*terminal status; the only combined commit status currently present is CodeRabbit. Treat this as canonical dispatcher/receipt owner work, not as source GREEN or a reason for leaf head churn.No qualifying independent exact-head approval exists. Do not synthesize status/review evidence, self-approve, weaken required gates, or transfer the older
2a8ed5d...results.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.mdmust converge with that cutover.Direct descendant #932 remains Draft and must converge on exact
#929@0f4fd26a5f0fcf26932d0945188aefb2143d6605. Its current product headc01e3109c987115c65bcbc74cd6f6247527387b8still contains the earlier #929 parent and therefore cannot inherit this parent movement implicitly. #932's secondary-auth repair and prior isolated/browser evidence remain child-only evidence and do not transfer to this parent.