XZBT-NGN/docs/reference/XZBT-NGN-Step6.6-Reference-Exhibit-Validation.md

# XZBT-NGN Step 6.6 — Reference Exhibit End-to-End Validation

Status: PASS — no implementation changes were required.

Step 6.6 validates Museum Gallery end-to-end as a complete Contract 5.3 reference
exhibit operating through the normal NGN operator UI. It is a validation task: no
architecture was redesigned, no features were added, and no source file was modified.

## A. Environment

| Item | Value |
| --- | --- |
| NGN UI | `http://127.0.0.1:4173/` |
| Server | The already-running `npm start` server on port 4173 (started at 16:43, before this session). A second instance started for validation failed to bind with `EADDRINUSE` and exited, so the served state was unchanged and the running server was left untouched. |
| Exhibit under test | `http://127.0.0.1:4173/test-fixtures/reference-exhibits/museum-gallery/control.html` |
| Replacement exhibit | `http://127.0.0.1:4173/test-fixtures/reference-exhibits/scifi/index.html` |
| Working tree | Step 6.3/6.4/6.5 uncommitted work preserved as found; HEAD `ed76cf6` |
| Method | Real NGN UI in a browser, driven through the served page (no test doubles) |

## B. Initial connection

Observed through the served NGN page after `Load exhibit`:

- Status: `connected · synchronized`
- Session: `sess-1f54f`
- Negotiated contract: `{ major: 5, minor: 3 }`
- Exhibit metadata: `Museum Gallery · 0.1.0 · build reference-exhibit`
- `registryRevision` 1, `stateRevision` 0
- Capabilities: `render: ready`
- Target registry discovered (5):

| Target | Kind | Access |
| --- | --- | --- |
| `artifact.selected` | selection | readable · writable |
| `lighting.level` | range | readable · writable |
| `rotation.speed` | range | readable · writable |
| `labels.enabled` | state | readable · writable |
| `action.spotlight-flash` | impulse | not readable · not writable |

- State snapshot received: `artifact.selected="the-orrery"`, `lighting.level=0.6`,
  `rotation.speed=0.4`, `labels.enabled=true`
- Protocol/error log: one `SESSION` entry, no errors

## C. Surface discovery and primary handling

`Presentation surfaces (3)` discovered, exactly the three the exhibit advertises:

| id | Label | Primary | Role | URL |
| --- | --- | --- | --- | --- |
| `surface.control` | Control Room | yes | control | `control.html` |
| `surface.artifact` | Artifact Display | no | ambient | `artifact.html` |
| `surface.info-wall` | Information Wall | no | information | `info-wall.html` |

Primary handling: the primary is not duplicated as a local pane. Its card carries the
`Primary` badge, shows `Open in the authoritative control frame. Use Connection controls
to reload or disconnect.`, and its Open/Reload/Close buttons are disabled. The two
non-primary surfaces open as local panes and each renders and reports
`Attached to Control Room.`

The Control Room's own `Attached non-primary surfaces` readout (the exhibit's participant
count) became `2` when both panes were open.

## D. Lifecycle validation

Measured participant count in the authoritative Control Room:

```text
open both:     2
reload:        2
reload again:  2
close one:     1
reopen:        2
```

Each reload produced a fresh secondary document (verified by a marker placed on the
frame's `contentWindow` disappearing after reload), which then re-attached and rendered
the current authoritative state. No ratcheting and no stale participant entries were
observed at any point.

## E. Shared-state validation

### Control -> secondaries

| Change made in Control Room | Observed propagation |
| --- | --- |
| Selected artifact -> Star Map | `selection.changed`, sequence 1, `stateRevision` 1, `source: "ui"`; both secondaries rendered `Star Map` |
| Lighting level -> 25% | `state.changed`, sequence 2, `stateRevision` 2, `source: "ui"`; Artifact Display rendered `Lighting: 25%` |

Control Room, Artifact Display, Information Wall and NGN's reported state all agreed
after each change.

### Secondary -> primary -> secondaries

A real mouse click on the Artifact Display's native `Cycle artifact` control while the
authoritative selection was `star-map`:

- Control Room's authoritative selection became `meteorite` (its combobox followed)
- `selection.changed`, sequence 3, `stateRevision` 3, `source: "ui"`
- Information Wall updated to `Meteorite Fragment`
- Artifact Display re-rendered from the authoritative result

The secondary remained a mirror: it holds no Core (see section H) and only routes
mutations back through the owner's canonical path.

### Late join

Information Wall closed (count 1) -> authoritative state mutated (rotation 1.7,
labels OFF, `stateRevision` 5) -> Information Wall reopened: it immediately rendered
`Meteorite Fragment` and `Labels: OFF`, and the count returned to 2.

### Reload recovery

Lighting mutated to 90% (`stateRevision` 6) -> Artifact Display reloaded: a fresh
document (marker gone) returned showing `Meteorite Fragment`, `Lighting: 90%`,
`Rotation: 1.7x` — current state, not exhibit defaults — with the count still 2.

### Sustained convergence

Four consecutive normal changes alternating between the primary and both secondaries
(control selection, Information Wall toggle, control rotation, Artifact Display cycle)
left Control Room, Artifact Display, Information Wall and NGN all in agreement at every
step, with revisions advancing 7 -> 8 -> 9 -> 10 and the count steady at 2.

## F. Host-command validation (NGN UI)

| Operation | NGN control used | Result |
| --- | --- | --- |
| Readable state query | `Refresh state` (`state.get`) | Succeeded; snapshot matched, `stateRevision` 10, status `connected · synchronized`, no error |
| `set` (range) | `lighting.level` -> `0.35` + `Set` | Succeeded; Control Room 35%, Artifact Display `Lighting: 35%`, `state.changed` revision 11, `source: "host"`, `correlationId: ngn-2-4` |
| `set` (selection) | `artifact.selected` -> Meteorite Fragment + `Set` | Succeeded; all surfaces `Meteorite Fragment`, `selection.changed` revision 12, `source: "host"`, `correlationId: ngn-2-6` |
| `invoke` (impulse) | `action.spotlight-flash` + `Invoke` | Succeeded; `action.executed` sequence 13, `source: "host"`, `correlationId: ngn-2-8`; exhibit `spotlightFlashCount` incremented; Control Room and both secondaries flashed `Spotlight flashed.` |

Each command left NGN's own state synchronized and produced no error entry. Instrumenting
the Artifact Display's announcement node with a DOM observer confirmed the host-initiated
`action.executed` event actually reached the secondary (it flashed, then returned to idle
after the announcer's 2.6 s window).

## G. Reconnect and replacement

### Disconnect / reconnect

- `Disconnect`: status `disconnected · not synchronized`; catalog reset to
  `Connect an exhibit to discover its controls.`; surfaces reset to
  `No presentation surfaces advertised.`; both local panes removed (0 surface iframes
  remaining); control frame removed; reported state `{}`; no error entries.
- `Reconnect`: new session `sess-15cf1`, Contract 5.3, all three surfaces rediscovered
  with correct primary handling, control frame re-established, participant count `0`
  (fresh authoritative document), no stale panes or counts.
- Both secondaries reopened and attached to the new session (count 2), each rendering the
  new session's current state.

### Exhibit replacement

- Museum -> SciFi (`scifi/index.html`): no Museum pane survived (0 iframes referencing
  the Museum exhibit), the surface catalog became `No presentation surfaces advertised.`
  (SciFi advertises none), and SciFi negotiated Contract 5.3 as
  `SciFi-XZBT · 5.2.0 · build production`, session `sess-2akzu3a7`,
  `connected · synchronized`, 61 targets, state snapshot received.
- SciFi -> Museum (`museum-gallery/control.html`): new session `sess-126c6`, Contract 5.3,
  5 targets, 3 surfaces rediscovered with the correct primary, participant count `0`,
  0 SciFi frames left, 0 stale Museum panes.

## H. Failure isolation

Live-tested through the served UI:

- **A non-primary surface holds no authority.** Inside the Artifact Display document:
  `XZBTContractCore` undefined, `MuseumGalleryContract` undefined,
  `MuseumGalleryExhibit` undefined, `XZBTHostTransport` undefined; only the surface bus is
  present, and `__museumGalleryDebug` exposes a `link` but no core.
- **A secondary cannot act as a protocol peer.** A forged `hello` and a forged `set`
  posted directly to the Artifact Display's window produced zero responses, and the
  authoritative selection was unchanged.
- **One broken presentation surface does not harm the control session.** The Artifact
  Display frame was navigated to a missing page (`does-not-exist.html`, served as
  `Not found`): the authoritative session stayed `connected · synchronized` on
  `sess-126c6`, the Control Room kept rendering, the registry/state were unaffected, and
  the surface's participant slot was released (count 2 -> 0) with no stale entry.
- **Reload failure is surface-local and recoverable.** NGN's per-surface `Reload` brought
  the pane back to `artifact.html`; it re-attached and the count returned to 1 while the
  session remained synchronized. No error was raised against the session.

Automated-only (covered by the suites below, not re-injected live):

- malformed / individually-invalid surface descriptors and catalog-level rejection
  (`surface-validation.test.js`, `museum-gallery.test.js` — 50 validation cases)
- isolated HTTP, frame and reload failures, external frame removal detection, and a
  stalled surface resource (`local-surfaces.test.js`)
- resource-check refusal of redirects before frame navigation (`local-surfaces.test.js`)
- presentation window cannot impersonate the authoritative peer over the production
  transport (`local-surfaces.test.js`)
- source/origin validation on the real postMessage transport
  (`postmessage-interop.test.js`)

## I. Automated verification

Focused run (Museum Gallery, local surfaces, surface validation, postMessage interop,
connection lifecycle):

```text
node --test tests/museum-gallery.test.js tests/local-surfaces.test.js \
  tests/surface-validation.test.js tests/postmessage-interop.test.js tests/connection.test.js
# tests 107
# pass 107
# fail 0
```

Full suite (run once):

```text
node --test
# tests 129
# pass 129
# fail 0
```

Other validation:

```text
git diff --check                 -> clean (exit 0)
python devlog_editor.py --validate -> devlog-editor: devlog is valid (exit 0)
```

## J. Files changed

None. Validation found no defect, so per the Step 6.6 fix policy no implementation file
was modified. The only additions are this report and its raw evidence record
(`test-fixtures/evidence/step6.6-museum-gallery-validation.txt`).

## K. Limitations

1. Failure isolation was live-tested only for the three cases in section H; malformed
   descriptor catalogs, redirect refusal, stalled resources and peer impersonation remain
   automated-only, and no risky manual failure injection was performed for them.
2. The `Spotlight flashed.` announcement on secondaries is transient (2.6 s idle timeout).
   It was confirmed with a DOM mutation observer rather than by a raw text read after the
   event, so the recorded evidence is the observer transition sequence.
3. All live checks were same-origin over `http://127.0.0.1:4173`. Cross-origin exhibits,
   `file://` documents, and non-`http` schemes were not exercised live.
4. The exhibit instance is recreated by `Disconnect`/`Reconnect` and by exhibit switching,
   so post-reconnect state is the exhibit's documented default state (`stateRevision` 0).
   No cross-session state persistence exists in the reference exhibit; this is expected
   standalone behavior, not a regression.
5. Local surfaces were exercised in one browser window; casting/remote displays remain
   out of scope for Step 6.6 and were not tested.

## L. Verdict

PASS. Museum Gallery behaves as a complete Contract 5.3 reference exhibit through the
normal NGN operator UI: connection and synchronization succeed, Contract 5.3 is
negotiated, the surface catalog and primary handling are correct, both secondaries render
locally and report attachment, participant counts stay correct across reload/close/reopen,
Control -> secondary and secondary -> primary -> secondaries synchronization are both
proven, late join and reload recovery return current state, representative host commands
work, disconnect/reconnect and exhibit switching clean up completely, SciFi still connects
and synchronizes, and the focused and full automated suites pass.