Document Step 6.7 packaging verification

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

@@ -0,0 +1,232 @@
+# 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.

docs/reference/XZBT-NGN-Step6.7-SciFi-Surface-Adaptation.md

@@ -1,9 +1,10 @@
 # XZBT-NGN Step 6.7B — SciFi Observation Surface Implementation
 
-Status: PARTIAL PASS. Implementation, focused tests, and full NGN test suite are
-complete against a pre-existing, out-of-scope defect. Live browser verification
-(report §15) and the standalone packaged-build check were not performed in this
-session.
+Status: PARTIAL PASS at the time of writing. Superseded 2026-09-15 by the
+[Step 6.7 closure report](XZBT-NGN-Step6.7-Closure-Report.md): the handshake
+defect recorded in §J/§M is fixed (full suite now 154/154) and the standalone
+packaged-build check in §H/§K.14 has been performed. Live NGN browser
+verification (report §15, steps 1–13) remains outstanding at that date.
 
 Step 6.7B implements the architecture selected by Step 6.7A (design-only, no
 code changes) — Candidate A, narrow form: SciFi-XZBT remains one document, one
@@ -120,6 +121,10 @@ Deviations, below) — narrative timing is shared, exact pixel content is not.
 
 ## H. Standalone verification
 
+Update (2026-09-15): performed — see the closure report and
+`test-fixtures/evidence/step6.7-packaging.txt`. The paragraph below retains the
+pre-verification state of this session.
+
 Not run live in this session (see §K). By construction: `index.html` with no
 query string resolves to console mode via `js/surface-mode.js`'s `resolve()`,
 which is unchanged from today's single-mode behavior for that input, and no
@@ -145,6 +150,10 @@ step (source → fixture), matching the procedure Step 5 used.
 | `tests/local-surfaces.test.js` | 20/20 pass |
 | Full NGN suite (`npm test`) | 149/154 pass |
 
+Update (2026-09-15): full suite **154/154** and `tests/postmessage-interop.test.js`
+**7/7** — the five failures are resolved (see the closure report). The
+paragraphs below are retained as this session's historical record.
+
 The 5 failures are all in `tests/postmessage-interop.test.js` (`hello timed
 out` ×4, one regex check), and are **not** caused by this step's changes.
 Root cause: `contract-adapter.js`'s `_setupWindowBridge` gates inbound
@@ -188,8 +197,8 @@ remain to be run manually:
 ## M. Remaining limitations
 
 - **Audio-reactive waveform is flat on the Observation surface**, as explicitly scoped out of 6.7B. No audio graph exists there; `observation-engine.js`'s pre-existing `am.analyser`-null guards degrade it gracefully. Deferred, not solved, per the governing report.
-- **`postmessage-interop.test.js`'s 5 failures** (see §J) are a pre-existing `5.2`/`5.3` handshake-gating mismatch between this SciFi-XZBT change and an independent, prior `src/host.js` change, outside this step's edit scope. Needs separate resolution — likely a version-gating fix in `contract-adapter.js`'s `_setupWindowBridge`, but that edit was withheld here because the report marks it must-not-change for 6.7B.
-- **Live browser verification and the packaged single-file build were not exercised** in this session (§K) — recommended before treating 6.7B as fully accepted.
+- **`postmessage-interop.test.js`'s 5 failures** (see §J) are a pre-existing `5.2`/`5.3` handshake-gating mismatch between this SciFi-XZBT change and an independent, prior `src/host.js` change, outside this step's edit scope. Needs separate resolution — likely a version-gating fix in `contract-adapter.js`'s `_setupWindowBridge`, but that edit was withheld here because the report marks it must-not-change for 6.7B. **Resolved 2026-09-15** as a separate, explicitly authorized task: the inbound filter is now a presence/type check on the advisory field, and the adapter advertises contract minor 3 / version 5.3.0. See the closure report.
+- **Live browser verification and the packaged single-file build were not exercised** in this session (§K) — recommended before treating 6.7B as fully accepted. Update (2026-09-15): the packaged build is regenerated and verified; live browser verification (report §15, steps 1–13) is still outstanding.
 
 ## Step 6.7 verdict
 
@@ -204,3 +213,10 @@ live NGN/browser and standalone/packaged-build verification in report §15
 has not been performed. Recommend resolving the handshake mismatch and running
 live verification before closing Step 6.7B, and explicitly deferring Step 6.8
 until then, per this task's instructions.
+
+Update (2026-09-15): the handshake mismatch is resolved and the full suite is
+green (154/154); the packaged single-file build has been regenerated and
+verified (fixture-consistent, structurally and behaviorally checked). See the
+[Step 6.7 closure report](XZBT-NGN-Step6.7-Closure-Report.md). What remains
+before Step 6.7 can be marked complete is the live NGN Observation
+verification in report §15, steps 1–13.