feat: add purpose-specific consent and research contribution lifecycle

[seonghobae]

Summary

Adds the next Hosted Assessment Runtime domain slice after scoring/result provenance: purpose-specific append-only consent evidence, immutable consent snapshots, and explicit research-contribution/withdrawal semantics.

Product boundary

• Consent is product-owned lifecycle state; identity credentials remain in Keyverse.
• Service operation, account persistence, longitudinal observation, research contribution, and communications are distinct purposes.
• Research contribution is absent by default and cannot begin without an active explicit research grant plus a versioned research scope.
• Research participant identity is stored separately from the operational participant reference represented by the consent snapshot.
• Revocation/withdrawal append evidence and never rewrite prior consent or contribution history.
• No psychometric arithmetic or research-release catalog implementation is added here.

Contract behavior

• Normalizes opaque participant/event/form/snapshot/contribution/research-participant/scope references before identity-bearing use.
• Requires research scope only for the research-contribution purpose and rejects cross-purpose scope leakage.
• Preserves server-authoritative non-decreasing consent event time.
• Replays identical consent events idempotently and rejects conflicting reuse of an event reference.
• Derives the active decision and form version per purpose from the latest immutable event while retaining the full event history.
• Requires active research consent to construct ResearchContribution.
• Makes exact withdrawal replay idempotent while rejecting contradictory second withdrawals and pre-start withdrawal time.

TDD evidence

The branch begins with test: define consent and research contribution contract before the consent module existed. Production implementation follows in subsequent commits.

Validation required on final exact head

• format/check/clippy/tests/rustdoc
• exact 100% production line and branch coverage
• Security Scan and SAST
• zero valid unresolved review findings

Summary by CodeRabbit

• 새로운 기능

  • 목적별 동의 결정을 독립적으로 기록하고 최신 상태를 확인할 수 있습니다.
  • 동의 철회와 감사 이력을 보존해 결정 변경 내역을 추적할 수 있습니다.
  • 명시된 연구 범위와 승인에 따라 연구 기여를 생성할 수 있습니다.
  • 연구 기여에는 운영 정보와 분리된 가명 식별자가 적용됩니다.
  • 연구 동의 철회 후 신규 기여가 차단되며 기존 이력은 보존됩니다.

• 버그 수정

  • 중복 요청, 잘못된 참조 재사용, 시간 역행 등 비정상 입력을 안정적으로 처리합니다.

[coderabbitai]

Warning

Review limit reached

@seonghobae, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 16 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8f0886ec-f1c6-4651-88cd-47bc4ec98538

📥 Commits

Reviewing files that changed from the base of the PR and between ee37c46 and e925071.

📒 Files selected for processing (6)

• src/consent.rs
• src/reference.rs
• tests/consent_identity_safety.rs
• tests/consent_research_contract.rs
• tests/consent_timestamp_boundary.rs
• tests/research_contribution_temporal_contract.rs

📝 Walkthrough

Walkthrough

목적별 불변 동의 이벤트와 스냅샷을 추가했습니다. 연구 동의 범위가 있는 경우에만 연구 기여를 생성합니다. 연구 기여는 가명 식별자를 사용하며, 철회는 불변 상태 전환과 멱등성 규칙을 따릅니다.

Changes

동의 및 연구 기여

Layer / File(s)	Summary
동의 이벤트 원장과 스냅샷 src/consent.rs, src/lib.rs, tests/consent_research_contract.rs	목적별 동의 이벤트, 최신 동의 스냅샷, 입력 검증, 멱등 재생, 충돌 및 시간 순서 오류를 추가했습니다. consent 모듈을 공개 API로 노출했습니다.
연구 기여 생성과 철회 src/consent.rs, tests/consent_research_contract.rs	활성 연구 동의 스냅샷에서 연구 기여를 생성합니다. 연구 기여 철회는 불변 상태 전환으로 처리하며, 동일 철회 요청만 멱등적으로 허용합니다.
통합 계약 검증과 변경 기록 tests/consent_research_contract.rs, CHANGELOG.md	동의와 연구 기여의 생성·철회·검증·오류 문자열 계약을 테스트합니다. 변경 기록에 새 기능을 추가했습니다.

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

Sequence Diagram(s)

sequenceDiagram
  participant ResearchParticipant
  participant ConsentLedger
  participant ResearchContribution
  ResearchParticipant->>ConsentLedger: 목적별 동의 이벤트 기록
  ConsentLedger->>ConsentLedger: 최신 동의 스냅샷 생성
  ResearchParticipant->>ResearchContribution: 연구 기여 생성 요청
  ResearchContribution->>ConsentLedger: 활성 연구 동의 확인
  ConsentLedger-->>ResearchContribution: 연구 범위와 스냅샷 반환
  ResearchParticipant->>ResearchContribution: 철회 증거 제출
  ResearchContribution-->>ResearchParticipant: 철회 상태 반환

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	제목은 목적별 동의와 연구 기여 수명주기 추가라는 변경의 핵심을 정확하고 간결하게 설명합니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 feat/purpose-consent-research-contribution

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/consent.rs`:
- Around line 351-364: Update ConsentSnapshot::from_snapshot to compare the
normalized contribution_ref and research_participant_ref values after
research_reference validation, returning a new
ResearchContributionError::OperationalIdentityReuse when they match. Add the
variant and its corresponding error message, while preserving the existing
validation flow for distinct references.
- Around line 499-505: Update normalized_reference, used by required_reference
and research_reference, to reject references consisting only of decimal digits
while preserving trimming and acceptance of other non-empty values. Add focused
tests covering numeric-only rejection and valid non-numeric references.

In `@tests/consent_research_contract.rs`:
- Around line 306-329: Extend
events_must_be_recorded_in_server_authoritative_time_order to record and assert
acceptance of a second event with timestamp 7,000, alongside the existing
rejection for 6,999. Keep the assertion focused on the equal-timestamp boundary
so an accidental <= comparison would fail the test.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4e7e268d-14dd-4f5a-86a8-11eb6af0833c

📥 Commits

Reviewing files that changed from the base of the PR and between fcb35de and ee37c46.

📒 Files selected for processing (4)

• CHANGELOG.md
• src/consent.rs
• src/lib.rs
• tests/consent_research_contract.rs