BookWeaver Runtime Convergence

[austery]

Wayfinder Map: BookWeaver Runtime Convergence

Label: wayfinder:map

Destination

Produce an owner-approved target architecture and staged refactor route that converges BookWeaver on one Supported Product Path: EPUB-to-EPUB through bookweaver, with Antigravity as the subscription runtime, explicitly authorized Gemini API execution, and durable segment-level resume.

Markdown and PDF remain Isolated Format Capabilities that can be reintroduced without constraining the supported EPUB design. DOCX and the legacy shell orchestration receive no new compatibility commitment. Reaching the destination means all architectural and migration decisions are resolved and ready to become specifications and an implementation plan; implementation is not part of this map.

Notes

• Planning only: decision tickets produce decisions, not implementation deliverables.
• Preserve the working hexagonal core unless a ticket demonstrates that an existing seam cannot support the destination.
• Treat uv run bookweaver as the canonical product entry point.
• Preserve completed EPUB translations across interruption and explicitly authorized provider changes.
• Technical API availability never authorizes metered token usage.
• Use codebase-design vocabulary when placing module seams and evaluating depth.
• Use domain-modeling for product terms and hard-to-reverse domain decisions.
• Ground provider, checkpoint, and migration decisions in docs/architecture/specs/SPEC-020-antigravity-cli-migration-and-paid-api-authorization.md and its external reviews.

Decisions so far

• Audit the Canonical EPUB Runtime — canonical runtime = ai.cli/bookweaver; translatebook.sh is a frozen legacy orchestration shell that delegates all translation to ai.cli; doc↔code contradiction inventory C1–C8 dispositioned. Graduated: Probe %% fidelity, Design AntigravityProvider (blocked-by Probe Antigravity's %% multi-segment fidelity over a temp-file prompt #22), Paid-API explicit-authorization policy. Doc/cleanup actions recorded as a deferred implementation backlog on the resolution (out of this planning map's scope).
• Assign Provider Execution Policy Ownership — provider execution policy owned per SPEC-020 (as corrected by external review): (1) a static typed LogicalModelProfile registry (flash|pro) replaces ModelResolver/ModelProbe/config aliases (fail-loud); (2) typed TranslationError subclass hierarchy at the provider port, split-eligibility is a type property, adapters map raw→typed; (3) retry budget = composition-root-decided policy injected into a provider-agnostic TranslationEngine, raw providers single-attempt, adapters zero retry loops, _CLIAPIFallbackAdapter deleted — overrides Choose the Canonical Application Seam #15's factory-wrapped retry-adapter plug point (review BLOCKER 1). Cross-refs Make the Gemini API a paid, explicitly-authorized path gated by QuotaTracker #24 (paid auth), Design the AntigravityProvider adapter contract behind ITranslationProvider #23 (Antigravity availability), Choose the Configuration and CLI Contract #19 (config contract). Doc follow-ups: CONTEXT.md Model Profile, SPEC-020 §7.2 amendment.
• Decide the Non-EPUB Isolation Lifecycle — clean MD/PDF source adapters (ai/adapters/sources/{markdown,pdf}_adapter.py) retained in place behind a hard --allow-isolated-format opt-in (non-EPUB rejected fail-loud without it; --help advertises EPUB-only; a fitness function locks the supported CLI surface to EPUB). The legacy 0X Markdown pipeline (01/02/04/05/06/07 + pipeline_utils/01_prepare_env) and translatebook.sh are archived-via-Git with their tests (recovery anchor de0534e). DOCX archived with its hosts + ai.cli fail-loud rejects .docx (no adapter/stub/reintroduction). Reuse substrate = the retained adapters. Feeds Choose the Configuration and CLI Contract #19 (CLI contract), Define Verification and Deletion Gates #21 (deletion gates), Decide SPEC Lineage and Refactor Slices #20 (SPEC lineage). benchmark_models.py / 08_epub_roundtrip_baseline.py left untouched (out-of-scope / EPUB-side; only their shell launchers go away).
• Choose the Configuration and CLI Contract — public bookweaver contract locked. Model: --model {flash,pro} (typed choices, default flash, no external-session) + a new orthogonal --effort {low,medium,high} passthrough; model_thresholds removed; concrete (profile,effort)→agy model-id mapping + sparse matrix + version pinning deferred to Design the AntigravityProvider adapter contract behind ITranslationProvider #23 (needs Probe Antigravity's %% multi-segment fidelity over a temp-file prompt #22). Config: strict fail-loud via a new config/schemas/config_schema.json (additionalProperties:false) with explicit removed-key/flag migration errors + an anti-rot fitness test (schema keys == loader keys); removed model_aliases/fallback_chain/enable_fallback/model_probe/default_model/model_thresholds/output_format/bilingual_style/cli_api_fallback_enabled. Formats: --input-format narrowed to {auto,epub} (Markdown/PDF only under --allow-isolated-format via auto-detect; unknown/.docx fail-loud). Resume: --resume default-on, EPUB-only, intent-split no-op (silent when defaulted; fail-loud when explicit on an isolated run). Provider: --provider {cli,api} shape kept (authorization→Make the Gemini API a paid, explicitly-authorized path gated by QuotaTracker #24, cli→agy→Design the AntigravityProvider adapter contract behind ITranslationProvider #23), --cli-api-fallback removed. Config dir translatebook→bookweaver (fail-loud migration). Handoff: --effort mismatch → Choose the Checkpoint Durability Contract #16.

Not yet specified

• Exact target package layout after the canonical application seam is chosen.
• The exact release and deprecation sequence for legacy entry points.
• Which live smoke tests are required at each migration gate without incurring unauthorized API cost.
• Whether future Markdown or PDF support reuses the isolated adapters directly or introduces new adapters against the final application seam.

Out of scope

• Implementing the refactor while charting this map.
• Restoring DOCX as a supported format.
• Providing full product guarantees for Markdown or PDF in this effort.
• Adding a GUI, billing dashboard, persistent spending authorization, or automatic paid-provider fallback.
• Rewriting the working EPUB parser, patcher, or batching behavior without evidence that the destination requires it.
• A future "evaluation" feature area (small-sample translation spot-check via a re-introduced --only-docs, benchmark_models.py, SPEC-004 agent-eval, SPEC-016 sanity probe). Future roadmap effort, not this destination; seed/reference = ai/epub_translate_roundtrip.py @ git 79768c6 and branch feature/spec004-agent-eval-wip (both git-recoverable).