[Feat] 동일 원본 재수집을 원본 재게시 없이 재확인 원장 행으로 등록

[AquilaXk]

Related issue

Refs #870
Refs #862
Refs #903

Summary

• 문제
  • 같은 공식 원본(바이트 sha256이 원장 head와 같음)을 다시 수집해 등록하면 두 곳에서 막혔습니다.
    • 코레일 게시기: 같은 UTC 날짜 키의 원본 객체가 이미 있으면 EXISTS로 실패했습니다. 대경선 재확인이 여기서 막혔습니다.
    • 수도권 시간표 등록기(KRIC 파일 900): snapshot 파일을 wx로 쓰다가 충돌했습니다.
  • 선례(2026-10-01·02 코레일 동일 파일 재확인)는 원본을 날짜 키로 다시 올렸습니다. 수도권은 재확인마다 16MB snapshot이 쌓일 구조였습니다.
• 결과
  • 원본이 같으면 원본을 다시 게시하지 않습니다. 기존 객체를 실제로 읽어 확인한 뒤 재확인 기록만 append합니다.
    • 코레일: 원장 행
    • 수도권: inventory 재확인 이력
  • 원본이 다르면 기존 신규 등록 경로를 그대로 탑니다.

Changes

• tools/datapack/lib/same-raw-reverification.mjs(공용, [Refactor] 데이터 파이프라인 운영 방식 전환: 자동 갱신·개발/발행 게이트 분리·생성 산출물 축소 #870 일일 자동 재확인에 재사용)
  • planRawObjectPublication: 원장 head와 원본 sha가 같으면 REVERIFY_EXISTING, 다르면 PUBLISH_NEW를 돌려줍니다. head의 크기나 URI가 맞지 않으면 실패합니다.
  • verifyReusedRawObject: 기존 OCI 객체를 GET으로 읽어 크기와 sha를 확인합니다. 객체가 없거나 다르면 실패합니다.
  • appendLedgerRow: append-only로 붙입니다. snapshot이 충돌하거나 head 계보가 맞지 않으면 실패합니다.
• 코레일 원본 게시기(publish-korail-metropolitan-timetable-raw.mjs)
  • 원장 head와 원본이 같으면 PUT 없이 head 객체를 확인합니다.
  • 확인 결과로 korail-metropolitan-timetable-raw-reverification-receipt를 남깁니다. 기록 항목: verifiedAt, reusedFromSnapshotId
• 대경선 topology 등록기(register-korail-route-topology.mjs)
  • 재확인 영수증은 원장 head 객체(URI, snapshot, sha, 크기)를 정확히 가리킬 때만 받습니다.
  • 새 원장 행에 rawObjectReusedFromSnapshotId를 남기고, appendLedgerRow로 잇습니다.
• 계획 시간표 등록기(register-korail-timetable.mjs): 부모 topology가 재확인 행이면, 같은 기존 객체를 가리키는 재확인 영수증을 받습니다.
• 수도권 시간표(kric-capital-timetable-records, capital-official-timetable, register-kric-capital-timetable). QA 결정(2026-10-03, B안)을 따랐습니다.
  • snapshot(schemaVersion 2)은 원본 내용만 담습니다. 관측 시각과 수집 파일명과는 무관하며, id와 records는 이전과 같습니다.
  • inventory capitalScheduleAdmissionEvidence.reverifications
    • 형식: [{observedAt, rawSha256, collectionReceiptSha256}], append-only
    • observedAt은 마지막 항목과 같고, prepare가 신선도 기준으로 씁니다.
  • 같은 원본이면 기존 snapshot을 재사용하고 파일을 쓰지 않습니다. 기존 snapshot 바이트와 records sha가 정확히 같아야 하며, 다르면 실패합니다.
  • 새 관측은 직전 관측보다 뒤여야 합니다. 이력 앞부분이 바뀌거나 지워지면 실패합니다.
  • 리뷰 F1 반영: 등록기는 --operation-directory만 받습니다.
    • 원본을 직접 수집(실제 GET·sha)하고, 같은 실행에서 만든 영수증만 씁니다. 외부 영수증 인자는 받지 않습니다.
    • 관측 시각이 실행 시계보다 미래이거나 1시간보다 오래되면 실패합니다.
  • 리뷰 F3 반영: 원본이 A → B → A로 돌아오면, 기존 snapshot 바이트가 같을 때만 재사용합니다.
• 리뷰 F4 반영: 재확인은 실제 GET 본문으로 sha를 계산하는 저장소 클라이언트(verifiesObjectBytes: true, PAR 클라이언트)만 받습니다.
• purge-expired-source-raw.mjs
  • 같은 object key는 같은 원본 hash일 때만 공유를 허용합니다. hash가 다르면 conflicting object key로 거부합니다.
  • 참조하는 entry 가운데 하나라도 보호 중이면 보호하고, 하나라도 만료 전이면(가장 늦은 만료 전) 보존합니다. 모두 만료됐을 때만 삭제합니다.
• 데이터
  • 기존 수집본(2026-10-02T15:57:05.773Z, raw 218f76dd…)으로 수도권 snapshot을 새 형식으로 다시 등록했습니다. 관측 시각은 그대로입니다.
  • 전국 후보를 재생성했습니다(seq125). 팩과 외부 시간표 파일 바이트는 바뀌지 않았습니다.

Scope

Included

• 같은 원본 재확인 등록에 쓰는 공용 lib
• 코레일 topology 게시·등록과 계획 시간표 등록
• 수도권 시간표 등록
• purge 공유 객체 가드
• 수도권 snapshot 형식 전환에 따른 후보 재생성

Excluded

• 실제 재수집·재확인 실행(데이터 PR)과 발행·dispatch
• 다른 원천(서울 접근성, 지역 topology 등)의 게시기
  • 같은 패턴으로 확장할 수 있지만 이번 범위에 넣지 않았습니다.
• 일일 자동 재확인 workflow([Refactor] 데이터 파이프라인 운영 방식 전환: 자동 갱신·개발/발행 게이트 분리·생성 산출물 축소 #870 후속)

Ownership / dependencies

• Accountable owner or plan: Claude([Refactor] 데이터 파이프라인 운영 방식 전환: 자동 갱신·개발/발행 게이트 분리·생성 산출물 축소 #870). 메인 세션이 조율했고 QA가 승인했습니다(2026-10-03, B안·purge 가드).
• Required predecessor output: [Fix] 수도권 공식 시간표를 전국 후보 시간표에 적재 #910(수도권 시간표 적재) 병합 완료. 그 위로 rebase했습니다.
• Concurrent work overlap: 없음

Contract & Compatibility

• Source / API / schema contract
  • 새 외부 API나 원천은 없습니다. 카탈로그 대조 대상이 아닌 파이프라인 도구 변경입니다.
  • 기존 원천 kric-nationwide-timetable-file, korail-metropolitan-timetable-file의 등록 계약만 확장했습니다.
• Artifact / provenance identity
  • 재확인 원장 행은 기존 원본 객체 URI를 참조하고, rawObjectReusedFromSnapshotId로 출처 행을 남깁니다.
  • 수도권 snapshot id는 records sha 기반이라 그대로입니다. 관측 시각은 evidence 재확인 이력에서 정합니다.
• Backward compatibility
  • 기존 신규 게시 영수증(korail-metropolitan-timetable-raw-receipt)과 기존 원장 행은 그대로 받습니다.
  • 수도권 snapshot schemaVersion 1(observedAt 포함)은 더 이상 받지 않습니다. 커밋된 snapshot은 이 PR에서 전환했습니다.
• Migration or cutover: 수도권 snapshot 재등록과 후보 재생성을 이 PR에 담았습니다.

Version impact

• no version change
• datapack release only
• route-map artifact change
• data contract change
• product gate JSON change
• CI workflow·계약 테스트 change

Product gate impact

• release/product-gates/** 영향 없음
• 변경한 gate의 근거를 갱신했습니다.
• 검증되지 않은 지원 범위 claim을 추가하거나 확대하지 않습니다.

Provenance impact

• source inventory·geometry provenance manifest 영향 없음
• 제공처·라이선스·갱신 시점·적용 범위를 갱신했습니다.
• 공식 source로 확인되지 않은 값을 배포 artifact에 추가하지 않습니다.

Version decision

• datapack version: 후보 releaseSequence 125(nationwide-candidate-20261002-seq125). 발행은 이 PR 밖에서 합니다.
• data contract: 수도권 snapshot schemaVersion 2, 재확인 영수증 kind 추가, inventory reverifications
• route-map artifact / product gate: 변경 없음
• promotion request id: release-request-nationwide-candidate-20261002-seq125

Verification

Check	Result / Evidence
Focused RED → GREEN	아래 "RED와 GREEN" 참고
Affected integration	아래 "통합 테스트" 참고
Required CI	PR CI 결과로 확인합니다
Live provider / release	아래 "실제 원본 재확인" 참고
Security / data integrity	기존 객체를 실제 GET으로 확인합니다(sha·크기). 재확인 영수증은 head와 정확히 결속돼야 하고, 원장과 이력은 append-only입니다. purge는 공유 객체를 보존합니다.

RED와 GREEN

• RED: 테스트를 먼저 커밋한 상태에서 실패를 확인했습니다.
  • 코레일 쪽
    • lib 테스트 파일은 모듈이 없어 실패했습니다.
    • 게시기 재확인 테스트 2건이 실패했습니다.
    • 등록기 테스트 2건이 RAW_RECEIPT, PUBLICATION_RECEIPT로 실패했습니다.
  • purge: 공유 객체 테스트 4건이 실패했습니다.
  • 수도권
    • snapshot 관측 무관 테스트와 lib 테스트가 실패했습니다.
    • 등록 계획 테스트 파일은 모듈이 없어 실패했습니다.
• GREEN
  • register-korail-timetable 10건, 게시기·lib 테스트 통과
  • purge-expired-source-raw 40건 통과
  • 수도권 lib·등록 테스트 15건 통과
• mutant: 등록기의 head 결속 검사(assertReverificationReceiptMatchesHead 호출)를 제거하면 테스트가 실패합니다.

통합 테스트

• 영향 테스트 묶음(korail·원장·purge·수도권·팩·inventory·후보 관련 테스트 파일): 2,075건 모두 통과했습니다.
• 파일을 쓰는 테스트(prepare, capital-official-timetable, canonical-pack-* 2개, regional-timetable-official-stop-times)는 직렬로 돌려 모두 통과했습니다.
• 문서 파편 --check: IN SYNC

실제 원본 재확인

• KRIC 파일 900을 다시 수집했습니다(2026-10-02T22:25:12Z, raw sha256 218f76dd…로 이전과 같음).
• 임시 저장소 사본에서 registerKricCapitalTimetable을 실행한 결과는 REVERIFY_EXISTING이었습니다.
  • snapshot 파일 바이트는 바뀌지 않았습니다(cmp 일치).
  • reverifications가 2건으로 append됐고, observedAt이 갱신됐습니다.

Not run

• Check 1: 코레일 대경선 실제 재수집과 OCI 재확인 실행
  • Reason: 데이터 PR과 운영 실행 범위입니다. OCI PAR 키가 필요합니다.
  • Rerun owner / condition: 메인 세션이 맡습니다. 대경선 데이터 갱신 PR에서 register-korail-route-topology.mjs publish-register로 실행합니다.
• Check 2: collect-korail-itx-cheongchun-timetable.test.mjs
  • Reason: 로컬 SQLite 3.53.3 런타임 고정 조건 때문에 로컬에서는 실행할 수 없습니다. CI에서 실행됩니다.

Risk

• Level: High
• Main risk
  • 공유 원본 객체의 보존
    • purge는 공유 객체를 가장 늦은 만료와 보호에 맞춰 보존합니다.
    • 다만 retention ledger 생성기와 purge workflow는 아직 없습니다. 지금은 가드와 테스트만 넣은 상태입니다.
  • 수도권 snapshot 형식 전환(schemaVersion 2): 이전 형식은 더 이상 받지 않습니다.
• Failure behavior: 다음 경우 등록이 실패하고 아무것도 쓰지 않습니다.
  • head와 결속이 맞지 않음
  • 기존 객체를 읽을 수 없거나 크기·sha가 다름
  • records 불일치
  • 관측 시각 역전
  • 재확인 이력 변조
• Candidate / admission / publication state on failure: 원장과 inventory는 바뀌지 않습니다(트랜잭션 원복과 단일 쓰기).
• Fallback or degraded-success path introduced: No

Rollout / Recovery

• Rollout or promotion: 병합한 뒤 데이터 PR에서 재수집과 재확인 등록을 실행합니다. 수도권 시간표 신선도 연장과 대경선 재확인이 대상입니다.
• Monitoring / success signal: 재확인 등록 결과가 REVERIFY_EXISTING이고, 원장과 이력이 1건 append됩니다.
• Rollback or recovery: 이 PR을 revert하면 이전 등록 경로로 돌아갑니다. 커밋된 수도권 snapshot도 revert로 복원됩니다.
• Existing artifact / schema compatibility after rollback: 원장의 기존 행은 바뀌지 않아 호환됩니다.

Review focus

• 재확인 영수증과 원장 head의 결속(URI, snapshot, sha, 크기)
• 수도권 재확인 이력의 append-only 보장과 관측 시각 규칙
• purge 공유 객체 규칙(보호·만료 결합, hash 충돌 거부)

Checklist

• 이슈 범위와 실제 diff가 일치합니다.
• 관련 없는 변경이나 다른 owner의 surface를 포함하지 않았습니다.
• 위험에 필요한 검증과 미실행 사유를 기록했습니다.
• 실패·호환성·promotion·recovery 동작이 명확합니다.
• current failure를 이전·stale·alternate 결과의 성공으로 바꾸지 않습니다.
• GitHub PR Review 객체가 있는지 확인했습니다. CodeRabbit status check만으로는 리뷰 완료로 보지 않습니다.
• CodeRabbit Review 객체가 없으면 지원되는 Codex CLI 폴백 Review를 단일 GitHub PR Review로 게시했습니다.
• datapack 배포 영향이 있는 경우 release workflow 상태를 확인했습니다.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: f8dd1664-a0ad-4ee6-a09b-fa743645ae26

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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

[AquilaXk]

Actionable comments posted: 4

🎯 Linked issue & acceptance criteria audit

• Linked issue: #870 [Refactor] Data pipeline operations: auto refresh, gate split, fewer artifacts
• Goal summary: Same-source reverification without republishing raw, keeping failures explicit.
• Acceptance criteria verified: 3/3

ID	Acceptance criterion	Status	Evidence
AC-1	New publication only when content changed; same raw is reverified	PASS	tools/datapack/lib/same-raw-reverification.mjs
AC-2	Failed reverification stays explicit with no fallback success	PASS	tools/datapack/publish-korail-metropolitan-timetable-raw.mjs
AC-3	Same-date snapshot re-registration no longer blocks	PASS	tools/datapack/register-kric-capital-timetable.mjs

🛡️ Adversarial audit evidence

• Falsifiability verified: Yes (Manual mutants of purge ordering, capital order checks and OCI authority were killed.)
• Hollow assertions detected: 0
• Production backdoors detected: 0
• Ground-truth sources verified:
  • Committed capital snapshot records sha unchanged
  • Issue 870 same-raw and Fallback rules
  • preauthenticatedObjectStorageClient GET plus sha verification
• Mutation testing evidence: Survivors: receipt byteSize and register-korail-timetable receipt field comparisons.

🤖 Prompt for all review comments with AI agents

Could we verify each finding against the current code and keep only those that
still apply? Could we make the smallest validated fix and briefly note why any
finding no longer applies?

Inline comments:
- `@tools/datapack/lib/same-raw-reverification.mjs:50-50`
  Could the helper call readObject and hash the body itself, or assert the
  client kind, so the actual-bytes guarantee does not depend on the caller?
- `@tools/datapack/lib/same-raw-reverification.mjs:58-63`
  Could a table-driven rejection test tamper each bound receipt field one at a
  time and expect RECEIPT_HEAD or PUBLICATION_RECEIPT? That would make each
  binding falsifiable.
- `@tools/datapack/register-kric-capital-timetable.mjs:75-75`
  Could registration require capturedAt to be at or before the injected clock and
  within a short window of it, and cross-check the date in rawFile? Adding a test
  with a forged receipt that keeps the sha but advances capturedAt would prove it.
- `@tools/datapack/register-kric-capital-timetable.mjs:92-92`
  Should the plan compare against an existing snapshot file by bytes and reuse it,
  as the REVERIFY branch does? A test for A to B to A would pin the behavior.

---

Outside diff comments:
None.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: aquila-review skill run by Claude Code with hub CLAUDE.md invariants

Review profile: ASSERTIVE

Plan: Aquila fallback

Run ID: N/A (Aquila fallback)

Review source: Aquila CLI

Repository visibility: public GitHub repository

Trigger:
Discovery review of the current change set for the automerge review gate

Base:
main@c8f83ea1c54ad7110ff51dcff85d4fb3e4ae06cb

Head:
lib/same-raw-reverification@e7cc6ba82df6a698f798d9c84946ab9cda38df58

Command:
node scripts/compile-review-payload.mjs input.json --output payload-1.json

📥 Commits

Reviewing files changed in this pull request between:

• Base: c8f83ea1c54ad7110ff51dcff85d4fb3e4ae06cb
• Head: e7cc6ba82df6a698f798d9c84946ab9cda38df58

📒 Files selected for processing (25)

• contracts/documentation/documentation-fragment.json
• tools/ci/data-test-ownership.json
• tools/datapack/lib/capital-official-timetable.mjs
• tools/datapack/lib/capital-official-timetable.test.mjs
• tools/datapack/lib/kric-capital-timetable-records.mjs
• tools/datapack/lib/kric-capital-timetable-records.test.mjs
• tools/datapack/lib/same-raw-reverification.mjs
• tools/datapack/lib/same-raw-reverification.test.mjs
• tools/datapack/publish-korail-metropolitan-timetable-raw.mjs
• tools/datapack/publish-korail-metropolitan-timetable-raw.test.mjs
• tools/datapack/purge-expired-source-raw.mjs
• tools/datapack/purge-expired-source-raw.test.mjs
• tools/datapack/register-korail-route-topology.mjs
• tools/datapack/register-korail-timetable.mjs
• tools/datapack/register-korail-timetable.test.mjs
• tools/datapack/register-kric-capital-timetable.mjs
• tools/datapack/register-kric-capital-timetable.test.mjs
• tools/datapack/release/candidate-build-spec.json
• tools/datapack/release/current-five-region-source-fan-in.json
• tools/datapack/release/hash-evidence.json
• tools/datapack/release/nationwide-candidate-preparation.json
• tools/datapack/release/release-request.json
• tools/datapack/reports/nationwide-requirement-ownership-ledger.json
• tools/datapack/source-inventory.json
• tools/datapack/sources/kric-nationwide-timetable-file-capital-dec3ef2fdb5318efd9cff47c6b012e88c80c34f7b4866106eabbed6e1e7bdd00.json

📜 Review details

[github-actions]

No description provided.

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud