[Feat] KRIC 역별 시간표 새 원천의 OCI 게시기·원장 등록기와 candidate 추가

[AquilaXk]

Related issue

Refs #903
Refs #862

Summary

• Problem: [Feat] KRIC 역별 시간표 API로 GTX-A·에버라인·의정부·김포골드·부산김해 trip 재구성 #906 수집본(GTX-A·에버라인·의정부·김포골드·부산김해)을 운영 원장에 올릴 경로가 없다. 기존 kric-subway-timetable 등록기는 4호선 pilot 형식에 고정돼 있다. 그 sourceId는 activate-current-source-set.mjs(current-capital-topology-refresh 워크플로)가 pilot handoff(20260809)로 inventory를 덮어쓴다. 그래서 같은 sourceId로 새 head를 올리면 충돌한다.
• Outcome: 메인 결정(나)에 따라 새 sourceId kric-subway-timetable-station-lines를 쓴다. 카탈로그 provider는 같은 provider:kric-subway-timetable operation이다. 이 PR은 그 원천의 게시기, 등록기, candidate를 추가하는 도구 PR이다. 실제 게시와 등록은 데이터 PR에서 명시적 입력 파일로 한다.

Changes

• tools/datapack/publish-kric-station-timetables-raw.mjs
  • 게시 전에 수집본 재구성을 검증한다.
  • source-raw/kric-subway-timetable-station-lines/<date>/<sha>.json에 immutable PUT 후 검증 GET을 한다.
  • receipt 형식은 기존 kric-timetable-raw-object-receipt와 같다.
  • 보존 만료일 계산: 등록 전에는 같은 약관 항목을 sourceId만 바꿔 투영한다. 등록기와 같은 규칙이다.
  • PAR과 키는 출력하지 않는다.
• tools/datapack/register-kric-station-timetables.mjs
  • 입력 파일(kric-station-timetable-registration-input)로 수집본, receipt, 검토 admission, governance 항목을 받는다.
  • 기존 kric-subway-timetable-review-admission 형식을 따르고, admission은 도구가 만들지 않는다.
  • 수집본은 고정 바인딩의 노선과 역 집합 전부를 재구성해야 한다. receipt와 admission은 원본 sha256·크기·snapshotId와 결속한다.
  • 같은 약관 결속: governance 항목이 kric-subway-timetable 항목과 sourceId를 빼고 동일해야 한다(데이터셋 id=162, termsHash 3496800e…). 다르면 GOVERNANCE_TERMS_MISMATCH로 실패한다.
  • 원장 행, inventory, governance(append-only), freshness(planned_timetable 클래스에 추가, 새 기준 없음)를 한 트랜잭션으로 쓴다.
  • 파생 스냅샷 tools/datapack/sources/<snapshotId>.json에 노선 목록, 역 코드 집합, 요일코드별 행 수, trip, 요일 정책을 결속한다.
  • 4호선 pilot 원장 행과 inventory 항목은 바꾸지 않는다.
• tools/datapack/source-candidates.json: kric-subway-timetable-station-lines candidate를 추가했다(catalogProviderId: provider:kric-subway-timetable, admissionStatus: preflight_only).
• tools/datapack/source-candidate-endpoint-contract.test.mjs: 새 KRIC candidate의 포털 id(162)를 고정했다.
• tools/ci/data-test-ownership.json: 새 테스트 2개를 등록했다.

Scope

Included

• 게시기, 등록기, candidate, 테스트

Excluded

• 실제 OCI 게시와 원장 등록. 데이터 PR에서 한다. OCI 게시는 [Fix] 전국 후보 기준으로 데이터 릴리스 파이프라인 복구(상위 이슈) #862 QA 승인 범위다.
• production-datapack-scope.json 필수 원천 추가. 데이터 PR에서 등록과 함께 한다(아래 검증기 테스트로 의무를 고정).
• prepare 통합. [Fix] 수도권 지하철 공식 시간표를 전국 데이터팩에 적재 #899 병합 뒤 진행한다.
• pilot 체인 정리(activate-current-source-set의 CURRENT_SOURCE_HANDOFF·applySchedule, 두 sourceId 통합). 메인이 후속 이슈로 만든다.

Ownership / dependencies

