xdata 가이드 — 멀티 프로젝트 데이터 레지스트리

tools/xdata/ 는 xvoice3 등 TTS 프로젝트들의 데이터(spk2path, context CSV)를 공통 스키마 플러그인 규약으로 파싱·관리한다. Primary 저장소는 NocoDB tts-data/dataset_variants 테이블이며(ADR 0002), 파일 레지스트리(JSON) 는 오프라인 재조회·재생성용 스냅샷으로 병행 저장된다.

관련 결정:

• ADR 0002 — xdata primary = NocoDB
• ADR 0007 — natural_key 4-field + processed_versions
• ADR 0008 — inclusion_policy / notes

1. 구성 요소

2. natural_key 스키마 (ADR 0007)

{speaker_id}/{language}/{utterance_style}/{phoneme_source}

예: bih/KOR/MAIN/manual (4번째 자리는 phoneme_source: manual/ip_info/ip_info2/raw 등 — phoneme_encoding(예: ko_ipa)과 혼동 금지)

phoneme_encoding / phoneme_source_version / preprocessing / data_source 는 variant 내부의 processed_versions[] 로 내려가서 한 variant 아래 여러 전처리 조합을 병렬 관리한다.

3. CLI 치트시트

모든 명령은 harness xdata … 또는 직접 xdata … 로 호출 가능.

등록 — 소스 파싱 후 레지스트리/NocoDB 신규 등록

harness xdata parse \
  --project xvoice3 \
  --registry /path/to/registry.v2.json \
  --source spk2path \
  --file /HDD0/data_list/spk2path.tsv \
  --storage-root nfs_train:/HDD0/TRAIN_DATA_S98_01 \
  --server server_162

수정 — 단일 variant 필드 갱신

harness xdata modify \
  --project xvoice3 \
  --registry /path/to/registry.v2.json \
  --key bih/KOR/MAIN/manual \
  --set inclusion_policy=excluded \
  --set 'notes=["outlier"]'

--set field=value 는 값을 JSON 으로 파싱 시도 후 실패하면 문자열로 저장한다.

업데이트 — 소스 재스캔 + diff 기반 reconcile

# 미리보기
harness xdata update --project xvoice3 --registry REG.json \
  --source spk2path --file NEW.tsv --dry-run

# 적용
harness xdata update --project xvoice3 --registry REG.json \
  --source spk2path --file NEW.tsv

Export — 포맷 변환

harness xdata export --project xvoice3 --registry REG.json \
  --format spk2path --out /tmp/spk2path.tsv --json

--json 은 {path, records, format} 메타만 stdout 으로 내보낸다 (본문은 파일).

조회/요약 (체이닝 계열)

harness xdata query --project xvoice3 --registry REG.json -f language=KOR --json
harness xdata view  --project xvoice3 --registry REG.json --json
harness xdata schemas list --json

FS sync — 파일시스템 → registry/NocoDB 정규 경로 (ground truth)

# 0) 백업 (apply 전에 항상 권장)
python -m tools.scripts.nocodb_backup --table dataset_variants --out-dir backups/nocodb

# 1) dry-run — added/modified/removed/pending_count + pending_report 경로
harness xdata fs-sync --project xvoice3 \
  --root server_162:/HDD0/TRAIN_DATA_S98_01 \
  --registry /HDD1/raymond/xvoice3/data_list/registry.v3.json \
  --dry-run

# 2) 적용 — accepted 만 upsert, pending 은 `pending_<ts>.json` 로 항상 분리
harness xdata fs-sync --project xvoice3 \
  --root server_162:/HDD0/TRAIN_DATA_S98_01 \
  --registry /HDD1/raymond/xvoice3/data_list/registry.v3.json

--root 포맷은 server_tag:/abs/path 단일. 경로 규약은 wiki/tech/fs-path-convention.md §5 (R1~R8) 정본.

마이그레이션

harness xdata migrate --registry OLD.json --out NEW.json

