utterplan 0.6.2__tar.gz → 0.6.3__tar.gz

{utterplan-0.6.2 → utterplan-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.2
+Version: 0.6.3
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License
@@ -353,6 +353,41 @@ creates or refreshes engine-backed profiles, then preflights and renders the
 resulting RenderPlans. The single-file `utterplan render-plan` command remains the
 low-level projection and deterministic replan primitive.
 
+When VoiceRender reports `preflight.replan`, use the new `replan-book` command to
+refine the exact active chapter plan. The operation reads the RenderProfile snapshot
+from the selected variant, writes a fingerprinted child RenderPlan, and updates only
+that chapter's active set entry. It does not replace the parent plan or rerun initial
+projection:
+
+```bash
+# VoiceRender measures the active plans; suppose chapter 5 returns preflight.replan.
+voicerender render-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5 \
+  --emphasis-policy defer-to-compose
+
+utterplan replan-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5
+
+# Measure/render the newly active child. Repeat these last two commands if it
+# still reports preflight.replan; each cycle must use feedback for the active plan.
+voicerender render-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5 \
+  --emphasis-policy defer-to-compose
+```
+
+Use the exact variant directory name (including its profile fingerprint). `replan-book`
+searches `preflight-recheck.toml` before `preflight.toml` and refuses stale feedback,
+so a report for a parent can never be applied to its child. The single-file
+`render-plan --previous ... --preflight ...` operation remains available for
+low-level replanning.
+
+This orchestration does not add a splitter, renderer-specific capacity estimate, or
+engine dependency. VoiceRender supplies preflight measurements and remains responsible
+for synthesis and audio composition.
+
 Related packages: [RenderPlan](https://pypi.org/project/renderplan/) defines the
 shared profile and plan contracts; [VoiceRender](https://pypi.org/project/voicerender/)
 creates engine-backed profiles and performs preflight and synthesis.

{utterplan-0.6.2 → utterplan-0.6.3}/README.md

@@ -109,6 +109,41 @@ creates or refreshes engine-backed profiles, then preflights and renders the
 resulting RenderPlans. The single-file `utterplan render-plan` command remains the
 low-level projection and deterministic replan primitive.
 
+When VoiceRender reports `preflight.replan`, use the new `replan-book` command to
+refine the exact active chapter plan. The operation reads the RenderProfile snapshot
+from the selected variant, writes a fingerprinted child RenderPlan, and updates only
+that chapter's active set entry. It does not replace the parent plan or rerun initial
+projection:
+
+```bash
+# VoiceRender measures the active plans; suppose chapter 5 returns preflight.replan.
+voicerender render-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5 \
+  --emphasis-policy defer-to-compose
+
+utterplan replan-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5
+
+# Measure/render the newly active child. Repeat these last two commands if it
+# still reports preflight.replan; each cycle must use feedback for the active plan.
+voicerender render-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5 \
+  --emphasis-policy defer-to-compose
+```
+
+Use the exact variant directory name (including its profile fingerprint). `replan-book`
+searches `preflight-recheck.toml` before `preflight.toml` and refuses stale feedback,
+so a report for a parent can never be applied to its child. The single-file
+`render-plan --previous ... --preflight ...` operation remains available for
+low-level replanning.
+
+This orchestration does not add a splitter, renderer-specific capacity estimate, or
+engine dependency. VoiceRender supplies preflight measurements and remains responsible
+for synthesis and audio composition.
+
 Related packages: [RenderPlan](https://pypi.org/project/renderplan/) defines the
 shared profile and plan contracts; [VoiceRender](https://pypi.org/project/voicerender/)
 creates engine-backed profiles and performs preflight and synthesis.

{utterplan-0.6.2 → utterplan-0.6.3}/docs/changelog.md

@@ -4,6 +4,14 @@
 
 ## [Unreleased]
 
+## [v0.6.3] - Unreleased
+
+### Added
+
+- Added replan-book to refine active book RenderPlans from matching VoiceRender preflight feedback
+
+<!-- generated by releaseledger -->
+
 ## [v0.6.2] - 2026-10-14
 
 ### Added

{utterplan-0.6.2 → utterplan-0.6.3}/docs/cli.md

@@ -205,6 +205,76 @@ are rejected before chapter processing. Exit status is 0 when all selected
 chapters succeed, 1 when any chapter fails, and 2 for usage or shared-configuration
 errors. See the [SSMDBook workflow guide](ssmdbook.md) for end-to-end and multi-voice examples.
 
+## Replan active RenderPlans for selected chapters
+
+`replan-book` is the book/variant orchestration for VoiceRender's capacity feedback.
+It loads the profile snapshot owned by the existing RenderPlanSet; callers must select
+the exact variant directory, not supply another profile:
+
+VoiceRender supplies capacity feedback: UtterPlan does not add renderer-specific
+metrics, a splitter, engine selection, synthesis, or audio composition.
+
+```text
+utterplan replan-book INPUT --variant VARIANT [--chapters SELECTOR]
+  [--renderplan-root PATH] [--voicerender-root PATH] [--report PATH]
+  [--dry-run] [--fail-fast] [--explain] [--json]
+```
+
+Example repeatable lifecycle:
+
+```bash
+# Initial projection and exact renderer preflight/render
+utterplan render-book . --profile narration4.renderprofile.toml --variant narration4 --chapters 5
+voicerender render-book . --variant narration4--28f616b6fe3b --chapters 5 \
+  --emphasis-policy defer-to-compose
+
+# If VoiceRender returns preflight.replan, refine only the active chapter plan
+utterplan replan-book . --variant narration4--28f616b6fe3b --chapters 5
+
+# Preflight/render the new active plan; repeat replan-book and this command if needed
+voicerender render-book . --variant narration4--28f616b6fe3b --chapters 5 \
+  --emphasis-policy defer-to-compose
+```
+
+`INPUT` is an SSMDBook root or its canonical `chapters/` directory. Chapter selectors
+use manifest source numbers and retain manifest order. The default RenderPlan root is
+`<book-root>/renderplan`; the default VoiceRender root is `<book-root>/voicerender`.
+The command reads `<variant>/renderprofile.toml` and the selected active plan paths
+from `renderplan-set.toml`. It discovers reports under
+`<voicerender-root>/<variant>/<chapter-id>/`, preferring `preflight-recheck.toml`
+over `preflight.toml` when both fully validate against the exact active RenderPlan.
+
+Only a matching `status="replan"` report is accepted. Missing reports, stale parent
+reports, mismatched profile/plan identities, and `ok`/`reject` statuses fail that
+chapter; the command never falls back to an initial RenderPlan projection. A successful
+replan writes a deterministic immutable child plan first, then atomically changes only
+the selected chapter's active set entry. Parent plans, source UtterPlans, profile
+identity, and unselected set entries remain unchanged. Run VoiceRender again after
+each replan; repeat the two feedback steps until preflight is `ok`.
+
+Defaults and behavior:
+
+- `--variant` is required and must name the existing full variant directory, including
+  its profile fingerprint. The profile snapshot is loaded from that collection.
+- `--chapters`: `all`, one source number, an inclusive range, or comma-separated
+  selections; default is `all`.
+- `--renderplan-root` and `--voicerender-root` override the collection/data roots,
+  not the selected variant or chapter paths recorded by the contracts.
+- `--report`: defaults to `<variant-dir>/replan-report.toml`; progress is persisted
+  after each chapter and the final report is marked complete.
+- `--dry-run`: validates and plans children without writing child RenderPlans or
+  changing the set index. It writes the operational report and reports successful
+  items as `planned`.
+- `--fail-fast`: later chapters are recorded as skipped after the first failure;
+  without it, later selected chapters continue.
+- `--explain` uses the existing per-request RenderPlan explanation; `--json` emits
+  structured outcome paths, identities, replacement counts, errors, and optional
+  explanations.
+
+Re-running with a stale report after activating a child fails with
+`renderplan.replan.book.preflight_stale`. VoiceRender must first measure the active
+child to produce its own matching feedback report.
+
 ## Explain a plan
 
 Explain an existing compiled plan as a human-readable speech narrative:

{utterplan-0.6.2 → utterplan-0.6.3}/tests/test_book_api.py

@@ -16,9 +16,15 @@ from utterplan import (
     BookCompileResult,
     BookRenderRequest,
     BookRenderResult,
+    BookReplanError,
+    BookReplanRequest,
+    BookReplanResult,
+    BookReplanStart,
     BookServiceError,
+    ReplanOutcome,
     compile_book,
     render_book,
+    replan_book,
 )
 from utterplan.config import LinguisticsConfig, PlannerConfig
 from utterplan.model import FlowPlan
@@ -95,9 +101,47 @@ def test_public_request_and_result_models_are_available_at_package_root() -> Non
         selected_chapter_ids=(),
         outcomes=(),
     )
+    replan_request = BookReplanRequest(Path("book"), variant="narration--abc")
+    replan_outcome = ReplanOutcome(
+        index=1,
+        id="chapter-0005",
+        source_number=5,
+        status="failed",
+        utterplan=None,
+        previous_renderplan=None,
+        previous_render_plan_id=None,
+        preflight=None,
+    )
+    replan_result = BookReplanResult(
+        workspace=Path("book"),
+        variant="narration--abc",
+        variant_dir=Path("book/renderplan/narration--abc"),
+        set_path=Path("book/renderplan/narration--abc/renderplan-set.toml"),
+        profile_path=Path("book/renderplan/narration--abc/renderprofile.toml"),
+        report_path=Path("book/renderplan/narration--abc/replan-report.toml"),
+        selected_chapter_ids=("chapter-0005",),
+        dry_run=False,
+        outcomes=(replan_outcome,),
+    )
+    replan_start = BookReplanStart(
+        workspace=Path("book"),
+        chapter_selector="5",
+        selected_chapter_ids=("chapter-0005",),
+        variant="narration--abc",
+        variant_dir=replan_result.variant_dir,
+        set_path=replan_result.set_path,
+        profile_path=replan_result.profile_path,
+        voicerender_dir=Path("book/voicerender/narration--abc"),
+        report_path=replan_result.report_path,
+    )
     assert compile_request.book == Path("book")
     assert render_request.profile == Path("profile.renderprofile.toml")
     assert compile_result.exit_code == render_result.exit_code == 0
+    assert replan_request.book == Path("book")
+    assert replan_result.exit_code == 1 and replan_result.failed == 1
+    assert replan_start.variant == replan_request.variant
+    assert callable(replan_book)
+    assert issubclass(BookReplanError, BookServiceError)
     assert compile_result.failed == render_result.failed == 0