utterplan 0.3.7__tar.gz → 0.4.0__tar.gz

{utterplan-0.3.7 → utterplan-0.4.0}/.codecrate.toml

@@ -17,6 +17,7 @@ include = [
   "**/*.yaml",
   "**/*.yml",
   "**/*.ssmd",
+  "**/*.typed",
   "LICENSE",
 ]
 split_max_chars = 0

{utterplan-0.3.7 → utterplan-0.4.0}/.github/workflows/python-publish.yml

@@ -89,6 +89,7 @@ jobs:
                   "utterplan/schemas/v1.schema.json",
                   "utterplan/schemas/v2.schema.json",
                   "utterplan/schemas/v3.schema.json",
+                  "utterplan/schemas/v4.schema.json",
               }
               assert expected <= names
           PY

{utterplan-0.3.7 → utterplan-0.4.0}/.github/workflows/tests.yml

@@ -43,12 +43,15 @@ jobs:
       - name: Install lower-bound dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install pytest jsonschema
+          # exceptiongroup 1.3+ requires typing_extensions >=4.6; keep the 4.0 lower-bound check viable.
+          # referencing 0.36+ uses TypeVar(default=...) unavailable in typing_extensions 4.0.
+          python -m pip install pytest jsonschema "exceptiongroup==1.2.2" "referencing<0.36"
           python -m pip install \
             "phrasplit==0.3.9" \
             "ssmd==0.9.3" \
             "spokenform==0.4.3" \
-            "typing_extensions>=4.0"
+            "typing_extensions==4.0.0" \
+            "tomlkit==0.13.0"
           python -m pip install --no-deps -e .
       - name: Run lower-bound tests
         run: python -m pytest -q
@@ -87,6 +90,7 @@ jobs:
               "utterplan/schemas/v1.schema.json",
               "utterplan/schemas/v2.schema.json",
               "utterplan/schemas/v3.schema.json",
