feat(topic): logistic-normal ALR coordinates with true-parameter RMSE

[seonghobae]

Summary

ADR 0012 first production slice: compositional topic coordinates. Rebased onto main after #47.

• New topic_measurement crate (no migration; 0007 remains owned by feat(persistence): retention deletion legal-hold SQL contracts (0007) #45)
• additive_log_ratio / from_additive_log_ratio with max-shifted stable maps
• True-parameter recovery RMSE on known simplex
• refuse_lexical_inferential_weight rejects TF-IDF / BM25 / keyword as estimator coordinates
• Workspace contract includes topic_measurement

Serial

• feat(persistence): event-relation vocabulary SQL contracts #37–feat(api): adaptive orchestration router selects modes under budget #47 merged
• Next focus after feat(api): adaptive orchestration router selects modes under budget #47 orchestration router

Test plan

• Exact-head Rust CI / coverage / docs quality
• OpenCode APPROVE when org gates allow (cannot self-approve)
• Squash-merge when CLEAN

Summary by CodeRabbit

• 새로운 기능
  • 토픽 비율을 안정적인 ALR 및 순차 ILR 좌표로 변환·복원하는 기능을 추가했습니다.
  • ILR 기반 Aitchison 거리를 계산하고 거리 보존을 지원합니다.
  • 잘못된 조성, 비유한 값, 차원 오류 및 수치 불안정 입력을 안전하게 거부합니다.
  • TF-IDF, BM25, 키워드 기반 점수를 추론 좌표로 사용하는 것을 제한합니다.
• 문서
  • ALR·ILR 좌표의 적용 기준, 수치 처리, 구현 상태 및 추적성 정보를 갱신했습니다.
• 검증
  • 변환 정확도, 거리 보존, 극단값 처리 및 입력 검증 테스트를 추가했습니다.
  • 커버리지 검증에서 문자열·주석·문자 리터럴 처리를 보강했습니다.

---

[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

topic_measurement Rust 크레이트에 ALR·sequential Egozcue ILR 변환과 역변환, Aitchison 거리, fail-closed 검증 및 어휘 가중치 거부를 추가했습니다. 워크스페이스 계약, 관련 문서 및 Rust LCOV 실행 라인 판별도 갱신했습니다.

Changes

토픽 측정 좌표 확장

Layer / File(s)	Summary
크레이트 계약과 공개 API crates/topic_measurement/Cargo.toml, crates/topic_measurement/src/error.rs, crates/topic_measurement/src/coordinates.rs, crates/topic_measurement/src/lib.rs, crates/topic_measurement/tests/crate_contract.rs	topic_measurement 패키지와 오류 타입을 추가했습니다. 조성 검증 규칙과 ALR·ILR·Aitchison API를 공개했습니다.
ALR·ILR 변환과 수치 검증 crates/topic_measurement/src/coordinates.rs, crates/topic_measurement/tests/*	ALR·ILR 변환과 역변환을 추가했습니다. 거리 일치, RMSE, 합산 오버플로우, 언더플로우 및 비유한 입력을 검증합니다.
어휘 가중치 거부 계약 crates/topic_measurement/src/lexical.rs, crates/topic_measurement/tests/logratio_recovery_contract.rs	정규화된 tfidf, bm25, keyword 방법을 LexicalWeightForbidden으로 거부합니다. 허용 및 거부 방법을 검증합니다.
워크스페이스 연결과 구현 기록 Cargo.toml, scripts/check_workspace_contract.py, tests/quality/test_check_docstrings.py, ARCHITECTURE.md, README.md, CHANGELOG.md, DOCUMENTATION.md, docs/*	새 크레이트를 워크스페이스와 계약 검사에 연결했습니다. 구현 상태, 연구 근거, 추적성 및 검증 문서를 갱신했습니다.

Rust 커버리지 판별 계약

Layer / File(s)	Summary
실행 가능 행 판별과 검증 scripts/check_coverage.py, tests/quality/test_check_coverage.py	Rust 멀티라인 문자열 continuation 행과 순수 구조 행을 실행 가능 대상에서 제외했습니다. 중첩 주석, raw 문자열, 문자 리터럴, feature 조건 및 LCOV fixture 검증을 갱신했습니다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: 🟡 Moderate · up to 16899

This PR adds logistic-normal topic coordinates and recovery validation, but the current head is not merge-ready because the coverage checker can incorrectly exclude executable code after block comments and the recovery contract validates the wrong RMSE metric. These issues can weaken release checks and fail the stated validation requirement; they should be fixed or explicitly accepted before merging.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant isometric_log_ratio
  participant from_isometric_log_ratio
  participant aitchison_distance
  Caller->>isometric_log_ratio: 양의 조성 벡터 전달
  isometric_log_ratio-->>Caller: ILR 좌표 반환
  Caller->>from_isometric_log_ratio: ILR 좌표 전달
  from_isometric_log_ratio-->>Caller: 조성 벡터 반환
  Caller->>aitchison_distance: 두 조성 전달
  aitchison_distance-->>Caller: CLR Aitchison 거리 반환

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 logistic-normal ALR 좌표와 true-parameter RMSE를 명확히 설명하며, 변경 사항의 주요 목적과 일치합니다.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
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.

✨ 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 agent/topic-logratio-coordinates

---

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.}

[opencode-agent]

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head a3de3fb1179708f18dee414ef4c5ff63e711e77d.

• Head SHA: a3de3fb1179708f18dee414ef4c5ff63e711e77d

• Workflow run: 31844834687

• Workflow attempt: 1

Coverage evidence

Coverage Decision

• Result: FAIL
• Test evidence: not proven passing
• Docstring evidence: not proven passing when configured
• Failure count: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (15 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (15 files)"]
  R1 --> V1["required checks"]
  Evidence --> S2["Docs (6 files)"]
  S2 --> I2["operator or user guidance"]
  I2 --> R2["Review risk: Docs (6 files)"]
  R2 --> V2["docs review"]
  Evidence --> S3["Test: test_check_docstrings.py"]
  S3 --> I3["regression suite"]
  I3 --> R3["Review risk: Test: test_check_docstrings.py"]
  R3 --> V3["targeted test run"]

Loading

[opencode-agent]

OpenCode Review Overview

• Head SHA: 6110d3660607ba46b312b4d76f048f1bcc4f3bc5
• Workflow run: 32699563289
• Workflow attempt: 1
• Gate result: REQUEST_CHANGES (approval step)

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head 6110d3660607ba46b312b4d76f048f1bcc4f3bc5.

• Head SHA: 6110d3660607ba46b312b4d76f048f1bcc4f3bc5

• Workflow run: 32699563289

• Workflow attempt: 1

Coverage evidence

Coverage Decision

• Result: FAIL
• Test evidence: not proven passing
• Docstring evidence: not proven passing when configured
• Failure count: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (66 files)"]
  S1 --> I1["repository behavior"]
  I1 --> Conflict["Merge conflict blocks this path"]
  Conflict --> V1["required checks"]
  Evidence --> S2["Workflow (2 files)"]
  S2 --> I2["GitHub Actions review job"]
  I2 --> Conflict["Merge conflict blocks this path"]
  Conflict --> V2["actionlint plus required checks"]
  Evidence --> S3["Docs (24 files)"]
  S3 --> I3["operator or user guidance"]
  I3 --> Conflict["Merge conflict blocks this path"]
  Conflict --> V3["docs review"]
  Evidence --> S4["Test (4 files)"]
  S4 --> I4["regression suite"]
  I4 --> Conflict["Merge conflict blocks this path"]
  Conflict --> V4["targeted test run"]

Loading

Merge Conflict Guidance

• Current merge state: DIRTY
• Base branch: main
• Head branch: agent/topic-logratio-coordinates
• Fix direction: merge or rebase origin/main into agent/topic-logratio-coordinates, resolve conflict markers in the changed files, rerun the focused checks, then push the same branch.
• Repair commands:

gh pr checkout 48 --repo ContextualWisdomLab/TEPP
git fetch origin main
git merge --no-ff origin/main  # or: git rebase origin/main
git status --short
# resolve files, then git add <resolved-files>
# merge path: git commit
# rebase path: git rebase --continue
git push origin HEAD:agent/topic-logratio-coordinates
# rebase path only: git push --force-with-lease origin HEAD:agent/topic-logratio-coordinates

[opencode-agent]

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head 6110d3660607ba46b312b4d76f048f1bcc4f3bc5.

• Head SHA: 6110d3660607ba46b312b4d76f048f1bcc4f3bc5

• Workflow run: 32699563289

• Workflow attempt: 1

Coverage evidence

Coverage Decision

• Result: FAIL
• Test evidence: not proven passing
• Docstring evidence: not proven passing when configured
• Failure count: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (66 files)"]
  S1 --> I1["repository behavior"]
  I1 --> Conflict["Merge conflict blocks this path"]
  Conflict --> V1["required checks"]
  Evidence --> S2["Workflow (2 files)"]
  S2 --> I2["GitHub Actions review job"]
  I2 --> Conflict["Merge conflict blocks this path"]
  Conflict --> V2["actionlint plus required checks"]
  Evidence --> S3["Docs (24 files)"]
  S3 --> I3["operator or user guidance"]
  I3 --> Conflict["Merge conflict blocks this path"]
  Conflict --> V3["docs review"]
  Evidence --> S4["Test (4 files)"]
  S4 --> I4["regression suite"]
  I4 --> Conflict["Merge conflict blocks this path"]
  Conflict --> V4["targeted test run"]

Loading

[devin-ai-integration]

Devin Review found 3 new potential issues.

[devin-ai-integration]

📝 Info: Credential-header substring match may over-block

header_is_credential now denies any extra header whose name contains secret, credential, openai, anthropic, bytez, or openrouter. Intended hardening, but substring matching would also reject future benign headers containing those tokens (e.g. x-openai-region).

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 2 new potential issues.

[devin-ai-integration]

📝 Info: ALR inverse max-shift includes reference coordinate

from_additive_log_ratio initializes maximum to 0.0 before folding the coordinate max, correctly including the implicit reference part (ALR value 0). The shift stays non-negative and the softmax reference exp(0) term is stable. Underflow paths fail closed as the tests assert.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

📝 Info: Empty trailing covariate columns silently dropped

build_design computes covariate_count from the maximum present column index rather than covariates.columns(). A sparse covariate matrix whose trailing column is all-zero yields one fewer Covariate prevalence feature than declared. The fit is unaffected (a zero column contributes nothing), but the reported feature layout can mismatch the caller's declared covariate dimension.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

🔍 Terminal-result parsing rejects future cutoffs against wall clock

AnalysisRunTerminalResult::validate reuses require_rfc3339_knowledge_cutoff, which compares the cutoff to Timestamp::now(). Terminal cutoffs are past-dated in normal flow, but this ties deserialization validity to the current wall clock. Confirm the future-cutoff rule belongs on stored terminal results and not only on inbound requests.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 3 new potential issues.

[devin-ai-integration]

🟡 Unbalanced code fence in README breaks docs check

The edit leaves README.md with 5 triple-backtick fences, an odd count. validate_markdown flags any file whose fence count is odd and raises, so the documentation check fails. A new ```text crate-list block was inserted without a matching closing fence, tangling with the existing crate-list block.

Prompt for agents

README.md now contains an odd number of ``` code fences (5), which validate_markdown rejects as an unbalanced fence. The inserted ```text block near the top (listing crates/analysis_engine ...) was added mid-file without a matching closing fence and overlaps the pre-existing crate-list block, producing garbled duplicate content. Reconcile the top-of-file 'Current implementation state' section: keep a single well-formed ```text crate list with matching open/close fences, remove the duplicated/half-merged lines, and verify README.md has an even number of ``` fences.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

📝 Info: Lexical-weight gate accepts "keywords" and other variants

refuse_lexical_inferential_weight rejects only exact folded tfidf, bm25, keyword. A label like keywords folds to keywords and passes, so keyword-based scoring can slip through under a near-synonym. Narrower than the ADR-0012 intent of refusing lexical retrieval weights.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 2 new potential issues.

[devin-ai-integration]

🟡 Duplicate rows in ARCHITECTURE foundation-crate table

The added rows for validation_core and tepp_api duplicate the existing rows immediately below them, each now listed twice with conflicting descriptions. location_membership is also re-added though it already appears in the file.

Suggested change

	| `validation_core` | RMSE, bias, coverage, graph, and Monte Carlo metrics |
	| `tepp_api` | versioned DTO, schema, terminal-result, and export contracts |
	| `location_membership` | location is not entity identity and not a language channel |
	| `topic_measurement` | logistic-normal ALR and sequential Egozcue ILR topic coordinates |
	| `analysis_engine` | bounded cutoff-safe temporal evidence readiness execution and digest-bound terminal artifacts |

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

📝 Info: Membership-count fold cannot overflow u64

With MAX_EVIDENCE_UNITS = 100,000 and u32 counts, the summed membership total is at most ~4.29e14, far below u64::MAX, so the fold is safe. The eligibility filter available_time <= cutoff matches the availability rule, and duplicate detection scans all units before filtering so duplicates are always caught.

---

Was this helpful? React with 👍 or 👎 to provide feedback.