utterplan 0.3.7__tar.gz → 0.4.1__tar.gz

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

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

{utterplan-0.3.7 → utterplan-0.4.1}/.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.1}/.github/workflows/tests.yml

@@ -43,13 +43,18 @@ 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: Verify SSMD 0.9.3 front-matter scene-break handling
+        run: python -m pytest -q tests/test_ssmd_09_parser.py -k front_matter_scene_break
       - name: Run lower-bound tests
         run: python -m pytest -q
 
@@ -87,6 +92,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 +159,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 +170,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 +180,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.1}/.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.1/MANIFEST.in

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.3.7
+Version: 0.4.1
 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,34 @@ 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
+utterplan inspect-attempt chapter.attempt.toml --issues
 ```
 
 `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`.
+
+`inspect-attempt` reads the separate `utterplan.planning-attempt.v1` TOML artifact,
+not a canonical plan. Use it to review renderability issues and safe repair
+assessments on blocked planning outcomes; such candidates remain inspect-only drafts.
+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 +317,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 +326,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 +349,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 +358,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 +380,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 +418,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.1}/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,34 @@ 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
+utterplan inspect-attempt chapter.attempt.toml --issues
 ```
 
 `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`.
+
+`inspect-attempt` reads the separate `utterplan.planning-attempt.v1` TOML artifact,
+not a canonical plan. Use it to review renderability issues and safe repair
+assessments on blocked planning outcomes; such candidates remain inspect-only drafts.
+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 +74,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 +83,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 +106,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 +115,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 +137,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 +175,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.1}/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.1}/docs/changelog.md

@@ -4,6 +4,51 @@
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-07
+
+### Added
+
+- Added persistable planning attempts with inspectable renderability outcomes and safe repair assessments
+
+### Changed
+
+- Changed planning APIs to expose blocked candidates without weakening canonical plan validation
+
+### Fixed
+
+- Fixed legacy SSMD scene breaks to preserve front-matter boundaries and clean-to-source offsets
+
+### Documentation
+
+- Documented planning-attempt artifacts, inspection workflows, and renderability guarantees
+
+<!-- generated by releaseledger -->
+
+## [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