utterplan 0.6.6__tar.gz → 0.6.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.6
+Version: 0.6.8
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License

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

@@ -26,10 +26,43 @@ utterplan bundle compile novel.ssmd-bundle --chapters 5-17
 utterplan bundle compile story.ssmd-bundle --text-preparation identity
 ```
 
+When already inside a bundle root, `.` is also accepted because the supplied path is resolved before the directory name is validated:
+
+```bash
+cd story.ssmd-bundle
+utterplan bundle compile --lang en .
+```
+
 Compilation defaults to all items. For book bundles, `--chapters` selects manifest `source_number` values: one number, an inclusive range, or comma-separated combinations such as `1,3-5,9`. Selected items retain manifest order. A document bundle accepts only `--chapters all`.
 
 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:
@@ -58,7 +91,7 @@ The full variant directory name, including its profile fingerprint, is required.
 
 ## Safe and read-only behavior
 
-The bundle path must be a directory named `<name>.ssmd-bundle` containing a regular `manifest.json`. Manifest item paths must be normalized relative POSIX paths, remain inside the resolved root, and resolve to regular files. Symlink escapes and unsafe output collisions are rejected. Manifest size and document size are bounded. Source digests are not used to replace current edited content; the manifest and source files are never refreshed or rewritten.
+The supplied workspace path is resolved first. The resolved directory must be named `<name>.ssmd-bundle` and contain a regular, non-symlink `manifest.json`. Therefore `.` and equivalent aliases are valid when they resolve to the bundle root; paths to `chapters/` or an item file remain invalid. Manifest item paths must be normalized relative POSIX paths, remain inside the resolved root, and resolve to regular files. Symlink escapes and unsafe output collisions are rejected. Manifest size and document size are bounded. Source digests are not used to replace current edited content; the manifest and source files are never refreshed or rewritten.
 
 ## Python API
 
@@ -80,3 +113,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.6 → utterplan-0.6.8}/docs/changelog.md

@@ -4,6 +4,22 @@
 
 ## [Unreleased]
 
+## [v0.6.8] - Unreleased
+
+### Added
+
+- Added renderer-neutral role inventories to full bundle compilation
+
+<!-- generated by releaseledger -->
+
+## [v0.6.7] - 2026-10-22
+
+### Fixed
+
+- Fixed bundle path detection when a path resolves to an SSMD bundle root
+
+<!-- generated by releaseledger -->
+
 ## [v0.6.6] - 2026-10-21
 
 ### Added

{utterplan-0.6.6 → utterplan-0.6.8}/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.6 → utterplan-0.6.8}/tests/test_bundle_replan.py

@@ -10,8 +10,10 @@ from renderplan import codec as renderplan_codec
 
 from tests.test_bundle_book_replan import _active_plan, _save_preflight, _setup
 from tests.test_bundle_services import _planner_config, _profile
+from utterplan._book_replan import BookReplanError, replan_book
 from utterplan.bundle import compile_bundle, render_bundle
 from utterplan.bundle_replan import BundleReplanError, replan_bundle
+from utterplan.ssmd_bundle import load_ssmd_bundle
 
 DOCUMENT_FIXTURE = Path(__file__).parent / "fixtures/document-bundle-v1/story.ssmd-bundle"
 
@@ -62,13 +64,24 @@ def _document_preflight(root: Path, variant: str, active_path: Path) -> Path:
 
 def test_replan_bundle_keeps_book_set_selection_and_immutable_child_behavior(
     tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     root, variant, variant_dir, _ = _setup(tmp_path, numbers=(5, 6))
     entry, parent, _ = _active_plan(variant_dir)
+    loaded_indexes = []
+
+    def tracked_load(path):
+        index = load_ssmd_bundle(path)
+        loaded_indexes.append(index)
+        return index
+
+    monkeypatch.setattr("utterplan.bundle_replan.load_ssmd_bundle", tracked_load)
+    monkeypatch.setattr("utterplan._book_replan.load_ssmd_bundle", tracked_load)
     preflight_path = _save_preflight(root / "voicerender", variant, entry.id, parent)
     starts = []
 
     result = replan_bundle(root, variant=variant, chapters="5", on_start=starts.append)
+    assert len(loaded_indexes) == 1
 
     assert result.kind == "book"
     assert result.selected_item_ids == ("chapter-0005",)
@@ -133,3 +146,10 @@ def test_document_replan_rejects_non_all_selector(tmp_path: Path) -> None:
     root = _document_bundle(tmp_path / "story.ssmd-bundle")
     with pytest.raises(BundleReplanError, match="document bundles only support --chapters all"):
         replan_bundle(root, variant="any", chapters="1")
+
+
+def test_book_replan_rejects_document_bundle_direct_call(tmp_path: Path) -> None:
+    root = _document_bundle(tmp_path / "story.ssmd-bundle")
+
+    with pytest.raises(BookReplanError, match="bundle manifest format is not a book"):
+        replan_book(root, variant="not-a-book")

utterplan-0.6.8/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]