feat(core): add bitemporal Employment absence truth

[seonghobae]

Buyer-visible gap

develop@9e3e4847510e1e612b48474ba42b177b8ed824df has bitemporal Employment and Assignment truth but no reason-free authoritative operational fact that answers whether one Employment is absent at a specific business date and system-knowledge cutoff. This Orgmetra-only slice adds that core truth without persisting medical/family/statutory/free-form leave reasons, changing Assignment, or writing any dedicated-writer dependency.

Test-first contract and repairs

The branch adds EmploymentAbsenceVersion, EmploymentAbsenceError, and build_employment_absence_snapshot(...) with regressions covering exact runtime primitives, tenant/Employment/Person binding, status vocabulary, visible-version uniqueness, one confirmed absence at a coordinate, active|leave Employment coverage, correction-not-rewrite cancellation, caller-defined UUID/date/timezone behavior, exact boolean snapshot state, deterministic evidence, and omission of Person/reason values. Root runtime-integrity repair 19ad4fe1a820a7b317958c331442169848af3150 plus current traceability head 3da7ad076f977a3ccd9e130a58786c9d26763a16 fail closed before forged scope/temporal values can influence comparison or canonicalization.

Shared DateInterval / RecordedInterval hardening remains separately owned by PR #69; #113 does not copy that adjacent owner repair or inherit its checks.

Architecture / privacy boundary

ADR 0113 records the reason-free bitemporal core decision. This fact records that an Employment is absent, not why. Medical, family, statutory, disciplinary, benefit, free-form reason, compensation, rating, and model-output data remain outside the HRIS-kernel evidence. The snapshot is descriptive operational truth only and grants no high-impact employment-decision authority.

Exact-current-head evidence

Current exact head: 3da7ad076f977a3ccd9e130a58786c9d26763a16
Live base: develop@9e3e4847510e1e612b48474ba42b177b8ed824df

GitHub live state is open · Draft · mergeable. Exact-current-head hosted runs remain terminal GREEN:

• Workforce Intelligence Quality 32782228751
• Recovery Rehearsal Quality 32782228754
• SAST Semgrep 32782228753
• Security Scan 32782228758
• Foundation CI 32782228771
• People API Quality 32782228799
• Job-Analysis API Quality 32782228776

Submitted review state is COMMENTED only. The three inline defect findings are resolved after the forged-tenant UUID, non-boolean snapshot state, and corresponding regressions were repaired. There is no qualifying independent non-author APPROVE or CHANGES_REQUESTED.

The technically GREEN head is nevertheless live-Draft. Prior event history and adjacent PRs show a separate same-repository lifecycle writer repeatedly changing GREEN PRs between Ready and Draft, so this loop does not race that writer by flipping lifecycle state.

Scope / stack / merge governance

Write scope is Orgmetra only. PR #47 remains a separate owner for non-authorizing pre-mutation leave-review evidence. Child #114 remains a Draft dependency-first persistence lane and its focused GREEN does not transfer here.

Keep the current lifecycle state until the authoritative PR-lifecycle writer advances it. Fresh effective organization ruleset 18156473 — CWL Central required workflows is active on ~DEFAULT_BRANCH, but its current live policy is weaker than Orgmetra's acquisition-grade acceptance: it requires 1 approving review, dismisses stale reviews on push, does not require last-push approval, requires review-thread resolution and central required workflows, blocks deletion/non-fast-forward updates, and permits OrganizationAdmin bypass_mode=always / current-user always-bypass.

Issue #89 owns that commercial-control gap plus lifecycle-writer collision evidence. Orgmetra acceptance remains at least 2 qualifying independent non-author approvals, approval after the last push, every applicable exact-head local/central gate terminal GREEN, resolved conversations, and no routine administrator bypass. Do not self-approve, race another writer, weaken/simulate protection, use routine admin bypass, or transfer predecessor/descendant evidence.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9a4ed143-c1ec-4f7b-87a2-757353c35c76

📥 Commits

Reviewing files that changed from the base of the PR and between 9e3e484 and 3da7ad0.

📒 Files selected for processing (11)

