ipakit 0.3.0__tar.gz → 0.4.0__tar.gz

{ipakit-0.3.0 → ipakit-0.4.0}/.github/workflows/ci.yml

@@ -209,7 +209,7 @@ jobs:
       - name: CLTS snapshot regeneration and exhaustive scorer parity
         env:
           IPAKIT_CLTS_DIR: ${{ github.workspace }}/.clts-source
-        run: pytest tests/test_clts_snapshot.py
+        run: pytest tests/test_clts_snapshot.py tests/test_clts_mapping.py tests/tiergraph/test_clts_profile.py
       - name: Comparison extras tests (partition check skips in the matrix job)
         run: pytest tests/test_comparison_example.py
 

{ipakit-0.3.0 → ipakit-0.4.0}/.pre-commit-config.yaml

@@ -53,7 +53,7 @@ repos:
       - id: mypy
         # Native GraphProfile subclasses need the same runtime types CI installs.
         # tests/test_ci_contract.py keeps this requirement equal to pyproject.
-        additional_dependencies: ["tiergraph>=0.3.0,<0.4.0"]
+        additional_dependencies: ["tiergraph>=0.4.0"]
         # NOT widened to match the others. `pyproject.toml` sets
         # `files = ["ipakit"]` deliberately, because the lint job installs
         # `.[lint]`, which has no pytest -- a scope reaching a test file

{ipakit-0.3.0 → ipakit-0.4.0}/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-29
+
+### Added
+
+- A JSON Schema and five canonical fixtures define the public CLTS import envelopes.
+- `unsupported="preserve"` keeps unsupported CLTS occurrences as source material instead of refusing the import.
+- `load_import` reloads a saved strict import only when a fresh import reproduces it exactly.
+- Public strict CLTS import now accepts explicit tokens; only reviewed plain stops (`p b t d`) import successfully, and every other occurrence is reported.
+- `InputLossWarning` is exported for callers that need to classify lossy public reads.
+- The CLTS mapping records its reviewed source-profile basis, and import compatibility refuses a different profile.
+- A final, verified CLTS core-BIPA receipt ships as `manifest.json`.
+- `ˢ`, `ʳ`, and `ʶ` write distinct sibilant, trilled, and uvular release values.
+- `ᵐ` writes the distinct `bilabial-nasal` release value; `ⁿ` remains generic nasal release.
+- `ipakit --version` prints the installed version.
+- `ipakit model transform` applies an explicit finite ternary-to-binary encoding and reports its preimage and loss evidence.
+- `ipakit model compare` compares original and explicitly selected binary encodings over exact token corpora.
+- Written `ːː` is the `overlong` value on the length scale. Each length step is now a quarter of the scale rather than a third; `confusion.json` and `metric_fingerprint` move, so a distance matrix saved before this change is read as a different feature space.
+- CLTS vowel and consonant duration declarations map to distinct house length values when the source asserts them.
+- The CLTS gap report records enhancement candidates, their evidence and dispositions, including the additions accepted for lane H.
+
+### Changed
+
+- The TIMIT map is generated from ipakit's transcription of NISTIR 4930 §4.3: `epi` is silence, the closures are unreleased stops, and `ux` and `ax-h` are mapped.
+- Requires tiergraph 0.4.0 or later.
+- eSpeak inventories are built from the user's eSpeak NG checkout (`IPAKIT_ESPEAK_NG` or an explicit path); no eSpeak-derived data ships.
+- PHOIBLE's GPL mapping tables are read from the user's PHOIBLE (`IPAKIT_PHOIBLE`); the CC BY-SA main data keeps shipping.
+- CLTS input documents refuse a second host for one tone, a duplicate relation, an unencodable raw, and an out-of-range integer time, each at its location.
+- Profile-bound CLTS eligibility now derives reviewed plain-stop projections and affricate-juncture refusals.
+- Profile-bound CLTS eligibility reports unattempted occurrences with the `not-attempted` reason.
+- Public soft-reader warnings are classified as input loss even when their warning location names the library caller.
+- PHOIBLE's shipped `manifest.json` now uses the shared source-receipt schema, and Panphon provenance lives only in its adjacent receipt.
+- Every CLI command declares the notation it reads, or that it reads none; the fourteen that read one without saying so now name it in their help.
+
+### Fixed
+
+- Rule changes can assign a declared feature value spelled `0`.
+- The X-SAMPA round-trip exception list covers every composition where a table key spans a unit boundary, and the README states the swept spaces exactly.
+- Postfix brace constraints conjoin with their base instead of overwriting it.
+- Reads refuse declared unspelled values instead of silently matching every unit or none.
+- Feature-valued CLTS release rules now state and enforce their source-assertion condition.
+- The public Form reader refuses declared source facts on a tier with no house unit.
+- Source-profile host relations preserve their supplied order through native graph restoration.
+- CLTS mapping dispositions use the reviewed audit classes, and segmental-release sequences state and enforce their host and juncture limits.
+- The CLTS declaration census refuses a same-kind value spelling declared under multiple features.
+- `ipakit corpus validate` exits 3 when a stored form holds a symbol the inventory does not register.
+- Assigning the declared unmarked `stress=none` value removes a written stress mark.
+- Empty and boundary-only forms return no inferred tier intervals instead of crashing.
+- Rest-posture lip, jaw and velum states reject unknown spellings.
+- The tract-anatomy guide describes and measures the current structured drawings.
+- Forms constructed from units use those units' custom inventory declarations in their graph facts.
+- An inventory refuses a declared unspelled value that one of its marks spells, and the metric anchors a prosodic feature at its declared unspelled value.
+
 ## [0.3.0] - 2026-09-23
 
 ### Added
