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

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

관련 결정:

• ADR 0002 — xdata primary = NocoDB
• ADR 0012 — natural_key 5-field + variation paradigm (supersedes ADR 0007)
• ADR 0008 — inclusion_policy / notes

1. 구성 요소

2. natural_key 스키마 (ADR 0012, supersedes ADR 0007)

{speaker_key}/{language}/{utterance_style}/{phoneme_source}/{variation}

예: bih/KOR/common/manual/vanilla (4번째 자리는 phoneme_source: manual/ip_info/ip_info2/raw 등 — phoneme_encoding(예: ko_ipa) 과 혼동 금지; 5번째 variation 은 variant 분할/처리 식별자 — vanilla default, 5h/10h/12h/20h ablation, 2023 maintenance — ADR-0012 catalog v1)

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/common/manual/vanilla \
  --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)

3 가지 모드 (정본 = metadata.sources[] 등록된 source 단위):

# 0) 백업 — 1회성 정정 시 .backups/{YYYY-MM-DD_label}/ 컨벤션
#    (registry pre-snapshot + NocoDB JSONL pair). 정기 ingest 는 nocodb_backup 만.
python -m tools.scripts.nocodb_backup --table dataset_variants --out-dir backups/nocodb

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

# 2) 적용 — accepted 만 upsert, pending 은 `pending_<ts>.json` 로 항상 분리
harness xdata fs-sync --project xvoice3 --all \
  --registry /HDD1/raymond/xvoice3/data_list/registry.v3.json \
  --reason "daily ingest 2026-05-20"

# 3) 단일 source 만 (다른 source 의 PV 는 보존, removed 무시)
harness xdata fs-sync --project xvoice3 --source xvoice3_main_local \
  --registry /HDD1/raymond/xvoice3/data_list/registry.v3.json

경로 규약은 wiki/tech/fs-path-convention.md §5 (R1~R8) 정본.

알려진 한계 (2026-05-20): --all 또는 --root 의 removed 는 registry 에서는 즉시 제거되지만 NocoDB upsert 대상에는 포함되지 않아 (cli.py upsert_targets = added + modified) NocoDB row 가 stale 로 잔존한다. 1회성 정정 시 delete_records_bulk 수동 정리 필요. 코드 트랙 → plan §9.3 묶음 D 큐 D-vi.

마이그레이션

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

4. NocoDB write-through 동작

parse/modify/update 는 tools.integrations.nocodb.writer.upsert_with_spool 로 dataset_variants (table_id: meeukod33twsor6) 에 natural_key 기준 write-through 한다 (GET-then-PATCH-or-POST, 중복 적재 차단 — fs-sync 와 동일 패턴).

• 네트워크·권한 예외는 전파하지 않는다.
• 실패 행은 $HARNESS_NOCODB_SPOOL_DIR (기본 ~/.harness/spool/) 에 JSONL 로 적재된다. 각 record 는 {"spooled_at", "row", "unique_column"} 형태로, unique_column 은 replay 가 upsert key 복원에 사용한다 (audit table 처럼 event_id 기준 스키마의 silent merge 방지).
• 킬 스위치 — HARNESS_NOCODB=disabled 면 즉시 스풀로 direct.
• 복구: python -m tools.integrations.nocodb.replay [--table ID] [--json]. 구 format record (pre-PR #41) 는 unique_column 메타가 없어 replay 가 _LEGACY_UNIQUE_COLUMN_FALLBACK (replay.py 정본) 매핑에 의존 — 등록 안 된 테이블의 record 는 skip+warn 으로 spool 에 보존된다.

컬럼 매핑:

• natural_key / project / speaker_key / inclusion_policy → 단순 필드
• context_profile → SingleSelect (운영자-curated, AI_HUB walker auto-emit + xvoice3 fs-sync preservation)
• processed_versions / derived_from / tags / notes / attrs → JSON 문자열(LongText)

processed_versions[].paths 의 키 의미 (server_tag 정본, 2026-05-19 정정):

• nfs_train — NFS 마운트의 절대 경로 (예: /HDD0/TRAIN_DATA_S98_01/...)
• server_162 — 162 서버 로컬 사본 경로 (예: /HDD1/raymond/data/...)
• 양쪽 키 모두 채워진 PV = 두 곳에 모두 존재하는 검증된 사본. 단일 키 PV = 한쪽에만 있음.

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"

수동·임의 변경 audit 기록

fs-sync 자동 경로(sync_run) 밖에서 NocoDB 를 직접 변경(client.upsert_record/ delete_records, 1회성 정정·복구)하면 audit 이 자동으로 남지 않아 추적 공백이 생긴다. 직접 변경 시 같은 작업에서 audit 을 emit 한다:

from tools.xdata import audit
# 예: registry 에는 있으나 NocoDB 에 누락된 variant 를 복구 등록 (old=None → variant_added)
events = audit.diff_variants(None, variant,
    reason="운영자 수동 복구 — …", source="cli:manual-restore")
audit.emit_all(events, client=client)  # dataset_variant_changes 에 기록

• 추가=variant_added, 삭제=variant_removed, 필드 변경=variant_field_changed (diff_variants 가 old/new 비교로 자동 분기).
• 새 event_type 도입 시 NocoDB event_type SingleSelect 옵션도 함께 추가해야 한다 — 코드 EVENT_TYPES 에만 있고 옵션에 없으면 write 가 거부되어 spool 에 적체된다 (variant_natural_key_migrated 838건 적체 사례).
• 1회성 정정 전체 절차(승인·백업·검증 포함)는 registry-manage SKILL §I 참조.

과거 이력 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.