utterplan 0.6.7__tar.gz → 0.6.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.7
+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.7 → utterplan-0.6.8}/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:
@@ -87,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.7 → utterplan-0.6.8}/docs/changelog.md

@@ -4,6 +4,14 @@
 
 ## [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

{utterplan-0.6.7 → 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.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]

{utterplan-0.6.7 → utterplan-0.6.8}/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")
 

{utterplan-0.6.7 → utterplan-0.6.8}/tests/test_cli_bundle_compile_book.py

@@ -284,7 +284,8 @@ def test_unselected_missing_or_malformed_chapter_does_not_block_selected_range(
         ["bundle", "compile", str(root), "--chapters", "5-6", "--text-preparation", "identity"]
     )
 
-    capsys.readouterr()
+    captured = capsys.readouterr()
+    assert "role inventory:" not in captured.err
     assert result == 0
     assert (root / "utterplan/chapter-0005.utterplan.toml").exists()
     assert (root / "utterplan/chapter-0006.utterplan.toml").exists()

{utterplan-0.6.7 → utterplan-0.6.8}/tests/test_cli_bundle_document.py

@@ -7,6 +7,7 @@ from pathlib import Path
 import pytest
 import tomlkit
 
+from utterplan.bundle_role_inventory import load_bundle_role_inventory
 from utterplan.cli import build_parser, main
 from utterplan.model import FlowPlan
 
@@ -56,6 +57,14 @@ def test_compile_document_writes_default_layout_and_keeps_source_unchanged(
     assert "UtterPlan bundle compile" in captured.err
     assert f"[1/1] document-0001  {source}" in captured.err
     assert "written:   1" in captured.err
+    inventory_path = output_dir / "role-inventory.toml"
+    inventory = load_bundle_role_inventory(inventory_path)
+    assert (
+        f"roles:           {', '.join(role.name for role in inventory.roles) or '(none)'}"
+        in captured.err
+    )
+    assert "default-role:    required by " in captured.err
+    assert f"role inventory:  {inventory_path}" in captured.err
     assert "Original content." in _plan_text(plan_path)
     report = _report(report_path)
     assert report["requested"] == 1

{utterplan-0.6.7 → utterplan-0.6.8}/utterplan/__init__.py

@@ -20,6 +20,15 @@ from .bundle_replan import (
     BundleReplanStartCallback,
     replan_bundle,
 )
+from .bundle_role_inventory import (
+    BundleRole,
+    BundleRoleInventory,
+    BundleRoleInventoryError,
+    BundleRoleInventoryItem,
+    build_bundle_role_inventory,
+    load_bundle_role_inventory,
+    save_bundle_role_inventory,
+)
 from .compiler import (
     CompileResult,
     InputFormat,
@@ -139,6 +148,13 @@ __all__ = [
     "BundleCompileResult",
     "BundleCompileStart",
     "BundleCompileStartCallback",
+    "BundleRole",
+    "BundleRoleInventory",
+    "BundleRoleInventoryError",
+    "BundleRoleInventoryItem",
+    "build_bundle_role_inventory",
+    "load_bundle_role_inventory",
+    "save_bundle_role_inventory",
     "BundleReplanError",
     "BundleReplanResult",
     "BundleReplanStart",

{utterplan-0.6.7 → utterplan-0.6.8}/utterplan/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.6.7'
-__version_tuple__ = version_tuple = (0, 6, 7)
+__version__ = version = '0.6.8'
+__version_tuple__ = version_tuple = (0, 6, 8)
 
-__commit_id__ = commit_id = 'g5282696da'
+__commit_id__ = commit_id = 'g167978804'