Shape v8 runtime graph contract

docs/BEARING.md

@@ -186,19 +186,21 @@ Current direction and active tensions. Historical ship data is in
 
 ## Next Target
 
-With Code Dojo, DX-047/#342, DL-018/#343, #335, and #354 landed, the immediate
-`v7.2.0` focus is final release prep: version metadata, dated changelog,
-front-door release copy, release-readiness, and final-main tag validation.
+With `v7.2.0` tagged, published, and verified, the immediate target is #457:
+shape the V8 Runtime Graph and Scene IR product contract before implementation
+continues.
 
 ```text
-DOGFOOD release-story surfaces
-  -> #354 criteria audit
-    -> release-readiness and preflight
-      -> v7.2.0 tag decision
+VISOR v8 tracker (#457)
+  -> GraphQL Blocks source contract
+    -> bijou-block/1 artifact contract
+      -> ui-scene-ir/1 lowering contract
+        -> receipts, source maps, lower modes, and debug facts
+          -> DOGFOOD round-trip witness
 ```
 
-After `v7.2.0` stabilizes the current V7 surface, V8 must turn the proof chain
-into product contract:
+The proof chain that V7 shipped must become a product contract before Bijou
+pulls in broad Geordi, Wesley, browser, or native-render work:
 
 ```text
 GraphQL SDL fixture
@@ -211,18 +213,19 @@ GraphQL SDL fixture
 
 Recommended pull order:
 
-1. Finish the `v7.2.0` release-prep branch and Release Dry Run before any tag
-   is created.
-2. Merge release prep, sync local `main` to `origin/main`, and rerun
-   milestone-aware release-readiness from the exact tag commit.
-3. Create `v7.2.0` only from synced `main` after final-main evidence is green.
-4. Shape #302 into a V8 design packet with artifact semantics, receipt
-   invariants, source-map ownership, lower-mode contracts, and failure cases.
-5. Promote only the Runtime Graph and Scene IR issues needed for that contract
+1. Land the #457 design packet that defines GraphQL Blocks source model,
+   `bijou-block/1` artifact semantics, `ui-scene-ir/1` lowering contract,
+   receipt and source-map ownership, lower-mode rules, debug facts, failure
+   cases, and DOGFOOD witness criteria.
+2. Promote only the Runtime Graph and Scene IR issues needed for that contract
    out of `Beyond`.
-6. Keep `v9.0.0` for Product Workbench and operator surfaces after V8 stabilizes
+3. Pull #458 as the first implementation proof: emit a GraphQL block artifact
+   bundle with replay and visual scene facts.
+4. Pull #459 after #458 fixes the bundle shape: validate
+   `packed-bijou-cells/1` and adapt it to `Surface`.
+5. Keep `v9.0.0` for Product Workbench and operator surfaces after V8 stabilizes
    the source/artifact/IR contract.
-7. Keep closed dependency PR #326 as superseded lineage, not active release
+6. Keep closed dependency PR #326 as superseded lineage, not active release
    work.
 
 Non-goals for the next cycle:

docs/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 All packages (`@flyingrobots/bijou`, `@flyingrobots/bijou-node`, `@flyingrobots/bijou-tui`, `@flyingrobots/bijou-tui-app`, `create-bijou-tui-app`, `@flyingrobots/bijou-i18n`, `@flyingrobots/bijou-i18n-tools`, `@flyingrobots/bijou-i18n-tools-node`, `@flyingrobots/bijou-i18n-tools-xlsx`, `@flyingrobots/bijou-mcp`) are versioned in lock-step.
 
+## [Unreleased]
+
+### Changed
+
+- **V8 Runtime Graph contract shaping** — `docs/BEARING.md` now treats #457 as
+  the immediate post-`v7.2.0` target,
+  [`DX-048`](design/DX-048-v8-runtime-graph-scene-ir-contract.md) records the
+  GraphQL Blocks, `bijou-block/1`, `ui-scene-ir/1`, receipts, source maps,
+  lower modes, debug facts, and DOGFOOD round-trip contract, and the `v7.2.0`
+  release packet now records the completed tag, publish, GitHub Release, and
+  npm registry verification evidence.
+
 ## [7.2.0] - 2026-07-05
 
 ### Added
@@ -2558,6 +2570,7 @@ First public release.
 - **Screen control** — `enterScreen()`, `exitScreen()`, `clearAndHome()`, `renderFrame()`
 - **Layout helpers** — `vstack()`, `hstack()`
 
+[Unreleased]: https://github.com/flyingrobots/bijou/compare/v7.2.0...HEAD
 [7.2.0]: https://github.com/flyingrobots/bijou/compare/v7.1.0...v7.2.0
 [7.1.0]: https://github.com/flyingrobots/bijou/compare/v7.0.0...v7.1.0
 [7.0.0]: https://github.com/flyingrobots/bijou/compare/v5.0.0...v7.0.0

docs/ROADMAP.md

@@ -228,8 +228,9 @@ that a cross-repository release is the next smallest honest boundary.
 
 ## Next Pull
 
-The immediate product pull after `v7.2.0` should shape the **v8.0.0 Runtime
-Graph and Scene IR product contract**.
+The immediate product pull after `v7.2.0` should land
+[`DX-048`](./design/DX-048-v8-runtime-graph-scene-ir-contract.md) and shape the
+**v8.0.0 Runtime Graph and Scene IR product contract**.
 
 That pull should keep the V8 tracker staged around VISOR, artifact semantics,
 receipts, source maps, lower modes, debug facts, DOGFOOD round-trip fixtures,
@@ -245,7 +246,7 @@ remain the intended feature horizons after the stabilization release.
 | :--- | :--- | :--- | :--- | :--- |
 | `v7.1.0` | Shipped Post-V7 Minor | Landed DX-046 [#329](https://github.com/flyingrobots/bijou/issues/329), release-prep guardrails [#270](https://github.com/flyingrobots/bijou/issues/270) and [#312](https://github.com/flyingrobots/bijou/issues/312), the v7.1.0 release PR, and `Unreleased` changelog work after `v7.0.0` | The repo shipped a meaningful post-V7 batch without turning it into a new product epoch. | Met: DX-046 green, #270/#312 green, release evidence packet written, #329 kept in `v7.1.0` without moving #302 out of `Beyond`, and no broad scope creep. |
 | `v7.2.0` | Demo Integrity And Framework Input Stabilization | Release-gate goalpost [#354](https://github.com/flyingrobots/bijou/issues/354), framework input stories [#344](https://github.com/flyingrobots/bijou/issues/344), [#345](https://github.com/flyingrobots/bijou/issues/345), [#353](https://github.com/flyingrobots/bijou/issues/353), landed DOGFOOD repair stories [#340](https://github.com/flyingrobots/bijou/issues/340), [#341](https://github.com/flyingrobots/bijou/issues/341), [#342](https://github.com/flyingrobots/bijou/issues/342), [#343](https://github.com/flyingrobots/bijou/issues/343), landed release-story story [#335](https://github.com/flyingrobots/bijou/issues/335), and security patches [#357](https://github.com/flyingrobots/bijou/issues/357), [#370](https://github.com/flyingrobots/bijou/issues/370). | The v7.1 proof exists, but the release-video rehearsal exposed demo-breaking seams in localization, theme posture, Blocks docs, release-story surfaces, and mouse routing; GitHub/npm audit also reported narrow development-tooling and dependency advisories that are now triaged clean. | Workspace pointer fallthrough fixed, page-frame helper exports public, mouse test helpers available, DOGFOOD demo surfaces honest enough for release video, audit clean, #335 release-story surfaces implemented, and release-readiness green. |
-| `v8.0.0` | Runtime Graph And Scene IR Product Contract | Staged milestone tracker [#457](https://github.com/flyingrobots/bijou/issues/457), VISOR artifact bundle [#458](https://github.com/flyingrobots/bijou/issues/458), and packed Bijou cell adapter [#459](https://github.com/flyingrobots/bijou/issues/459). Candidate source lineage remains in Beyond: [#202](https://github.com/flyingrobots/bijou/issues/202), [#209](https://github.com/flyingrobots/bijou/issues/209), [#210](https://github.com/flyingrobots/bijou/issues/210), [#211](https://github.com/flyingrobots/bijou/issues/211), [#212](https://github.com/flyingrobots/bijou/issues/212), [#213](https://github.com/flyingrobots/bijou/issues/213), [#216](https://github.com/flyingrobots/bijou/issues/216), [#219](https://github.com/flyingrobots/bijou/issues/219), [#301](https://github.com/flyingrobots/bijou/issues/301), and [#302](https://github.com/flyingrobots/bijou/issues/302). | This is the current product direction after DX-043 through DX-046 and the VISOR planning turn: portable scenes, GraphQL blocks, deterministic debug facts, packed terminal cells, replay/capture evidence, and product fixtures need to become a stable contract. | Stable artifact semantics, DOGFOOD round-trip fixtures, terminal/frame-capture proof, lower-mode and source-map receipts, and failure tests. |
+| `v8.0.0` | Runtime Graph And Scene IR Product Contract | Staged milestone tracker [#457](https://github.com/flyingrobots/bijou/issues/457), design packet [`DX-048`](./design/DX-048-v8-runtime-graph-scene-ir-contract.md), VISOR artifact bundle [#458](https://github.com/flyingrobots/bijou/issues/458), and packed Bijou cell adapter [#459](https://github.com/flyingrobots/bijou/issues/459). Candidate source lineage remains in Beyond: [#202](https://github.com/flyingrobots/bijou/issues/202), [#209](https://github.com/flyingrobots/bijou/issues/209), [#210](https://github.com/flyingrobots/bijou/issues/210), [#211](https://github.com/flyingrobots/bijou/issues/211), [#212](https://github.com/flyingrobots/bijou/issues/212), [#213](https://github.com/flyingrobots/bijou/issues/213), [#216](https://github.com/flyingrobots/bijou/issues/216), [#219](https://github.com/flyingrobots/bijou/issues/219), [#301](https://github.com/flyingrobots/bijou/issues/301), and [#302](https://github.com/flyingrobots/bijou/issues/302). | This is the current product direction after DX-043 through DX-046 and the VISOR planning turn: portable scenes, GraphQL blocks, deterministic debug facts, packed terminal cells, replay/capture evidence, and product fixtures need to become a stable contract. | Stable artifact semantics, DOGFOOD round-trip fixtures, terminal/frame-capture proof, lower-mode and source-map receipts, and failure tests. |
 | `v9.0.0` | Product Workbench And Operator Surfaces | Beyond: [#204](https://github.com/flyingrobots/bijou/issues/204), [#205](https://github.com/flyingrobots/bijou/issues/205), [#206](https://github.com/flyingrobots/bijou/issues/206), [#207](https://github.com/flyingrobots/bijou/issues/207), [#208](https://github.com/flyingrobots/bijou/issues/208), [#214](https://github.com/flyingrobots/bijou/issues/214), [#215](https://github.com/flyingrobots/bijou/issues/215), [#217](https://github.com/flyingrobots/bijou/issues/217), [#218](https://github.com/flyingrobots/bijou/issues/218), [#248](https://github.com/flyingrobots/bijou/issues/248), [#272](https://github.com/flyingrobots/bijou/issues/272), [#311](https://github.com/flyingrobots/bijou/issues/311), [#315](https://github.com/flyingrobots/bijou/issues/315), [#318](https://github.com/flyingrobots/bijou/issues/318). Triage: [#317](https://github.com/flyingrobots/bijou/issues/317), [#316](https://github.com/flyingrobots/bijou/issues/316). | Once V8 stabilizes the artifact contract, the next value is authoring and inspecting real product surfaces: BlockLab, Theme Lab, localization operations, artifact matrices, and host controls. | Storybook-grade BlockLab workflows, Theme Inspector/Lab provenance, localization workbench proof, artifact matrices, and playback-backed terminal input where applicable. |
 | `v10.0.0+` | Ecosystem Integration | Wesley, Geordi, and host integration follow-on work after V8/V9 shape the contracts | Cross-repository integration should consume proven Bijou contracts rather than define them under release pressure. | A cross-repo release packet with explicit dependency ordering, proof artifacts, and rollback boundaries. |
 

docs/design/DX-048-v8-runtime-graph-scene-ir-contract.md

@@ -0,0 +1,259 @@
+---
+title: DX-048 V8 Runtime Graph And Scene IR Contract
+legend: DX
+lane: release
+priority: high
+github_issue: 457
+status: active
+keywords:
+  - developer-experience
+  - runtime-graph
+  - scene-ir
+  - graphql
+  - blocks
+  - visor
+  - v8.0.0
+---
+
+# DX-048 V8 Runtime Graph And Scene IR Contract
+
+Legend: [DX - Developer Experience](../legends/DX-developer-experience.md)
+
+## Linked Work
+
+- Goalpost tracker: [#457](https://github.com/flyingrobots/bijou/issues/457)
+- First artifact proof:
+  [#458](https://github.com/flyingrobots/bijou/issues/458)
+- Packed-cell proof:
+  [#459](https://github.com/flyingrobots/bijou/issues/459)
+- Broad source lineage:
+  [#302](https://github.com/flyingrobots/bijou/issues/302)
+- VISOR coordination surface:
+  [flyingrobots/visor](https://github.com/flyingrobots/visor)
+- Prior Bijou proof:
+  [DX-046 GraphQL Authored DOGFOOD Block Fixture](./DX-046-graphql-authored-dogfood-block-fixture.md)
+
+## Decision Summary
+
+`v7.1.0` proved a constrained path from GraphQL SDL to `bijou-block/1`,
+`ui-scene-ir/1`, terminal proof, grouped debug facts, and DOGFOOD product
+facts. `v7.2.0` stabilized the demo and release surface enough to stop treating
+that path as release bookkeeping.
+
+The V8 work starts by freezing the product contract before implementation
+continues. DX-048 defines the source, artifact, IR, receipt, source-map,
+lower-mode, debug, capture, and witness boundaries that #458 and #459 must
+consume.
+
+VISOR is the coordination surface for the proof. Bijou remains responsible for
+the source-side contracts and the terminal `Surface` proof. Geordi, Wesley,
+Bunny, WARP TTD, browser renderers, and native renderers may consume or inform
+the contract later, but they do not define the first Bijou release gate.
+
+## Sponsor Human
+
+A maintainer wants V8 to become a stable product contract, not a pile of
+exciting demos. They should be able to ask, "what exactly crosses from GraphQL
+Blocks into Bijou Blocks IR and then into render targets?" and get a versioned,
+testable answer.
+
+## Sponsor Agent
+
+An agent needs to trace one product fact from a GraphQL source fixture through
+artifact fields, scene nodes, terminal cells, lower modes, source maps, debug
+facts, and receipts without scraping rendered text or guessing ownership.
+
+## Hill
+
+Given a checked-in DOGFOOD GraphQL fixture, Bijou can produce a deterministic
+artifact bundle with `bijou-block/1`, `ui-scene-ir/1`,
+`graphql-bijou-block-debug/1`, lower-mode witnesses, source maps, receipts, and
+packed-cell render evidence, and reviewers can replay the full path without any
+Wesley or Geordi repository changes.
+
+## Playback Questions
+
+- What is the GraphQL Blocks source model allowed to express?
+- Which facts belong in the `bijou-block/1` artifact and which belong only in
+  the compiler receipt?
+- What is the `ui-scene-ir/1` lowering contract and what facts must it preserve?
+- Who owns receipt and source-map ownership when a source field fans out into
+  multiple scene nodes or terminal cells?
+- Which lower modes are mandatory for a fixture before V8 calls it product
+  proof?
+- What debug facts are stable enough for DOGFOOD, VISOR, and future replay
+  tooling to inspect?
+- What invalid source cases fail before terminal rendering?
+
+## Scope
+
+This cycle defines the V8 contract and proof boundaries:
+
+- GraphQL Blocks source model:
+  - fixture identity
+  - component identity
+  - field identity
+  - group identity
+  - binding and command-intent identity
+  - i18n key references
+  - theme token references
+  - target render profile
+- `bijou-block/1` artifact semantics:
+  - stable artifact version
+  - deterministic field and group ordering
+  - explicit product-fact inventory
+  - hashable payload shape
+  - no hidden global registry dependency
+- `ui-scene-ir/1` lowering contract:
+  - stable scene version
+  - node identity and role ownership
+  - text, style, focus, and geometry facts
+  - lower-mode witness fields
+  - source-map references back to artifact and source spans
+- receipt and source-map ownership:
+  - source hash
+  - artifact hash
+  - scene hash
+  - packed-cell hash
+  - dependency and transform list
+  - failure facts for rejected input
+- debug fact contract:
+  - `graphql-bijou-block-debug/1` summary facts
+  - group, field, i18n, token, action, binding, lower-mode, and hash inventory
+  - deterministic error categories
+- DOGFOOD round-trip fixture:
+  - source fixture checked into the repo
+  - artifact bundle checked or snapshotted as test evidence
+  - terminal `Surface` proof
+  - lower-mode evidence
+  - review path documented in DOGFOOD or release-facing docs
+
+## Non-Goals
+
+This cycle does not:
+
+- implement the #458 artifact bundle
+- implement the #459 packed-cell adapter
+- migrate every DOGFOOD block to GraphQL
+- introduce a general GraphQL resolver runtime
+- require Geordi, Wesley, Bunny, WARP TTD, browser, or native app changes
+- ship BlockLab, Theme Lab, localization workbench, or operator surfaces
+- define the final browser or native render target APIs
+- move all #302 lineage issues into `v8.0.0`
+
+## Contract Sketch
+
+The minimum accepted artifact bundle should be inspectable as plain facts:
+
+```text
+graphql-source/1
+  -> bijou-block/1
+    -> ui-scene-ir/1
+      -> packed-bijou-cells/1
+        -> terminal-surface-proof/1
+```
+
+Each transition must produce a receipt:
+
+```text
+receipt/1 {
+  fromVersion
+  toVersion
+  sourceHash
+  outputHash
+  dependencyHashes[]
+  transformFacts[]
+  sourceMapRefs[]
+  lowerModeWitnesses[]
+  debugFactRefs[]
+}
+```
+
+The receipt is not a logging nicety. It is the review contract. If a future
+VISOR, DOGFOOD, WARP TTD, or browser proof cannot name the receipt it consumed,
+it is not part of the V8 release gate.
+
+## Failure Cases
+
+The V8 contract must reject:
+
+- duplicate source, field, group, node, binding, or command ids
+- missing component identity
+- missing product facts for a DOGFOOD witness
+- broken i18n key references
+- broken theme token references
+- source spans that cannot map back from artifact or scene facts
+- lower-mode witnesses that omit required role or text facts
+- packed cells that cannot map to scene nodes
+- debug summaries that omit hashes or dependency facts
+
+## Accessibility Posture
+
+The contract must preserve lower-mode witnesses. Terminal proof alone is not
+enough. Every accepted DOGFOOD fixture must expose accessible text and role
+facts through the artifact or scene receipt so reviewers can inspect a non-TTY
+representation.
+
+## Localization / Directionality Posture
+
+The GraphQL source may reference i18n keys and source-language fallback copy,
+but it must not smuggle untracked visible copy into the artifact. V8 must keep
+localization keys visible in debug facts and receipts so DOGFOOD can explain
+what translated and what fell back.
+
+## Agent Inspectability / Explainability Posture
+
+Agents must be able to inspect the complete source-to-render chain without
+executing a full app:
+
+- parse the fixture
+- read the artifact
+- read the scene IR
+- read the receipt list
+- read the source map
+- read debug facts
+- run the terminal proof
+- compare hashes
+
+This is the line between a demo and a product contract.
+
+## Linked Invariants
+
+- Tests Are the Spec
+- Runtime Truth Wins
+- Docs Are the Demo
+- Work Is Issue-Backed
+- Release Claims Need Proof
+- Facts Before Behavior
+
+## Implementation Outline
+
+1. Land this design packet and post-release BEARING refresh.
+2. Update #457 with the contract decision and the #458 / #459 pull order.
+3. Add tests that keep ROADMAP, BEARING, and this design aligned.
+4. In #458, introduce the artifact bundle fixture and receipt shape.
+5. In #459, validate `packed-bijou-cells/1` and adapt it to `Surface`.
+6. Only after #458 and #459 are stable, promote broader #302 lineage into V8
+   implementation scope.
+
+## Tests To Write First
+
+- WF-130 roadmap tests must require this design packet while #457 is open.
+- Artifact bundle tests in #458 should fail until `bijou-block/1`,
+  `ui-scene-ir/1`, receipts, source maps, and debug facts are emitted together.
+- Packed-cell tests in #459 should fail until `packed-bijou-cells/1` can map
+  cells back to scene nodes and render a `Surface` proof.
+
+## Validation Plan
+
+```bash
+npx vitest run --config vitest.config.ts tests/cycles/WF-130/roadmap-goalpost-policy.part01.test.ts tests/cycles/WF-130/roadmap-goalpost-policy.part02.test.ts tests/cycles/WF-130/roadmap-goalpost-policy.part03.test.ts
+npm run docs:inventory
+npm run typecheck:test
+npm run lint
+git diff --check
+```
+
+## Closeout Notes
+
+Open. This design is the first V8 pull after `v7.2.0` shipped.