XZBT-NGN/STEP4-INDEPENDENT-REVIEW.md

Step 4 MVP — Independent Conformance Review

Reviewer: independent (not the implementing agent) Date: 2026-09-14 Scope: XZBT-NGN Step 4 MVP — host, transport, validation, UI, server, tests, and the three copied reference fixtures — against XZBT Exhibit Contract 5.2 and the NGN Implementation Plan v5.2. Method: read-only. No file in either repository was modified. Every claim below is tied to a command result or a file line.

---

1. Verdict

The Step 4 MVP is a genuine, working implementation of the Contract 5.2 host boundary, and its central genericity claim holds.

The host is real, not a mock: it negotiates a session, discovers a catalog it has never seen, renders controls from descriptors, drives state and impulses, tracks two independent counters, and recovers from desynchronization. I reproduced the automated suite at 20/20 passing. I independently confirmed that no product source file contains any exhibit-domain vocabulary.

The report's own verdict — STEP 4 MVP COMPLETE — MINOR FOLLOW-UP REQUIRED — is accurate and appropriately hedged. I found no defect that invalidates the MVP. I found one substantive conformance gap in the fixture layer (F-1), one host-side robustness gap (F-2), and a set of documentation and evidence-scope issues.

The most important finding is not a bug. It is that the fixture repairs are load-bearing for the genericity claim, and the report does not say so. The three fixtures are the only evidence that the host is generic. Those fixtures were edited to make them conform. That is legitimate — but it means the MVP has demonstrated that the host drives three repaired exhibits, not three unmodified ones. The report's phrase "a single unmodified host drives all three" is true of the host and false of the fixtures, and the distinction matters for what the MVP has actually proven.

---

2. What I verified independently

