utterplan 0.6.9__tar.gz → 0.6.12__tar.gz

{utterplan-0.6.9 → utterplan-0.6.12}/.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.2.0", "0.3")
               names = set(archive.namelist())
               expected = {
                   "utterplan/py.typed",

{utterplan-0.6.9 → utterplan-0.6.12}/.github/workflows/tests.yml

@@ -51,7 +51,7 @@ jobs:
             "ssmd==0.9.3" \
             "ttsready==0.2.3" \
             "spokenform==0.4.5" \
-            "renderplan==0.1.1" \
+            "renderplan==0.2.0" \
             "typing_extensions==4.0.0" \
             "tomlkit==0.13.0"
           python -m pip install --no-deps -e .
@@ -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.2.0", "0.3"),
           }
 
           def check_metadata(contents):

{utterplan-0.6.9 → utterplan-0.6.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.9
+Version: 0.6.12
 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.3,>=0.2.0
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: jsonschema; extra == "dev"
@@ -408,6 +408,8 @@ 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.
 
+Character-spelling segments keep exact identity in their portable token lemmas: a single alphanumeric token under `say_as = {interpret_as = "characters"}` has the exact token surface as its lemma, even when a linguistic provider reports a context-sensitive lowercase lemma. Ordinary lexical lemmas retain compact casefold-default encoding. Newly generated RenderPlans use schema v2 and store each used role's concrete configuration once in a top-level `[bindings.<role>]` table. The RenderPlan codec restores the complete `SpeechItem.binding` mapping on load; this changes disk layout, not the consumer API.
+
 ### 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:

{utterplan-0.6.9 → utterplan-0.6.12}/README.md

@@ -164,6 +164,8 @@ 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.
 
+Character-spelling segments keep exact identity in their portable token lemmas: a single alphanumeric token under `say_as = {interpret_as = "characters"}` has the exact token surface as its lemma, even when a linguistic provider reports a context-sensitive lowercase lemma. Ordinary lexical lemmas retain compact casefold-default encoding. Newly generated RenderPlans use schema v2 and store each used role's concrete configuration once in a top-level `[bindings.<role>]` table. The RenderPlan codec restores the complete `SpeechItem.binding` mapping on load; this changes disk layout, not the consumer API.
+
 ### 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:

{utterplan-0.6.9 → utterplan-0.6.12}/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.9 → utterplan-0.6.12}/docs/changelog.md

@@ -4,6 +4,22 @@
 
 ## [Unreleased]
 
+## [v0.6.12] - Unreleased
+
+### Changed
+
+- Preserved exact character spelling and adopted RenderPlan v2 binding catalogs
+
+<!-- generated by releaseledger -->
+
+## [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

{utterplan-0.6.9 → utterplan-0.6.12}/docs/consumer-guide.md

@@ -42,6 +42,8 @@ In Python, `PlannerConfig.document_format` defaults to `"plain"`; select `"ssmd"
 Token offsets are half-open Python-character ranges into the owning `segment.text`. Do not use them to slice document text or add offsets from another segment. Consumers preserve stored segment order but decide downstream chunk boundaries; a segment is not necessarily one TTS call.
 Token `pos`, `tag`, `lemma`, and `morph` describe that exact prepared text and are the authoritative linguistic context, not model-token IDs or counts. Consumers may pass them through without retokenizing or rerunning spaCy. Optional replacements are provenance only: their output spans are segment-local, source values are original spellings, and they do not alter hashes independently of the source digest and are not synthesis inputs.
 
+For `say_as.interpret_as = "characters"`, a single alphanumeric spelling token keeps its exact surface as the portable lemma (`T`, not a provider's contextual `t`); POS, tag, and morphology remain provider facts. The ordinary casefold-default encoding is unchanged. If the plan is projected and saved as RenderPlan v2, role bindings are interned in top-level `[bindings.<role>]` tables; `renderplan.codec.load_plan()` restores each complete `SpeechItem.binding` mapping for consumers.
+
 ```python
 from utterplan import FlowPlan
 