• Accountable owner or plan: Claude([Feat] 코레일 단독 노선 등 시간표 미지원 노선의 공식 시간표 적재 #903)
• Required predecessor output
  • [Feat] KRIC 역별 시간표 API로 GTX-A·에버라인·의정부·김포골드·부산김해 trip 재구성 #906: 이 PR은 [Feat] KRIC 역별 시간표 API로 GTX-A·에버라인·의정부·김포골드·부산김해 trip 재구성 #906 브랜치 위에 스택돼 있다.
  • Hub [Chore] 계획 시간표 신선도 클래스에 KRIC 역별 시간표 원천 추가 easysubway#3025: freshness 계약에 새 id 추가. 데이터 PR 전에 pin 상향이 필요하다.
• Concurrent work overlap: #899는 source-inventory.json의 kric-nationwide-timetable-file 항목을 다룬다. 이 PR은 inventory를 수정하지 않는다.

Contract & Compatibility

• Source / API / schema contract: 기존 receipt·review admission·원장 행 형식을 그대로 쓴다. 새 artifactKind는 입력 파일(kric-station-timetable-registration-input)과 파생 스냅샷(kric-station-timetable-snapshot) 두 개다.
• Artifact / provenance identity: snapshotId kric-subway-timetable-station-lines-<YYYYMMDD>. 원장 행에 rawObjectUri, receipt sha256, governance 정책 sha256을 결속한다.
• Backward compatibility: 기존 원천과 등록기는 바꾸지 않았다.
• Migration or cutover: 데이터 PR 순서는 hub pin 상향 → 게시 → 등록 → scope 갱신이다.

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 영향 없음
• 제공처·라이선스·갱신 시점·적용 범위를 갱신했습니다. candidate만 추가했고, inventory는 데이터 PR 등록 때 갱신된다.
• 공식 source로 확인되지 않은 값을 배포 artifact에 추가하지 않습니다.

Version decision

• datapack version: 변경 없음
• data contract: 새 등록 입력과 파생 스냅샷 형식
• route-map artifact / product gate: 변경 없음
• promotion request id: 없음

Verification

Check	Result / Evidence
Focused RED → GREEN	RED: 두 모듈이 없을 때 ERR_MODULE_NOT_FOUND. 개발 중 실패 원인 두 가지를 테스트로 찾아 고쳤다. 하나는 requiredUtcInstant가 숫자를 반환하는데 다시 Date.parse해서 생긴 NaN이고, 다른 하나는 nextReviewAt(초 단위 Z)를 엄격 파서로 해석한 문제다. GREEN: 아래 묶음 pass 50 / fail 0.
Affected integration	node --test tools/datapack/source-candidate-endpoint-contract.test.mjs tools/datapack/publish-kric-station-timetables-raw.test.mjs tools/datapack/register-kric-station-timetables.test.mjs tools/datapack/collect-kric-station-timetables.test.mjs tools/datapack/lib/kric-station-timetable-api-trips.test.mjs tools/datapack/lib/kric-station-row-timetable-trips.test.mjs: tests 50 / pass 50. 저장소 inventory 검증(CI와 같은 인자, stage-contracts 사용) exit 0. node tools/ci/data-test-discovery.mjs verify exit 0. 등록 결과는 scope 필수 원천에 새 id를 함께 올리면 validate-source-inventory(inventory·governance·freshness·admission)를 통과하고, 빠뜨리면 실패함을 테스트로 고정했다.
Required CI	Data contracts(이 PR의 CI 결과)
Live provider / release	Not required — reason: 합성 수집본으로 검증했다. 실수집본 검증은 #906 본문에 있다. 실제 게시와 등록은 데이터 PR에서 한다.
Security / data integrity	PAR·키 비노출(오류 메시지에 상태 코드만 노출). 수집본 sha256·크기·snapshotId를 receipt·admission·원장과 결속했다.

• candidate 파일을 읽는 테스트 43개도 로컬에서 실행했다. 817건 중 5건이 실패했고 모두 이 변경과 무관한 환경 요인이다.
  • 4건: 로컬에 모바일 fixture(apps/mobile/assets/datapacks/capital.sqlite.gz)가 없다. CI는 fixture를 stage한다.
  • 1건: ITX 테스트의 Node 24.19.0·SQLite 3.53.3 런타임 고정 검사다. [Feat] KRIC 파일 900 코레일 역별 행을 열차별 시간표 trip으로 재구성 #905 기준 브랜치에서도 같은 결과다.

Not run

• Check: run-rc-full
• Reason: 후보 조립에 아직 연결하지 않았다.
• Rerun owner / condition: 통합 PR([Fix] 수도권 지하철 공식 시간표를 전국 데이터팩에 적재 #899 병합 뒤)에서 Claude가 실행한다.

Risk

• Level: High
• Main risk: 새 sourceId가 Hub freshness 계약(#3025)과 data pin에 반영되기 전에 등록하면 CI의 SOURCE_FRESHNESS_POLICY_MISSING으로 실패한다. 순서로 막는다.
• Failure behavior: 다음 경우 쓰기 전에 실패한다. 약관 불일치, 미승인 admission, receipt 불일치, 수집 결손, HEAD 불일치(테스트로 확인).
• Candidate / admission / publication state on failure: 원장, inventory, 정책 파일을 바꾸지 않는다.
• Fallback or degraded-success path introduced: No

Rollout / Recovery

• Rollout or promotion: Hub #3025 병합 → data pin 상향 → 데이터 PR(게시·등록·scope) → prepare 통합
• Monitoring / success signal: 데이터 PR CI의 validate-source-inventory 통과, 노선별 trip 수
• Rollback or recovery: 이 PR을 revert한다. 등록 전이면 의존하는 데이터가 없다.
• Existing artifact / schema compatibility after rollback: 영향 없음

Review focus

• 같은 약관 결속 방식(기존 governance 항목과의 동일성)
• 등록 전 보존 만료일 투영
• 파생 스냅샷 결속 항목

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: 46383b42-ab48-47bc-b7bc-45045bd1f961

• 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: 6

🎯 Linked issue & acceptance criteria audit

• Linked issue: #903 [Feat] 코레일 단독 노선 등 시간표 미지원 노선의 공식 시간표 적재
• Goal summary: Load official timetables for lines lacking trips; five KRIC API lines here.
• Acceptance criteria verified: 1/1

ID	Acceptance criterion	Status	Evidence
C2	Sources for GTX-A and Busan-Gimhae checked against the catalog and measured	PASS	tools/datapack/source-candidates.json:5568

🛡️ Adversarial audit evidence

• Falsifiability verified: No (Failed: Publisher catch rewrap and registrar lines 74, 92, 166 survived mutation)
• Hollow assertions detected: 0
• Production backdoors detected: 0
• Ground-truth sources verified:
  • Existing pilot governance entry compared field by field via canonicalJson with only sourceId changed
  • Issue 903 body and QA decisions on dayCd 9 and line scope
  • validate-source-inventory.mjs exits 0 with the new candidate

🤖 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/publish-kric-station-timetables-raw.mjs:54-57`
  Could tests be added where the client throws an error embedding the PAR base URL
  and asserting the message omits it, and where the stored object differs from the
  upload and publication fails without a receipt?
- `@tools/datapack/register-kric-station-timetables.mjs:74-75`
  Could a fixture be added whose artifact.lines drops or swaps one station code and
  the expectation be COLLECTION_LINES, with the snapshot test comparing the actual
  station code arrays instead of their lengths?
- `@tools/datapack/register-kric-station-timetables.mjs:91-93`
  Could a second registration with a later capture date be tested, asserting the
  previous head link and an unchanged governance entry, plus cases that expect
  SUCCESSOR_STATE and SNAPSHOT_COLLISION?
- `@tools/datapack/register-kric-station-timetables.mjs:116-116`
  Could one rejection case per operand be added for these two guards?
- `@tools/datapack/register-kric-station-timetables.mjs:164-166`
  Could a test mutate the candidate lineIds in the copied source-candidates.json and
  assert CANDIDATE, so the binding is pinned from both sides?
- `@tools/datapack/register-kric-station-timetables.test.mjs:137-138`
  Could the expected value use the binding station code arrays directly?

---

Outside diff comments:
None.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: CLAUDE.md files, data repo PR template, and aquila-review skill defaults

Review profile: ASSERTIVE

Plan: Aquila fallback

Run ID: N/A (Aquila fallback)

Review source: Aquila CLI

Repository visibility: public GitHub repository

Trigger:
QA-requested discovery review of PR 909 at head faaa09b

Base:
feat/kric-api-station-timetables-903@ad28cefa091ccb9089cc87a8a720cfd29f7008c7

Head:
feat/kric-station-lines-registration-903@faaa09b6925e889c16d4ee677208c7d55891984f

Command:
aquila-review discovery via post-review.mjs on AquilaXk/easysubway-data PR 909

📥 Commits

Reviewing files changed in this pull request between:

• Base: ad28cefa091ccb9089cc87a8a720cfd29f7008c7
• Head: faaa09b6925e889c16d4ee677208c7d55891984f

📒 Files selected for processing (7)

• tools/ci/data-test-ownership.json
• tools/datapack/publish-kric-station-timetables-raw.mjs
• tools/datapack/publish-kric-station-timetables-raw.test.mjs
• tools/datapack/register-kric-station-timetables.mjs
• tools/datapack/register-kric-station-timetables.test.mjs
• tools/datapack/source-candidate-endpoint-contract.test.mjs
• tools/datapack/source-candidates.json

📜 Review details

[github-actions]

No description provided.

[sonarqubecloud]

Quality Gate failed

Failed conditions
D Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE