Generate shared narrative assets

README.md

@@ -78,7 +78,7 @@ solving remains future work.
 | Native solver event trace | Implemented as separate opt-in reference/optimized entry points with bounded observed events, full initial state, checkpoints, manifest v3, independent offline replay, and deterministic PNG/GIF views |
 | Reproducible Z3 summaries | Implemented for fixed seed/thread settings and explicit Boolean/Wang encoding order, result/model, and stable project-owned counts; no internal Z3 trace claim |
 | Observed-run dossier | Implemented as one opt-in generator of closed raw run metadata, fixed LaTeX, PDF, and reused trace/square/hex assets; four versioned SAT/UNSAT case definitions cover distinct execution shapes |
-| Full-pipeline multi-engine capture | Implemented as separate closed v2 case/run contracts and one atomic raw capture over Boolean Z3, one native reduction, reference, optimized, Wang Z3, and existing independent checkers; narrative assets and PDF v2 remain downstream work |
+| Full-pipeline multi-engine capture | Implemented as separate closed v2 case/run contracts and one atomic capture over Boolean Z3, one native reduction, reference, optimized, Wang Z3, and existing independent checkers; a closed shared-asset pass now binds semantic milestones and static square/generalized/hex presentations, while PDF v2 remains downstream work |
 | Native C JSON layer | Not implemented; `src/io/json.c` is a placeholder |
 | `TaskPlan` and native OpenMP solver | Not implemented; only the build scaffold exists |
 
@@ -234,6 +234,16 @@ The [observed-run dossier contract](docs/run_dossiers.md) defines the four
 versioned case classes, authoritative raw metadata, fixed TeX scaffolding,
 asset reuse, atomic output, and UNSAT evidence boundary.
 
+The v2 shared-asset pass is also opt-in through the same dossier command. It
+validates the raw multi-engine capture, renders Boolean/Wang encoding order,
+Yang--Zhang construction, both observed traces, verification receipts, the
+checked witness presentation, and the six-mechanism didactic overview, then
+records every GIF, reduced-motion fallback, contact sheet, frame, caption, alt
+text, semantic label, owner, and source hash in
+`wang-narrative-assets-v1`. The same generator can target a temporary
+`canonical-pages` bundle; tests require all compositor-produced bytes to match
+the run-specific bundle for identical inputs and parameters.
+
 To export one observed reference run and render selected replay states:
 
 ```sh

docs/plans/2026-08-31-narrative-migration-checklist.md

@@ -140,6 +140,7 @@ checks prove the old files are unreferenced before deletion.
 | `wang-explain-manifest-v3` | `/wang-solver-trace/` | Retain trace-stage meaning |
 | `wang-run-case-v1` | `/run-dossiers/` | Preserve exact diagnostic case meaning and initial-domain override support |
 | `wang-run-dossier-v1` | `/run-dossiers/` | Preserve exact single-native-run report meaning and output shape |
+| `wang-narrative-assets-v1` | `/run-dossiers/` and `renderer/README.md` | Closed downstream record for fixed component assets, accessibility metadata, source identities, semantic milestones, and static PDF inputs |
 
 - [x] Add separate closed v2 case and dossier contracts; do not extend or
   loosen either v1 schema.
@@ -175,11 +176,11 @@ checks prove the old files are unreferenced before deletion.
    the atomic tileset or standard square/hex output.
 2. [x] Capture the explicit v2 multi-engine fields once per engine and bind all
    component identities by SHA-256.
-3. [ ] Produce shared assets through the existing validators, replay, and
+3. [x] Produce shared assets through the existing validators, replay, and
    compositor, including static semantic milestones.
-4. [ ] Update the optimized didactic asset to all six accepted mechanisms,
+4. [x] Update the optimized didactic asset to all six accepted mechanisms,
    keeping it secondary to observed trace output.
-5. [ ] Generate reduced-motion fallback, contact sheet, caption, alt text, and
+5. [x] Generate reduced-motion fallback, contact sheet, caption, alt text, and
    semantic record for every GIF.
 6. [ ] Move public ownership to component pages without duplicating files or
    explanations; update old pages to links in the same change.

docs/run_dossiers.md

@@ -120,19 +120,36 @@ once each. SAT assignments and tilings are checked with the existing pure
 Python checkers; native tilings also retain the assignment extracted by the
 existing Yang--Zhang witness bridge.
 
-The raw v2 directory contains `run.json`, the copied CM1-in-3 input, two
+The v2 directory contains `run.json`, the copied CM1-in-3 input, two
 existing trace-v3 manifests, their content-addressed snapshots, and the two
 existing Z3 summary documents. Both native manifests bind the same formula,
 tileset, region, and construction-provenance hashes. Agreement means equal
 SAT/UNSAT status plus independently valid SAT witnesses; different valid
 witnesses are not required to be byte-equal. UNKNOWN, mismatch, a truncated
 trace, or a failed checker aborts the capture before installation.
 
-The raw-capture implementation intentionally produces no v2 PDF or narrative
-raster. The closed run contract names the square, generalized, and hex
-relationships and leaves their artifact references null for the shared-asset
-pass. A later PDF formatter will consume those validated static assets without
-solving, checking, replaying, or rendering again.
+The downstream shared-asset pass then consumes only that validated capture.
+Its closed `wang-narrative-assets-v1` manifest names fixed component assets,
+not generic stages: Boolean and Wang Z3 encoding order, canonical region
+construction, observed reference and optimized traces, the six checker
+records, the checked square/generalized/hex witness sequence, the six retained
+optimized mechanisms, and the complete pipeline overview. Every GIF record
+contains one reduced-motion PNG, contact sheet, caption, alt text, semantic
+label, source identity, completeness/selection scope, and all static frame
+hashes.
+
+Trace frames use `semantic-milestones-v1`, which selects event and phase
+transitions before deterministic gap filling; it is distinct from uniform
+sampling and reuses the same single replay as PNG, contact-sheet, and GIF
+encoding. For SAT, `run.json` binds the three reserved static presentation
+artifacts and their hashes. For UNSAT they remain null, while the asset bundle
+records an explicit not-applicable panel and never fabricates a witness or
+certificate. The separate example is versioned at
+`examples/run-cases-v2/pipeline-unsat-search.json`.
+
+No v2 PDF is produced yet. Its later formatter will consume only the validated
+static milestone PNGs already named by the asset manifest, without solving,
+checking, replaying, or rendering again.
 
 All v2 durations use one monotonic nanosecond clock and are labelled
 `run-specific-observation-not-a-benchmark`. They are raw facts about that

docs/solver_byte_support_2026-08-20.md

@@ -14,10 +14,10 @@ nav_order: 60
 
 <figure class="algorithm-animation">
   <picture>
-    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-05.png' | relative_url }}">
-    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the five retained optimized serial mechanisms.">
+    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-06.png' | relative_url }}">
+    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the six retained optimized serial mechanisms.">
   </picture>
-  <figcaption><strong>Didactic replay.</strong> This shared animation locates byte-wise support aggregation among the five isolated mechanisms; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
+  <figcaption><strong>Didactic.</strong> This shared animation locates byte-wise support aggregation among the six isolated mechanisms, including the later lazy MRV index; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
 </figure>
 
 This report evaluates only the union of compatible neighbor tiles during

docs/solver_dynamic_stack_2026-08-17.md

@@ -14,10 +14,10 @@ nav_order: 30
 
 <figure class="algorithm-animation">
   <picture>
-    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-05.png' | relative_url }}">
-    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the five retained optimized serial mechanisms.">
+    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-06.png' | relative_url }}">
+    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the six retained optimized serial mechanisms.">
   </picture>
-  <figcaption><strong>Didactic replay.</strong> This shared animation locates the dynamic stack among the five isolated mechanisms; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
+  <figcaption><strong>Didactic.</strong> This shared animation locates the dynamic stack among the six isolated mechanisms, including the later lazy MRV index; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
 </figure>
 
 This report evaluates only DFS stack storage. The reference path still

docs/solver_initial_trail_2026-08-17.md

@@ -14,10 +14,10 @@ nav_order: 40
 
 <figure class="algorithm-animation">
   <picture>
-    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-05.png' | relative_url }}">
-    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the five retained optimized serial mechanisms.">
+    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-06.png' | relative_url }}">
+    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the six retained optimized serial mechanisms.">
   </picture>
-  <figcaption><strong>Didactic replay.</strong> This shared animation locates initial-trail omission among the five isolated mechanisms; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
+  <figcaption><strong>Didactic.</strong> This shared animation locates initial-trail omission among the six isolated mechanisms, including the later lazy MRV index; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
 </figure>
 
 This report evaluates undo-trail recording during initial propagation. The

docs/solver_queue_dedup_2026-08-20.md

@@ -14,10 +14,10 @@ nav_order: 80
 
 <figure class="algorithm-animation">
   <picture>
-    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-05.png' | relative_url }}">
-    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the five retained optimized serial mechanisms.">
+    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-06.png' | relative_url }}">
+    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the six retained optimized serial mechanisms.">
   </picture>
-  <figcaption><strong>Didactic replay.</strong> This shared animation locates queue deduplication among the five isolated mechanisms; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
+  <figcaption><strong>Didactic.</strong> This shared animation locates queue deduplication among the six isolated mechanisms, including the later lazy MRV index; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
 </figure>
 
 This accepted mechanism changes only the optimized propagation queue. An

docs/solver_sat_ownership_2026-08-20.md

@@ -14,10 +14,10 @@ nav_order: 50
 
 <figure class="algorithm-animation">
   <picture>
-    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-05.png' | relative_url }}">
-    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the five retained optimized serial mechanisms.">
+    <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/optimized-mechanisms/frame-06.png' | relative_url }}">
+    <img src="{{ '/assets/images/optimized-mechanisms/trace.gif' | relative_url }}" alt="Didactic comparison of the reference solver baseline and the six retained optimized serial mechanisms.">
   </picture>
-  <figcaption><strong>Didactic replay.</strong> This shared animation locates SAT ownership transfer among the five isolated mechanisms; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
+  <figcaption><strong>Didactic.</strong> This shared animation locates SAT ownership transfer among the six isolated mechanisms, including the later lazy MRV index; the measurements below, not the animation, establish its effect. The <a href="{{ '/assets/images/optimized-mechanisms/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all stages.</figcaption>
 </figure>
 
 This report evaluates only construction of a successful solver result. The

docs/wang_square_to_hex.md

@@ -37,9 +37,9 @@ construction. They are not attributed to either source's diagram notation.
 <figure class="algorithm-animation">
   <picture>
     <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/square-to-hex/frame-02.png' | relative_url }}">
-    <img src="{{ '/assets/images/square-to-hex/trace.gif' | relative_url }}" alt="Canonical square Wang tile mapped to a pointy-top hex tile while preserving four source edges and adding the fresh kappa color.">
+    <img src="{{ '/assets/images/square-to-hex/trace.gif' | relative_url }}" alt="Verified square-to-hex transformation preserving four source edges and adding the fresh kappa color.">
   </picture>
-  <figcaption><strong>Canonical example.</strong> The pure renderer-side port and its raster-independent checker produce this mapping; the animation itself is not a proof. The <a href="{{ '/assets/images/square-to-hex/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all four stages.</figcaption>
+  <figcaption><strong>Verified transformation.</strong> The pure renderer-side port and its raster-independent checker produce this mapping; the animation itself is not a proof. The <a href="{{ '/assets/images/square-to-hex/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all four stages.</figcaption>
 </figure>
 
 ## Project convention

docs/yang_zhang_builder_design.md

@@ -47,9 +47,9 @@ transport, and rendering have separate contracts.
 <figure class="algorithm-animation">
   <picture>
     <source media="(prefers-reduced-motion: reduce)" srcset="{{ '/assets/images/builder-routing/frame-04.png' | relative_url }}">
-    <img src="{{ '/assets/images/builder-routing/trace.gif' | relative_url }}" alt="Canonical Yang–Zhang region with native variable, forwarder, crossover, and clause gadget spans appearing in construction order.">
+    <img src="{{ '/assets/images/builder-routing/trace.gif' | relative_url }}" alt="Canonical Yang–Zhang construction with native variable, forwarder, crossover, and clause gadget spans appearing in source order.">
   </picture>
-  <figcaption><strong>Canonical example.</strong> The frames reveal spans from the versioned native construction sidecar; they are not timestamps from an instrumented builder. The <a href="{{ '/assets/images/builder-routing/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all six stages.</figcaption>
+  <figcaption><strong>Canonical construction.</strong> The frames reveal spans from the versioned native construction sidecar; they are not timestamps from an instrumented builder. The <a href="{{ '/assets/images/builder-routing/contact-sheet.png' | relative_url }}">static contact sheet</a> shows all six stages.</figcaption>
 </figure>
 
 ## 1. Module boundary

examples/run-cases-v2/pipeline-unsat-search.json

@@ -0,0 +1,18 @@
+{
+  "schema": "wang-run-case-v2",
+  "id": "pipeline-unsat-search-v2",
+  "title": "Separate UNSAT full-pipeline search capture",
+  "purpose": "Capture the named engines and observed native search for pipeline_unsat_search.cm13 without presenting it as part of the canonical SAT worked example.",
+  "source": "tests/instances/pipeline_unsat_search.cm13",
+  "expected_status": "unsat",
+  "reference_trace": {
+    "event_capacity": 8192,
+    "checkpoint_interval": 128,
+    "checkpoint_capacity": 64
+  },
+  "optimized_trace": {
+    "event_capacity": 8192,
+    "checkpoint_interval": 128,
+    "checkpoint_capacity": 64
+  }
+}

python/dossier/multi_engine.py

@@ -271,7 +271,7 @@ def generate_multi_engine_dossier(
     case_path: str | Path,
     output_directory: str | Path,
 ) -> Path:
-    """Capture all named engines once and atomically install the raw v2 dossier."""
+    """Capture all named engines once and atomically install the complete v2 dossier."""
     case: MultiEngineRunCase = load_run_case_v2(case_path, ROOT)
     destination = Path(output_directory).resolve()
     if destination.exists():
@@ -410,8 +410,32 @@ def generate_multi_engine_dossier(
             timings_ns=timings_ns,
             artifacts=artifacts,
         )
-        _write_atomic(staging / "run.json", _encode_document(run_document))
-        load_run_dossier_v2(staging / "run.json")
+        run_path = staging / "run.json"
+        _write_atomic(run_path, _encode_document(run_document))
+        load_run_dossier_v2(run_path)
+        from dossier.narrative_assets import (
+            NarrativeAssetError,
+            attach_narrative_assets,
+            generate_narrative_assets,
+        )
+
+        try:
+            narrative_manifest = generate_narrative_assets(
+                run_path,
+                staging / "assets/narrative",
+                product="run-specific",
+            )
+            run_document = attach_narrative_assets(
+                run_document,
+                staging,
+                narrative_manifest,
+            )
+        except NarrativeAssetError as error:
+            raise MultiEngineDossierError(
+                f"shared narrative asset pass failed: {error}"
+            ) from error
+        _write_atomic(run_path, _encode_document(run_document))
+        load_run_dossier_v2(run_path)
         _install_directory(staging, destination)
         return destination
     except Exception: