FS 경로 규약 — dataset_variants ↔ 디렉토리 매핑

fs_walker / harness xdata fs-sync 의 행동 정본. 본 문서가 명시하지 않은 토큰/패턴은 자동 등록하지 않고 pending 으로 보류해 작업자 판단을 받는다.

1. 스코프

• 1차: KOR/MAIN (한국어 메인 TTS 서비스 카테고리).
• 후속: KOR/PERSONAL/{client}/..., AI_HUB_DATA/..., 타 언어 — 별 규약 추가.

2. 구조 (R1)

{storage_root}/{lang}/{service}/{gender}/{speaker_key}/base_phnseq/
  {phoneme_source}_xvoice{phoneme_source_version}/
    {utterance_style}[_{v1}[_{v2}...]]/

• lang ∈ {KOR} (스코프 내).
• service ∈ {MAIN}.
• gender ∈ {female, male}.
• speaker_key — ADR 0004, 불변. 디렉토리명 그대로 사용.
• base_phnseq — 고정 문자열. 없으면 해당 speaker 는 pending.
• phoneme_source + version — 디렉토리명 ^(.+?)_xvoice(\d+(?:\.\d+)?)$ 정규식 매칭. 예: manual_xvoice3.1 → source=manual, version=xvoice3.1.
• utterance_style — 마지막 디렉토리의 첫 세그먼트. §3 의 허용 집합에 속해야 한다.
• v1 ... vN — 축 값 토큰. §5 규약.

3. natural_key 매핑 (ADR 0007)

natural_key = "{speaker_key}/{lang}/{utterance_style}/{phoneme_source}"

허용 utterance_style (1차 스코프, 정규):

실험용 utterance_style (leaf 전체가 정확히 매칭되면 axes 분리 없이 통째로 채택, processed_version.experimental=true):

정규 enum / 실험 enum 어디에도 없는 값은 pending(unknown_utterance_style). 정본은 tools/xdata/fs_walker.py:KNOWN_UTTERANCE_STYLES 와 EXPERIMENTAL_UTTERANCE_STYLES.

4. processed_version 매핑

utterance_style 뒤 토큰들은 하나의 processed_version 을 구성:

processed_version:
  phoneme_encoding: <§5 참조>
  phoneme_source_version: "xvoice3.1"     # 디렉토리에서 추출
  preprocessing:
    breath: vanilla | reduce_brth | rm_brth
    trim: vanilla | trimIP | trim
    sample_rate: native | 16k
    sbert: vanilla | sbert
    perturbation: vanilla | perturb
  data_source: internal | internal_processed   # 조합에서 도출 (phase2 §16-A.3 A안)
  mfa_set: null        # 본 경로 규약 범위 밖 — 수작업 메타
  mfa_tnqst: false     # 본 경로 규약 범위 밖 — 수작업 메타
  paths: {server_162: "<local_path>"}
  updated_at: <mtime>

5. 디렉토리 suffix 네이밍 규약 (정본 — R1~R8)

워커(전처리 파이프라인) 는 본 절을 강제 준수한다. 위반 시 fs-sync 가 pending 버킷으로 분리하여 레지스트리 진입을 차단한다.

R1. 구조

{utterance_style}[_{v1}[_{v2}...]]

첫 세그먼트는 utterance_style, 이후는 축 값 (value-only, axis 이름 미노출).

R2. value 전역 unique

한 값은 정확히 한 축에만 속한다. 축 판별은 전역 token 레지스트리 tools/xdata/preprocessing.py 의 PREPROC_TOKEN_MAP + PHONEME_ENCODING_TOKENS 조회로 수행. 신규 값 도입 시 (a) 본 문서 R5 표 (b) 레지스트리를 동시 PR 로 추가한다.

R3. 토큰 순서 (고정, 생성 측 의무)

breath → trim → sample_rate → phoneme_encoding → sbert → perturbation

파서는 순서 무관 매칭이나, 전처리 파이프라인은 위 순서로 디렉토리명을 생성한다 (사람이 읽을 때 일관성 + 충돌 조기 감지).

R4. 기본값 생략

축 기본값(vanilla/native/full)은 경로에 쓰지 않는다.