+              "utterplan/schemas/v4.schema.json",
           }
           expected_ranges = {
               "phrasplit": ("0.3.9", "0.4"),
@@ -153,10 +157,10 @@ jobs:
           [Hello]{voice-name="test"} ...200ms world.
           EOF
           "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" compile \
-            "$RUNNER_TEMP/test.ssmd.md" --lang en-us --text-preparation identity --json \
-            > "$RUNNER_TEMP/test.utterplan.json"
+            "$RUNNER_TEMP/test.ssmd.md" --lang en-us --text-preparation identity \
+            > "$RUNNER_TEMP/test.utterplan.toml"
           "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" validate \
-            "$RUNNER_TEMP/test.utterplan.json"
+            "$RUNNER_TEMP/test.utterplan.toml"
           cat > "$RUNNER_TEMP/test-0.8.ssmd.md" <<'EOF'
           ---
           ssmd_version: "0.8"
@@ -164,7 +168,7 @@ jobs:
           Hello.
           EOF
           if "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" compile \
-            "$RUNNER_TEMP/test-0.8.ssmd.md" --lang en-us --text-preparation identity --json \
+            "$RUNNER_TEMP/test-0.8.ssmd.md" --lang en-us --text-preparation identity \
             > "$RUNNER_TEMP/test-0.8.out" 2>&1; then
             cat "$RUNNER_TEMP/test-0.8.out"
             echo "Installed wheel accepted an SSMD 0.8 document" >&2
@@ -174,4 +178,19 @@ jobs:
           "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" migrate \
             "$GITHUB_WORKSPACE/tests/schema_history/v1/basic.json" --check
           "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" inspect \
-            "$RUNNER_TEMP/test.utterplan.json" --segment 0
+            "$RUNNER_TEMP/test.utterplan.toml" --segment 0
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
+      - name: Build documentation
+        run: sphinx-build -W --keep-going -b html docs docs/_build/html

{utterplan-0.3.7 → utterplan-0.4.0}/.gitignore

@@ -221,4 +221,4 @@ context_utterplan*.*
 utterplan/_version.py
 
 # Generated outputs from the runnable examples
-examples/*.utterplan.json
+examples/*.utterplan.toml

utterplan-0.4.0/MANIFEST.in

@@ -0,0 +1 @@
+prune .ledger

{utterplan-0.3.7/utterplan.egg-info → utterplan-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.3.7
+Version: 0.4.0
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License
@@ -226,6 +226,7 @@ Requires-Dist: phrasplit<0.4,>=0.3.9
 Requires-Dist: ssmd<0.10,>=0.9.3
 Requires-Dist: spokenform<0.5,>=0.4.3
 Requires-Dist: typing_extensions>=4.0
+Requires-Dist: tomlkit<1,>=0.13
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: jsonschema; extra == "dev"
@@ -259,13 +260,13 @@ consumer workspaces, and stops before G2P, synthesis, and audio.
 Compile literal text directly:
 
 ```bash
-utterplan compile "Doctor Smith bought 5 kg." --input-format plain --language en-us --json
+utterplan compile "Doctor Smith bought 5 kg." --input-format plain --language en-us
 ```
 
 Compile a file to a plan file:
 
 ```bash
-utterplan compile examples/chapter.ssmd -o chapter.utterplan.json
+utterplan compile examples/chapter.ssmd -o chapter.utterplan.toml
 ```
 
 SSMD header `language` is authoritative, so `--language` is optional when it is present. Otherwise pass `--language` as the fallback; plain input always requires a language. `--language` never forces a language over SSMD semantics.
@@ -273,21 +274,29 @@ SSMD header `language` is authoritative, so `--language` is optional when it is
 Use stdin and shell pipelines:
 
 ```bash
-cat examples/chapter.ssmd | utterplan compile --lang en-us --input-format ssmd | jq .
+cat examples/chapter.ssmd | utterplan compile --lang en-us --input-format ssmd > chapter.utterplan.toml
 ```
 
+Compile independent documents incrementally; every successful plan is saved immediately, and ordinary failures do not discard earlier outputs:
+
+```bash
+utterplan compile-many examples/*.ssmd --output-dir build/plans
+```
+
+This writes one `.utterplan.toml` per source plus an atomically refreshed `compile-report.toml`. Use `--fail-fast` to skip later inputs after a failure, `--force` to replace existing plans, or `--report PATH` to choose another report location.
+
 The CLI also provides:
 
 ```bash
 utterplan --version
-utterplan validate chapter.utterplan.json
-utterplan inspect chapter.utterplan.json --segment 0
-utterplan explain chapter.utterplan.json
+utterplan validate chapter.utterplan.toml
+utterplan inspect chapter.utterplan.toml --segment 0
+utterplan inspect chapter.utterplan.toml --semantic-boundaries
+utterplan explain chapter.utterplan.toml
 ```
 
 `explain` presents the compiled plan as a human-readable speech plan, while `inspect` exposes lower-level diagnostic fields.
-Compile JSON is written to stdout when no output file is supplied. Status
-messages use stderr, and existing output files require `--force`.
+Canonical plan output is TOML (`.utterplan.toml`) and is written to stdout when no output file is supplied. Status messages use stderr, and existing output files require `--force`. Safe punctuation repair is the default; use `--renderability strict` to reject every repair opportunity.
 
 ## SSMD source contract
 
@@ -303,7 +312,8 @@ command:
 ssmd migrate old.ssmd --to 0.9
 ```
 
-`utterplan migrate` is only for historical `.utterplan.json` schema migration. It does not migrate SSMD source.
+`utterplan migrate` explicitly imports supported historical `.utterplan.json` plans and writes current TOML. It does not migrate SSMD source.
+Normal plan loading is TOML-only: `UtterancePlan.load()` and plan-inspection commands reject JSON rather than auto-detecting it.
 
 ## Planning defaults
 
@@ -311,6 +321,8 @@ The minimal CLI defaults are explicit: `spokenform` is the default text-preparat
 
 Python `PlannerConfig` defaults to `document_format="plain"`; set it to `"ssmd"` when a Python string contains SSMD source.
 
+Python `PlannerConfig.renderability_mode` also defaults to safe punctuation-only repair; choose `"strict"` to reject every repair opportunity. Neither mode guesses a symbol's pronunciation or crosses semantic blockers.
+
 `spacy auto` is opt-in. When enabled and a compatible local model is available, UtterPlan may expose richer tokenization, POS tags, lemmas, and tags; `auto` is not the default.
 
 ## Python API
@@ -332,8 +344,8 @@ result = compile_document(
 )
 plan = result.plan
 assert result.trace is not None
-plan.save("example.utterplan.json")
-assert UtterancePlan.load("example.utterplan.json") == plan
+plan.save("example.utterplan.toml")
+assert UtterancePlan.load("example.utterplan.toml") == plan
 ```
 
 `compile_document` is the stable public one-document API shared by consumers. The
@@ -341,7 +353,7 @@ immutable `CompileResult` contains the semantic plan, diagnostics, and optional
 explanatory trace. Trace is not serialized in the plan and does not affect its
 identity. Plain text must be explicitly selected in Python and always requires a
 language fallback. Existing `UtterancePlanner.plan` remains supported and returns
-only the plan; JSON is the portable persistence and interchange format.
+only the plan; TOML is the portable persistence and interchange format.
 
 For operational progress from a long-running Python plan, pass `on_progress` to
 `UtterancePlanner.plan`, `UtterancePlanner.compile`, or `compile_document`. The
@@ -363,8 +375,11 @@ Callbacks run synchronously and exceptions propagate. See the [Python API guide]
 
 Renderers consume `PlanSegment.text`, which is prepared/spoken text, and use
 `spoken_start`/`spoken_end` for spoken-text coordinates. Resolved segment
-pauses, language, directives, annotations, boundaries, markers, units, and
-document metadata are public plan fields. Plans contain no phonemes, model
+pauses, language, directives, annotations, boundaries, semantic boundaries,
+markers, units, and
+document metadata are public plan fields. Semantic boundaries are stable
+engine-neutral opportunities for spoken-text subdivision; they are not pause
+events and carry no duration or renderer policy. Plans contain no phonemes, model
 tokens, model sessions, renderer configuration, provider documents, or audio.
 For SSMD input, `plan.annotations` preserve declared source semantics and source
 provenance, `document_metadata` preserves portable header data, and
@@ -398,10 +413,10 @@ renderer repository rather than UtterPlan's test suite.
 
 ## Versions
 
-The package version is dynamically derived from Git tags by setuptools-scm. Package version and UtterPlan schema version are independent. Current plans use schema v3; released schema v1 and v2 remain immutable and supported through sequential v1-to-v2-to-v3 and direct v2-to-v3 migrations.
+The package version is dynamically derived from Git tags by setuptools-scm. Package version and UtterPlan schema version are independent. Current `.utterplan.toml` plans use semantic schema v4; released schema v1, v2, and v3 remain immutable and supported through sequential migrations.
 
-Schema v3 adds typed renderer-neutral SSMD semantics. Migration converts serialized plan data only. It does not reparse source, replan, or rerun linguistic analysis, G2P, rendering, or audio processing. Unit hashes retain the `utterplan-unit-v2` algorithm.
-Schema v3 persists final pass-B token facts, including optional POS, tag, lemma, and morphology, plus per-language-run provider provenance. Unit hashes include pronunciation-relevant token semantics but exclude model/audio state.
+Schema v4 adds stable `SemanticBoundary` records in spoken-text coordinates. Migration converts serialized plan data only: the registered v3-to-v4 step preserves existing evidence and derives topology where possible, but does not rerun parsing, NLP, planning, G2P, rendering, or audio processing. Unit hashes use `utterplan-unit-v3` and include relative semantic-boundary positions; older hash algorithms remain available for their historical migration paths.
+Schema v4 retains typed renderer-neutral SSMD semantics, final pass-B token facts, and per-language-run provider provenance. Plans never serialize provider documents, models, sessions, phonemes, token IDs, or audio.
 
 ## Development
 

{utterplan-0.3.7 → utterplan-0.4.0}/README.md

@@ -17,13 +17,13 @@ consumer workspaces, and stops before G2P, synthesis, and audio.
 Compile literal text directly:
 
 ```bash
-utterplan compile "Doctor Smith bought 5 kg." --input-format plain --language en-us --json
+utterplan compile "Doctor Smith bought 5 kg." --input-format plain --language en-us
 ```
 
 Compile a file to a plan file:
 
 ```bash
-utterplan compile examples/chapter.ssmd -o chapter.utterplan.json
+utterplan compile examples/chapter.ssmd -o chapter.utterplan.toml
 ```
 
 SSMD header `language` is authoritative, so `--language` is optional when it is present. Otherwise pass `--language` as the fallback; plain input always requires a language. `--language` never forces a language over SSMD semantics.
@@ -31,21 +31,29 @@ SSMD header `language` is authoritative, so `--language` is optional when it is
 Use stdin and shell pipelines:
 
 ```bash
-cat examples/chapter.ssmd | utterplan compile --lang en-us --input-format ssmd | jq .
+cat examples/chapter.ssmd | utterplan compile --lang en-us --input-format ssmd > chapter.utterplan.toml
 ```
 
+Compile independent documents incrementally; every successful plan is saved immediately, and ordinary failures do not discard earlier outputs:
+
+```bash
+utterplan compile-many examples/*.ssmd --output-dir build/plans
+```
+
+This writes one `.utterplan.toml` per source plus an atomically refreshed `compile-report.toml`. Use `--fail-fast` to skip later inputs after a failure, `--force` to replace existing plans, or `--report PATH` to choose another report location.
+
 The CLI also provides:
 
 ```bash
 utterplan --version
-utterplan validate chapter.utterplan.json
-utterplan inspect chapter.utterplan.json --segment 0
-utterplan explain chapter.utterplan.json
+utterplan validate chapter.utterplan.toml
+utterplan inspect chapter.utterplan.toml --segment 0
+utterplan inspect chapter.utterplan.toml --semantic-boundaries
+utterplan explain chapter.utterplan.toml
 ```
 
 `explain` presents the compiled plan as a human-readable speech plan, while `inspect` exposes lower-level diagnostic fields.
-Compile JSON is written to stdout when no output file is supplied. Status
-messages use stderr, and existing output files require `--force`.
+Canonical plan output is TOML (`.utterplan.toml`) and is written to stdout when no output file is supplied. Status messages use stderr, and existing output files require `--force`. Safe punctuation repair is the default; use `--renderability strict` to reject every repair opportunity.
 
 ## SSMD source contract
 
@@ -61,7 +69,8 @@ command:
 ssmd migrate old.ssmd --to 0.9
 ```
 
-`utterplan migrate` is only for historical `.utterplan.json` schema migration. It does not migrate SSMD source.
+`utterplan migrate` explicitly imports supported historical `.utterplan.json` plans and writes current TOML. It does not migrate SSMD source.
+Normal plan loading is TOML-only: `UtterancePlan.load()` and plan-inspection commands reject JSON rather than auto-detecting it.
 
 ## Planning defaults
 
@@ -69,6 +78,8 @@ The minimal CLI defaults are explicit: `spokenform` is the default text-preparat
 
 Python `PlannerConfig` defaults to `document_format="plain"`; set it to `"ssmd"` when a Python string contains SSMD source.
 
+Python `PlannerConfig.renderability_mode` also defaults to safe punctuation-only repair; choose `"strict"` to reject every repair opportunity. Neither mode guesses a symbol's pronunciation or crosses semantic blockers.
+
 `spacy auto` is opt-in. When enabled and a compatible local model is available, UtterPlan may expose richer tokenization, POS tags, lemmas, and tags; `auto` is not the default.
 
 ## Python API
@@ -90,8 +101,8 @@ result = compile_document(
 )
 plan = result.plan
 assert result.trace is not None
-plan.save("example.utterplan.json")
-assert UtterancePlan.load("example.utterplan.json") == plan
+plan.save("example.utterplan.toml")
+assert UtterancePlan.load("example.utterplan.toml") == plan
 ```
 
 `compile_document` is the stable public one-document API shared by consumers. The
@@ -99,7 +110,7 @@ immutable `CompileResult` contains the semantic plan, diagnostics, and optional
 explanatory trace. Trace is not serialized in the plan and does not affect its
 identity. Plain text must be explicitly selected in Python and always requires a
 language fallback. Existing `UtterancePlanner.plan` remains supported and returns
-only the plan; JSON is the portable persistence and interchange format.
+only the plan; TOML is the portable persistence and interchange format.
 
 For operational progress from a long-running Python plan, pass `on_progress` to
 `UtterancePlanner.plan`, `UtterancePlanner.compile`, or `compile_document`. The
@@ -121,8 +132,11 @@ Callbacks run synchronously and exceptions propagate. See the [Python API guide]
 
 Renderers consume `PlanSegment.text`, which is prepared/spoken text, and use
 `spoken_start`/`spoken_end` for spoken-text coordinates. Resolved segment
-pauses, language, directives, annotations, boundaries, markers, units, and
-document metadata are public plan fields. Plans contain no phonemes, model
+pauses, language, directives, annotations, boundaries, semantic boundaries,
+markers, units, and
+document metadata are public plan fields. Semantic boundaries are stable
+engine-neutral opportunities for spoken-text subdivision; they are not pause
+events and carry no duration or renderer policy. Plans contain no phonemes, model
 tokens, model sessions, renderer configuration, provider documents, or audio.
 For SSMD input, `plan.annotations` preserve declared source semantics and source
 provenance, `document_metadata` preserves portable header data, and
@@ -156,10 +170,10 @@ renderer repository rather than UtterPlan's test suite.
 
 ## Versions
 
-The package version is dynamically derived from Git tags by setuptools-scm. Package version and UtterPlan schema version are independent. Current plans use schema v3; released schema v1 and v2 remain immutable and supported through sequential v1-to-v2-to-v3 and direct v2-to-v3 migrations.
+The package version is dynamically derived from Git tags by setuptools-scm. Package version and UtterPlan schema version are independent. Current `.utterplan.toml` plans use semantic schema v4; released schema v1, v2, and v3 remain immutable and supported through sequential migrations.
 
-Schema v3 adds typed renderer-neutral SSMD semantics. Migration converts serialized plan data only. It does not reparse source, replan, or rerun linguistic analysis, G2P, rendering, or audio processing. Unit hashes retain the `utterplan-unit-v2` algorithm.
-Schema v3 persists final pass-B token facts, including optional POS, tag, lemma, and morphology, plus per-language-run provider provenance. Unit hashes include pronunciation-relevant token semantics but exclude model/audio state.
+Schema v4 adds stable `SemanticBoundary` records in spoken-text coordinates. Migration converts serialized plan data only: the registered v3-to-v4 step preserves existing evidence and derives topology where possible, but does not rerun parsing, NLP, planning, G2P, rendering, or audio processing. Unit hashes use `utterplan-unit-v3` and include relative semantic-boundary positions; older hash algorithms remain available for their historical migration paths.
+Schema v4 retains typed renderer-neutral SSMD semantics, final pass-B token facts, and per-language-run provider provenance. Plans never serialize provider documents, models, sessions, phonemes, token IDs, or audio.
 
 ## Development
 

{utterplan-0.3.7 → utterplan-0.4.0}/docs/architecture.md

@@ -35,17 +35,17 @@ Legacy `UtterancePlanner.plan` remains a compatibility API returning only the
 plan.
 
 The public `UtterancePlan` Python object is immutable in-process renderer input;
-the `.utterplan.json` schema is the portable persistence and semantic interchange
-contract. UtterPlan ends before G2P. Engine/model selection, synthesis, and audio
-composition happen downstream.
+the `.utterplan.toml` document is the portable persistence and semantic interchange
+format; it encodes semantic schema v4. UtterPlan ends before G2P. Engine/model
+selection, synthesis, and audio composition happen downstream.
 
 ## SSMD source contract
 
 The document parser calls SSMD with `dialect="0.9"` for every SSMD source path,
 including unversioned fragments selected with `document_format="ssmd"`. UtterPlan
 does not parse SSMD 0.8 or migrate source. Older documents must first be converted
-with `ssmd migrate FILE --to 0.9`. The `utterplan migrate` command is reserved for
-serialized UtterPlan schema migrations.
+with `ssmd migrate FILE --to 0.9`. The `utterplan migrate` command explicitly
+imports legacy JSON plans and applies serialized schema migrations.
 
 SSMD header language is authoritative over a fallback language. The CLI can omit
 `--language` when the header declares a language; plain input always needs an
@@ -66,7 +66,7 @@ text. Preparation-trace source offsets address SSMD-clean structural text, while
 its transformation output offsets address prepared spoken text.
 
 Linguistic analysis and provider documents are request-local. Returned plans
-contain JSON-compatible semantic results only: no live parser objects, spaCy
+contain plain, round-trippable semantic data only: no live parser objects, spaCy
 documents, models, sessions, provider caches, phonemes, engine token IDs, or audio.
 A reusable planner may share sequential resource caches, but concurrent use is not
 promised.
@@ -77,41 +77,34 @@ preparation can invalidate their offsets.
 
 Pause events retain provenance and resolved event IDs. Pause defaults are
 normalized to finite seconds with explicit precedence, and segments expose
-resolved pauses directly. Logical voices are intent references; document
-`voice_bindings` metadata remains separate and no concrete engine voice is
-selected.
+resolved pauses directly. Semantic boundaries are a separate immutable
+collection of stable spoken-text split opportunities; they have no duration,
+activation state, or renderer choice. Logical voices are intent references;
+document `voice_bindings` metadata remains separate and no concrete engine
+voice is selected.
 
-Plan identity is deterministic and renderer-independent. It covers semantic
-source/configuration/metadata; it does not include renderer-only model, sample
+Plan identity is deterministic and renderer-independent. It covers semantic source/configuration/metadata; it does not include renderer-only model, sample
 rate, or output-file settings. Unit hashes include ordered segment semantics,
 resolved pauses, marker content, and semantic token facts referenced by each
-segment. Diagnostics and producer metadata do not define unit identity. Package
-version is derived by setuptools-scm and is independent of the explicit UtterPlan
-`schema_version`.
+segment. Semantic-boundary positions relative to each unit are part of the
+`utterplan-unit-v3` hash; diagnostics and producer metadata do not define unit
+identity. Package version is derived by setuptools-scm and is independent of
+the explicit UtterPlan `schema_version`.
+
+Current plans persist as deterministic `.utterplan.toml` files; schema v4 remains the semantic contract, and `plan_id` is derived from canonical semantic data rather than TOML bytes. `UtterancePlan.load()` accepts TOML only. Legacy JSON plan import is an explicit migration command, never a normal load fallback.
+
+`compile-many` orchestrates independent source documents in order. Each successful plan is validated and atomically saved before the next source is processed; ordinary failures are reported and later inputs continue unless fail-fast is requested. Its atomically refreshed TOML report is operational data, not an `UtterancePlan`.
 
 ## Persistence compatibility boundary
 
 ```text
-                         .utterplan.json
-                                |
-                                v
-                       inspect schema version
-                                |
-                    +-----------+-----------+
-                    |                       |
-                 current                    old
-                    |                       |
-                    |                 migration chain
-                    |                       |
-                    +-----------+-----------+
-                                |
-                                v
-                      current UtterancePlan
-                                |
-                                v
-                            renderer
+current plan file:
+.utterplan.toml -- TOML decode / schema-v4 validation --> UtterancePlan --> renderer
+
+legacy saved plan:
+.utterplan.json -- explicit `utterplan migrate` --> current .utterplan.toml
 ```
 
 Migration is not planning. UtterPlan owns persistence, schema validation, and migration. Renderers consume only the current in-memory `UtterancePlan` and do not implement historical schema branches.
 
-Schema v3 is current. Released schema v1 and v2 remain frozen; v1 migration proceeds sequentially through v2 to v3, while v2 plans migrate directly to v3. These migrations transform serialized data only and never reparse or replan source.
+Schema v4 is current. Released schemas v1, v2, and v3 remain frozen; supported plans migrate through the registered sequential chain to v4. The v3-to-v4 step transforms serialized data only and does not rerun parsing, NLP, planning, G2P, rendering, or audio processing. Consumers receive only the current in-memory model.

{utterplan-0.3.7 → utterplan-0.4.0}/docs/changelog.md

@@ -4,6 +4,31 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-06
+
+### Added
+
+- Added stable spoken-coordinate semantic boundaries for clause, parenthetical, sentence, and paragraph splits
+
+### Changed
+
+- Changed serialized plans to schema v4 with deterministic v3-to-v4 migration and boundary-sensitive unit identity
+- Changed plan persistence to deterministic TOML with explicit legacy JSON import and incremental batch compilation
+
+### Documentation
+
+- Documented spoken-coordinate semantics, pause separation, migration limits, and consumer lowering
+
+<!-- generated by releaseledger -->
+
+## [0.3.7] - 2026-10-05
+
+### Quality
+
+- Improved package publishing workflow for the release toolchain
+
+<!-- generated by releaseledger -->
+
 ## [0.3.6] - 2026-10-05
 
 ### Added

{utterplan-0.3.7 → utterplan-0.4.0}/docs/cli.md

@@ -9,7 +9,7 @@ usage: utterplan compile [-h] [--file FILE] [--language LANGUAGE]
                          [--text-preparation {spokenform,identity}]
                          [--pause-mode {tts,manual,auto}]
                          [--spacy {auto,off,sm,md,lg,trf}] [-o OUTPUT]
-                         [--force] [--json]
+                         [--force] [--stdout] [--renderability {strict,repair}]
                          [text ...]
 ```
 
@@ -56,33 +56,46 @@ ssmd migrate old.ssmd --to 0.9 --output migrated.ssmd
 utterplan compile migrated.ssmd --lang en-us
 ```
 
-`utterplan migrate` applies only to `.utterplan.json` schema versions. It cannot migrate SSMD source.
+`utterplan migrate` is the explicit JSON-plan import path: it applies supported schema migrations and writes canonical TOML. It cannot migrate SSMD source.
 
 ## Output and errors
 
-Without `--output`, compile writes the actual pretty plan JSON to stdout. With
-`--output`, the file is written and an existing file is refused unless
-`--force` is supplied. Add `--json` with an output path to write the file and
-also emit the same plan JSON to stdout.
+Without `--output`, compile writes the pretty TOML plan to stdout. With
+`--output`, the TOML file is written and an existing file is refused unless
+`--force` is supplied. Add `--stdout` with an output path to write the file and
+also emit the same TOML plan to stdout.
 
-Human status messages are written to stderr, never mixed into JSON stdout:
+Human status messages are written to stderr, never mixed into TOML stdout:
 
 ```bash
-utterplan compile chapter.ssmd.md -o chapter.utterplan.json
+utterplan compile chapter.ssmd.md -o chapter.utterplan.toml
 # status is written to stderr
-utterplan compile chapter.ssmd.md -o chapter.utterplan.json --json | jq .
+utterplan compile chapter.ssmd.md -o chapter.utterplan.toml --stdout
 ```
 
 Argparse usage errors use exit code 2. Input, planning, file, and plan
 validation errors use exit code 1 and are reported without a traceback.
 
+## Compile many documents incrementally
+
+`compile-many` reads source files in the requested order, compiles each independently, and atomically saves each successful plan before reading the next. Ordinary input, planning, and write failures are reported per item and do not roll back earlier plans; processing continues unless `--fail-fast` is set.
+
+```bash
+utterplan compile-many chapters/*.ssmd --output-dir build/plans \
+  --language en-us --report build/compile-report.toml
+```
+
+Source names determine output names: `chapter.ssmd`, `chapter.ssmd.md`, and `chapter.md` each map to `chapter.utterplan.toml`. Duplicate output names and a report path that collides with a plan output are rejected before any writes. Existing plans are protected unless `--force` is supplied. By default the command writes an atomically refreshed `compile-report.toml` in the output directory; the report is operational TOML, not a plan accepted by `UtterancePlan.load()`.
+
+Shared planning options include `--language`, `--input-format auto|plain|ssmd`, `--unit`, `--text-preparation`, `--pause-mode`, `--spacy`, and `--renderability`. Progress, repair notices, actionable errors, and the final counts are written to stderr. Exit status is 0 if every input succeeds, 1 if any input fails, and 2 for usage errors such as output collisions. `--fail-fast` skips later requests after the first failure but preserves all completed outputs and updates the report.
+
 ## Explain a plan
 
 Explain an existing compiled plan as a human-readable speech narrative:
 
 ```bash
-utterplan explain chapter.utterplan.json
-utterplan explain chapter.utterplan.json --details
+utterplan explain chapter.utterplan.toml
+utterplan explain chapter.utterplan.toml --details
 ```
 
 The default output shows prepared wording, render units, ordered segments, languages, resolved pauses, headings, SSMD version/title/document language, effective typed directives, metadata, and warning/error codes with source locations. Add `--details` for IDs, offsets, provenance, hashes, plan identity, and token analysis beneath each segment. Use `inspect --tokens` for a compact token/provenance view.
@@ -94,6 +107,7 @@ The default output shows prepared wording, render units, ordered segments, langu
 - `--pause-mode tts|manual|auto` selects semantic pause policy.
 - `--spacy off|auto|sm|md|lg|trf` selects deterministic fallback, automatic
   spaCy use, or a required model tier.
+- `--renderability repair|strict` defaults to safe punctuation-only repair. Semantic blockers remain failures with source context and an actionable next step; strict mode reports safe repair opportunities without applying them.
 
 The default spaCy policy is `off`, so the CLI does not depend on whichever optional model happens to be installed.
 
@@ -105,28 +119,43 @@ Use `--spacy auto` only as an opt-in enrichment policy. If a compatible local mo
 
 ```bash
 utterplan --version
-utterplan validate chapter.utterplan.json
+utterplan validate chapter.utterplan.toml
 utterplan validate chapter.ssmd.md
 utterplan validate plain.txt --input-format plain --language en-us
-utterplan inspect chapter.utterplan.json --segment 0
-utterplan inspect chapter.utterplan.json --unit 0 --boundaries --tokens
-utterplan inspect chapter.utterplan.json --preparation
+utterplan inspect chapter.utterplan.toml --segment 0
+utterplan inspect chapter.utterplan.toml --unit 0 --boundaries --tokens
+utterplan inspect chapter.utterplan.toml --preparation
+utterplan inspect chapter.utterplan.toml --semantic-boundaries
 ```
 
-`inspect --preparation` reports the preparation backend and version, structural and spoken text lengths, replacement count, and each replacement's structural and spoken ranges and text. This is the supported human-facing preparation diagnostic; raw coordinate lookup tables are intentionally absent from plan JSON.
+`inspect --preparation` reports the preparation backend and version, structural and spoken text lengths, replacement count, and each replacement's structural and spoken ranges and text. This is the supported human-facing preparation diagnostic; raw coordinate lookup tables are intentionally absent from the persisted TOML plan.
 
 ## Migrate a saved plan
 
-Migrate a supported saved plan to the current schema without rerunning planning:
+Import a supported legacy JSON plan to the current schema without rerunning
+planning. `migrate` is the only CLI path that reads saved plan JSON; its output is
+always canonical TOML:
 
 ```bash
-utterplan migrate old.utterplan.json -o current.utterplan.json
+utterplan migrate old.utterplan.json -o current.utterplan.toml
 utterplan migrate old.utterplan.json --check
-utterplan migrate old.utterplan.json | jq .
+utterplan migrate old.utterplan.json > current.utterplan.toml
 ```
 
-Without `-o`, migrated JSON is written to stdout. Status is written to stderr. Existing output files are refused unless `--force` is supplied. `--check` validates the route and reports source schema, target schema, and whether migration is required without writing a file. A future schema version is rejected rather than guessed or downgraded.
-
-Schema migration is a separate operation from SSMD source migration. UtterPlan preserves released schema v1 and v2 and migrates v1 plans sequentially through v2 to current schema v3. It never reparses source or replans. Use `ssmd migrate FILE --to 0.9` for older SSMD source documents.
-
-For a saved JSON plan, `validate` performs the in-memory schema compatibility check and reports source/current schema versions without modifying the file. For an SSMD or plain-text source document, it runs the canonical one-document semantic compiler without writing a plan; plain input requires `--language`, while SSMD can use its header language or an explicit fallback.
+Without `-o`, TOML is written to stdout and status is written to stderr. Existing
+output files are refused unless `--force` is supplied. `--check` validates the
+route and reports source schema, target schema, and whether migration is required
+without writing a file. A future schema version is rejected rather than guessed
+or downgraded.
+
+Schema migration is a separate operation from SSMD source migration. UtterPlan
+preserves released schemas v1, v2, and v3 and migrates supported plans through the
+registered chain to current schema v4. The v3-to-v4 step does not rerun parsing,
+NLP, or planning. Use `ssmd migrate FILE --to 0.9` for older SSMD source
+documents.
+
+For a saved TOML plan, `validate` verifies the current semantic schema and plan
+invariants; JSON plan paths are rejected outside `migrate`. For an SSMD or
+plain-text source document, it runs the canonical one-document semantic compiler
+without writing a plan; plain input requires `--language`, while SSMD can use its
+header language or an explicit fallback.