• docs/adr/0113-authoritative-employment-absence-truth.md
• docs/doctoring/employment-absence-truth-references.md
• docs/traceability/employment-absence-truth.md
• packages/hris-kernel/README.md
• packages/hris-kernel/src/orgmetra_hris_kernel/__init__.py
• packages/hris-kernel/src/orgmetra_hris_kernel/absence.py
• packages/hris-kernel/src/orgmetra_hris_kernel/errors.py
• packages/hris-kernel/src/orgmetra_hris_kernel/facts.py
• packages/hris-kernel/tests/test_employment_absence.py
• packages/hris-kernel/tests/test_employment_absence_runtime_integrity.py
• packages/hris-kernel/tests/test_employment_absence_timezone_integrity.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Employment absence truth를 위한 이중 시간축 사실, 스냅샷 빌더, 공개 패키지 계약, 문서, 계약 테스트, 런타임 무결성 테스트를 추가했습니다. 스냅샷은 유효일과 지식 시점에서 부재 상태를 결정하고, 사유와 Person 식별자를 정규 출력에서 제외합니다.

Changes

Employment absence truth

Layer / File(s)	Summary
부재 사실 계약과 패키지 공개 표면 packages/hris-kernel/src/orgmetra_hris_kernel/facts.py, packages/hris-kernel/src/orgmetra_hris_kernel/errors.py, packages/hris-kernel/src/orgmetra_hris_kernel/__init__.py, packages/hris-kernel/README.md, docs/adr/..., docs/traceability/..., docs/doctoring/...	EmploymentAbsenceVersion, EmploymentAbsenceError, 스냅샷 API와 패키지 export를 추가했습니다. 이유 없는 운영 사실과 적용 경계를 문서화했습니다.
스냅샷 검증과 사실 해석 packages/hris-kernel/src/orgmetra_hris_kernel/absence.py	UTC 지식 시점, UUID/date/bool 타입, 테넌트·Person·Employment 범위, 단일 Employment anchor, 단일 confirmed absence를 검증합니다. 결정적 canonical JSON과 SHA-256 digest를 생성합니다.
스냅샷 동작 계약 테스트 packages/hris-kernel/tests/test_employment_absence.py	effective time과 recorded time, 상태 해석, Employment 연결, 테넌트 범위, 중복 및 fail-closed 오류, 민감정보 비노출을 검증합니다.
런타임 및 timezone 무결성 테스트 packages/hris-kernel/tests/test_employment_absence_runtime_integrity.py, packages/hris-kernel/tests/test_employment_absence_timezone_integrity.py	위조된 런타임 하위 클래스, 잘못된 직접 스냅샷 입력, naive timezone, 불완전한 offset, timezone provider 예외를 검증합니다.

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

Merge Risk: ⚪ Minimal · up to 3da7a

The PR adds reason-free bitemporal Employment absence truth, with all listed current-head checks passing and no unresolved correctness or security issue identified; no actionable merge-blocking risk remains beyond required independent approval and enforceable branch protection.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant SnapshotBuilder
  participant EmploymentFacts
  participant AbsenceFacts
  participant Snapshot
  Caller->>SnapshotBuilder: 유효일과 지식 시점으로 snapshot 요청
  SnapshotBuilder->>EmploymentFacts: 동일 테넌트의 visible Employment 해석
  EmploymentFacts-->>SnapshotBuilder: active 또는 leave Employment 반환
  SnapshotBuilder->>AbsenceFacts: visible absence version 해석
  AbsenceFacts-->>SnapshotBuilder: confirmed absence 또는 없음 반환
  SnapshotBuilder->>Snapshot: reason-free snapshot 생성
  Snapshot-->>Caller: canonical evidence와 digest 반환

Loading

Suggested reviewers: cursoragent

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 68.66% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 67 functions across 7 files. (4 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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	제목은 변경의 핵심인 이중 시간축 Employment 부재 진실 기능 추가를 정확하고 간결하게 설명합니다.

Full details: Docstring Coverage

Explanation

Docstring coverage is 68.66% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 67 functions across 7 files. (4 skipped: 4 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/employment-absence-truth

---

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

[devin-ai-integration]

Devin Review found 2 new potential issues.