4. NocoDB write-through 동작

parse/modify/update 는 tools.integrations.nocodb.writer.post_with_spool 로 dataset_variants (table_id: meeukod33twsor6) 에 write-through 한다.

• 네트워크·권한 예외는 전파하지 않는다.
• 실패 행은 $HARNESS_NOCODB_SPOOL_DIR (기본 ~/.harness/spool/) 에 JSONL 로 적재된다.
• 킬 스위치 — HARNESS_NOCODB=disabled 면 즉시 스풀로 direct.
• 복구: python -m tools.integrations.nocodb.replay [--table ID] [--json].

컬럼 매핑:

• natural_key / project / speaker_key / inclusion_policy → 단순 필드
• processed_versions / derived_from / tags / notes / attrs → JSON 문자열(LongText)

5. Audit log — dataset_variant_changes

xdata 의 변경 이력은 NocoDB tts-data/dataset_variant_changes 테이블에 이벤트 row 로 기록된다 (table_id mryfgqxoe1643yg, unique=event_id). 현재 구현 기준 emit 경로는 fs-sync apply (sync_run 1건/실행) 만 배선되어 있으며, parse/modify/update 등 다른 CLI write 경로는 추후 PR 에서 배선 예정 — 그 사이 개별 variant/pv timeline 은 dataset_variants 의 inverted (variant|pv).last_change_event_id 로 추적한다.

설계 근거: docs/superpowers/plans/2026-04-24-registry-audit-log.md.

before / after 컬럼은 LongText 에 JSON 문자열로 저장. 빈 칸 = null (NocoDB Text nullable 관례) — consumer 는 cell and json.loads(cell) 패턴으로 파싱.

이벤트 유형

fs-sync 와의 통합

apply 경로 — fs-sync 1회당 sync_run 배치 이벤트 1건을 audit.emit 으로 기록한다. 변경된 variant/pv 에는 동일 event_id 가 variant_last_change_event_id / processed_versions[*].last_change_event_id 로 tagging 되어 timeline 추적이 가능하다. --reason 옵션으로 이벤트 사유를 명시할 수 있다 (기본값: "fs-sync").

harness xdata fs-sync --project xvoice3 \
  --root server_162:/HDD0/TRAIN_DATA_S98_01 \
  --registry /HDD1/raymond/xvoice3/data_list/registry.v3.json \
  --reason "daily ingest 2026-04-24"

과거 이력 import

python -m tools.scripts.import_legacy_changelog --dry-run
python -m tools.scripts.import_legacy_changelog --apply

event_id 는 (timestamp, natural_key, event_type, payload) 해시 → 재실행해도 upsert no-op. 기본 입력 경로는 /HDD1/raymond/xvoice3/data_list/registry_changelog.jsonl.

부트스트랩

python -m tools.scripts.nocodb_bootstrap_audit --probe
python -m tools.scripts.nocodb_bootstrap_audit --apply

6. 플러그인 등록

프로젝트 스키마는 배포 패키지의 [project.entry-points."xdata.schemas"] 섹션으로 등록한다. 예 (xvoice3/pyproject.toml):

[project.entry-points."xdata.schemas"]
xvoice3 = "xdata_plugin.schema"

해당 모듈은 탑레벨에서 @register_schema 를 호출해야 list_schemas() / CLI --project 에서 인식된다. 허용 목록을 좁히려면 XDATA_SCHEMAS="xvoice3" 환경변수 사용. 테스트·실험용 명시 모듈 로딩은 XDATA_SCHEMAS_MODULES.

7. 문제 해결

8. 개발자 노트

• CLI 는 argparse 전용이며 외부 의존성 없음.
• 모든 --json 은 체이닝 수요가 있는 하위명령(query/view/schemas + export 메타) 에만 달렸다. 쓰기·마이그레이션은 체이닝 대상 아님 (플랜 Q9).
• 테스트 — pytest tests/xdata/ tests/test_nocodb_*.py.