GitHub Actions workflow (.github/workflows/*.yml) 가 호출하는 Python 스크립트들. 도메인 동사별 sub-dir 로 분류.

repo 의 scripts/ (build/dev/audit 도구) 와 별개 — .github/scripts/ 는 Actions runner 에서만 호출된다.

.github/scripts/
├── _hfRetry.py             # HF API retry helper (sub-dir 5 개가 sys.path parent 로 접근)
├── sync/                   # HF ↔ 로컬 양방향 sync
├── prebuild/               # derived artifact build
├── meta/                   # 메타 데이터 (corp/kind list refresh)
├── search/                 # search index build
└── ops/                    # operational (monitor / plan)

4 개 스크립트 (sync/uploadData, sync/prebuildValuation, prebuild/prebuildData, search/buildSearchMain) 가 _hfRetry 사용. sub-dir 의 sys.path 가 부모를 못 잡으므로 다음 boilerplate:

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from _hfRetry import retryHfCall  # noqa: E402

랜딩/터미널(ui/packages/runtime 어댑터)이 HF 에서 직접 읽는 산출물. HF dir SSOT = src/dartlab/core/dataConfig.py DATA_RELEASES. 회사 단위 접근은 아래 두 패턴 중 하나 — 둘 다 stock_code(6자리)가 canonical 키(URL /company/{code}, 모든 per-company 산출물 공통).

패턴 1 — 회사별 파일 {code}.parquet|.json (큰 per-company 페이로드, 통째 읽기)

패턴 2 — 코드 파티션 또는 전역 파일 + stock_code 필터 (회사마다 얇은 슬라이스만 HTTP range read)

stock_code 가 파일에 박혀 정렬돼 있어야 pushdown 필터가 된다 — kindList/dartList 같은 매핑表로 대체 불가. 그 둘은 name↔corp_code↔stock_code 해소(검색·수집 시 stock_code 부착) 용 별도 lookup 이고, 이미 빌드된 데이터 파일을 회사별로 잘라주지는 못한다. allFilings 가 stock_code 키인 건 (a) pushdown 필터 키이자 (b) 패턴 1·전 UI 와 동일한 canonical 키라 일관.

패턴 3 — 연/날짜 샤드 + 필터: gov/prices/date/{year}.parquet(priceSource) · gov/indices/{index/{key}|date/{year}}.parquet(govIndexSource).

이관 주의(운영): byCode/manifest.json이 없는 첫 실행만 기존 recent.parquet를 읽어 코드 버킷을 만든다. 이후 cron은 이번 수집분에 등장한 버킷만 merge한다. legacy 파일은 안전한 UI 순차 배포용 fallback으로만 남고 더 이상 재생성하지 않는다.

1. 도메인 식별 → sync/·prebuild/·meta/·search/·ops/ 중 적절한 sub-dir 에 작성.
2. _hfRetry 사용 시 위 boilerplate 적용.
3. .github/workflows/<workflow>.yml 의 run: 라인에 .github/scripts/<domain>/<name>.py 경로 명시.
4. 본 README 의 도메인별 표에 행 추가.