utterplan 0.6.7__tar.gz → 0.6.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.7
+Version: 0.6.9
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License
@@ -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.7 → utterplan-0.6.9}/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.7 → utterplan-0.6.9}/docs/bundles.md

@@ -37,6 +37,32 @@ Compilation defaults to all items. For book bundles, `--chapters` selects manife
 
 By default, one schema-v7 `.utterplan.toml` plan per selected item and `compile-report.toml` are written under `<bundle>/utterplan/`. `--output-dir` and `--report` override those destinations. Existing plans are protected unless `--force` is supplied; `--fail-fast` records later selected items as skipped after a failure. `--language` is a fallback for SSMD language metadata. Bundle sources are SSMD 0.9, so the command does not accept an input-format override. The report is operational metadata and does not affect plan identity.
 
+### Bundle-level logical role inventory
+
+A successful complete bundle compile writes `utterplan/role-inventory.toml` under the selected UtterPlan output directory (by default, `<bundle>/utterplan/`). For example:
+
+```bash
+ssmdconvert bundle convert story.ssmd.md
+utterplan bundle compile story.ssmd-bundle
+```
+
+The bundle contains the source and compiled document plan alongside the derived inventory:
+
+```text
+story.ssmd-bundle/
+├── document.ssmd.md
+├── manifest.json
+└── utterplan/
+    ├── document.utterplan.toml
+    └── role-inventory.toml
+```
+
+The TOML contract uses `format = "utterplan.bundle-role-inventory"` and `version = 1`. It records `bundle_kind`, a SHA-256 of the exact manifest bytes, aggregate `[[roles]]` with speech-segment occurrence counts, bundle-order `[[items]]`, and each item's source and plan paths, actual source-byte SHA-256, canonical `plan_id`, explicit role order/counts, and implicit/default-role count. Paths are bundle-relative POSIX paths, not absolute machine paths. Inventory bytes are deterministic and the file is replaced atomically.
+
+Roles and counts derive from compiled FlowPlan speech segments through UtterPlan's logical role semantics, not by scanning SSMD markup or inspecting RenderPlans. Aggregate role order is first semantic occurrence across items in manifest order; item role order is first occurrence within that plan. Empty and audio-only segments do not count. Speech without an explicit role sets `uses_default_role = true` and increments `implicit_occurrences`; it is not assigned an invented role name. A profile-aware consumer resolves the concrete default role later.
+
+Freshness is content-based: `manifest_sha256` hashes the current `manifest.json` bytes, each `source_sha256` hashes its current source bytes, and each item stores the compiled plan's `plan_id`. Modification times are not used. A subset book compile never replaces the canonical whole-bundle inventory and returns no inventory path. A failed full compile also leaves any previous inventory untouched. The successful full-compile summary reports explicit roles, whether a default role is required, and the inventory path; partial compiles do not claim a whole-bundle inventory was produced.
+
 ## Render
 
 Compilation and rendering are separate operations. Rendering reads saved plans and requires an explicit RenderProfile:
