XZBT-NGN/docs/reference/XZBT-NGN-Step6.7-Closure-Report.md

# XZBT-NGN Step 6.7 — Closure Report

**Status: not fully closed.** As of 2026-09-15, Step 6.7's implementation, its
handshake defect resolution, the automated baseline, and the packaged
standalone-build verification are complete. The live NGN Observation
verification (Step 6.7B report §15, steps 1–13) has not been performed and is
the only remaining item. Step 6.8 has not been started.

- Step 6.7A (design, no code): [architecture report](../architecture/XZBT-NGN-Step6.7A-SciFi-Observation-Surface.md)
- Step 6.7B (implementation): [implementation report](XZBT-NGN-Step6.7-SciFi-Surface-Adaptation.md)
- Packaging evidence: [step6.7-packaging.txt](../../test-fixtures/evidence/step6.7-packaging.txt)
- Fixture provenance: [PROVENANCE.md](../../test-fixtures/PROVENANCE.md)

## 1. What this report closes

Three items were outstanding when the 6.7B session ended; all three are now
closed:

1. The five failing `tests/postmessage-interop.test.js` tests (the "handshake
   gating mismatch") — resolved 2026-09-15, committed in `745912e` (§3).
2. The packaged standalone-build verification (6.7B report §K.14) — performed
   2026-09-15 (§4).
3. Source/fixture provenance for the SciFi-XZBT fixture — re-verified, and
   extended with the packaging record (§5).

Not closed by this report: live browser verification of the Observation
surface through NGN (6.7B report §15, steps 1–13) — see §9.

## 2. Step 6.7 delivery summary

SciFi-XZBT remains one document with two boot modes (`js/surface-mode.js`),
advertising a Contract 5.3 Observation presentation surface as a query-mode
view of its own `index.html` (`?surface=observation&xi=<instanceId>`, the
§31.4 form that keeps the surface inside the single-file build). Console mode
owns the single Contract 5.3 session, the one authoritative SciFi state, and
an instance-scoped `BroadcastChannel` bridge (`js/surface-bus.js`); an
Observation document attaches to that authority and never creates a second
one. Two new canonical targets (`view.pillars`, `view.warp-flight`) carry the
surface control path, and the heavy subsystems (WebLLM/Kokoro experience,
visualizer, control bus, contract adapter, hotkeys, sleep timer) remain
console-only, guarded by `isConsoleMode`.

NGN `src/**` was not modified by Step 6.7B: NGN renders whatever surface
catalog `describe()` advertises, generically. New focused coverage from 6.7B
is `tests/scifi-surfaces.test.js` (24 tests) and `tests/local-surfaces.test.js`
(20 tests, one driving SciFi's real descriptors); both are part of the
full-suite run recorded in §7.

## 3. Handshake defect: root cause and correction

**Root cause.** `js/contract-adapter.js`'s `_setupWindowBridge` admitted
inbound messages only when the advisory envelope field matched exactly:
`… e.data.xzbt !== '5.2'` → return. NGN's host stamps outgoing envelopes
`xzbt: '5.3'` (`src/host.js`, since Step 6.3). The adapter therefore silently
dropped the host's `hello` and every message after it; NGN's request timeout
produced four `hello timed out` interop failures. The fifth failure was the
existing static regression guard doing its job: an exact-string comparison
against the advisory field existed in a maintained file.

**Contributing defect.** The same adapter advertised `contractMinor = 2` and
product version `'5.2.0'` while already implementing the Contract 5.3-only
`surfaces` field in `describe()`, so the two interop assertions expecting
`contract.minor === 3` could not pass either.

**Correction** (in `G:/.vibe/SciFi-XZBT/js/contract-adapter.js`, then copied
verbatim into the fixture): the inbound filter now checks only the advisory
field's presence and type (`typeof e.data.xzbt !== 'string'`) — matching the
host's own envelope validation — and the adapter advertises
`contractMinor = 3` / `version = '5.3.0'`. Four lines in one file changed:
the header comment, `version`, `contractMinor`, and the filter. The outbound
advisory `xzbt: '5.2'` stamps were deliberately left unchanged (advisory
only; no receiver gates on the value; SciFi's own browser harness reads the
envelope as-is).

**Coverage.** The fix's behavior is pinned by `tests/postmessage-interop.test.js`'s
static guard ("no maintained bridge source gates on exact equality against the
advisory `xzbt` field") plus its two behavioral regression tests that
negotiate an *unexpected* advisory tag — the same tests that were failing.
No test was added or weakened for this correction.

## 4. Packaged standalone verification (this pass)

`tools/package.ps1` was run against the SciFi-XZBT source tree
(`powershell -ExecutionPolicy Bypass -File .\tools\package.ps1 -Force`, exit
code 0). It regenerated `dist/SciFiAmbientDisplay_V179b9db.html`, replacing a
pre-6.7B build (SHA-256
`B441820627D3FB23994D129B7425D781797E705867AC02967F96846B243435D4`; a
byte-identical copy of that pre-6.7B content is retained as
`dist/SciFiAmbientDisplay_Va723f46=1.html`). The new artifact:

- 920,730 bytes; 12 script blocks + 1 style block inlined
- SHA-256 `DFD9A91CB04CABD7BD6AAA53DA0FA7A641DBB21E3B3E11FAF3EC75946D6FA271`
- mirrored verbatim into `test-fixtures/reference-exhibits/scifi/dist/`
  (both copies byte-identical)

Verification performed on the regenerated artifact:

- **Inlining** (6.7B report risk R7: inlining failure is silent): every one of
  the 13 inputs is present as a contiguous byte-identical block after newline
  normalization; the built file contains zero `<script src=`, `<link href=`,
  or `<img src=` references; the two 6.7B scripts are inlined in `index.html`
  order; the corrected handshake filter is present and no exact advisory
  comparison remains anywhere in the file.
- **Standalone boot (`file://`)**: loads complete with 12 inline scripts
  (none with `src`), zero `<link>` elements, and one inlined stylesheet; the
  console UI renders (universe selector, 7 preset buttons, themed layout,
  canvases); `window.xzbtContractAdapter` advertises contract 5/3, version
  `5.3.0`, and the two-entry surface catalog.
- **Handshake over the served path**: served from
  `http://127.0.0.1:4173/test-fixtures/reference-exhibits/scifi/dist/…` — the
  same origin and tree NGN serves fixtures from — a same-origin host
  simulation stamped `xzbt: '5.3'` completed `hello` → `describe` →
  `state.get`: contract `{major: 5, minor: 3}`, exhibit version `5.3.0`,
  63 targets, both surfaces, and a state snapshot. This is precisely the
  exchange the pre-fix build silently dropped.
- **Boundary observed**: from `file://` the same probe gets no reply, because
  the adapter's origin guard rejects it (Chrome reports `e.origin` as
  `"null"` for `file://` documents). That is the designed same-origin/self
  safety filter — NGN attaches exhibits over `http://` only — not a defect,
  and it was not changed.

Filename caveat: the artifact's name carries SciFi-XZBT's HEAD commit
`179b9db`, but the build reads the working tree, which is ahead of that
commit (that repo's contract work, including the adapter correction, is still
uncommitted there — §9). The artifact is a snapshot of the working tree, not
of a single commit.

Environmental note: an `npm start` server was already running on
`http://127.0.0.1:4173` and served the artifact; this pass neither started
nor stopped a server.

Raw outputs: [step6.7-packaging.txt](../../test-fixtures/evidence/step6.7-packaging.txt).

## 5. Source/fixture provenance check

Re-verified after the packaging pass:

- `test-fixtures/reference-exhibits/scifi/` and `G:/.vibe/SciFi-XZBT/` are
  file-set identical for the deployable surface: the 13 `js/` + `css/` files
  and `index.html`, no extras and no omissions, every file byte-identical
  (per-file SHA-256 comparison).
- The regenerated `dist/` artifact is mirrored byte-identically (§4).
- The handshake correction is present in the authoritative adapter and the
  fixture copy alike; the one-directional source → fixture flow, including
  this packaging pass, is recorded in
  [PROVENANCE.md](../../test-fixtures/PROVENANCE.md).
- One cosmetic artifact is mirrored along with the content: `index.html`
  carries trailing whitespace on four script lines added by 6.7B. It predates
  this pass, is byte-identical in both trees, and was left unchanged to
  preserve that byte-identity.

## 6. Contract-policy confirmation

- Maintained contract: **major 5, minor 3**. NGN's host stamps the advisory
  `xzbt: '5.3'` and admits exhibits on the negotiated contract fields
  (`supportedContractMajors`, `contract.major`, integer `contract.minor`).
- The advisory `xzbt` field is **not** a compatibility gate anywhere in
  maintained paths: a repo-wide static scan for exact comparisons against it
  returns zero hits in `src/`, `tests/`, `public/`, `server/`, and the
  maintained reference exhibit sources (generated `dist/` builds and the
  git-ignored `test-fixtures/local/` copies excluded; the retained pre-6.7B
  artifact still contains the old comparison but is a build, not a maintained
  source path).
- Maintained exhibits advertise 5/3: the shared `contract-core.js` default,
  Museum Gallery, and SciFi-XZBT. Aquarium, Haunted House, and Planetarium
  declare no surface catalog (optional per §31; unchanged by 6.7).
- Compatibility with a genuine 5.2 exhibit remains the contract's own §28.2
  guarantee and was not altered; no maintained exhibit is pinned to 5.2.

## 7. Verification totals (2026-09-15)

| Check | Result |
| --- | --- |
| NGN full suite (`node --test`) | **154 / 154** pass, 0 fail, 0 skipped |
| `tests/postmessage-interop.test.js` | **7 / 7** (was 2 / 7) |
| `tests/scifi-surfaces.test.js` (inside the full run) | 24 / 24 |
| `tests/local-surfaces.test.js` (inside the full run) | 20 / 20 |
| SciFi-XZBT contract harness | 21 / 21 |
| SciFi-XZBT real-adapter suite | 32 / 32 |
| `python devlog_editor.py --validate` | devlog is valid |
| `git diff --check` | clean for this pass's files |
| Packaged artifact, structural + runtime | §4 above |

## 8. Files changed by this closure pass

Documentation, evidence, and generated artifacts only (left uncommitted; no
commit was requested):

- `test-fixtures/PROVENANCE.md` — packaging record added; two stale statements
  corrected (the resync's version-bump claim; the "dist/ not regenerated" note)
- `README.md` — Step 6.7 status line added; the SciFi surface declaration
  corrected (it now declares two surfaces)
- `docs/reference/XZBT-NGN-Step6.7-SciFi-Surface-Adaptation.md` — dated status
  updates in the header, §H, §J, §M, and the verdict
- `docs/reference/XZBT-NGN-Step6.7-Closure-Report.md` — this report
- `test-fixtures/evidence/step6.7-packaging.txt` — raw verification outputs
- `test-fixtures/reference-exhibits/scifi/dist/SciFiAmbientDisplay_V179b9db.html`
  — regenerated (git-ignored artifact)
- `G:/.vibe/SciFi-XZBT/dist/SciFiAmbientDisplay_V179b9db.html` — regenerated
  (outside this repository)

The handshake correction that this report closes was committed earlier as part
of `745912e` ("Steps 6.4-6.7B …"), pushed to `origin/main`.

## 9. Remaining work

**Step 6.7 remains open for one item: live NGN Observation verification**
(6.7B report §15, steps 1–13). Not performed in this pass:

1. Connect NGN to the SciFi fixture; confirm connected · synchronized, Contract 5/3, and the target catalog.
2. Confirm the Surfaces panel lists exactly two entries (`surface.console` primary, no Open button; `surface.observation`).
3. Open the Observation pane; confirm it renders the current universe/preset within ~1 s, shows no exit chrome, and is inert to background clicks.
4. Confirm the console does not black out and `view.observation` stays `false`.
5. Drive `set` from NGN for the seven listed targets (universe, preset, alert, viewport frame, activity, pillars, warp-flight); confirm both surfaces converge with advancing `stateRevision`.
6. Reload the pane; confirm it returns to current (not default) state, and close/reopen does not ratchet the participant count.
7. Press WATCH EXPERIENCE; confirm the pane is unaffected and `view.observation` toggles only the console overlay.
8. Inspect the pane's frame: no WebLLM/Kokoro network activity, no `window.generativeExperience`, no `AudioContext`.
9. Confirm transient activity events and AI announcements appear on console and pane at the same moment.
10. Disconnect/reconnect NGN; confirm clean pane release and rediscovery.
11. Standalone `index.html` opened directly with interaction (hotkeys, WATCH EXPERIENCE, audio) — only the packaged boot is evidenced so far (§4).
12. Standalone two-window mirroring (`index.html?surface=observation&xi=<real id>` with no NGN present).
13. `?surface=observation&xi=nonexistent` alone; confirm a waiting state with no invented authority.

Also outstanding, by design and outside Step 6.7:

- Step 6.8 has not been started.
- SciFi-XZBT's working tree remains uncommitted (its contract work, including
  the adapter correction, is untracked in that repository); the packaged
  artifact therefore reflects an uncommitted tree. A decision on committing
  that repository is pending.
- The retained pre-6.7B artifact `dist/SciFiAmbientDisplay_Va723f46=1.html`
  should not be distributed.