{utterplan-0.6.9 → utterplan-0.6.12}/docs/format.md

@@ -55,6 +55,8 @@ Pause intents represent authored `none`, strength values (`x-weak`, `weak`, `med
 
 `plan_id` identifies canonical executable semantics and, in schema v7, the SHA-256 digest of exact raw source when available; it does not hash TOML bytes. The plan-level `hash_schema` is `utterplan-flow-v3`; canonical boundary opportunities and authored pause intents participate in executable identity and flow-unit hashes. Compact replacement provenance is excluded. Producer identity and formatting do not alter executable identity. Plans contain no phonemes, model token IDs, models, sessions, renderer configuration, or audio.
 
+For a segment with `say_as = {interpret_as = "characters"}`, each single alphanumeric token's portable lemma is its exact surface (for example, `T` remains `T` even if a provider reports `t`). This semantic normalization occurs before v7 sparse lemma encoding; ordinary lexical lemmas still default to the case-folded surface, and provider POS, tag, and morphology are retained. When projected separately, RenderPlan v2 stores concrete role bindings in one top-level `[bindings.<role>]` table per used role rather than repeating them in speech entries. Loading with the RenderPlan codec still exposes the complete mapping as `SpeechItem.binding`.
+
 ## TOML API and optional compiler trace
 
 `FlowPlan.to_toml()`, `FlowPlan.from_toml()`, `FlowPlan.save()`, and `FlowPlan.load()` are the persistence APIs. `save()` writes atomically. Normal plan loading and the `validate`, `inspect`, and `explain` commands accept TOML; JSON is never auto-detected as a current plan format. Import a historical plan explicitly with `utterplan migrate`; schema-v6 data cannot be promoted to v7 without recompiling the original source, so migration may report `migration.recompile_required` instead of writing a file.

{utterplan-0.6.9 → utterplan-0.6.12}/docs/pykokoro-integration.md

@@ -38,6 +38,8 @@ for unit in plan.flow:
 
 Use the v7 linguistic token fields (not model-token IDs or counts) as authoritative context: pass available `pos`, `tag`, `lemma`, and `morph` through unchanged rather than rerunning spaCy or inferring tags. Default `auto` uses installed compatible local models, preferring `sm`, `md`, `lg`, `trf`, and safely falls back if unavailable; model packages are never downloaded. When fields are unavailable, follow the adapter's documented non-contextual fallback.
 
+Character spelling is an explicit semantic exception to contextual lemmatization: within `say_as.interpret_as = "characters"`, each single alphanumeric token's portable lemma is its exact surface (so `T` remains uppercase even if the provider reports `t`). POS, tag, and morphology are not rewritten, and ordinary lexical lemmas keep the compact casefold default. On the separate RenderPlan path, schema-v2 files store role bindings once in a plan-level catalog; loading them still supplies the full `SpeechItem.binding` to the consumer.
+
 ## Pause behavior
 
 Schema v7 carries safe boundary opportunities separately from authored pause intents and exact timed breaks; neither selects a renderer activation policy or fixes a chunk. PyKokoro may choose its own chunking and native, automatic, or manual pause realization. A `FlowSegment` is not necessarily one TTS call, and renderer/acoustic variance remains outside UtterPlan and plan identity.

{utterplan-0.6.9 → utterplan-0.6.12}/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.9 → utterplan-0.6.12}/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.2.0,<0.3",
  ]
 classifiers = [
   "Development Status :: 3 - Alpha",

{utterplan-0.6.9 → utterplan-0.6.12}/tests/test_bundle_document_render.py

@@ -47,6 +47,12 @@ def test_render_document_bundle_projects_canonical_flowplan_without_book_index(
     assert result.renderplan_path.name == "document.renderplan.toml"
     plan = renderplan_codec.load_plan(result.renderplan_path)
     plan.validate_against_profile(profile)
+    serialized = result.renderplan_path.read_text(encoding="utf-8")
+    assert plan.schema_version == 2
+    assert serialized.count("[bindings.narrator]") == 1
+    assert "[flow.binding]" not in serialized
+    assert plan.plan_id == plan.computed_id()
+    assert all(speech.binding == dict(profile.roles[speech.role].binding) for speech in plan.speech)
     flow = FlowPlan.load(result.source_plan_path)
     assert result.variant.startswith("narration--")
     assert result.snapshot_path.is_file()
@@ -119,3 +125,11 @@ def test_render_document_bundle_returns_multi_role_coverage_and_bindings(tmp_pat
     plan = renderplan_codec.load_plan(result.renderplan_path)
     assert {speech.role for speech in plan.speech} == {"host", "guest", "narrator"}
     assert {speech.binding["engine"] for speech in plan.speech} == {"kokoro", "kitten", "piper"}
+    serialized = result.renderplan_path.read_text(encoding="utf-8")
+    for role in ("narrator", "host", "guest"):
+        assert serialized.count(f"[bindings.{role}]") == 1
+    assert "[flow.binding]" not in serialized
+    assert plan.schema_version == 2
+    assert plan.plan_id == plan.computed_id()
+    assert all(speech.binding == dict(profile.roles[speech.role].binding) for speech in plan.speech)
+    plan.validate_against_profile(profile)

{utterplan-0.6.9 → utterplan-0.6.12}/tests/test_cli_bundle_render_book.py

@@ -319,6 +319,20 @@ def test_render_book_reports_multi_role_coverage(tmp_path: Path, capsys) -> None
         "narrator",
     }
 
+    for chapter, plan in zip(collection.chapters, plans, strict=True):
+        serialized = (variant / chapter.renderplan).read_text(encoding="utf-8")
+        roles = {speech.role for speech in plan.speech}
+        assert len(roles) == 1
+        for role in roles:
+            assert serialized.count(f"[bindings.{role}]") == 1
+        assert "[flow.binding]" not in serialized
+        assert plan.schema_version == 2
+        assert plan.plan_id == plan.computed_id()
+        assert all(
+            speech.binding == dict(profile.roles[speech.role].binding) for speech in plan.speech
+        )
+        plan.validate_against_profile(profile)
+
 
 def test_render_book_accumulates_successful_chapters_and_replaces_latest_report(
     tmp_path: Path, capsys

{utterplan-0.6.9 → utterplan-0.6.12}/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.12/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.9 → utterplan-0.6.12}/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.2.0,<0.3" in project["project"]["dependencies"]

{utterplan-0.6.9 → utterplan-0.6.12}/tests/test_renderplan_export.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+from dataclasses import replace
 from pathlib import Path
 
 import pytest
@@ -91,7 +92,7 @@ def _preflight(plan, profile) -> PreflightReport:
     ).with_identity()
 
 
-def test_public_build_is_deterministic_and_rejects_incomplete_replan_inputs() -> None:
+def test_public_build_is_deterministic_and_rejects_incomplete_replan_inputs(tmp_path: Path) -> None:
     source = _source()
     profile = _profile()
 
@@ -103,6 +104,23 @@ def test_public_build_is_deterministic_and_rejects_incomplete_replan_inputs() ->
     assert first.speech[0].text == "one two three."
     assert first.speech[0].source[0].locator == "f000000.s000"
     assert first.speech[0].wav == "000001.wav"
+    renderplan_path = tmp_path / "single-role.renderplan.toml"
+    renderplan_codec.save_plan(first, renderplan_path)
+    serialized = renderplan_path.read_text(encoding="utf-8")
+    loaded = renderplan_codec.load_plan(renderplan_path)
+    assert first.schema_version == 2
+    assert serialized.count("[bindings.narrator]") == 1
+    assert "[flow.binding]" not in serialized
+    assert loaded.plan_id == first.plan_id == first.computed_id()
+    assert all(
+        speech.binding == dict(profile.roles[speech.role].binding) for speech in loaded.speech
+    )
+    loaded.validate_against_profile(profile)
+
+    changed_role = replace(profile.roles["narrator"], binding={"engine": "changed"})
+    changed_profile = replace(profile, roles={"narrator": changed_role}, profile_id=None)
+    changed_plan = build_render_plan(source, changed_profile)
+    assert changed_plan.speech[0].segment_id != first.speech[0].segment_id
     try:
         build_render_plan(source, profile, preflight=_preflight(first, profile))
     except RenderPlanProjectionError as error:
@@ -314,7 +332,8 @@ def test_render_plan_json_reports_role_coverage_metadata(tmp_path: Path, capsys)
     profile_path = tmp_path / "cast.renderprofile.toml"
     output_path = tmp_path / "roles.renderplan.toml"
     _multi_role_source().save(source_path)
-    renderplan_codec.save_profile(_multi_role_profile(), profile_path)
+    profile = _multi_role_profile()
+    renderplan_codec.save_profile(profile, profile_path)
 
     assert (
         main(
@@ -341,6 +360,15 @@ def test_render_plan_json_reports_role_coverage_metadata(tmp_path: Path, capsys)
     }
     assert output_path.is_file()
 
+    plan = renderplan_codec.load_plan(output_path)
+    serialized = output_path.read_text(encoding="utf-8")
+    for role in ("narrator", "host", "guest"):
+        assert serialized.count(f"[bindings.{role}]") == 1
+    assert "[flow.binding]" not in serialized
+    assert plan.schema_version == 2
+    assert plan.plan_id == plan.computed_id()
+    assert all(speech.binding == dict(profile.roles[speech.role].binding) for speech in plan.speech)
+    plan.validate_against_profile(profile)
     human_output_path = tmp_path / "roles-human.renderplan.toml"
     assert (
         main(

{utterplan-0.6.9 → utterplan-0.6.12}/tests/test_renderplan_v7_contract.py

@@ -22,10 +22,13 @@ from utterplan import (
     FlowUnit,
     LegacyFlowPlan,
     PauseIntent,
+    PlannerConfig,
     ProsodyDirective,
     SegmentDirectives,
     TokenView,
     VoiceDirective,
+    build_render_plan,
+    compile_document,
 )
 from utterplan.hashing import V5_FLOW_HASH_SCHEMA, V6_FLOW_HASH_SCHEMA
 from utterplan.renderplan_grouping import group_initial_plan
@@ -554,3 +557,46 @@ def test_model_token_capacity_is_not_interpreted_by_utterplan() -> None:
     with pytest.raises(RenderPlanProjectionError) as error:
         _group(plan, profile)
     assert error.value.code == "renderplan.capacity.metric"
+
+
+@pytest.mark.parametrize(
+    ("source", "expected"),
+    [
+        (
+            "Because someone called [ART's]{sub=\"A R T's\"} finally.",
+            "Because someone called A R T's finally.",
+        ),
+        (
+            'Because someone called [ART’s]{sub="A R T’s"} finally.',
+            "Because someone called A R T’s finally.",
+        ),
+    ],
+)
+def test_character_spelling_projects_one_sentence_with_exact_request_control(
+    source: str, expected: str
+) -> None:
+    compiled = compile_document(
+        source,
+        input_format="ssmd",
+        config=PlannerConfig(language="en-us", document_format="ssmd"),
+    )
+    rendered = build_render_plan(compiled.plan, _profile(pauses={"sentence": 120}))
+    speech = [item for item in rendered.flow if isinstance(item, SpeechItem)]
+
+    assert len(speech) == 1
+    assert speech[0].planning_level == "sentence"
+    assert speech[0].text == expected
+    tokens = speech[0].tokens
+    assert tokens is not None
+    t_index = next(
+        index for index, (start, end) in enumerate(tokens.span) if speech[0].text[start:end] == "T"
+    )
+    assert dict(tokens.lemma)[t_index] == "T"
+    assert "A- R- T" not in speech[0].text
+    assert not any(isinstance(item, PauseItem) for item in rendered.flow)
+    say_as = [control for control in speech[0].controls if control.name == "say_as"]
+    assert len(say_as) == 1
+    control = say_as[0]
+    start = expected.index("A R T")
+    assert (control.start, control.end) == (start, start + len("A R T"))
+    assert dict(control.params) == {"interpret_as": "characters"}