@@ -51,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:
@@ -87,3 +123,5 @@ print(projected.variant)
 ```
 
 `compile_bundle()`, `render_bundle()`, and `replan_bundle()` accept paths and keyword options. Their result records expose the resolved bundle, kind, selection, per-item outcomes, artifact paths, reports, and exit status. Optional progress and start callbacks receive typed records; services do not print. Invalid or unsafe requests raise `BundleServiceError` or `BundleReplanError`, while item-level failures are returned in result outcomes.
+
+For a successful full bundle compile, `BundleCompileResult.role_inventory_path` is the canonical `role-inventory.toml` path. It is `None` for partial selections and any compile with a failed item; in those cases the prior whole-bundle inventory, if present, remains untouched. The artifact is additive and does not alter plan identity or bundle rendering.

{utterplan-0.6.7 → utterplan-0.6.9}/docs/changelog.md

@@ -4,6 +4,30 @@
 
 ## [Unreleased]
 
+## [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
+
+- Added renderer-neutral role inventories to full bundle compilation
+
+<!-- generated by releaseledger -->
+
 ## [v0.6.7] - 2026-10-22
 
 ### Fixed

{utterplan-0.6.7 → utterplan-0.6.9}/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.7 → utterplan-0.6.9}/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.7 → utterplan-0.6.9}/docs/python-api.md

@@ -236,6 +236,41 @@ The compile and render services accept paths and keyword options. `chapters` def
 
 `BundleCompileResult`, `BundleRenderResult`, and `BundleReplanResult` expose the resolved bundle, manifest-declared kind, selected item IDs, per-item outcomes, generated paths, reports, and exit status. Their start records provide resolved configuration to optional callbacks. Invalid or unsafe shared requests raise `BundleServiceError` or `BundleReplanError`; item-level failures are reported in result outcomes. The package also exports manifest loader, selector, item-path, result, start, and callback types for integrations that need to inspect dispatch results.
 
+## Bundle role inventory
+
+`BundleRole`, `BundleRoleInventoryItem`, and `BundleRoleInventory` are immutable public models for the version-1 `utterplan.bundle-role-inventory` TOML interoperability contract. `build_bundle_role_inventory()` consumes compiled item records in manifest order; each record provides `id`, `source_path`, and `plan_path`, with optional `source_relative_path` and `plan_relative_path` values. It loads the saved FlowPlan, reuses `logical_role_inventory()`, and hashes the exact manifest and source file bytes.
+
+```python
+from pathlib import Path
+
+from utterplan import (
+    build_bundle_role_inventory,
+    load_bundle_role_inventory,
+    save_bundle_role_inventory,
+)
+
+bundle = Path("story.ssmd-bundle")
+inventory = build_bundle_role_inventory(
+    bundle_root=bundle,
+    bundle_kind="document",
+    manifest_path=bundle / "manifest.json",
+    compiled_items=[
+        {
+            "id": "document-0001",
+            "source_path": bundle / "document.ssmd.md",
+            "source_relative_path": "document.ssmd.md",
+            "plan_path": bundle / "utterplan/document.utterplan.toml",
+            "plan_relative_path": "utterplan/document.utterplan.toml",
+        }
+    ],
+)
+save_bundle_role_inventory(inventory, bundle / "utterplan/role-inventory.toml")
+restored = load_bundle_role_inventory(bundle / "utterplan/role-inventory.toml")
+assert restored == inventory
+```
+
+The loader rejects unsupported versions, malformed hashes/paths, duplicate roles or item IDs, invalid counts, inconsistent explicit-role maps, and aggregates that do not match their item records. Saving is deterministic and atomic. Persisted `uses_default_role` and `implicit_occurrences` describe unresolved profile-default speech; no concrete role is inferred. Item source and plan references are bundle-relative POSIX paths, and their hashes/`plan_id` let consumers detect stale metadata without modification-time checks. The bundle compiler emits this artifact only for successful complete selections; partial or failed compiles do not replace it. Downstream tools may read this serialized contract without importing UtterPlan or parsing SSMD.
+
 ## Planner progress callbacks
 
 `UtterancePlanner.plan`, `UtterancePlanner.compile`, and `compile_document` accept an optional keyword-only `on_progress` callback. It receives typed `PlannerProgressEvent` objects synchronously in the planner thread. Progress is operational only: it is not added to `PlannerConfig` or the plan, and enabling a callback does not change plan identity or serialization.

utterplan-0.6.9/tests/test_bundle_role_inventory.py

@@ -0,0 +1,380 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+import utterplan
+from utterplan import (
+    AudioDirective,
+    FlowPlan,
+    FlowSegment,
+    FlowUnit,
+    SegmentDirectives,
+    VoiceDirective,
+)
+from utterplan.bundle_role_inventory import (
+    BundleRole,
+    BundleRoleInventory,
+    BundleRoleInventoryError,
+    BundleRoleInventoryItem,
+    build_bundle_role_inventory,
+    load_bundle_role_inventory,
+    save_bundle_role_inventory,
+    sha256_file,
+)
+
+
+def _plan(*segments: FlowSegment) -> FlowPlan:
+    return FlowPlan(language="en-US", flow=(FlowUnit(tuple(segments)),))
+
+
+def _simple_inventory() -> BundleRoleInventory:
+    item = BundleRoleInventoryItem(
+        id="document-0001",
+        source="document.ssmd.md",
+        source_sha256="b" * 64,
+        plan="utterplan/document.utterplan.toml",
+        plan_id="sha256:" + "c" * 64,
+        explicit_roles=("host",),
+        explicit_occurrences={"host": 1},
+        uses_default_role=False,
+        implicit_occurrences=0,
+    )
+    return BundleRoleInventory(
+        bundle_kind="document",
+        manifest_sha256="a" * 64,
+        roles=(BundleRole("host", 1),),
+        uses_default_role=False,
+        implicit_occurrences=0,
+        items=(item,),
+    )
+
+
+def _item(
+    bundle_root: Path,
+    item_id: str,
+    source_name: str,
+    plan_name: str,
+    plan: FlowPlan,
+) -> SimpleNamespace:
+    source = bundle_root / source_name
+    plan_path = bundle_root / plan_name
+    source.write_bytes(f"source for {item_id}".encode())
+    plan.save(plan_path, create_parent=True)
+    return SimpleNamespace(
+        id=item_id,
+        source_path=source,
+        source_relative_path=source_name,
+        plan_path=plan_path,
+        plan_relative_path=plan_name,
+    )
+
+
+def test_builder_aggregates_compiled_roles_in_manifest_order_and_hashes_exact_files(
+    tmp_path: Path,
+) -> None:
+    manifest = tmp_path / "manifest.json"
+    manifest.write_bytes(b'{ "bundle_kind" : "book" }\n')
+    first = _item(
+        tmp_path,
+        "chapter-0001",
+        "chapter-1.ssmd.md",
+        "plans/chapter-1.toml",
+        _plan(
+            FlowSegment(
+                "Narration.",
+                "en-US",
+                directives=SegmentDirectives(voice=VoiceDirective("narrator")),
+            ),
+            FlowSegment("Default speech.", "en-US"),
+            FlowSegment("", "en-US", directives=SegmentDirectives(voice=VoiceDirective("empty"))),
+            FlowSegment(
+                "Music",
+                "en-US",
+                directives=SegmentDirectives(audio=AudioDirective(src="music.wav")),
+            ),
+        ),
+    )
+    second = _item(
+        tmp_path,
+        "chapter-0002",
+        "chapter-2.ssmd.md",
+        "plans/chapter-2.toml",
+        _plan(
+            FlowSegment(
+                "Host.", "en-US", directives=SegmentDirectives(voice=VoiceDirective("host"))
+            ),
+            FlowSegment(
+                "Narration again.",
+                "en-US",
+                directives=SegmentDirectives(voice=VoiceDirective("narrator")),
+            ),
+            FlowSegment(
+                "Another host.", "en-US", directives=SegmentDirectives(voice=VoiceDirective("host"))
+            ),
+        ),
+    )
+
+    inventory = build_bundle_role_inventory(
+        bundle_root=tmp_path,
+        bundle_kind="book",
+        manifest_path=manifest,
+        compiled_items=(first, second),
+    )
+
+    assert inventory.bundle_kind == "book"
+    assert inventory.manifest_sha256 == sha256_file(manifest)
+    assert [role.name for role in inventory.roles] == ["narrator", "host"]
+    assert [role.occurrences for role in inventory.roles] == [2, 2]
+    assert inventory.uses_default_role is True
+    assert inventory.implicit_occurrences == 1
+    assert [item.id for item in inventory.items] == ["chapter-0001", "chapter-0002"]
+    assert inventory.items[0].source == "chapter-1.ssmd.md"
+    assert inventory.items[0].plan == "plans/chapter-1.toml"
+    assert inventory.items[0].source_sha256 == sha256_file(first.source_path)
+    assert inventory.items[0].plan_id == FlowPlan.load(first.plan_path).plan_id
+    assert inventory.items[0].explicit_roles == ("narrator",)
+    assert inventory.items[0].implicit_occurrences == 1
+    assert inventory.items[1].explicit_roles == ("host", "narrator")
+    with pytest.raises(TypeError):
+        inventory.items[0].explicit_occurrences["new"] = 1  # type: ignore[index]
+
+
+def test_save_load_is_deterministic_and_round_trips(tmp_path: Path) -> None:
+    manifest = tmp_path / "manifest.json"
+    manifest.write_bytes(b"{}")
+    compiled = _item(
+        tmp_path,
+        "document-0001",
+        "document.ssmd.md",
+        "document.utterplan.toml",
+        _plan(
+            FlowSegment(
+                "Host.", "en-US", directives=SegmentDirectives(voice=VoiceDirective("host"))
+            ),
+            FlowSegment(
+                "Host again.", "en-US", directives=SegmentDirectives(voice=VoiceDirective("host"))
+            ),
+        ),
+    )
+    inventory = build_bundle_role_inventory(
+        bundle_root=tmp_path,
+        bundle_kind="document",
+        manifest_path=manifest,
+        compiled_items=(compiled,),
+    )
+    first = tmp_path / "first.toml"
+    second = tmp_path / "second.toml"
+
+    save_bundle_role_inventory(inventory, first)
+    save_bundle_role_inventory(inventory, second)
+
+    assert first.read_bytes() == second.read_bytes()
+    assert load_bundle_role_inventory(first) == inventory
+    assert 'format = "utterplan.bundle-role-inventory"' in first.read_text(encoding="utf-8")
+    assert 'name = "host"' in first.read_text(encoding="utf-8")
+
+
+def test_loader_rejects_unsupported_version_and_inconsistent_aggregate(tmp_path: Path) -> None:
+    manifest = tmp_path / "manifest.json"
+    manifest.write_bytes(b"{}")
+    compiled = _item(
+        tmp_path,
+        "document-0001",
+        "document.ssmd.md",
+        "document.utterplan.toml",
+        _plan(
+            FlowSegment(
+                "Host.", "en-US", directives=SegmentDirectives(voice=VoiceDirective("host"))
+            )
+        ),
+    )
+    inventory = build_bundle_role_inventory(
+        bundle_root=tmp_path,
+        bundle_kind="document",
+        manifest_path=manifest,
+        compiled_items=(compiled,),
+    )
+    path = tmp_path / "inventory.toml"
+    save_bundle_role_inventory(inventory, path)
+    original = path.read_text(encoding="utf-8")
+
+    path.write_text(original.replace("version = 1", "version = 2", 1), encoding="utf-8")
+    with pytest.raises(BundleRoleInventoryError, match="version"):
+        load_bundle_role_inventory(path)
+
+    path.write_text(original.replace("occurrences = 1", "occurrences = 2", 1), encoding="utf-8")
+    with pytest.raises(BundleRoleInventoryError, match="aggregate role"):
+        load_bundle_role_inventory(path)
+
+
+def test_models_reject_duplicate_roles_and_inconsistent_implicit_metadata() -> None:
+    with pytest.raises(BundleRoleInventoryError, match="duplicate aggregate role"):
+        BundleRoleInventory(
+            bundle_kind="document",
+            manifest_sha256="a" * 64,
+            roles=(BundleRole("host", 1), BundleRole("host", 1)),
+            uses_default_role=False,
+            implicit_occurrences=0,
+            items=(),
+        )
+
+
+def test_inventory_contract_is_exported_from_package_root() -> None:
+    assert utterplan.BundleRole is BundleRole
+    assert utterplan.BundleRoleInventory is BundleRoleInventory
+    assert utterplan.BundleRoleInventoryError is BundleRoleInventoryError
+    assert utterplan.build_bundle_role_inventory is build_bundle_role_inventory
+    assert utterplan.load_bundle_role_inventory is load_bundle_role_inventory
+    assert utterplan.save_bundle_role_inventory is save_bundle_role_inventory
+
+
+@pytest.mark.parametrize(
+    ("old", "new", "message"),
+    [
+        ('format = "utterplan.bundle-role-inventory"', 'format = "other"', "format"),
+        ('manifest_sha256 = "' + "a" * 64 + '"', 'manifest_sha256 = "bad"', "manifest_sha256"),
+        ('source_sha256 = "' + "b" * 64 + '"', 'source_sha256 = "bad"', "source_sha256"),
+        ("occurrences = 1", "occurrences = -1", "non-negative integer"),
+        ("occurrences = 1", "occurrences = true", "non-negative integer"),
+        ('explicit_roles = ["host"]', 'explicit_roles = ["host", "host"]', "duplicate"),
+        ('source = "document.ssmd.md"', 'source = "/tmp/document.ssmd.md"', "relative path"),
+        ("host = 1\n", "", "exactly the roles"),
+        ("uses_default_role = false", "uses_default_role = true", "uses_default_role"),
+        ('plan = "utterplan/document.utterplan.toml"\n', "", "missing"),
+    ],
+)
+def test_loader_rejects_malformed_or_inconsistent_contract(
+    tmp_path: Path, old: str, new: str, message: str
+) -> None:
+    path = tmp_path / "inventory.toml"
+    save_bundle_role_inventory(_simple_inventory(), path)
+    text = path.read_text(encoding="utf-8")
+    assert old in text
+    path.write_text(text.replace(old, new, 1), encoding="utf-8")
+
+    with pytest.raises(BundleRoleInventoryError, match=message):
+        load_bundle_role_inventory(path)
+
+
+def test_loader_rejects_duplicate_item_ids() -> None:
+    inventory = _simple_inventory()
+    item = inventory.items[0]
+    with pytest.raises(BundleRoleInventoryError, match="duplicate bundle item id"):
+        BundleRoleInventory(
+            bundle_kind="document",
+            manifest_sha256=inventory.manifest_sha256,
+            roles=(BundleRole("host", 2),),
+            uses_default_role=False,
+            implicit_occurrences=0,
+            items=(item, item),
+        )
+
+
+def test_uppercase_sha256_values_are_normalized() -> None:
+    item = BundleRoleInventoryItem(
+        id="document-0001",
+        source="document.ssmd.md",
+        source_sha256="B" * 64,
+        plan="document.utterplan.toml",
+        plan_id="sha256:" + "c" * 64,
+        explicit_roles=("host",),
+        explicit_occurrences={"host": 1},
+        uses_default_role=False,
+        implicit_occurrences=0,
+    )
+    inventory = BundleRoleInventory(
+        bundle_kind="document",
+        manifest_sha256="A" * 64,
+        roles=(BundleRole("host", 1),),
+        uses_default_role=False,
+        implicit_occurrences=0,
+        items=(item,),
+    )
+    assert inventory.manifest_sha256 == "a" * 64
+    assert inventory.items[0].source_sha256 == "b" * 64
+
+
+def test_implicit_only_builder_does_not_invent_an_explicit_role(tmp_path: Path) -> None:
+    manifest = tmp_path / "manifest.json"
+    manifest.write_bytes(b"{}")
+    compiled = _item(
+        tmp_path,
+        "document-0001",
+        "document.ssmd.md",
+        "document.utterplan.toml",
+        _plan(
+            FlowSegment("Unassigned speech.", "en-US"),
+            FlowSegment("", "en-US", directives=SegmentDirectives(voice=VoiceDirective("empty"))),
+            FlowSegment(
+                "Audio only",
+                "en-US",
+                directives=SegmentDirectives(audio=AudioDirective(src="music.wav")),
+            ),
+        ),
+    )
+
+    inventory = build_bundle_role_inventory(
+        bundle_root=tmp_path,
+        bundle_kind="document",
+        manifest_path=manifest,
+        compiled_items=(compiled,),
+    )
+
+    assert inventory.roles == ()
+    assert inventory.uses_default_role is True
+    assert inventory.implicit_occurrences == 1
+    assert inventory.items[0].explicit_roles == ()
+
+
+def test_manifest_and_source_content_hashes_change_when_bytes_change(tmp_path: Path) -> None:
+    manifest = tmp_path / "manifest.json"
+    manifest.write_bytes(b'{"version":1}')
+    compiled = _item(
+        tmp_path,
+        "document-0001",
+        "document.ssmd.md",
+        "document.utterplan.toml",
+        _plan(
+            FlowSegment(
+                "Host.", "en-US", directives=SegmentDirectives(voice=VoiceDirective("host"))
+            )
+        ),
+    )
+    first = build_bundle_role_inventory(
+        bundle_root=tmp_path,
+        bundle_kind="document",
+        manifest_path=manifest,
+        compiled_items=(compiled,),
+    )
+    manifest.write_bytes(b'{ "version": 1 }')
+    compiled.source_path.write_bytes(b"updated source bytes")
+    second = build_bundle_role_inventory(
+        bundle_root=tmp_path,
+        bundle_kind="document",
+        manifest_path=manifest,
+        compiled_items=(compiled,),
+    )
+
+    assert first.manifest_sha256 != second.manifest_sha256
+    assert first.items[0].source_sha256 != second.items[0].source_sha256
+    assert first.items[0].plan_id == second.items[0].plan_id
+
+
+def test_save_failure_preserves_previous_inventory_atomically(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    path = tmp_path / "role-inventory.toml"
+    path.write_bytes(b"previous inventory")
+
+    def fail_replace(_source: object, _destination: object) -> None:
+        raise OSError("simulated replace failure")
+
+    monkeypatch.setattr("utterplan.atomic_io.os.replace", fail_replace)
+    with pytest.raises(OSError, match="simulated replace failure"):
+        save_bundle_role_inventory(_simple_inventory(), path)
+
+    assert path.read_bytes() == b"previous inventory"
+    assert list(tmp_path.iterdir()) == [path]

{utterplan-0.6.7 → utterplan-0.6.9}/tests/test_bundle_services.py

@@ -10,7 +10,9 @@ from renderplan import codec as renderplan_codec
 
 from utterplan._book_service import BookServiceError, compile_book, render_book
 from utterplan.bundle import BundleServiceError, compile_bundle, render_bundle
+from utterplan.bundle_role_inventory import load_bundle_role_inventory, sha256_file
 from utterplan.config import LinguisticsConfig, PlannerConfig
+from utterplan.model import FlowPlan
 from utterplan.ssmd_bundle import load_ssmd_bundle
 
 DOCUMENT_FIXTURE = Path(__file__).parent / "fixtures/document-bundle-v1/story.ssmd-bundle"
@@ -114,10 +116,73 @@ def test_compile_bundle_dispatches_both_kinds_and_returns_uniform_result(
     assert starts[0].kind == kind
     assert starts[0].selected_item_ids == result.selected_item_ids
     assert result.report_path.is_file()
+    assert result.role_inventory_path == result.output_dir / "role-inventory.toml"
+    assert result.role_inventory_path.is_file()
+    inventory = load_bundle_role_inventory(result.role_inventory_path)
+    assert inventory.bundle_kind == kind
+    assert [item.id for item in inventory.items] == list(result.selected_item_ids)
+    assert inventory.manifest_sha256 == sha256_file(root / "manifest.json")
+    for item in inventory.items:
+        assert item.source_sha256 == sha256_file(root / item.source)
+        assert item.plan_id == FlowPlan.load(root / item.plan).plan_id
 
     assert len(loaded_indexes) == 1
 
 
+def test_partial_book_compile_leaves_canonical_inventory_absent_or_unchanged(
+    tmp_path: Path,
+) -> None:
+    partial_root = _book(tmp_path / "partial.ssmd-bundle")
+    partial = compile_bundle(partial_root, chapters="5", planner_config=_planner_config())
+    assert partial.exit_code == 0
+    assert partial.role_inventory_path is None
+    assert not (partial.output_dir / "role-inventory.toml").exists()
+
+    full_root = _book(tmp_path / "full-then-partial.ssmd-bundle")
+    full = compile_bundle(full_root, planner_config=_planner_config())
+    assert full.role_inventory_path is not None
+    previous = full.role_inventory_path.read_bytes()
+    subset = compile_bundle(full_root, chapters="5", planner_config=_planner_config(), force=True)
+    assert subset.exit_code == 0
+    assert subset.role_inventory_path is None
+    assert full.role_inventory_path.read_bytes() == previous
+
+
+@pytest.mark.parametrize("preexisting", [False, True])
+def test_failed_full_book_compile_does_not_replace_existing_inventory(
+    tmp_path: Path, preexisting: bool
+) -> None:
+    root = _book(tmp_path / "failed-full.ssmd-bundle")
+    output = root / "utterplan"
+    output.mkdir()
+    inventory_path = output / "role-inventory.toml"
+    previous = b"previous inventory"
+    if preexisting:
+        inventory_path.write_bytes(previous)
+    invalid_source = root / "chapters/chapter-0006.ssmd.md"
+    invalid_source.write_text("not valid SSMD", encoding="utf-8")
+
+    failed = compile_bundle(root, planner_config=_planner_config())
+
+    assert failed.exit_code == 1
+    assert failed.role_inventory_path is None
+    if preexisting:
+        assert inventory_path.read_bytes() == previous
+    else:
+        assert not inventory_path.exists()
+
+    invalid_source.write_text(
+        (root / "chapters/chapter-0005.ssmd.md").read_text(encoding="utf-8"),
+        encoding="utf-8",
+    )
+    recovered = compile_bundle(root, planner_config=_planner_config(), force=True)
+    assert recovered.exit_code == 0
+    assert recovered.role_inventory_path == inventory_path
+    assert load_bundle_role_inventory(inventory_path).bundle_kind == "book"
+    if preexisting:
+        assert inventory_path.read_bytes() != previous
+
+
 def test_document_bundle_only_accepts_all_chapters_for_compile_and_render(tmp_path: Path) -> None:
     root = _document(tmp_path / "story.ssmd-bundle")