• breath=vanilla & trim=vanilla & sample_rate=native & sbert=vanilla & perturbation=vanilla & subset=full & phoneme_encoding=ko_base → 디렉토리명 = common (단독).

R5. 허용 token 표 (초기 세트)

preprocessing 축

vad, vad2_1 토큰은 정규 매핑에서 빠져 있다. 디스크에 존재하더라도 fs-sync 는 unknown_suffix_tokens pending 으로 분리한다 (실험 그룹 자체로 인정되기 전 단계 — VAD 파이프라인 정합성 결정 후 재분류 예정).

실험(●) 축 = ADR 0008 에 정의된 EXPERIMENTAL_AXES(subset, sample_rate, perturbation, experiment_tag). 해당 축에 기본값이 아닌 토큰이 있으면 processed_version.experimental = true 로 기록되고 기본 export 에서 자동 제외된다 (§5 R8).

phoneme_encoding (processed_version 직속)

R6. 불법 패턴 예

참고: common_torchmel, common_16000, common_perturb_ipa 는 등록되어 있어 accepted (실험 pv 로 분류) — 미등록 token 예시로는 부적합.

R7. 준수 검증

1. 1차(자동 감시): fs-sync 실행 시 위반 variant 는 pending 리포트로 통지 — pending_<ts>.json.
2. 후속(선제 차단): scripts/lint_fs_paths.py (전처리 PR CI) — 신규 경로를 PR 단계에서 검증. 구현 시점은 운영 경험 축적 후 판단.

R8. 실험 축 / processed_version.experimental

• EXPERIMENTAL_AXES = (subset, sample_rate, perturbation, experiment_tag) 중 한 축이라도 기본값이 아니면 해당 processed_version 은 experimental=true 로 기록된다 (정본: tools/xdata/preprocessing.py:is_experimental).
• 또한 §3 의 실험용 utterance_style (novel_*, pat_16k, emotion 라벨 등) 로 매칭된 디렉토리는 자동으로 experimental=true (fs_walker._parse_style_dir 의 EXPERIMENTAL_UTTERANCE_STYLES 분기).
• 실험 pv 는 동일 natural_key 아래 vanilla pv 와 공존한다. version_key 가 실험 축(subset/experiment_tag) 을 포함하므로 해시 충돌 없이 별도 레코드로 저장.
• export 필터: variant.inclusion_policy != 'excluded' AND pv.experimental == false (ADR 0008). 실험 pv 는 별도 요청 없이는 기본 훈련셋에 편입되지 않음.
• 신규 실험 토큰 추가 시 §5.5 R5 표 + PREPROC_TOKEN_MAP / REGEX_TOKEN_MATCHERS / EXPERIMENTAL_AXES 동시 갱신 (§7 워크플로우 참조). 새 utterance_style 실험 그룹은 EXPERIMENTAL_UTTERANCE_STYLES 갱신.
• vad 축은 한때 정규 실험 축이었으나 (vad/vad2_1 토큰) 분류 정합성 정리 전 pending 으로 후퇴 — 디스크에 vad 디렉토리가 있으면 unknown_suffix_tokens 로 들어간다.

6. fallback / skip 규약

7. 신규 축/값 추가 워크플로우 (Q19)

새 전처리 단계가 디렉토리 suffix 로 노출될 때 따르는 절차:

1. spec 갱신 PR — 본 문서 R5 표에 값 + 의미 추가.
2. 레지스트리 갱신 — 같은 PR 에서 tools/xdata/preprocessing.py 의 PREPROC_TOKEN_MAP 또는 PHONEME_ENCODING_TOKENS 확장.
3. 축 신규 도입 시 — DEFAULT_PREPROCESSING 확장 + ADR 0007 추가 PR (스키마 변경이므로 별 ADR 필요).
4. 검증 — harness xdata fs-sync --dry-run 에서 관련 pending 이 added/modified 로 승격되는지 확인.

참조

• ADR 0007 — docs/decisions/0007-variant-natural-key-schema.md
• ADR 0008 — docs/decisions/0008-variant-inclusion-and-notes.md
• plan — docs/superpowers/plans/2026-04-24-fs-walker-registry-sync.md
• 기존 CLI 가이드 — xdata-guide.md