Claim	How I checked	Result
20 automated tests pass	node --test in G:\.vibe\XZBT-NGN	Confirmed. tests 20 / pass 20 / fail 0, 357 ms.
No domain vocabulary in product source	Select-String over src/*.js, src/transport/*.js, public/*.html, public/*.css, server/*.js for aquarium|planetarium|haunted|fish|apparition|scifi|universe|preset|warp|speech|announcement|tank|sky|room|telemetry	Confirmed. Zero matches. The only hit for a broader pattern was host.js:3, the canonical event-type list.
Fixture repairs are exactly as documented	git diff --no-index between G:\.vibe\SciFi-XZBT\exhibit-test\abacusai\reference-exhibits and test-fixtures/reference-exhibits	Confirmed, and complete. The entire delta is: 8 × kind: 'telemetry' → kind: 'state'; 1 × args: → arguments:; 3 × sky.magnitudeLimit → sky.magnitude-limit; 32 added lines in shared/contract-core.js; and deletion of host-harness/ and tests/.
The upstream source was not modified	git status in G:\.vibe\SciFi-XZBT	Confirmed. exhibit-test/ is untracked; no tracked file in the exhibit repo was touched by this work.
The magnitude repair was a real bug, not a cosmetic rename	Compared read() and dispatch() in both copies	Confirmed. Upstream planetarium/exhibit.js:397 read case 'sky.magnitudeLimit' while the descriptor at contract-adapter.js:36 declared sky.magnitude-limit. The reader returned null for a declared readable target, and native slider writes fell through to no case. The repair is correct and minimal.
The arguments repair was necessary	Read argumentSchema() in src/validation.js and the invoke path in shared/contract-core.js	Confirmed. Both read target.arguments. Upstream Planetarium declared args:, so its minutes argument was invisible to both the host and the fixture's own validator.

---

3. Findings

F-1 — Substantive: the fixture invoke path does not enforce INVALID_ARGUMENTS

Severity: medium. Conformance gap in the fixture layer, not in the host.

Contract §24 lists INVALID_ARGUMENTS as a distinct base error code, and the Authoring Guide's conformance checklist (line 522) requires that "unknown target, invalid value, invalid session, and invalid arguments each return the correct distinct error code."

The fixture core's invoke path (shared/contract-core.js, the block marked // Fixture-only correction for the owner's authoritative 5.2 clarification) returns INVALID_VALUE for every argument failure: undeclared key, missing required argument, wrong type, enum miss, bounds, step, and length. INVALID_ARGUMENTS appears in the ERROR_CODES array at the top of the same file and is never returned by anything.

The host is not at fault. src/validation.js validates arguments locally and raises INVALID_VALUE before the request leaves the browser, and src/host.js faithfully surfaces whatever code the exhibit returns. The host would handle INVALID_ARGUMENTS correctly if a fixture emitted it.

The practical consequence is that the MVP has no end-to-end evidence that a distinct INVALID_ARGUMENTS code survives the transport, because no fixture can produce one. The report's coverage list claims "argument constraints" are covered — true — but does not claim INVALID_ARGUMENTS specifically, and it should not, because it is not.

Note also that planetarium/exhibit.js does return INVALID_ARGUMENTS from advanceTime() for out-of-range minutes. That path is unreachable through the contract, because the fixture core rejects the value first with INVALID_VALUE. So the code exists in the fixture, is declared in the fixture's own error table, and is dead.

Recommendation: either return INVALID_ARGUMENTS from the fixture core for argument-shape failures (keeping INVALID_VALUE for value-constraint failures), or record explicitly in PROVENANCE.md and the report that the fixture layer collapses the two codes and that INVALID_ARGUMENTS is therefore unverified end-to-end. Do not leave it implicit.

F-2 — Host: validateCatalog does not validate restorable, category, or label

Severity: low. Robustness, not correctness.

Contract §9 requires each descriptor to carry restorable, category, and requires, and the Authoring Guide (line 94) repeats the list. validateCatalog in src/validation.js checks id, kind, readable, writable, and requires — but not restorable or category. A descriptor missing either is accepted silently.

This is defensible for an MVP: the host does not currently use restorable (no scenario restore yet) or category (no grouping in the UI), so an absent field cannot cause a wrong action. But the host is the component that will later drive scenario restore, and restorable is exactly the field that decides whether a target belongs in a restore snapshot. Validating it now is cheap and prevents a malformed descriptor from becoming a silent restore bug in Phase 4.

Recommendation: add typeof t.restorable === 'boolean' and typeof t.category === 'string' to the descriptor check in validateCatalog. Low priority; safe to defer to the scenario milestone if the owner prefers.

F-3 — Documentation: the genericity claim is stated more strongly than the evidence supports

Severity: medium. This is a reporting-accuracy issue, and it is the one I would fix first.

test-fixtures/reference-exhibits/README.md states: "The point of the set is not the exhibits; it is that a single unmodified host drives all three." The host is indeed unmodified and generic — I verified that. But the fixtures are not unmodified, and the README is the upstream document that PROVENANCE.md explicitly says "describes upstream verification and is not evidence of NGN verification."

The risk is concrete. A future reader — or a future agent — opening test-fixtures/reference-exhibits/README.md sees a claim of three unmodified exhibits driven by one host, and the README's own "Bugs found and fixed during verification" section lists the camelCase-ID bug as already fixed upstream. It is not fixed upstream. The upstream copy at G:\.vibe\SciFi-XZBT\exhibit-test\abacusai\reference-exhibits still has sky.magnitudeLimit in read() and dispatch(), still has kind: 'telemetry' in eight descriptors, and still has args: in Planetarium. Anyone who re-copies the fixtures from the stated source will reintroduce all three defects.

PROVENANCE.md is accurate and does list the corrections. The problem is that the README sits in the same directory, is longer, is more confident, and contradicts it.

Recommendation: add a short header note to the copied test-fixtures/reference-exhibits/README.md stating that this is a locally corrected copy, that the upstream README's verification claims do not apply to it, and pointing at PROVENANCE.md. One paragraph. Do not rewrite the upstream document.

F-4 — Evidence scope: the browser suite is not reproducible from the repository

Severity: low. Process, not product.

The report's strongest evidence is the real-browser suite: "3/3 real exhibits passed" via /test-fixtures/host-verification.html. I read test-fixtures/host-verification.js and it is a real, substantive test — it drives the production ExhibitHost and postMessageTransport against actual exhibit HTML in iframes, and it covers version rejection, handshake, catalog, state/range/selection writes, no-op revision, impulse execution, argument delivery, error survival, events, reconnect, forced session invalidation, and recovery. That is good evidence and I have no reason to doubt it.

What I cannot do is reproduce it. It requires a human to run npm start, open a browser, and click a button. There is no recorded output, no timestamped artifact, and no way for a reviewer to confirm the 3/3 result without re-running it by hand. The report is honest about this ("This is local Chromium evidence, not a cross-browser certification"), which is the right hedge.

Recommendation: none required for the MVP. If the owner wants the browser suite to carry weight in future reviews, have it write its result to a file or the console in a form that can be captured. Otherwise, treat the browser suite as supporting evidence and the 20 automated tests as the reproducible baseline — which is how the report already frames it.

F-5 — Observation: stateRevision is not reset on reconnect, and the host depends on that

Severity: informational. No action needed.

shared/contract-core.js deliberately preserves stateRevision across sessions while resetting sequence. The host's refresh() enforces snapshot.stateRevision >= baseline and rejects a regressed snapshot. The browser suite asserts host.stateRevision >= revisionBeforeReconnect.

This is correct and matches the README's stated rationale. I flag it only because it is a cross-component invariant that is not written down in the contract itself — Contract §14 says stateRevision is monotonic, and §16.1 says sequence resets per session, but the contract does not explicitly say what happens to stateRevision on a new session. The fixture and host agree; a future exhibit that reset stateRevision on handshake would be rejected by the host with "Snapshot revision regressed." Worth a line in the contract's §14 or in the authoring guide.

---

4. Contract conformance assessment

Against Contract §29 (Conformance Minimum), for the host:

Requirement	Status
Compatible handshake	Met. host.js sends supportedContractMajors: [5], validates the negotiated major, rejects otherwise.
Normalized message envelope	Met. Requests carry xzbt, type, requestId, sessionId; responses are matched by requestId and expected type.
describe	Met. refresh(true) requests it, validateCatalog checks it, the UI renders from it.
At least one discoverable target	Met. Catalog is built entirely from describe; no hard-coded IDs.
state.get for readable persistent targets	Met. refresh() requests it and enforces that the snapshot contains exactly the readable non-impulse set — both directions.
stateRevision	Met. Tracked, displayed, gap-detected, and protected against regression.
Normalized responses	Met. responses map enforces the expected result type per request.
Normalized event emission	Met. All six base event types accepted; unknown types rejected.
Session event sequencing	Met. Monotonic check, gap detection, resync, and per-session reset.
Command validation	Met. validateSet and validateArgs run before the request is sent.
Version reporting	Met. Contract, exhibit identity, registry revision, and state revision are all displayed.

The host meets the conformance minimum. The two gaps I found (F-1, F-2) are in the fixture layer and in descriptor-field strictness respectively; neither is a conformance-minimum failure.

Against the Implementation Plan §36 (MVP Acceptance Criteria), all twelve criteria are met, including the last one — "no SciFi-specific target vocabulary is hard-coded into core NGN logic" — which I verified directly rather than taking on trust.

---

5. Assessment of the report itself

The report is unusually good on the dimension that usually fails: it separates what was verified from what was not. Section N names the browser and date and calls the result local evidence. Section Q lists limitations without prompting. Section M states plainly that the fixtures needed repairs. Section O distinguishes the automated suite from the browser suite. The verdict is hedged rather than triumphant.

Three places where it is weaker than it should be:

1. Section M's framing. "The copied fixtures needed narrow documented corrections" is accurate but understates the consequence. Those corrections are what makes the genericity demonstration possible. The report should say that the MVP proves the host drives three repaired exhibits, and that the repairs are the reason the demonstration works.

2. Section O's coverage list. It claims "argument constraints" are covered, which is true, but a reader will reasonably infer that INVALID_ARGUMENTS is among them. It is not, and cannot be, given F-1.

3. Section M's table. "Aquarium 12 / Planetarium 14 / Haunted House 13" matches the descriptors I counted. Good. But the report does not note that the upstream README claims the same counts while the upstream fixtures would fail to load at all under a strict catalog validator — the camelCase IDs would throw at Catalog construction. That is worth one sentence, because it is the clearest evidence that the repairs were necessary rather than cosmetic.

None of these change the verdict. They change how much weight a future reader should put on it.

---

6. Recommended follow-up, in priority order

1. Add the copy-notice header to test-fixtures/reference-exhibits/README.md (F-3). One paragraph. Highest value per unit of effort, because it prevents a future re-copy from silently reintroducing three defects.
2. Resolve INVALID_ARGUMENTS (F-1) — either implement it in the fixture core or document the collapse explicitly in PROVENANCE.md.
3. Tighten validateCatalog (F-2) to check restorable and category. Deferrable to the scenario milestone.
4. Correct the three report framings in §5 above.
5. Optional: note the stateRevision-across-sessions invariant in the contract or authoring guide (F-5).

---

7. Bottom line

The MVP does what it claims. The host is genuinely generic, the transport genuinely validates origin and source, the state machine genuinely distinguishes revision from sequence, and the recovery paths are genuinely exercised. The fixture repairs were necessary, correctly diagnosed, and minimal — the magnitude repair in particular fixed a real null-read and a real dead native write path, not a cosmetic naming mismatch.

The one thing I would not let stand is the impression that three pristine exhibits were driven by an unmodified host. Three repaired exhibits were driven by an unmodified host, and the repairs are load-bearing. That is a fine result for an MVP — it is arguably the more useful result, because it found real bugs in the reference set. It just needs to be said plainly.