Steps 6.4-6.7B — Local surfaces, reference-exhibit validation, SciFi Observation surface

One commit for the work accumulated in the working tree since Step 6.3,
which had never been split into per-step commits:

- src/local-surfaces.js + src/surface-url.js (new); src/ui.js,
  src/validation.js, src/connection.js and public/index.html updated for
  local-surface hosting and generic surface rendering
- tests: local-surfaces (20), scifi-surfaces (24) and postmessage-interop (7)
  new; connection/museum-gallery/surface-validation suites updated
- reference exhibits: shared/contract-core.js defaults to Contract 5.3
  (major 5, minor 3, xzbt 5.3); museum-gallery advertises its surface
  catalog; aquarium/haunted-house/planetarium adapters updated
- SciFi-XZBT (Step 6.7A/6.7B): surface-mode.js + surface-bus.js,
  Observation-surface boot branch, local-change hooks, view.pillars /
  view.warp-flight targets; fixture byte-identical to G:/.vibe/SciFi-XZBT
- SciFi-XZBT contract adapter handshake fix: the inbound bridge filter no
  longer gates on an exact advisory xzbt value (Contract 5.3 §6.5), only on
  its presence/type, matching the host's own envelope validation; the
  adapter now advertises contract minor 3 / version 5.3.0, which it already
  implemented via the 5.3 surfaces field. Root cause of the five failing
  postmessage-interop tests (host hello was silently dropped).
- docs: architecture 6.4 and 6.7A, reference 6.6 and 6.7; evidence logs;
  test-fixtures/PROVENANCE.md resync record

Test results: NGN 154/154 (was 149/154); postmessage-interop 7/7 (was 2/7);
SciFi contract harness 21/21, real-adapter suite 32/32. git diff --check
clean for changed files; two pre-existing trailing-whitespace lines remain
in test-fixtures/reference-exhibits/scifi/index.html, copied verbatim from
the authoritative SciFi source.

Step 6.7 live verification (browser Observation, packaged standalone) is
still pending and is not claimed here.
This commit is contained in:
2026-09-14 19:45:27 -07:00
parent ed76cf6189
commit 745912e451
40 changed files with 5346 additions and 210 deletions
+73
View File
@@ -29,3 +29,76 @@ Local compatibility corrections:
NGN has no fixture-specific target logic. These corrections apply only to
the local fixture copies. No upstream fixes or independent conformance
certification are claimed.
## Step 6.7B resync (2026-09-15)
The `scifi/` fixture was resynced from the real SciFi-XZBT exhibit source at
`G:/.vibe/SciFi-XZBT/` after that repo's Step 6.7B implementation (SciFi
Observation Surface Integration, `docs/architecture/XZBT-NGN-Step6.7A-SciFi-Observation-Surface.md`).
Copied files (byte-for-byte from source, no fixture-local corrections):
- `index.html` — two new `<script>` tags for `surface-mode.js`/`surface-bus.js`
- `js/app.js` — boot-mode resolution, console/observation branching, the
surface-attachment bus wiring, `view.pillars`/`view.warp-flight` routing
- `js/contract-adapter.js` — `surfaces`/`instanceId` constructor options,
the `view.pillars`/`view.warp-flight` targets, `onLocalChange`/`onLocalAction`
hooks, `describe()`'s conditional `surfaces` field, version bump to 5.3.0
- `js/observation-engine.js` — WARP/PILLARS dock buttons now route through
`onMutation` (matching the existing VIEWPORT/RED ALERT/PRESET pattern)
instead of mutating engine state directly
- `css/style.css` — additive `body.surface-observation` rules
- `js/surface-mode.js` (new) — boot-mode resolver + surface catalog
- `js/surface-bus.js` (new) — instance-scoped BroadcastChannel sync
No fixture-local corrections were added on top of this resync; the fixture
is a faithful mechanical copy of the source as it stood after Step 6.7B.
`js/audio.js`, `js/config.js`, `js/core-animations.js`, `js/visualizer.js`,
`js/observation-bezels.js`, `js/generative-experience.js`, and `js/control-bus.js`
were not touched by Step 6.7B and were not recopied. `dist/` was not
regenerated (no PowerShell available in the environment that performed this
resync); it still reflects a pre-6.7B build and should be rebuilt from
source before any test or procedure that opens the packaged file.
## SciFi adapter handshake correction (2026-09-15)
Correction to the record above: the Step 6.7B resync note listed a "version
bump to 5.3.0" for `js/contract-adapter.js`, but no such bump was present in
the file as resynced — it still read `version = '5.2.0'` / `contractMinor = 2`.
The adapter also still carried a pre-5.3 inbound gate in `_setupWindowBridge`:
```js
if (!e.data || typeof e.data !== 'object' || e.data.xzbt !== '5.2') return;
```
That is an exact-string comparison against the advisory `xzbt` field, which
Contract 5.3 §6.5 designates as diagnostics-only metadata ("The negotiated
session contract major/minor is authoritative after handshake"). Because
XZBT-NGN's host stamps outgoing envelopes `xzbt: '5.3'` (Step 6.3), the gate
silently dropped every host message — including `hello` — and NGN's handshake
timed out against this exhibit (`tests/postmessage-interop.test.js`, four
tests).
Two source-side corrections were made in `G:/.vibe/SciFi-XZBT/js/contract-adapter.js`
and then copied here verbatim, keeping the one-directional source -> fixture
flow this file documents:
1. The inbound filter now checks the advisory field's *presence and type*
(`typeof e.data.xzbt !== 'string'`), matching how XZBT-NGN's host validates
the same field. It no longer branches on any particular value, so the
field cannot act as a compatibility gate for any sender.
2. The adapter advertises the contract it actually implements: `contractMinor`
`2` -> `3` and the exhibit product version `'5.2.0'` -> `'5.3.0'` (its
`describe()` already emitted the Contract 5.3 `surfaces` field added by
Step 6.7B). The file header now reads "Specification v5.3" to match.
The outbound advisory `xzbt: '5.2'` stamps on this adapter's own envelopes were
deliberately left unchanged: §6.5 makes the value non-authoritative, Step 6.7B
documented the envelope as unchanged, and no receiver — NGN included — reads
that value for admission. `dist/` remains a stale generated artifact and was
not regenerated.
Resynced file (source and fixture byte-identical,
SHA-256 `10ED30527153D5B30F23557BA6EC427884D470AB6561AC33C47E7F17AFA28DD9`):
- `js/contract-adapter.js`