utterplan 0.6.8__tar.gz → 0.6.11__tar.gz

{utterplan-0.6.8 → utterplan-0.6.11}/.github/workflows/python-publish.yml

@@ -82,7 +82,7 @@ jobs:
               assert has_range(requirements, "phrasplit", "0.3.9", "0.4")
               assert has_range(requirements, "ssmd", "0.9.3", "0.10")
               assert has_range(requirements, "ttsready", "0.2.3", "0.3")
-              assert has_range(requirements, "renderplan", "0.1.1", "0.2")
+              assert has_range(requirements, "renderplan", "0.1.4", "0.2")
               names = set(archive.namelist())
               expected = {
                   "utterplan/py.typed",

{utterplan-0.6.8 → utterplan-0.6.11}/.github/workflows/tests.yml

@@ -120,7 +120,7 @@ jobs:
               "phrasplit": ("0.3.9", "0.4"),
               "ssmd": ("0.9.3", "0.10"),
               "ttsready": ("0.2.3", "0.3"),
-              "renderplan": ("0.1.1", "0.2"),
+              "renderplan": ("0.1.4", "0.2"),
           }
 
           def check_metadata(contents):

{utterplan-0.6.8 → utterplan-0.6.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.8
+Version: 0.6.11
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License
@@ -227,7 +227,7 @@ Requires-Dist: ssmd<0.10,>=0.9.3
 Requires-Dist: ttsready<0.3,>=0.2.3
 Requires-Dist: typing_extensions>=4.0
 Requires-Dist: tomlkit<1,>=0.13
-Requires-Dist: renderplan<0.2,>=0.1.1
+Requires-Dist: renderplan<0.2,>=0.1.4
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: jsonschema; extra == "dev"
@@ -408,6 +408,16 @@ engine-backed profiles, then preflights and renders the resulting RenderPlans.
 UtterPlan's single-file `render-plan` command remains the low-level projection and
 deterministic replan primitive.
 
+### Troubleshooting RenderProfile identity mismatch
+
+A RenderProfile `profile_id` is a semantic content identity validated by RenderPlan; it is not a hash of the TOML file bytes. If the profile's identity-bearing semantics change without refreshing its ID, UtterPlan rejects it before creating RenderPlan artifacts. Regenerate or re-save the complete profile with VoiceRender, then validate it before rendering:
+
+```bash
+voicerender profile validate narration.renderprofile.toml
+```
+
+Do not replace `profile_id` with `sha256sum` of the TOML file. `--force` only replaces an otherwise valid existing RenderPlan output; it never bypasses profile validation.
+
 When VoiceRender reports `preflight.replan`, refine the active bundle variant
 using matching feedback:
 

{utterplan-0.6.8 → utterplan-0.6.11}/README.md

@@ -164,6 +164,16 @@ engine-backed profiles, then preflights and renders the resulting RenderPlans.
 UtterPlan's single-file `render-plan` command remains the low-level projection and
 deterministic replan primitive.
 
+### Troubleshooting RenderProfile identity mismatch
+
+A RenderProfile `profile_id` is a semantic content identity validated by RenderPlan; it is not a hash of the TOML file bytes. If the profile's identity-bearing semantics change without refreshing its ID, UtterPlan rejects it before creating RenderPlan artifacts. Regenerate or re-save the complete profile with VoiceRender, then validate it before rendering:
+
+```bash
+voicerender profile validate narration.renderprofile.toml
+```
+
+Do not replace `profile_id` with `sha256sum` of the TOML file. `--force` only replaces an otherwise valid existing RenderPlan output; it never bypasses profile validation.
+
 When VoiceRender reports `preflight.replan`, refine the active bundle variant
 using matching feedback:
 

{utterplan-0.6.8 → utterplan-0.6.11}/docs/architecture.md

@@ -1,6 +1,6 @@
 ---
 title: "Architecture Documentation"
-version: 4
+version: 6
 generator: "archledger 0.4.0"
 arc42_template_version: "9.0-EN"
 ---
@@ -237,6 +237,14 @@ Supporting tactics:
   evidence live in an optional versioned trace TOML that never affects plan
   identity or executable content.
 
+## Prepared character-spelling semantics
+
+After written-to-spoken preparation and before segmentation, UtterPlan inspects verified replacement records for the exact character-spelling transformation: an ASCII uppercase-letter/digit core of at least two characters becomes the same characters joined by single spaces, optionally retaining an identical `'s` or `’s` suffix. This derives a compiler-owned `say_as=characters` annotation over only the prepared character core. For example, `[ART]{sub=\"A R T\"}` keeps prepared text `A R T`; `[ART's]{sub=\"A R T's\"}` keeps `A R T's` and marks only `A R T`.
+
+The derivation is portable executable intent, not a renderer-specific spelling rewrite. Prepared text never becomes `A- R- T`; a renderer adapter may choose that frontend form. Existing semantic-edge segmentation produces the exact controlled span, while RenderPlan sentence grouping retains the full sentence as one normal speech request with a request-local control. This feature adds neither a sentence split nor an automatic pause.
+
+Authored `say-as` semantics take precedence, and the consumed SSMD `sub` annotation remains consumed. The derived directive uses existing schema-v7 `SayAsDirective` serialization and identity hashing; replacement records remain diagnostic provenance and are not synthesis input. No schema version or migration changes are required.
+
 ## Strategy Items
 
 <!-- archledger: no accepted records for this section yet -->
@@ -281,6 +289,8 @@ from `manifest.json`, normalizes item selection, and enforces path containment.
 services; private book and document helpers retain kind-specific persistence and
 report behavior. The generic source loader remains limited to standalone files.
 
+Preparation semantics include the compiler-only `prepared_semantics.py` pass. It consumes verified preparation replacement records after text preparation and before language-run/segment construction, appending deterministic `say-as=characters` annotations without changing prepared text, replacement provenance, boundaries, source maps, or consumed substitutions. It reuses existing directive resolution, semantic-edge segmentation, FlowPlan v7 serialization/identity, and RenderPlan request-local control projection.
+
 <!-- archledger: no accepted records for this section yet -->
 
 # Runtime View
@@ -479,6 +489,10 @@ semantic blockers. Blocked planning outcomes may be reviewed through the separat
 `utterplan.planning-attempt.v1` inspect-only artifact; such candidates remain
 drafts and never become canonical plans.
 
+### Character spelling: text, intent, and realization
+
+Character spelling keeps four concerns separate: source spelling (for example, `ART`), prepared spoken text (`A R T`), portable executable intent (`say_as=characters` over the exact prepared core), and downstream renderer realization. The matcher uses only verified replacement metadata and does not guess from arbitrary uppercase words or normalization changes. Possessive suffixes remain outside the semantic range. Replacement provenance is excluded from executable identity; the derived directive affects FlowUnit and FlowPlan identity. UtterPlan never persists a frontend-specific hyphen form or adds a pause for this feature.
+
 <!-- archledger: no accepted records for this section yet -->
 
 # Architecture Decisions

{utterplan-0.6.8 → utterplan-0.6.11}/docs/bundles.md

@@ -77,6 +77,16 @@ The default RenderPlan root is `<bundle>/renderplan/`. Each variant includes a c
 
 Role coverage is checked before new variant artifacts are written. The selected profile must cover every required logical role, including its default role when any speech has no explicit role. Profile identity mismatches, unsafe paths, and metadata collisions are not bypassed by `--force`.
 
+### Troubleshooting stale RenderProfile identity
+
+RenderProfile IDs represent semantic profile content, not the bytes or formatting of the TOML file. A profile edited after its identity was persisted (or produced with a stale identity) fails validation before UtterPlan creates a variant. Regenerate or re-save the complete profile with VoiceRender and validate it before rendering:
+
+```bash
+voicerender profile validate narration.renderprofile.toml
+```
+
+Do not set `profile_id` to the result of `sha256sum` on the TOML file; RenderPlan owns the canonical semantic identity. `--force` permits replacing an otherwise valid existing RenderPlan output only. It does not bypass profile identity/schema checks, role coverage, unsafe paths, or snapshot mismatches.
+
 ## Replan
 
 When VoiceRender reports `preflight.replan`, refine the active plan using its exact matching feedback:

{utterplan-0.6.8 → utterplan-0.6.11}/docs/changelog.md

@@ -4,7 +4,31 @@
 
 ## [Unreleased]
 
-## [v0.6.8] - Unreleased
+## [v0.6.10] - 2026-10-28
+
+### Added
+
+- Added portable character-spelling semantics for verified substitutions
+
+<!-- generated by releaseledger -->
+
+## [v0.6.9] - 2026-10-27
+
+### Added
+
+- Added shared RenderProfile loading with canonical path resolution, validation, and actionable stale-identity diagnostics
+
+### Changed
+
+- Changed bundle rendering and replanning to use validated profile identities and keep --force limited to valid outputs
+
+### Fixed
+
+- Fixed token projection to preserve optional morphology and report missing required fields with locators
+
+<!-- generated by releaseledger -->
+
+## [v0.6.8] - 2026-10-23
 
 ### Added
 

{utterplan-0.6.8 → utterplan-0.6.11}/docs/cli.md

@@ -161,7 +161,9 @@ utterplan bundle replan BUNDLE --variant VARIANT [--chapters SELECTOR]
 
 Compilation writes one schema-v7 FlowPlan per selected item and an operational `compile-report.toml` under `<bundle>/utterplan/` by default. Rendering reads those saved plans and requires an explicit RenderProfile; it writes profile-fingerprinted RenderPlans, a profile snapshot, and an operational report (book bundles also maintain a set index) under `<bundle>/renderplan/`. Replanning refines active plans from matching VoiceRender preflight feedback and updates only the selected active entries. These commands never mutate the manifest or source documents. `render-plan` remains the low-level one-file projection/replan command.
 
-The diagnostics option controls compile terminal verbosity; failures are always reported and complete diagnostics remain in the operational report. `--fail-fast` skips later selected items after a failure. `--force` replaces selected plan artifacts but does not bypass unsafe paths, metadata collisions, or profile-identity checks. Exit status is 0 when all selected work succeeds, 1 when an item fails, and 2 for usage or shared-configuration errors. See the [bundle guide](bundles.md) for layouts, safety behavior, and Python examples.
+The diagnostics option controls compile terminal verbosity; failures are always reported and complete diagnostics remain in the operational report. `--fail-fast` skips later selected items after a failure. For compile commands, `--force` replaces selected plan artifacts. For rendering, it only replaces an otherwise valid existing RenderPlan output; it does not bypass unsafe paths, metadata collisions, role-coverage failures, profile schema/identity validation, or existing snapshot identity checks. Exit status is 0 when all selected work succeeds, 1 when an item fails, and 2 for usage or shared-configuration errors. See the [bundle guide](bundles.md) for layouts, safety behavior, and Python examples.
+
+A RenderProfile `profile_id` is a semantic content identity, not a hash of TOML bytes. If it is stale, the path-aware error recommends regenerating or re-saving the profile with VoiceRender and validating it with `voicerender profile validate PROFILE` before rendering. Do not substitute `sha256sum` of the profile file; `--force` never bypasses this validation.
 
 Explain an existing compiled plan as a human-readable speech narrative:
 

{utterplan-0.6.8 → utterplan-0.6.11}/docs/debugging.md

@@ -40,3 +40,16 @@ If spoken wording is wrong, inspect `FlowSegment.text`. If effective language is
 For source-coordinate bugs, inspect `PreparationTrace.source_text`, `source_spans`, and the structural/spoken maps. Source offsets address exact input Python characters, including SSMD headers and markup; diagnostic line and column are 1-based. Preparation transformation source ranges address structural text, while output ranges address prepared spoken text. See the [coordinate-space contract](coordinate-spaces).
 
 If the FlowPlan is correct but G2P or audio is wrong, the issue belongs to the renderer or acoustic runtime, not the planning boundary.
+
+## RenderProfile identity mismatch
+
+A RenderProfile's `profile_id` identifies its canonical semantic content, not its TOML serialization. The error `profile_id does not match profile content` means the persisted ID is stale for the current profile semantics. UtterPlan fails closed and names the profile path; it does not repair or re-hash the profile, and `--force` does not bypass validation.
+
+Regenerate or re-save the complete engine-backed RenderProfile with VoiceRender, then validate it before invoking UtterPlan:
+
+```bash
+voicerender profile validate narration.renderprofile.toml
+utterplan bundle render story.ssmd-bundle --profile narration.renderprofile.toml --force
+```
+
+Do not use `sha256sum` on the TOML file as a replacement ID. If VoiceRender created the file and it was not manually edited, report the producer path for investigation; all binding and renderer metadata must be assembled before the final profile identity is persisted.

{utterplan-0.6.8 → utterplan-0.6.11}/docs/python-api.md

@@ -329,6 +329,12 @@ print(segment.directives.emphasis)
 
 The `document` record retains compact portable document information. Effective directives and pause intents live on their owning flow segments. Compiler-only source spans and preparation coordinate maps remain in the optional trace. See the [coordinate-space contract](coordinate-spaces) and [consumer guide](consumer-guide) for renderer responsibilities.
 
+### Character-spelling substitutions
+
+When a verified preparation replacement is exactly an ASCII uppercase-letter/digit sequence expanded into its individual characters separated by single spaces, UtterPlan derives `say_as=characters` for that prepared core. For example, `[ART]{sub="A R T"}` keeps prepared text `A R T`; `[ART's]{sub="A R T's"}` keeps `A R T's` and covers only `A R T`. This applies to exact SSMD substitutions and other preparation backends' verified replacement records, including TTSReady. It does not guess from arbitrary acronyms, case changes, normalization, punctuation, or altered spacing. An authored `say-as` takes precedence.
+
+The derived directive is executable semantic intent and participates in FlowPlan identity. Replacement provenance remains diagnostic only. With sentence-level RenderPlan grouping, the full sentence stays one speech request and the request-local `say_as` control covers only the spelled core. UtterPlan never rewrites prepared text to frontend-specific forms such as `A- R- T` and does not add an automatic pause for this feature; an engine adapter owns any renderer-specific realization.
+
 ## Flow segments and local tokens
 
 A `FlowPlan` stores ordered `FlowUnit` objects. Each unit owns its ordered segments, so consumers do not join plan-global IDs. Token offsets use Python-character coordinates local to `segment.text`:

{utterplan-0.6.8 → utterplan-0.6.11}/pyproject.toml

@@ -17,7 +17,7 @@ dependencies = [
   "ttsready>=0.2.3,<0.3",
   "typing_extensions>=4.0",
   "tomlkit>=0.13,<1",
-  "renderplan>=0.1.1,<0.2",
+  "renderplan>=0.1.4,<0.2",
  ]
 classifiers = [
   "Development Status :: 3 - Alpha",

{utterplan-0.6.8 → utterplan-0.6.11}/tests/test_cli_bundle_render_book.py

@@ -183,6 +183,7 @@ def test_render_book_success_matches_single_file_projection(tmp_path: Path, caps
     root = _write_book(tmp_path / "ordered.ssmd-bundle", (5, 7, 6))
     profile_path = root / "narration.renderprofile.toml"
     profile = _profile(profile_path)
+    profile_bytes_before = profile_path.read_bytes()
     manifest_before = (root / "manifest.json").read_bytes()
 
     result = _render(root, profile_path, "--chapters", "5-7")
@@ -221,6 +222,7 @@ def test_render_book_success_matches_single_file_projection(tmp_path: Path, caps
     assert report["failed"] == 0
     assert len(report["item"]) == 3
     assert (root / "manifest.json").read_bytes() == manifest_before
+    assert profile_path.read_bytes() == profile_bytes_before
 
     source_plan = root / "utterplan/chapter-0005.utterplan.toml"
     single_output = tmp_path / "chapter-0005.single.renderplan.toml"
@@ -243,6 +245,55 @@ def test_render_book_success_matches_single_file_projection(tmp_path: Path, caps
     assert batch_plan.plan_id == single_plan.plan_id
 
 
+@pytest.mark.parametrize("force", (False, True))
+def test_stale_profile_identity_fails_closed_with_and_without_force(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str], force: bool
+) -> None:
+    root = _write_book(tmp_path / "stale.ssmd-bundle", (5,))
+    profile_path = root / "stale.renderprofile.toml"
+    _profile(profile_path)
+    stale_content = profile_path.read_text(encoding="utf-8").replace(
+        'voice = "amy"', 'voice = "changed"', 1
+    )
+    assert stale_content != profile_path.read_text(encoding="utf-8")
+    profile_path.write_text(stale_content, encoding="utf-8")
+
+    options = ("--force",) if force else ()
+    assert _render(root, profile_path, *options) != 0
+    error = capsys.readouterr().err
+    assert f"invalid RenderProfile {profile_path.resolve()}" in error
+    assert "profile_id does not match profile content" in error
+    assert "stale for the current profile semantics" in error
+    assert "Regenerate or re-save the RenderProfile with its producer" in error
+    assert "validate it before rendering" in error
+    assert "--force does not bypass profile identity validation" in error
+    assert not (root / "renderplan").exists()
+
+
+@pytest.mark.parametrize("invalid_kind", ("missing", "malformed", "schema"))
+def test_profile_load_failures_include_path_and_write_nothing(
+    tmp_path: Path, capsys, invalid_kind: str
+) -> None:
+    root = _write_book(tmp_path / f"{invalid_kind}.ssmd-bundle", (5,))
+    profile_path = root / f"{invalid_kind}.renderprofile.toml"
+    if invalid_kind == "malformed":
+        profile_path.write_text("[roles\n", encoding="utf-8")
+    elif invalid_kind == "schema":
+        _profile(profile_path)
+        profile_path.write_text(
+            profile_path.read_text(encoding="utf-8").replace(
+                "schema_version = 1", "schema_version = 99"
+            ),
+            encoding="utf-8",
+        )
+
+    assert _render(root, profile_path) != 0
+    error = capsys.readouterr().err
+    assert "invalid RenderProfile" in error
+    assert str(profile_path.resolve()) in error
+    assert not (root / "renderplan").exists()
+
+
 def test_render_book_reports_multi_role_coverage(tmp_path: Path, capsys) -> None:
     root = _write_book(tmp_path / "multi-role.ssmd-bundle", (5, 6, 7))
     _write_role_plan(root, 5, "host")

{utterplan-0.6.8 → utterplan-0.6.11}/tests/test_cli_bundle_render_document.py

@@ -110,6 +110,7 @@ def test_render_document_writes_profile_specific_direct_variant_and_report(
     source_plan_before = source_plan.read_bytes()
     profile_path = tmp_path / "narration.renderprofile.toml"
     profile = _profile(profile_path)
+    profile_bytes_before = profile_path.read_bytes()
 
     assert _render(root, profile_path) == 0
     capsys.readouterr()
@@ -146,6 +147,55 @@ def test_render_document_writes_profile_specific_direct_variant_and_report(
         "utterplan",
         "renderplan",
     }
+    assert profile_path.read_bytes() == profile_bytes_before
+
+
+def test_stale_profile_identity_fails_closed_with_and_without_force(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path)
+    profile_path = tmp_path / "stale.renderprofile.toml"
+    _profile(profile_path)
+    stale_content = profile_path.read_text(encoding="utf-8").replace(
+        'voice = "amy"', 'voice = "changed"', 1
+    )
+    assert stale_content != profile_path.read_text(encoding="utf-8")
+    profile_path.write_text(stale_content, encoding="utf-8")
+
+    for options in ((), ("--force",)):
+        assert _render(root, profile_path, *options) != 0
+        error = capsys.readouterr().err
+        assert f"invalid RenderProfile {profile_path.resolve()}" in error
+        assert "profile_id does not match profile content" in error
+        assert "stale for the current profile semantics" in error
+        assert "Regenerate or re-save the RenderProfile with its producer" in error
+        assert "validate it before rendering" in error
+        assert "--force does not bypass profile identity validation" in error
+        assert not (root / "renderplan").exists()
+
+
+@pytest.mark.parametrize("invalid_kind", ("missing", "malformed", "schema"))
+def test_profile_load_failures_include_path_and_write_nothing(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str], invalid_kind: str
+) -> None:
+    root = _workspace(tmp_path)
+    profile_path = tmp_path / f"{invalid_kind}.renderprofile.toml"
+    if invalid_kind == "malformed":
+        profile_path.write_text("[roles\n", encoding="utf-8")
+    elif invalid_kind == "schema":
+        _profile(profile_path)
+        profile_path.write_text(
+            profile_path.read_text(encoding="utf-8").replace(
+                "schema_version = 1", "schema_version = 99"
+            ),
+            encoding="utf-8",
+        )
+
+    assert _render(root, profile_path) != 0
+    error = capsys.readouterr().err
+    assert "invalid RenderProfile" in error
+    assert str(profile_path.resolve()) in error
+    assert not (root / "renderplan").exists()
 
 
 def test_missing_utterplan_fails_actionably_without_partial_variant(

{utterplan-0.6.8 → utterplan-0.6.11}/tests/test_identity_units.py

@@ -2,7 +2,7 @@ from dataclasses import replace
 from types import SimpleNamespace
 
 from tests.compiler_helpers import CompilerTestPlanner as UtterancePlanner
-from utterplan import PlannerConfig, SemanticBoundary
+from utterplan import FlowUnit, LinguisticsConfig, PlannerConfig, SemanticBoundary, compile_document
 from utterplan.hashing import (
     LEGACY_UNIT_HASH_SCHEMA,
     UNIT_HASH_SCHEMA,
@@ -182,3 +182,63 @@ def test_serialized_and_runtime_unit_hash_payloads_match() -> None:
     migrated_payload = unit_hash_payload_from_serialized(serialized_unit, serialized_plan)
 
     assert migrated_payload == runtime_payload
+
+
+def test_derived_say_as_changes_identity_and_v7_roundtrips_without_hashing_provenance() -> None:
+    source = 'Because someone called [ART]{sub="A R T"} finally.'
+    plan = compile_document(
+        source,
+        input_format="ssmd",
+        config=PlannerConfig(
+            language="en-us",
+            document_format="ssmd",
+            linguistics=LinguisticsConfig(use_spacy=False),
+        ),
+    ).plan
+    assert "".join(segment.text for unit in plan.flow for segment in unit.segments) == (
+        "Because someone called A R T finally."
+    )
+    spelled_ref = next(
+        (unit_index, segment_index, segment)
+        for unit_index, unit in enumerate(plan.flow)
+        for segment_index, segment in enumerate(unit.segments)
+        if segment.text == "A R T"
+    )
+    unit_index, segment_index, spelled = spelled_ref
+    assert spelled.directives.say_as is not None
+    assert spelled.directives.say_as.interpret_as == "characters"
+
+    without_units = []
+    for unit in plan.flow:
+        without_units.append(
+            FlowUnit(
+                tuple(
+                    replace(
+                        segment,
+                        directives=replace(segment.directives, say_as=None),
+                    )
+                    for segment in unit.segments
+                )
+            )
+        )
+    without_say_as = replace(plan, flow=tuple(without_units), plan_id="")
+    assert without_say_as.flow[unit_index].segments[segment_index].text == spelled.text
+    assert without_say_as.flow[unit_index].content_hash != plan.flow[unit_index].content_hash
+    assert without_say_as.plan_id != plan.plan_id
+
+    replacement = spelled.replacements[0]
+    provenance_only = replace(replacement, source="different diagnostic spelling")
+    changed_segments = list(plan.flow[unit_index].segments)
+    changed_segments[segment_index] = replace(spelled, replacements=(provenance_only,))
+    changed_units = list(plan.flow)
+    changed_units[unit_index] = FlowUnit(tuple(changed_segments))
+    provenance_changed = replace(plan, flow=tuple(changed_units), plan_id="")
+    assert provenance_changed.flow[unit_index].content_hash == plan.flow[unit_index].content_hash
+    assert provenance_changed.plan_id == plan.plan_id
+
+    restored = type(plan).from_toml(plan.to_toml())
+    assert restored == plan
+    assert restored.schema_version == 7
+    assert restored.flow[unit_index].segments[segment_index].directives.say_as == (
+        spelled.directives.say_as
+    )

utterplan-0.6.11/tests/test_prepared_semantics.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import pytest
+
+from utterplan.model import AnnotationSpan, BoundaryEvent, TextPreparationInfo
+from utterplan.preparation import PreparedText
+from utterplan.prepared_semantics import (
+    CharacterSpellingMatch,
+    detect_character_spelling,
+    infer_prepared_semantics,
+)
+
+
+@dataclass(frozen=True)
+class _MappedSource:
+    source_length: int
+    output_length: int
+    source_start: int
+    source_end: int
+    output_start: int
+    output_end: int
+
+    def map_source_span(self, start: int, end: int) -> tuple[int, int]:
+        if (start, end) == (self.source_start, self.source_end):
+            return self.output_start, self.output_end
+        return start, end
+
+    def map_output_span(self, start: int, end: int) -> tuple[int, int]:
+        if (start, end) == (self.output_start, self.output_end):
+            return self.source_start, self.source_end
+        return start, end
+
+
+def _replacement(source: str, replacement: str, *, start: int = 0) -> PreparedText:
+    output_start = start + 10
+    source_map = _MappedSource(
+        source_length=start + len(source) + 5,
+        output_length=output_start + len(replacement) + 5,
+        source_start=start,
+        source_end=start + len(source),
+        output_start=output_start,
+        output_end=output_start + len(replacement),
+    )
+    spoken = " " * output_start + replacement + " " * 5
+    record: dict[str, Any] = {
+        "source_start": start,
+        "source_end": start + len(source),
+        "output_start": output_start,
+        "output_end": output_start + len(replacement),
+        "source": source,
+        "replacement": replacement,
+        "kind": "ssmd-sub",
+        "rule": "ssmd.sub",
+        "annotation_id": "sub-1",
+    }
+    source_annotation = AnnotationSpan(
+        id="sub-1",
+        kind="directive",
+        attrs={"sub": replacement},
+        structural_start=start,
+        structural_end=start + len(source),
+        spoken_start=output_start,
+        spoken_end=output_start + len(replacement),
+        source_start=100 + start,
+        source_end=100 + start + len(source),
+        source_node_id="source-node-1",
+    )
+    return PreparedText(
+        spoken_text=spoken,
+        info=TextPreparationInfo("ssmd", None, replacements=(record,)),
+        annotations=(source_annotation,),
+        boundaries=(BoundaryEvent("b-1", 0, "sentence"),),
+        source_map=source_map,
+        consumed_substitutions=("sub-1",),
+    )
+
+
+@pytest.mark.parametrize(
+    ("source", "replacement", "expected"),
+    [
+        ("ART", "A R T", CharacterSpellingMatch(0, 3, 0, 5)),
+        ("AI", "A I", CharacterSpellingMatch(0, 2, 0, 3)),
+        ("USA", "U S A", CharacterSpellingMatch(0, 3, 0, 5)),
+        ("R2D2", "R 2 D 2", CharacterSpellingMatch(0, 4, 0, 7)),
+        ("ART's", "A R T's", CharacterSpellingMatch(0, 3, 0, 5)),
+        ("ART’s", "A R T’s", CharacterSpellingMatch(0, 3, 0, 5)),
+    ],
+)
+def test_detect_exact_character_spelling(
+    source: str, replacement: str, expected: CharacterSpellingMatch
+) -> None:
+    assert detect_character_spelling(source, replacement) == expected
+
+
+@pytest.mark.parametrize(
+    ("source", "replacement"),
+    [
+        ("A", "A"),
+        ("NASA", "nasa"),
+        ("NASA", "N A S A agency"),
+        ("Dr.", "Doctor"),
+        ("kg", "kilograms"),
+        ("ART", "A-R-T"),
+        ("ABC", "A B C D"),
+        ("AB", "A  B"),
+        ("A&B", "A and B"),
+        ("ARTs", "A R T s"),
+        ("ART's", "A R T’s"),
+    ],
+)
+def test_rejects_non_exact_character_spelling(source: str, replacement: str) -> None:
+    assert detect_character_spelling(source, replacement) is None
+
+
+def test_inference_adds_immutable_core_only_deterministic_annotation() -> None:
+    prepared = _replacement("ART's", "A R T's", start=4)
+    result = infer_prepared_semantics(prepared)
+    derived = result.annotations[-1]
+
+    assert result.spoken_text == prepared.spoken_text
+    assert result.info is prepared.info
+    assert result.info.replacements == prepared.info.replacements
+    assert result.boundaries is prepared.boundaries
+    assert result.source_map is prepared.source_map
+    assert result.consumed_substitutions is prepared.consumed_substitutions
+    assert derived.id == "derived.say-as.characters.4.7.14.19"
+    assert derived.kind == "directive"
+    assert derived.attrs == {
+        "tag": "say-as",
+        "as": "characters",
+        "origin": "derived-character-spelling",
+    }
+    assert (derived.structural_start, derived.structural_end) == (4, 7)
+    assert (derived.spoken_start, derived.spoken_end) == (14, 19)
+    assert prepared.spoken_text[derived.spoken_start : derived.spoken_end] == "A R T"
+    assert (derived.source_start, derived.source_end) == (104, 109)
+    assert derived.source_node_id == "source-node-1"
+    assert infer_prepared_semantics(result).annotations == result.annotations
+
+
+def test_authored_say_as_prevents_derived_overlap_and_wins() -> None:
+    prepared = _replacement("ART", "A R T")
+    authored = AnnotationSpan(
+        id="authored-say-as",
+        kind="directive",
+        attrs={"tag": "say-as", "as": "initialism"},
+        structural_start=0,
+        structural_end=3,
+        spoken_start=10,
+        spoken_end=15,
+    )
+    prepared = PreparedText(
+        prepared.spoken_text,
+        prepared.info,
+        (*prepared.annotations, authored),
+        prepared.boundaries,
+        prepared.source_map,
+        prepared.consumed_substitutions,
+    )
+
+    result = infer_prepared_semantics(prepared)
+
+    assert result is prepared
+    assert [item.id for item in result.annotations].count("authored-say-as") == 1
+    assert all(
+        item.attrs.get("origin") != "derived-character-spelling" for item in result.annotations
+    )
+
+
+def test_unverified_replacement_is_ignored() -> None:
+    prepared = _replacement("ART", "A R T")
+    bad = dict(
+        prepared.info.replacements[0], output_end=prepared.info.replacements[0]["output_end"] - 1
+    )
+    info = TextPreparationInfo("ssmd", None, replacements=(bad,))
+    unverified = PreparedText(
+        prepared.spoken_text,
+        info,
+        prepared.annotations,
+        prepared.boundaries,
+        prepared.source_map,
+        prepared.consumed_substitutions,
+    )
+
+    assert infer_prepared_semantics(unverified) is unverified

{utterplan-0.6.8 → utterplan-0.6.11}/tests/test_renderplan_dependency_contract.py

@@ -29,4 +29,4 @@ def test_renderplan_collection_api_minimum_is_declared_as_runtime_dependency() -
     project = tomlkit.parse(
         (Path(__file__).resolve().parents[1] / "pyproject.toml").read_text(encoding="utf-8")
     ).unwrap()
-    assert "renderplan>=0.1.1,<0.2" in project["project"]["dependencies"]
+    assert "renderplan>=0.1.4,<0.2" in project["project"]["dependencies"]