@@ -389,6 +441,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Precomposed characters (`ã`) were dropped at ingest; decomposed `ç` misparsed as bare `c` (#8).
 - `docs/distance.md` states plainly that `distance` is not a metric.
 
-[Unreleased]: https://github.com/lenzo-ka/ipakit/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/lenzo-ka/ipakit/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/lenzo-ka/ipakit/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/lenzo-ka/ipakit/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/lenzo-ka/ipakit/releases/tag/v0.2.0

{ipakit-0.3.0 → ipakit-0.4.0}/MANIFEST.in

@@ -46,7 +46,11 @@ global-exclude *.py[cod] .DS_Store
 prune tests/.pytest_cache
 
 # Bridge declarations and the grammars stating their shape.
-recursive-include ipakit/data/bridges *.xml *.rng
+include ipakit/data/bridges/vocabulary.rng
+recursive-include ipakit/data/bridges/kana *.xml
+recursive-include ipakit/data/bridges/mfa *.xml
+recursive-include ipakit/data/bridges/pinyin *.xml
 recursive-include ipakit/data/textgrid *.json
-recursive-include ipakit/data/feature-models *.xml *.txt *.md
-recursive-include ipakit/data/phoible *.gz *.txt *.json
+recursive-include ipakit/data/feature-models *.xml *.txt *.md *-receipt.json
+recursive-include ipakit/data/phoible *.txt *.json
+recursive-include ipakit/data/phoible/data *.gz

{ipakit-0.3.0 → ipakit-0.4.0}/Makefile

@@ -16,12 +16,12 @@ HEAD   ?= adult-male
 # put IPA; the symbol it draws is in the second column.
 FIGURES := m:m n:n eng:ŋ t:t k:k theta:θ s:s esh:ʃ a:a i:i u:u silence:␣
 
-.PHONY: figures figures-clean tutorial tutorial-basics notebook inventory-cards inventory-cards-check house-style perceptual-validation state-of-work espeak-vocabularies espeak-vocabularies-check mfa-vocabularies mfa-vocabularies-check panphon-geometry-check lint check gate-subject
+.PHONY: figures figures-clean tutorial tutorial-basics notebook inventory-cards inventory-cards-check house-style perceptual-validation state-of-work espeak-vocabularies espeak-vocabularies-check mfa-vocabularies mfa-vocabularies-check timit-map timit-map-check panphon-geometry-check lint check gate-subject
 
 ESPEAK_NG ?= $(HOME)/dev/other/espeak-ng
 MFA_MODELS ?= $(HOME)/.cache/ipakit/mfa-models
 
-## espeak-vocabularies: regenerate every language-scoped eSpeak declaration
+## espeak-vocabularies: validate user-sourced declarations and refresh the summary
 espeak-vocabularies:
 	@if test ! -d "$(ESPEAK_NG)/.git"; then \
 		echo "espeak-vocabularies: pinned checkout absent; nothing regenerated"; \
@@ -51,19 +51,25 @@ mfa-vocabularies-check:
 		$(PYTHON) scripts/mfa_vocabularies.py check --source "$(MFA_MODELS)"; \
 	fi
 
+timit-map:
+	@$(PYTHON) scripts/timit_map.py generate --write
+
+timit-map-check:
+	@$(PYTHON) scripts/timit_map.py check
+
 ## inventory-cards: regenerate docs/inventories.md from declarations and counts
 inventory-cards:
 	@if test ! -f "$(MFA_MODELS)/dictionary/english/us_mfa/english_us_mfa.dict"; then \
 		echo "inventory-cards: pinned MFA dictionary absent; nothing regenerated"; \
 	else \
-		$(PYTHON) scripts/inventory_cards.py build --mfa-models "$(MFA_MODELS)"; \
+		IPAKIT_ESPEAK_NG="$(ESPEAK_NG)" $(PYTHON) scripts/inventory_cards.py build --mfa-models "$(MFA_MODELS)"; \
 	fi
 
 inventory-cards-check:
 	@if test ! -f "$(MFA_MODELS)/dictionary/english/us_mfa/english_us_mfa.dict"; then \
 		echo "inventory-cards: pinned MFA dictionary absent; generated-document check skipped"; \
 	else \
-		$(PYTHON) scripts/inventory_cards.py check --mfa-models "$(MFA_MODELS)"; \
+		IPAKIT_ESPEAK_NG="$(ESPEAK_NG)" $(PYTHON) scripts/inventory_cards.py check --mfa-models "$(MFA_MODELS)"; \
 	fi
 
 panphon-geometry-check:
@@ -177,6 +183,7 @@ check: gate-subject lint
 	@$(NICE) $(PYTHON) scripts/state_of_work.py check
 	@$(MAKE) --no-print-directory espeak-vocabularies-check
 	@$(MAKE) --no-print-directory mfa-vocabularies-check
+	@$(MAKE) --no-print-directory timit-map-check
 	@$(MAKE) --no-print-directory panphon-geometry-check
 	@$(MAKE) --no-print-directory inventory-cards-check
 	@PYTHONHASHSEED=0 $(NICE) $(PYTHON) scripts/tutorial.py check all

{ipakit-0.3.0 → ipakit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipakit
-Version: 0.3.0
+Version: 0.4.0
 Summary: IPA toolkit: phonetic features, distance, tokenization, rules, and conversions
 Author: Kevin Lenzo
 License-Expression: BSD-2-Clause
@@ -22,11 +22,12 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tiergraph<0.4.0,>=0.3.0
+Requires-Dist: tiergraph>=0.4.0
 Provides-Extra: test
 Requires-Dist: pytest>=9.1.1; extra == "test"
 Requires-Dist: pytest-xdist>=3.8.0; extra == "test"
 Requires-Dist: lxml>=6.1.2; extra == "test"
+Requires-Dist: jsonschema>=4.26.0; extra == "test"
 Requires-Dist: packaging>=24.2; extra == "test"
 Requires-Dist: PyYAML<7,>=6.0.3; extra == "test"
 Requires-Dist: setuptools>=84.0.0; extra == "test"
@@ -88,7 +89,7 @@ derived forms, expose structural queries at the shell, and test rule systems
 against paired forms. That is also the substrate on which rule induction can
 run; the inducer itself remains a separate concern.
 
-Praat TextGrids enter and leave through named tier profiles, including an MFA alignment profile. The shipped [inventory registry](https://github.com/lenzo-ka/ipakit/blob/main/docs/inventories.md) includes the pinned MFA phone declarations and eSpeak NG vocabularies, and [TextGrid interchange](https://github.com/lenzo-ka/ipakit/blob/main/docs/textgrid.md) applies those inventory styles to tier labels without guessing.
+Praat TextGrids enter and leave through named tier profiles, including an MFA alignment profile. The [inventory registry](https://github.com/lenzo-ka/ipakit/blob/main/docs/inventories.md) includes pinned MFA phone declarations and adds eSpeak NG vocabularies from a user-supplied checkout, while [TextGrid interchange](https://github.com/lenzo-ka/ipakit/blob/main/docs/textgrid.md) applies those inventory styles to tier labels without guessing.
 
 The package uses tiergraph for graph navigation; its phonetic data and geometry
 ship as declarations. It is typed, and the Python API and `ipakit` command expose the
@@ -305,11 +306,27 @@ A word comparison reports `coverage` — the shorter token count over the longer
   onset: `from_cmu(["K", "AE1", "T"])` → `kˈæt`. Syllabification is preserved
   across round trips (`W AO1 T ER0` ↔ `wˈɔtɚ`).
 - **Ties are typed** (house convention; see [docs/ties.md](https://github.com/lenzo-ka/ipakit/blob/main/docs/ties.md)): the over-tie fuses constituents into one timing slot (affricates and double articulations: `t͡ʃ`, `k͡p`), the under-tie binds a sequence into one unit (diphthongs, morae: `e͜ɪ`, `a͜ɪ͜ə`), and the over-tie binds tighter in mixed chains (`t͡s͜a`). The glyph is authoritative everywhere; text written in other conventions (where the glyphs are typographic variants, and where the keyboard stands in for the phonetic alphabet) imports explicitly via `ipakit.from_wild` — default parsing never rewrites its input. Tie *presence* is contrastive: `t͡s` is one segment, `ts` is a cluster.
-- **Round-trip guarantee (X-SAMPA only):** IPA written in these conventions round-trips through X-SAMPA (`ipa → xsampa → ipa`), **up to tie sense**: X-SAMPA has a single tie encoding, so the under-tie projects onto the over-tie at the boundary and round trips return canonical over-tie spellings (`t͜s → t_s → t͡s`); the sequential/simultaneous distinction survives only in IPA. Every other exception is enumerated here, and the suite asserts the round-trip failure set is *exactly* this list over two spaces — the registered inventory, and the composed forms built from it (every registered base carrying one registered mark, in either position; every adjacent pair of bases) — so nothing can join it in silence. The accepted ligature alias spellings (`ʧ`, `ʦ`, `ƛ`) convert as the thing they spell and come back canonical; they sit outside that inventory, so a second test sweeps the alias map to keep them out of the dropped set.
+- **Round-trip guarantee (X-SAMPA only):** IPA written in these conventions round-trips through X-SAMPA (`ipa → xsampa → ipa`), **up to tie sense**: X-SAMPA has a single tie encoding, so the under-tie projects onto the over-tie at the boundary and round trips return canonical over-tie spellings (`t͜s → t_s → t͡s`); the sequential/simultaneous distinction survives only in IPA. Every exception in the tested spaces is enumerated here, and the suite asserts the failure set is *exactly* this list. Those spaces are the registered inventory; every registered base with one registered mark in either position; every ordered pair of registered bases; and the finite local boundary-spanning windows derived from the X-SAMPA table. A local window factors each reverse key across two or more forward-table outputs of registered bases and encodable marks (the structural ties and boundaries are left to the composed-form space), keeps an overshooting final output and every factorization of the result, and admits the resulting base run, base-plus-marks unit, or mark run on neutral carrier `a`; runs are bounded by those factorizations. An exhaustive check of every two- and three-atom sequence made from the participating bases and marks also verifies that a greedy match which starts inside an output follows an already enumerated first divergence. This is a claim about those finite spaces, not arbitrary surrounding context. The accepted ligature alias spellings (`ʧ`, `ʦ`, `ƛ`) convert as the thing they spell and come back canonical; they sit outside the registered inventory, so a separate test sweeps the alias map to keep them out of the dropped set.
   - *Ambiguous* — `b͡v`, `t͡θ`, `ŋ͡m` come back as `b̬`, `t˥`, `ŋ̻`: the tie encoding `_` collides with a diacritic/tone encoding (`_v`, `_T`, `_m`). Inherent to X-SAMPA; ICU shares it.
-  - *Ambiguous on composition* (see [docs/ties.md](https://github.com/lenzo-ka/ipakit/blob/main/docs/ties.md)) — the table is not prefix-free, so a join between two encodings can spell a key a third entry already claims and longest-match reads that one. `` ` `` is both the rhotacized modifier and X-SAMPA's retroflex suffix, so a base plus `ʴ` spells the retroflex phone and the sound changes: `dʴ lʴ nʴ rʴ sʴ tʴ zʴ ɹʴ t͡sʴ d͡zʴ` come back `ɖ ɭ ɳ ɽ ʂ ʈ ʐ ɻ t͡ʂ d͡ʐ`. `ǀǀ → ǁ` and `ǀǁ → ǁǀ`, because `|\|\` (the alveolar lateral click) is two `|\` (the dental one). In three more the sound survives and only a redundant spelling of it does not — `əʴ → ɚ`, `ɜʴ → ɝ`, `tʼ → ť` — which is the canonicalization `from_wild` is there to do, X-SAMPA being an ASCII convention for writing IPA rather than a phoneset beside it. Writing loses nothing at a join (`to_xsampa` of a join is the join of the `to_xsampa`s, over both spaces), so each of these is the reader re-segmenting, not the writer dropping.
+  - *Ambiguous on composition* (see [docs/ties.md](https://github.com/lenzo-ka/ipakit/blob/main/docs/ties.md)) — the table is not prefix-free, so a join between two encodings can spell a key a third entry already claims and longest-match reads that one. `` ` `` is both the rhotacized modifier and X-SAMPA's retroflex suffix, so a base plus `ʴ` spells the retroflex phone and the sound changes: `dʴ lʴ nʴ rʴ sʴ tʴ zʴ ɹʴ t͡sʴ d͡zʴ` come back `ɖ ɭ ɳ ɽ ʂ ʈ ʐ ɻ t͡ʂ d͡ʐ`. `ǀǀ → ǁ`, `ǀǁ → ǁǀ`, and `ǀǀǀ → ǁǀ`, because `|\|\` (the alveolar lateral click) is two `|\` (the dental one). The length marks collide the same way: `aːˑ → aːː`: the extra-long key `::` consumes the long mark `:` and the colon of the following half-long `:\`, and the reader reports the leftover backslash as input loss. The retroflex and click keys are X-SAMPA's own.
+  - *Redundant on composition* — in three existing cases the sound survives and only a redundant spelling of it does not: `əʴ → ɚ`, `ɜʴ → ɝ`, `tʼ → ť`. The table-derived tone windows below do the same thing: each returned contour spelling declares exactly the same ordered tone levels as its source. The keys that cause them (`_M_H`, `_H_M`, `_L_M`, `_M_L`, `_L_H_L`, `_H_L_H`) are ipakit's own spellings for the contour diacritics, written as the runs of level bars they name; standard X-SAMPA and ICU spell those contours differently. Unlike `_hh` below, they change no value, so they stay. These are the canonicalization `from_wild` is there to do, X-SAMPA being an ASCII convention for writing IPA rather than a phoneset beside it. Writing loses nothing at the joins in the swept spaces, so each is the reader re-segmenting, not the writer dropping.
+
+    ```text
+    a˦˧ → a᷇       a˦˧˦ → a᷇˦       a˦˧˨ → a᷇˨
+    a˦˨˦ → a᷉      a˦˨˦˧ → a᷉˧      a˦˨˦˨ → a᷉˨
+    a˦˨˦˨˦ → a᷉˨˦  a˦˨᷇ → a᷉˧       a˦˨᷉ → a᷉˨˦
+    a˦᷄ → a᷇˦      a˦᷆ → a᷇˨      a˦᷈ → a᷉˨
+    a˦᷈˦ → a᷉˨˦    a˧˦ → a᷄       a˧˦˧ → a᷄˧
+    a˧˦˨˦ → a᷄˨˦   a˧˨ → a᷆       a˧˨˦˨ → a᷆˦˨
+    a˧˨˧ → a᷆˧     a˧᷅ → a᷆˧      a˧᷇ → a᷄˧
+    a˧᷈ → a᷆˦˨    a˧᷉ → a᷄˨˦     a˨˦˨ → a᷈
+    a˨˦˨˦ → a᷈˦    a˨˦˨˦˨ → a᷈˦˨  a˨˦˨˧ → a᷈˧
+    a˨˦᷅ → a᷈˧     a˨˦᷈ → a᷈˦˨    a˨˧ → a᷅
+    a˨˧˦ → a᷅˦     a˨˧˨ → a᷅˨     a˨᷄ → a᷅˦
+    a˨᷆ → a᷅˨      a˨᷉ → a᷈˦      a˨᷉˨ → a᷈˦˨
+    ```
   - *Redundant spelling* — `˞`, `̀`, `́`, `̄`, `ʻ` are dropped: X-SAMPA has one encoding where IPA has two, and in a bijective table it belongs to the house-canonical spelling — `ʴ` (`` ` ``), the tone bars `˨`/`˦`/`˧` (`_L`/`_H`/`_M`), `ʰ` (`_h`). Written that way, the sound round-trips exactly.
-  - *Unencodable* — `ⱱ`, `ˀ`, `ᵊ`, `͈`, `^` are dropped: X-SAMPA has no notation for the labiodental flap (X-SAMPA predates the IPA's 2005 adoption of the symbol, and the standard chart marks that cell as having none), for glottalization, schwa release, or extIPA strong articulation, and unit prominence is house IPA notation that X-SAMPA never had. An invented spelling would collide with notation already in use, so these stay unmapped rather than approximated.
+  - *Unencodable* — `ⱱ`, `ˀ`, `ᵊ`, `ᵐ`, `ˢ`, `ʳ`, `ʶ`, `͈`, `^` are dropped: X-SAMPA has no notation for the labiodental flap (X-SAMPA predates the IPA's 2005 adoption of the symbol, and the standard chart marks that cell as having none), for glottalization, schwa release, bilabial nasal release, sibilant release, trilled release, uvular release, or extIPA strong articulation, and unit prominence is house IPA notation that X-SAMPA never had. `_n` already means generic nasal release and `_m` means laminal, so neither can preserve `ᵐ`'s distinction; existing s, r, and uvular spellings describe whole segments rather than these release phases. Invented spellings would collide with notation already in use, so these stay unmapped rather than approximated.
   - *Declined rather than impossible* — `ʱ` is dropped too, and for a different reason worth keeping separate from the four above. It had a curated encoding, `_hh`, which extended X-SAMPA's `_h`, so `ʰh` and `ʰɦ` both read back as `ʱ`: an ambiguity ipakit introduced rather than one the standard has. IPA is the primary notation and X-SAMPA a convenience, so declining to spell one mark there costs less than inventing an ambiguity to keep it.
 
   A dropped symbol takes its neighbors' adjacency with it (`kⱱt → kt`), which is what `strict=True` is for: `to_xsampa("kⱱt", strict=True)` raises `ValueError` naming the symbol instead. The CMU, TIMIT, and Kirshenbaum mappings are lossy (they collapse IPA distinctions) and carry no round-trip guarantee; Kirshenbaum has no labiodental-flap notation either.
@@ -376,5 +393,7 @@ table and the phone-distance matrix) against their generators in `scripts/`.
 ## License
 
 BSD 2-Clause — see [LICENSE](https://github.com/lenzo-ka/ipakit/blob/main/LICENSE).
-Third-party data retain their separate terms; the shipped PHOIBLE source
-aggregate carries [file-scoped notices and licenses](ipakit/data/phoible/NOTICE.txt).
+Third-party data retain their separate terms; the shipped PHOIBLE dataset and
+bibliography carry [file-scoped notices and licenses](ipakit/data/phoible/NOTICE.txt).
+PHOIBLE mapping tables and eSpeak phoneme tables are read from user-supplied
+sources and are not included in the wheel.

{ipakit-0.3.0 → ipakit-0.4.0}/README.md

@@ -37,7 +37,7 @@ derived forms, expose structural queries at the shell, and test rule systems
 against paired forms. That is also the substrate on which rule induction can
 run; the inducer itself remains a separate concern.
 
-Praat TextGrids enter and leave through named tier profiles, including an MFA alignment profile. The shipped [inventory registry](https://github.com/lenzo-ka/ipakit/blob/main/docs/inventories.md) includes the pinned MFA phone declarations and eSpeak NG vocabularies, and [TextGrid interchange](https://github.com/lenzo-ka/ipakit/blob/main/docs/textgrid.md) applies those inventory styles to tier labels without guessing.
+Praat TextGrids enter and leave through named tier profiles, including an MFA alignment profile. The [inventory registry](https://github.com/lenzo-ka/ipakit/blob/main/docs/inventories.md) includes pinned MFA phone declarations and adds eSpeak NG vocabularies from a user-supplied checkout, while [TextGrid interchange](https://github.com/lenzo-ka/ipakit/blob/main/docs/textgrid.md) applies those inventory styles to tier labels without guessing.
 
 The package uses tiergraph for graph navigation; its phonetic data and geometry
 ship as declarations. It is typed, and the Python API and `ipakit` command expose the
@@ -254,11 +254,27 @@ A word comparison reports `coverage` — the shorter token count over the longer
   onset: `from_cmu(["K", "AE1", "T"])` → `kˈæt`. Syllabification is preserved
   across round trips (`W AO1 T ER0` ↔ `wˈɔtɚ`).
 - **Ties are typed** (house convention; see [docs/ties.md](https://github.com/lenzo-ka/ipakit/blob/main/docs/ties.md)): the over-tie fuses constituents into one timing slot (affricates and double articulations: `t͡ʃ`, `k͡p`), the under-tie binds a sequence into one unit (diphthongs, morae: `e͜ɪ`, `a͜ɪ͜ə`), and the over-tie binds tighter in mixed chains (`t͡s͜a`). The glyph is authoritative everywhere; text written in other conventions (where the glyphs are typographic variants, and where the keyboard stands in for the phonetic alphabet) imports explicitly via `ipakit.from_wild` — default parsing never rewrites its input. Tie *presence* is contrastive: `t͡s` is one segment, `ts` is a cluster.
-- **Round-trip guarantee (X-SAMPA only):** IPA written in these conventions round-trips through X-SAMPA (`ipa → xsampa → ipa`), **up to tie sense**: X-SAMPA has a single tie encoding, so the under-tie projects onto the over-tie at the boundary and round trips return canonical over-tie spellings (`t͜s → t_s → t͡s`); the sequential/simultaneous distinction survives only in IPA. Every other exception is enumerated here, and the suite asserts the round-trip failure set is *exactly* this list over two spaces — the registered inventory, and the composed forms built from it (every registered base carrying one registered mark, in either position; every adjacent pair of bases) — so nothing can join it in silence. The accepted ligature alias spellings (`ʧ`, `ʦ`, `ƛ`) convert as the thing they spell and come back canonical; they sit outside that inventory, so a second test sweeps the alias map to keep them out of the dropped set.
+- **Round-trip guarantee (X-SAMPA only):** IPA written in these conventions round-trips through X-SAMPA (`ipa → xsampa → ipa`), **up to tie sense**: X-SAMPA has a single tie encoding, so the under-tie projects onto the over-tie at the boundary and round trips return canonical over-tie spellings (`t͜s → t_s → t͡s`); the sequential/simultaneous distinction survives only in IPA. Every exception in the tested spaces is enumerated here, and the suite asserts the failure set is *exactly* this list. Those spaces are the registered inventory; every registered base with one registered mark in either position; every ordered pair of registered bases; and the finite local boundary-spanning windows derived from the X-SAMPA table. A local window factors each reverse key across two or more forward-table outputs of registered bases and encodable marks (the structural ties and boundaries are left to the composed-form space), keeps an overshooting final output and every factorization of the result, and admits the resulting base run, base-plus-marks unit, or mark run on neutral carrier `a`; runs are bounded by those factorizations. An exhaustive check of every two- and three-atom sequence made from the participating bases and marks also verifies that a greedy match which starts inside an output follows an already enumerated first divergence. This is a claim about those finite spaces, not arbitrary surrounding context. The accepted ligature alias spellings (`ʧ`, `ʦ`, `ƛ`) convert as the thing they spell and come back canonical; they sit outside the registered inventory, so a separate test sweeps the alias map to keep them out of the dropped set.
   - *Ambiguous* — `b͡v`, `t͡θ`, `ŋ͡m` come back as `b̬`, `t˥`, `ŋ̻`: the tie encoding `_` collides with a diacritic/tone encoding (`_v`, `_T`, `_m`). Inherent to X-SAMPA; ICU shares it.
-  - *Ambiguous on composition* (see [docs/ties.md](https://github.com/lenzo-ka/ipakit/blob/main/docs/ties.md)) — the table is not prefix-free, so a join between two encodings can spell a key a third entry already claims and longest-match reads that one. `` ` `` is both the rhotacized modifier and X-SAMPA's retroflex suffix, so a base plus `ʴ` spells the retroflex phone and the sound changes: `dʴ lʴ nʴ rʴ sʴ tʴ zʴ ɹʴ t͡sʴ d͡zʴ` come back `ɖ ɭ ɳ ɽ ʂ ʈ ʐ ɻ t͡ʂ d͡ʐ`. `ǀǀ → ǁ` and `ǀǁ → ǁǀ`, because `|\|\` (the alveolar lateral click) is two `|\` (the dental one). In three more the sound survives and only a redundant spelling of it does not — `əʴ → ɚ`, `ɜʴ → ɝ`, `tʼ → ť` — which is the canonicalization `from_wild` is there to do, X-SAMPA being an ASCII convention for writing IPA rather than a phoneset beside it. Writing loses nothing at a join (`to_xsampa` of a join is the join of the `to_xsampa`s, over both spaces), so each of these is the reader re-segmenting, not the writer dropping.
+  - *Ambiguous on composition* (see [docs/ties.md](https://github.com/lenzo-ka/ipakit/blob/main/docs/ties.md)) — the table is not prefix-free, so a join between two encodings can spell a key a third entry already claims and longest-match reads that one. `` ` `` is both the rhotacized modifier and X-SAMPA's retroflex suffix, so a base plus `ʴ` spells the retroflex phone and the sound changes: `dʴ lʴ nʴ rʴ sʴ tʴ zʴ ɹʴ t͡sʴ d͡zʴ` come back `ɖ ɭ ɳ ɽ ʂ ʈ ʐ ɻ t͡ʂ d͡ʐ`. `ǀǀ → ǁ`, `ǀǁ → ǁǀ`, and `ǀǀǀ → ǁǀ`, because `|\|\` (the alveolar lateral click) is two `|\` (the dental one). The length marks collide the same way: `aːˑ → aːː`: the extra-long key `::` consumes the long mark `:` and the colon of the following half-long `:\`, and the reader reports the leftover backslash as input loss. The retroflex and click keys are X-SAMPA's own.
+  - *Redundant on composition* — in three existing cases the sound survives and only a redundant spelling of it does not: `əʴ → ɚ`, `ɜʴ → ɝ`, `tʼ → ť`. The table-derived tone windows below do the same thing: each returned contour spelling declares exactly the same ordered tone levels as its source. The keys that cause them (`_M_H`, `_H_M`, `_L_M`, `_M_L`, `_L_H_L`, `_H_L_H`) are ipakit's own spellings for the contour diacritics, written as the runs of level bars they name; standard X-SAMPA and ICU spell those contours differently. Unlike `_hh` below, they change no value, so they stay. These are the canonicalization `from_wild` is there to do, X-SAMPA being an ASCII convention for writing IPA rather than a phoneset beside it. Writing loses nothing at the joins in the swept spaces, so each is the reader re-segmenting, not the writer dropping.
+
+    ```text
+    a˦˧ → a᷇       a˦˧˦ → a᷇˦       a˦˧˨ → a᷇˨
+    a˦˨˦ → a᷉      a˦˨˦˧ → a᷉˧      a˦˨˦˨ → a᷉˨
+    a˦˨˦˨˦ → a᷉˨˦  a˦˨᷇ → a᷉˧       a˦˨᷉ → a᷉˨˦
+    a˦᷄ → a᷇˦      a˦᷆ → a᷇˨      a˦᷈ → a᷉˨
+    a˦᷈˦ → a᷉˨˦    a˧˦ → a᷄       a˧˦˧ → a᷄˧
+    a˧˦˨˦ → a᷄˨˦   a˧˨ → a᷆       a˧˨˦˨ → a᷆˦˨
+    a˧˨˧ → a᷆˧     a˧᷅ → a᷆˧      a˧᷇ → a᷄˧
+    a˧᷈ → a᷆˦˨    a˧᷉ → a᷄˨˦     a˨˦˨ → a᷈
+    a˨˦˨˦ → a᷈˦    a˨˦˨˦˨ → a᷈˦˨  a˨˦˨˧ → a᷈˧
+    a˨˦᷅ → a᷈˧     a˨˦᷈ → a᷈˦˨    a˨˧ → a᷅
+    a˨˧˦ → a᷅˦     a˨˧˨ → a᷅˨     a˨᷄ → a᷅˦
+    a˨᷆ → a᷅˨      a˨᷉ → a᷈˦      a˨᷉˨ → a᷈˦˨
+    ```
   - *Redundant spelling* — `˞`, `̀`, `́`, `̄`, `ʻ` are dropped: X-SAMPA has one encoding where IPA has two, and in a bijective table it belongs to the house-canonical spelling — `ʴ` (`` ` ``), the tone bars `˨`/`˦`/`˧` (`_L`/`_H`/`_M`), `ʰ` (`_h`). Written that way, the sound round-trips exactly.
-  - *Unencodable* — `ⱱ`, `ˀ`, `ᵊ`, `͈`, `^` are dropped: X-SAMPA has no notation for the labiodental flap (X-SAMPA predates the IPA's 2005 adoption of the symbol, and the standard chart marks that cell as having none), for glottalization, schwa release, or extIPA strong articulation, and unit prominence is house IPA notation that X-SAMPA never had. An invented spelling would collide with notation already in use, so these stay unmapped rather than approximated.
+  - *Unencodable* — `ⱱ`, `ˀ`, `ᵊ`, `ᵐ`, `ˢ`, `ʳ`, `ʶ`, `͈`, `^` are dropped: X-SAMPA has no notation for the labiodental flap (X-SAMPA predates the IPA's 2005 adoption of the symbol, and the standard chart marks that cell as having none), for glottalization, schwa release, bilabial nasal release, sibilant release, trilled release, uvular release, or extIPA strong articulation, and unit prominence is house IPA notation that X-SAMPA never had. `_n` already means generic nasal release and `_m` means laminal, so neither can preserve `ᵐ`'s distinction; existing s, r, and uvular spellings describe whole segments rather than these release phases. Invented spellings would collide with notation already in use, so these stay unmapped rather than approximated.
   - *Declined rather than impossible* — `ʱ` is dropped too, and for a different reason worth keeping separate from the four above. It had a curated encoding, `_hh`, which extended X-SAMPA's `_h`, so `ʰh` and `ʰɦ` both read back as `ʱ`: an ambiguity ipakit introduced rather than one the standard has. IPA is the primary notation and X-SAMPA a convenience, so declining to spell one mark there costs less than inventing an ambiguity to keep it.
 
   A dropped symbol takes its neighbors' adjacency with it (`kⱱt → kt`), which is what `strict=True` is for: `to_xsampa("kⱱt", strict=True)` raises `ValueError` naming the symbol instead. The CMU, TIMIT, and Kirshenbaum mappings are lossy (they collapse IPA distinctions) and carry no round-trip guarantee; Kirshenbaum has no labiodental-flap notation either.
@@ -325,5 +341,7 @@ table and the phone-distance matrix) against their generators in `scripts/`.
 ## License
 
 BSD 2-Clause — see [LICENSE](https://github.com/lenzo-ka/ipakit/blob/main/LICENSE).
-Third-party data retain their separate terms; the shipped PHOIBLE source
-aggregate carries [file-scoped notices and licenses](ipakit/data/phoible/NOTICE.txt).
+Third-party data retain their separate terms; the shipped PHOIBLE dataset and
+bibliography carry [file-scoped notices and licenses](ipakit/data/phoible/NOTICE.txt).
+PHOIBLE mapping tables and eSpeak phoneme tables are read from user-supplied
+sources and are not included in the wheel.

{ipakit-0.3.0 → ipakit-0.4.0}/conftest.py

@@ -9,10 +9,34 @@ per session (rather than once per test) keeps the suite fast. The instances are
 treated as read-only by the tests, so sharing them across tests is safe.
 """
 
+import os
+
 import pytest
 from ipakit import CMUMapper, IPAFeatures
 
 
+def pytest_collection_modifyitems(items):  # type: ignore[no-untyped-def]
+    """Skip source-dependent eSpeak integration tests when no source is supplied."""
+    if os.environ.get("IPAKIT_ESPEAK_NG"):
+        return
+    reason = "set IPAKIT_ESPEAK_NG to run tests requiring eSpeak NG source"
+    for item in items:
+        path = item.path.name
+        if (
+            path == "test_espeak_binary.py"
+            or (
+                path in {"test_bridges.py", "test_inventories.py"}
+                and (
+                    "espeak" in item.name
+                    or item.name == "test_styles_normalize_canonically_equivalent_input"
+                )
+                and item.name != "test_espeak_requires_user_source"
+            )
+            or (path == "test_phoneset_comparison.py" and "espeak" in item.nodeid)
+        ):
+            item.add_marker(pytest.mark.skip(reason=reason))
+
+
 @pytest.fixture(autouse=True)
 def _doctest_ipakit(doctest_namespace):  # type: ignore[no-untyped-def]
     import ipakit

{ipakit-0.3.0 → ipakit-0.4.0}/docs/README.md

@@ -40,18 +40,19 @@ keep source distinctions, coverage and conversion losses explicit.
 | --- | --- |
 | [Comparative systems](systems.md) | Compare organizing principles and implemented boundaries across models. |
 | [Inventories and styles](inventories.md) | Named vocabularies, strict reading/spelling and dictionary-derived inventories. |
-| [PHOIBLE source inventories](phoible.md) | Shipped complete source catalog, explicit checkout overrides, doculect provenance and import refusals. |
+| [PHOIBLE source inventories](phoible.md) | Shipped main catalog, user-supplied mapping tables, doculect provenance and import refusals. |
 | [Inventory supplements](supplements.md) | Extend the house declaration and understand the effects on realization and comparison. |
 | [Pinyin](pinyin.md) | Syllable-hosted tone, orthographic rendering and the internal graph-constructor boundary. |
 | [Kana](kana.md) | Mora-tier rendering and bounded curated-adaptation API/CLI support. |
 | [CLTS/BIPA](clts-audit.md) | Frozen native feature-set/Jaccard scoring, shared cost comparisons, source extraction and provenance; semantic mapping remains unresolved. |
+| [CLTS import](clts-import.md) | Import explicit source tokens into a native graph, inspect refusals and preservation, and reload same-provenance envelopes. |
 | [CLTS/BIPA coverage gaps](clts-gaps.md) | Generated coverage and refusal counts for the frozen CLTS/BIPA snapshot. |
 | [CLTS mapping table](clts-mapping.md) | Generated directional mapping evidence for the bounded CLTS correspondence. |
 | [Finite model operations](model-operations.md) | Typed declarations, explicit model CLI selection, feature edits and exact realization candidates; links to finite rules and transforms. |
 | [Operations across inventories](inventory-operations.md) | House and Panphon matching and respelling, custom declarations, and all-pairs comparisons across named cost models. |
 | [Feature transformations](feature-transforms.md) | Declared finite re-encoding, explicit loss and preimages, and binary comparison through shared cost/alignment machinery. |
 | [MFA vocabulary exhibit](mfa-vocabularies.md) | Generated declarations, source pins and refusal classes. |
-| [eSpeak vocabulary exhibit](espeak-vocabularies.md) | Generated language-scoped and union vocabulary coverage. |
+| [eSpeak vocabulary exhibit](espeak-vocabularies.md) | User-source-generated language-scoped and union vocabulary coverage. |
 | [House declaration exhibits](house-style-exhibits.md) | Generated tie, boundary and character-class inventories behind the house conventions. |
 
 ## Rules and comparison

{ipakit-0.3.0 → ipakit-0.4.0}/docs/capabilities.md

@@ -221,11 +221,12 @@ and comparison tooling are usable today. The [CLTS/BIPA library](clts-audit.md)
 provides a frozen finite core feature snapshot, native Jaccard scoring, shared
 alignment cost packs, and a declaration census. Runtime scoring uses the shipped
 snapshot; development extraction has separate source pins and validation.
-The CLTS source-preserving runtime bridge remains in development. A public
-importer that retains source-only CLTS claims safely in `Form` still requires
-an adaptation/restoration boundary, guarded incomplete projections, and
-directional mapping artifacts. The existing scripts provide auditing and
-approximation. Full native graph persistence and the public `Form.to_json()`
+The [CLTS import](clts-import.md) turns explicitly segmented CLTS tokens into
+a house `Form` for the reviewed plain stops `p b t d` and refuses every other
+occurrence with a per-occurrence report; preserve mode keeps the native source
+graph instead. A house `Form` does not carry source-only CLTS claims: a
+preserved import is source-complete and house-incomplete, and `house_form()`
+refuses it. The existing scripts provide auditing and approximation. Full native graph persistence and the public `Form.to_json()`
 linear projection have separate fidelity contracts.
 
 The [historical ecosystem assessment](design/ecosystem.md) retains the

{ipakit-0.3.0 → ipakit-0.4.0}/docs/cli-api-sync.md

@@ -11,7 +11,7 @@ objects or require caller-supplied graph structure and linguistic choices.
 | Module implementation support imports | `annotations`, `Any`, `Iterable`, `Path`, `Sequence` | **Library-only by decision:** these are non-underscored bindings used by the flat module's implementation and type annotations, not ipakit capabilities suitable for CLI commands. |
 | Canonical forms, graph construction, containment, serialization, and DOT rendering | `Form`, `FormBuilder`, `FormProjectionError`, `Attribute`, `Boundary`, `Interval`, `Node`, `Timing`, `Unit`, `levels`, `tier_names`, `units`, `read`, `read_json`, `read_graph_json`, `write_graph_json`, `to_dot`, `Form.graph`, `Form.at`, `Form.to_dot` | **CLI-reachable:** `convert to-json [--pretty]`, `convert from-json`, `graph-json`, `rules units`, and `tiergraph IPA` / `tiergraph --from-json PATH`; graph editing is available through the library constructors. |
 | Segments and normalization | `Constituent`, `Kind`, `Segment`, `Sense`, `tokenize`, `segmented`, `segments`, `segment`, `to_ipa`, `normalize`, `from_wild`, `normalize_lookalikes`, `add_ties` | **CLI-reachable:** `convert tokenize`, `normalize`, and `add-ties`; `features` intentionally offers interactive lookalike reading. |
-| Feature lookup, querying, and respelling | `Feature`, `FeatureNarrowingWarning`, `FeatureQuery`, `Phone`, `PhoneMapping`, `Phoneset`, `features`, `feature_values`, `features_from_cmu`, `features_from_xsampa`, `feature_bundles`, `phones_matching`, `to_phone`, `respell`, `find`, `features_to_shorts`, `shorts_to_features`, `import_phoneset` | **CLI-reachable:** `features`; `query match`, `list`, `features`, `classes`, and `shorts` provide the terminal views and searches. The warning type is the Python control surface for narrowing reads. |
+| Feature lookup, querying, and respelling | `Feature`, `FeatureNarrowingWarning`, `InputLossWarning`, `FeatureQuery`, `Phone`, `PhoneMapping`, `Phoneset`, `features`, `feature_values`, `features_from_cmu`, `features_from_xsampa`, `feature_bundles`, `phones_matching`, `to_phone`, `respell`, `find`, `features_to_shorts`, `shorts_to_features`, `import_phoneset` | **CLI-reachable:** `features`; `query match`, `list`, `features`, `classes`, and `shorts` provide the terminal views and searches. The warning types are the Python control surface for narrowing reads and input loss. |
 | Description, references, validation, and hierarchy | `wiki`, `wiki_ref`, `wiki_refs`, `describe`, `natural_class`, `minimal_pairs`, `nearest_phones`, `hierarchy`, `hierarchy_text`, `hierarchy_dot`, `stress_markers`, `validate_ipa`, `is_valid_ipa`, `extensions_in`, `is_pure_ipa` | **CLI-reachable:** `describe`; `analysis`; `hierarchy`; `info stress`; and `analyze` provide the useful terminal reports. |
 | Raw distance and inventory-relative percentile positions | `Alignment`, `AlignmentStep`, `CostSchedule`, `Correspondence`, `Coverage`, `PhoneCost`, `PhonePosition`, `UnusableReferenceWarning`, `PhonesetMapping`, `PhonesetComparison`, `PronunciationMatch`, `ScoringParameters`, `SequenceMatch`, `TranscriptionDistanceResult`, `DistanceModel`, `distance`, `segment_distance`, `pairwise_distances`, `transcription_distance`, `directional_transcription_distance`, `transcription_similarity`, `explain_transcription_distance`, `nearest_pronunciation`, `rank_pronunciations`, `sequence_distance`, `sequence_similarity`, `rank_sequences`, `distance_position`, `similarity_position`, `distance_model`, `phoneset_mapping`, `phoneset_comparison` | **CLI-reachable:** `distance pair`, `segment`, `matrix`, `positions`, `transcription`, `nearest`, `seq`, `map`, and `compare`, including alignment/explanation output. `positions` emits `similarity_position` and `distance_position`; `map` relates two phonesets in one selected way; `compare` reports the ordered sets, nearest mappings both ways, similarity matrix, source terms, directional means and worst cases, asymmetry, and caller-chosen `--coverage-at` thresholds. |
 | Inventory lookup and construction | `Inventory`, `Style`, `inventories`, `inventory`, `inventory_from_dictionary` | **CLI-reachable:** `inventory list`, `inventory show`, and `inventory from-dict`, including `min_entries` as `--min-entries` and `refuse_unreadable` as `--refuse-unreadable`. |

{ipakit-0.3.0 → ipakit-0.4.0}/docs/clts-audit.md

@@ -37,9 +37,9 @@ upstream resolver may support additional sounds.
 Inspect `requested`, `entries` and `excluded` for the exact generated
 population. The full CLTS-to-Form importer and general semantic feature mapping
 remain separate work. The [bounded correspondence authority](clts-mapping.md)
-records four exact plain-stop witnesses; its
+records profile-bound reviewed plain-stop projections; its
 [generated gap report](clts-gaps.md) accounts for master declarations while
-keeping unresolved mappings and pending structural-profile binding explicit.
+keeping unresolved mappings and the bounded profile context explicit.
 
 <a id="substitute-the-cost-model-not-the-aligner"></a>