generated from Labyricorn/labyricorn-project-template
Compare commits
4
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
5075394f2a | ||
|
|
835d966e75 | ||
|
|
7249b33fca | ||
|
|
9dcd3993db |
@@ -2,26 +2,71 @@ _model: project
|
|||||||
---
|
---
|
||||||
schema_version: 1
|
schema_version: 1
|
||||||
---
|
---
|
||||||
project_id: labyricorn-project-template
|
project_id: xzbt-ngn
|
||||||
---
|
---
|
||||||
title: Labyricorn Project Template
|
title: XZBT-NGN Exhibit Engine
|
||||||
---
|
---
|
||||||
summary:
|
summary:
|
||||||
|
|
||||||
Initial template and publishing structure for Labyricorn-compatible projects and development logs.
|
A generic single-exhibit host for XZBT Exhibit Contract 5.3: session negotiation, descriptor-driven control discovery, presentation-surface rendering, state inspection, and set/invoke operations, with no exhibit-specific vocabulary in the host.
|
||||||
---
|
---
|
||||||
status: active
|
status: active
|
||||||
---
|
---
|
||||||
started: 2026-08-23
|
started: 2026-09-13
|
||||||
---
|
---
|
||||||
author: Labyricorn
|
author: cgcha
|
||||||
---
|
---
|
||||||
repository_url: https://git.labyricorn.com/Labyricorn/labyricorn-project-template
|
repository_url: https://git.labyricorn.com/Labyricorn/XZBT-NGN
|
||||||
---
|
---
|
||||||
default_branch: main
|
default_branch: main
|
||||||
---
|
---
|
||||||
tags: template, lektor, python
|
tags: xzbt, xzbt-ngn, exhibit-engine, contract-5-3, multi-surface, javascript
|
||||||
---
|
---
|
||||||
body:
|
body: |
|
||||||
|
XZBT-NGN is the host, orchestration and integration environment for exhibits that
|
||||||
|
speak the XZBT Exhibit Contract. It does not replace an exhibit; it extends one.
|
||||||
|
Everything an exhibit offers is discovered through the contract's target surface
|
||||||
|
and rendered generically, so no exhibit-specific vocabulary is hard-coded
|
||||||
|
anywhere in the host.
|
||||||
|
|
||||||
Starter template providing the standard .labyricorn/ publishing records, assistant instructions, devlog structure, and repository tooling for publication on Labyricorn.
|
## Completed work
|
||||||
|
|
||||||
|
The contract-boundary MVP is implemented and verified. A single unmodified host
|
||||||
|
negotiates a session, requests `describe`, renders discovered capabilities and
|
||||||
|
targets grouped by the exhibit's own categories, reads authoritative state,
|
||||||
|
submits set and invoke operations with full descriptor validation, displays
|
||||||
|
events with source and sequence, tracks registry and state revisions, and
|
||||||
|
recovers from synchronization loss. That same unmodified host drives five
|
||||||
|
maintained reference exhibits -- Aquarium, Planetarium, Haunted House, Museum
|
||||||
|
Gallery and SciFi-XZBT -- with no fixture-specific logic.
|
||||||
|
|
||||||
|
Contract 5.3 multi-surface support is complete. The host discovers presentation
|
||||||
|
surfaces from `describe`, resolves their URLs against the supplying exhibit's
|
||||||
|
document URL inside a same-origin boundary, and renders each in a local pane
|
||||||
|
that carries no contract session of its own. Museum Gallery exercises three
|
||||||
|
surfaces; SciFi-XZBT declares a console surface plus an Observation surface that
|
||||||
|
attaches to the console's single authority and never creates a second one.
|
||||||
|
|
||||||
|
Verification is automated and repeatable: 154 tests pass under `node --test`
|
||||||
|
with no npm dependencies and no build step, and the loopback server exposes only
|
||||||
|
`public/`, `src/` and `test-fixtures/` while denying paths that escape them.
|
||||||
|
|
||||||
|
## Formal design work
|
||||||
|
|
||||||
|
This repository is the canonical home of the XZBT Exhibit Contract Specification
|
||||||
|
(5.3 current; 5.2 retained as its historical predecessor, additively superseded),
|
||||||
|
the XZBT Exhibit Authoring Guide, and the NGN Implementation Plan. The
|
||||||
|
multi-surface architectural model was specified in full before implementation
|
||||||
|
and fixes the Step 6 / Step 7 boundary at the schema level: a surface descriptor
|
||||||
|
may name a document the host can load, and may never name a display transport,
|
||||||
|
casting protocol, network endpoint or device class.
|
||||||
|
|
||||||
|
## Future work
|
||||||
|
|
||||||
|
Step 7 -- display endpoints, meaning where a surface is physically shown -- is
|
||||||
|
specified by contrast in the multi-surface model but is not started. Casting and
|
||||||
|
remote displays, MIDI, MCP, webhooks, scenario authoring, recording, telemetry
|
||||||
|
connectors, integration adapters, packaging, multi-exhibit orchestration and
|
||||||
|
persistence all remain unimplemented; the host keeps in-memory state only. Five
|
||||||
|
non-blocking follow-up items requiring sustained human observation remain open
|
||||||
|
from the Step 6 closure.
|
||||||
@@ -1,594 +0,0 @@
|
|||||||
--- /mnt/user-data/uploads/XZBT-NGN/docs/contract/XZBT-Exhibit-Contract-Specification-v5.2.md 2026-09-14 20:04:53.376627937 +0000
|
|
||||||
+++ /home/claude/XZBT-Exhibit-Contract-Specification-v5.3.md 2026-09-14 20:19:48.228607469 +0000
|
|
||||||
@@ -1,10 +1,14 @@
|
|
||||||
# XZBT Exhibit Contract Specification
|
|
||||||
-## Version 5.2
|
|
||||||
+## Version 5.3
|
|
||||||
|
|
||||||
-**Status:** Proposed normative specification
|
|
||||||
-**Document version:** 5.2
|
|
||||||
-**Contract family:** XZBT Exhibit Contract
|
|
||||||
-**Compatibility major:** 5
|
|
||||||
+**Status:** Proposed normative specification
|
|
||||||
+**Document version:** 5.3
|
|
||||||
+**Contract family:** XZBT Exhibit Contract
|
|
||||||
+**Compatibility major:** 5
|
|
||||||
+**Supersedes:** Version 5.2, additively. No normative text in Sections 1–30
|
|
||||||
+below has been altered from 5.2 except the two explicitly-marked additions in
|
|
||||||
+Section 7 (the `surfaces` field reference) and Section 28 (subsection 28.8).
|
|
||||||
+See Section 39 for the full changelog.
|
|
||||||
**Primary consumers:** XZBT-compatible exhibits and XZBT-NGN Exhibit Engine
|
|
||||||
|
|
||||||
---
|
|
||||||
@@ -111,7 +115,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "hello",
|
|
||||||
"requestId": "req-001",
|
|
||||||
"host": {
|
|
||||||
@@ -126,7 +130,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "hello.result",
|
|
||||||
"requestId": "req-001",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -137,13 +141,15 @@
|
|
||||||
},
|
|
||||||
"contract": {
|
|
||||||
"major": 5,
|
|
||||||
- "minor": 2
|
|
||||||
+ "minor": 3
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
If no compatible major version exists, the exhibit MUST respond with an `error` carrying code `UNSUPPORTED_VERSION`, MUST echo the `requestId` when recoverable, and MUST NOT create a session.
|
|
||||||
|
|
||||||
+A 5.2-only exhibit reporting `{"major": 5, "minor": 2}` remains fully compatible with a 5.3-aware host under the ordinary contract-major compatibility rule (Section 28.1); nothing in this handshake requires either party to implement 5.3-specific behavior.
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Message Envelope
|
|
||||||
@@ -154,7 +160,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "invoke",
|
|
||||||
"requestId": "req-1042",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -169,7 +175,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "invoke.result",
|
|
||||||
"requestId": "req-1042",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -181,7 +187,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "error",
|
|
||||||
"requestId": "req-1042",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -219,7 +225,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "describe",
|
|
||||||
"requestId": "req-010",
|
|
||||||
"sessionId": "sess-7f2a"
|
|
||||||
@@ -230,7 +236,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "describe.result",
|
|
||||||
"requestId": "req-010",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -241,12 +247,13 @@
|
|
||||||
},
|
|
||||||
"contract": {
|
|
||||||
"major": 5,
|
|
||||||
- "minor": 2
|
|
||||||
+ "minor": 3
|
|
||||||
},
|
|
||||||
"registryRevision": 1,
|
|
||||||
"stateRevision": 27,
|
|
||||||
"capabilities": [],
|
|
||||||
- "targets": []
|
|
||||||
+ "targets": [],
|
|
||||||
+ "surfaces": []
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
@@ -256,6 +263,14 @@
|
|
||||||
|
|
||||||
NGN MUST discover targets instead of assuming that an exhibit exposes a fixed science-fiction vocabulary.
|
|
||||||
|
|
||||||
+**`surfaces` (introduced in Contract 5.3).** An OPTIONAL array of presentation
|
|
||||||
+surface descriptors, normatively defined in Section 31. Its absence, or an
|
|
||||||
+empty array, both mean the exhibit has not adopted multi-surface presentation
|
|
||||||
+and is functionally equivalent to a Contract 5.2 `describe.result`, which
|
|
||||||
+never contained this field. A 5.3-aware host MUST treat a `describe.result`
|
|
||||||
+lacking `surfaces` identically to one where `surfaces` is present and empty
|
|
||||||
+(Section 31.5).
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Canonical Target IDs
|
|
||||||
@@ -294,6 +309,9 @@
|
|
||||||
[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+
|
|
||||||
```
|
|
||||||
|
|
||||||
+This grammar also governs presentation surface identifiers (Section 31.2);
|
|
||||||
+no separate identifier grammar is defined for surfaces.
|
|
||||||
+
|
|
||||||
### 8.2 Stability
|
|
||||||
|
|
||||||
Once published as part of an exhibit's external contract, a canonical target ID becomes part of that exhibit's compatibility surface.
|
|
||||||
@@ -405,6 +423,11 @@
|
|
||||||
|
|
||||||
`kind` is authoritative for invokability. No separate `invokable` field is defined.
|
|
||||||
|
|
||||||
+Presentation surfaces (Section 31) are a structurally distinct descriptor
|
|
||||||
+family from targets and are never expressed using any target `kind`,
|
|
||||||
+including `impulse`. A host MUST NOT infer surface existence from any target
|
|
||||||
+descriptor.
|
|
||||||
+
|
|
||||||
### 9.5 Impulse arguments (authoritative Contract 5.2 clarification)
|
|
||||||
|
|
||||||
Impulse descriptors use `arguments`, an array of argument descriptors. This
|
|
||||||
@@ -489,7 +512,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "invoke",
|
|
||||||
"requestId": "req-200",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -514,7 +537,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "set",
|
|
||||||
"requestId": "req-201",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -537,7 +560,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "state.get",
|
|
||||||
"requestId": "req-300",
|
|
||||||
"sessionId": "sess-7f2a"
|
|
||||||
@@ -548,7 +571,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "state.result",
|
|
||||||
"requestId": "req-300",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -568,6 +591,11 @@
|
|
||||||
|
|
||||||
A state snapshot MUST NOT imply that every internal exhibit variable is externally exposed.
|
|
||||||
|
|
||||||
+State exposed through `values` is scoped to the one logical exhibit instance
|
|
||||||
+and its one session, regardless of how many presentation surfaces (Section
|
|
||||||
+31) are currently open. `state.get` MUST NOT be parameterized by surface, and
|
|
||||||
+no surface-specific state view is defined by this contract.
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 14. State Revision and Mutation Transactions
|
|
||||||
@@ -588,6 +616,10 @@
|
|
||||||
|
|
||||||
All contract-visible state changes committed by one transaction share one resulting `stateRevision`.
|
|
||||||
|
|
||||||
+A native interaction originating on any presentation surface (Section 31) is
|
|
||||||
+one mutation transaction, subject to this same rule, regardless of which
|
|
||||||
+surface it originated on.
|
|
||||||
+
|
|
||||||
### 14.2 Ordering
|
|
||||||
|
|
||||||
The exhibit MUST:
|
|
||||||
@@ -608,6 +640,11 @@
|
|
||||||
|
|
||||||
The counters serve different purposes and MUST NOT be treated as interchangeable.
|
|
||||||
|
|
||||||
+Multi-surface presentation does not introduce a second revision or sequence
|
|
||||||
+counter of any kind. Every presentation surface of one exhibit instance
|
|
||||||
+observes the same `stateRevision` history and the same event `sequence`
|
|
||||||
+stream defined here.
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 15. Source and Origin
|
|
||||||
@@ -632,6 +669,12 @@
|
|
||||||
|
|
||||||
This distinction is required for recording and feedback-loop prevention.
|
|
||||||
|
|
||||||
+An interaction originating on a presentation surface other than the primary
|
|
||||||
+surface (Section 31.3) uses the same `source` vocabulary as an interaction on
|
|
||||||
+the primary surface — typically `ui`. This contract does not define a
|
|
||||||
+per-surface source value; which surface an interaction originated on is not
|
|
||||||
+contract-visible.
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 16. Events
|
|
||||||
@@ -653,7 +696,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "state.changed",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
"sequence": 144,
|
|
||||||
@@ -669,7 +712,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "action.executed",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
"sequence": 145,
|
|
||||||
@@ -710,6 +753,13 @@
|
|
||||||
|
|
||||||
It SHOULD NOT automatically record its own `scenario` or host playback events back into the scenario being recorded unless explicitly configured.
|
|
||||||
|
|
||||||
+### 16.6 `registry.changed` and surfaces (Contract 5.3)
|
|
||||||
+
|
|
||||||
+`registry.changed` (Section 23) covers changes to `surfaces` in addition to
|
|
||||||
+`targets` and capability metadata. A single `registryRevision` governs both;
|
|
||||||
+this contract does not define a separate surface-registry revision. See
|
|
||||||
+Section 31.6.
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 17. Capability Model
|
|
||||||
@@ -751,6 +801,10 @@
|
|
||||||
|
|
||||||
A host MUST treat the current discovered state as authoritative.
|
|
||||||
|
|
||||||
+A presentation surface (Section 31) MAY declare `requires` against
|
|
||||||
+capability IDs defined here, using identical semantics to target `requires`
|
|
||||||
+(Section 9).
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 18. Speech
|
|
||||||
@@ -765,7 +819,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "invoke",
|
|
||||||
"requestId": "req-410",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -843,6 +897,9 @@
|
|
||||||
|
|
||||||
Each text target SHOULD declare a maximum accepted length.
|
|
||||||
|
|
||||||
+This restriction applies equally to any text rendered by a presentation
|
|
||||||
+surface (Section 31); surfaces introduce no new text-injection surface area.
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 21. Telemetry
|
|
||||||
@@ -899,7 +956,7 @@
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
- "xzbt": "5.2",
|
|
||||||
+ "xzbt": "5.3",
|
|
||||||
"type": "set",
|
|
||||||
"requestId": "req-520",
|
|
||||||
"sessionId": "sess-7f2a",
|
|
||||||
@@ -914,7 +971,7 @@
|
|
||||||
|
|
||||||
After lease expiration, the exhibit MAY return to simulated ownership.
|
|
||||||
|
|
||||||
-The exact telemetry lease mechanism remains optional in 5.2.
|
|
||||||
+The exact telemetry lease mechanism remains optional in 5.2, unchanged in 5.3.
|
|
||||||
|
|
||||||
A simple explicit release mechanism is also acceptable.
|
|
||||||
|
|
||||||
@@ -932,6 +989,10 @@
|
|
||||||
|
|
||||||
Registry revision SHOULD NOT change merely because a fixed target becomes contextually unavailable.
|
|
||||||
|
|
||||||
+As of Contract 5.3, `registryRevision` also governs the `surfaces` array
|
|
||||||
+(Section 31.6). One counter covers both; this contract does not define an
|
|
||||||
+independent surface-registry revision.
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 24. Error Codes
|
|
||||||
@@ -978,6 +1039,11 @@
|
|
||||||
|
|
||||||
Same-origin `postMessage` transports MUST validate both `event.origin` and `event.source` against the expected host relationship.
|
|
||||||
|
|
||||||
+The same-origin requirement in this section extends to presentation surface
|
|
||||||
+resolution and to any exhibit-internal attachment channel used between an
|
|
||||||
+exhibit's own documents (Section 31.7). Neither introduces a new trust
|
|
||||||
+boundary beyond the one already defined here.
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 26. Scenario Independence
|
|
||||||
@@ -1056,6 +1122,16 @@
|
|
||||||
|
|
||||||
An exhibit may add targets without changing the contract version, provided existing target semantics remain compatible.
|
|
||||||
|
|
||||||
+### 28.8 Contract 5.3 (presentation surfaces)
|
|
||||||
+
|
|
||||||
+Contract 5.3 adds the optional `surfaces` field to `describe.result`
|
|
||||||
+(Section 7) and the normative Presentation Surfaces model (Section 31), per
|
|
||||||
+the rule in 28.2: this is a backward-compatible addition, not a breaking
|
|
||||||
+change. Contract major remains 5. An exhibit reporting `{major: 5, minor: 2}`
|
|
||||||
+is unaffected by this addition and remains fully conformant; a 5.3-aware host
|
|
||||||
+MUST continue to interoperate with it exactly as under Contract 5.2 (Section
|
|
||||||
+31.5).
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 29. Conformance Minimum
|
|
||||||
@@ -1076,6 +1152,11 @@
|
|
||||||
|
|
||||||
Speech, telemetry, MIDI, scenarios, Web3D, and any particular exhibit namespace are optional capabilities.
|
|
||||||
|
|
||||||
+This conformance minimum is unchanged by Contract 5.3. Presentation surfaces
|
|
||||||
+(Section 31) are an optional capability of the same kind: an exhibit that
|
|
||||||
+implements none of Section 31 and never emits `surfaces` remains fully
|
|
||||||
+conformant, at either contract minor.
|
|
||||||
+
|
|
||||||
---
|
|
||||||
|
|
||||||
## 30. Architectural Summary
|
|
||||||
@@ -1089,3 +1170,222 @@
|
|
||||||
**The contract defines how that capability is described, observed, and invoked.**
|
|
||||||
|
|
||||||
**XZBT-NGN decides how to orchestrate and integrate it.**
|
|
||||||
+
|
|
||||||
+Version 5.3 preserves this architecture without modification and adds exactly
|
|
||||||
+one optional capability class — presentation surfaces (Section 31) — built
|
|
||||||
+entirely on the existing session, state-revision, event, and registry-revision
|
|
||||||
+mechanisms defined above.
|
|
||||||
+
|
|
||||||
+---
|
|
||||||
+
|
|
||||||
+## 31. Presentation Surfaces (introduced in Contract 5.3)
|
|
||||||
+
|
|
||||||
+This section is new in Contract 5.3. It formalizes the multi-surface
|
|
||||||
+presentation model approved in XZBT-NGN's Step 6.1 architecture document
|
|
||||||
+(`docs/architecture/XZBT-Multi-Surface-Model-Step6.1.md`, Revision 2). Its
|
|
||||||
+scope is narrowly the discovery and identification of presentation surfaces
|
|
||||||
+and the contract-visible guarantees around them; it does not define display
|
|
||||||
+transport, casting, or remote endpoints (explicitly out of scope — see
|
|
||||||
+Section 31.9).
|
|
||||||
+
|
|
||||||
+### 31.1 Definition
|
|
||||||
+
|
|
||||||
+A **presentation surface** is a renderable, full-screen-capable visual view
|
|
||||||
+of one logical exhibit instance, addressable by a stable identifier, that an
|
|
||||||
+exhibit advertises as independently viewable. Every presentation surface of
|
|
||||||
+one exhibit instance is driven by that exhibit's one authoritative
|
|
||||||
+`stateRevision` history and one event `sequence` stream (Sections 13, 14,
|
|
||||||
+16); this contract defines no mechanism by which two surfaces of the same
|
|
||||||
+exhibit instance could observe divergent state.
|
|
||||||
+
|
|
||||||
+A presentation surface is not a target (Section 9), not a capability
|
|
||||||
+(Section 17), and not the host's own control/administration interface. It
|
|
||||||
+MUST NOT be represented using any target `kind`.
|
|
||||||
+
|
|
||||||
+### 31.2 Surface descriptor
|
|
||||||
+
|
|
||||||
+When an exhibit advertises presentation surfaces, each entry in the
|
|
||||||
+`surfaces` array (Section 7) MUST be an object with the following fields:
|
|
||||||
+
|
|
||||||
+| Field | Requirement | Notes |
|
|
||||||
+| --- | --- | --- |
|
|
||||||
+| `id` | REQUIRED string | MUST conform to the canonical target-ID grammar (Section 8.1). No separate identifier grammar is defined for surfaces. |
|
|
||||||
+| `label` | REQUIRED string | Human-readable. |
|
|
||||||
+| `kind` | REQUIRED, constant `"surface"` | Identifies the descriptor type. |
|
|
||||||
+| `primary` | REQUIRED boolean | Governed by Section 31.3. |
|
|
||||||
+| `url` | REQUIRED string | Governed by Section 31.4. |
|
|
||||||
+
|
|
||||||
+The following fields are OPTIONAL:
|
|
||||||
+
|
|
||||||
+| Field | Purpose |
|
|
||||||
+| --- | --- |
|
|
||||||
+| `description` | Longer human-readable text. |
|
|
||||||
+| `role` | Advisory grouping hint (e.g. `"control"`, `"ambient"`, `"information"`). No contract behavior depends on this field's value in Contract 5.3. |
|
|
||||||
+| `aspectRatio` | Advisory sizing hint (e.g. `"16:9"`). |
|
|
||||||
+| `category` | Mirrors target `category` (Section 9) for consistent grouping. |
|
|
||||||
+| `requires` | Array of capability IDs (Section 17), with identical semantics to target `requires`: the surface remains discoverable but SHOULD be presented as degraded or unavailable when a required capability is not `ready`. |
|
|
||||||
+
|
|
||||||
+No field of a surface descriptor MAY reference a display transport, casting
|
|
||||||
+protocol, network endpoint, or device class (Section 31.9).
|
|
||||||
+
|
|
||||||
+### 31.3 The `primary` invariant
|
|
||||||
+
|
|
||||||
+`surfaces` (Section 7) has exactly three conformant forms:
|
|
||||||
+
|
|
||||||
+1. **Absent.** The exhibit does not advertise multi-surface presentation.
|
|
||||||
+ Functionally equivalent to a Contract 5.2 `describe.result`.
|
|
||||||
+2. **Present and empty (`[]`).** MUST be treated identically to form 1 by a
|
|
||||||
+ conformant host.
|
|
||||||
+3. **Present and non-empty.** The array MUST contain exactly one entry with
|
|
||||||
+ `primary: true`. An array with zero or more than one `primary: true`
|
|
||||||
+ entry is malformed as a whole; a host encountering this MUST fall back to
|
|
||||||
+ treating `surfaces` as absent (form 1) and SHOULD report a diagnostic.
|
|
||||||
+
|
|
||||||
+The `primary` surface, when `surfaces` is present and non-empty, is the
|
|
||||||
+surface a host with no surface-specific UI opens by default, and is the
|
|
||||||
+surface whose standalone-use guarantee is unconditional (Section 31.8).
|
|
||||||
+
|
|
||||||
+### 31.4 URL resolution
|
|
||||||
+
|
|
||||||
+`url` MUST be one of:
|
|
||||||
+
|
|
||||||
+- a path relative to the exhibit's own base document location — the same
|
|
||||||
+ base URL already used to establish the exhibit's session;
|
|
||||||
+- such a relative path with an appended query string and/or fragment;
|
|
||||||
+- a bare query string and/or fragment, resolving against the exhibit's own
|
|
||||||
+ base document, for a single-page exhibit whose surfaces are views within
|
|
||||||
+ one already-served document.
|
|
||||||
+
|
|
||||||
+A host resolving `url` MUST:
|
|
||||||
+
|
|
||||||
+1. resolve it against the exhibit's already-established base URL, not
|
|
||||||
+ against the host's own administrative interface location;
|
|
||||||
+2. reject the entry (Section 31.5) if the resolved URL is not same-origin
|
|
||||||
+ with that base, per the same-origin requirement in Section 25;
|
|
||||||
+3. apply the same path-containment validation the host already applies to
|
|
||||||
+ the exhibit's primary document, if any such validation exists in that
|
|
||||||
+ host implementation.
|
|
||||||
+
|
|
||||||
+Absolute, protocol-relative, or cross-origin `url` values MUST be rejected as
|
|
||||||
+malformed individual entries; they do not invalidate the rest of the array.
|
|
||||||
+
|
|
||||||
+### 31.5 Validation and backward compatibility
|
|
||||||
+
|
|
||||||
+A host MUST validate each surface entry independently. An entry missing a
|
|
||||||
+required field, using an invalid `id` (Section 8.1), or specifying a `url`
|
|
||||||
+that fails Section 31.4 MUST be rejected individually; the host SHOULD skip
|
|
||||||
+only that entry, log a diagnostic, and continue processing the remainder of
|
|
||||||
+`surfaces`, except for the structural `primary` violation in Section 31.3,
|
|
||||||
+which invalidates the whole array.
|
|
||||||
+
|
|
||||||
+A host that does not implement any Section 31 behavior MAY safely ignore the
|
|
||||||
+`surfaces` field entirely; doing so is fully conformant with the
|
|
||||||
+`describe.result` schema, since the field is OPTIONAL (Section 7).
|
|
||||||
+
|
|
||||||
+An exhibit implementing only Contract 5.2 behavior is unaffected: it never
|
|
||||||
+emits `surfaces`, and no 5.3-only requirement applies to it.
|
|
||||||
+
|
|
||||||
+### 31.6 Registry governance
|
|
||||||
+
|
|
||||||
+`surfaces` is governed by `registryRevision` (Section 23) exactly as
|
|
||||||
+`targets` is. There is no independent surface-registry counter. A
|
|
||||||
+`registry.changed` event (Section 16.6) requires the host to re-run
|
|
||||||
+`describe` and re-read both `targets` and `surfaces`.
|
|
||||||
+
|
|
||||||
+### 31.7 State and interaction
|
|
||||||
+
|
|
||||||
+All presentation surfaces of one exhibit instance share that instance's one
|
|
||||||
+session, one `stateRevision` history, and one event `sequence` stream
|
|
||||||
+(Sections 13, 14, 16); this contract defines no per-surface state channel
|
|
||||||
+and no per-surface session. How an exhibit internally propagates state to
|
|
||||||
+each surface's rendering code, and how it routes a surface-originated
|
|
||||||
+interaction back into its own state mutation logic, is an exhibit
|
|
||||||
+implementation detail outside this contract's normative scope — the contract
|
|
||||||
+requires only the observable outcome: one authoritative state, and any
|
|
||||||
+successful interaction on any surface behaves, from the contract's
|
|
||||||
+perspective, exactly like the equivalent `set`/`invoke` (Section 14.1).
|
|
||||||
+
|
|
||||||
+An exhibit's internal mechanism for connecting a surface's rendering code to
|
|
||||||
+its own state, including any same-origin channel used between the exhibit's
|
|
||||||
+own documents, is not part of the message envelope defined in Section 6 and
|
|
||||||
+is never observed by the host.
|
|
||||||
+
|
|
||||||
+### 31.8 Standalone behavior
|
|
||||||
+
|
|
||||||
+Per the governing rule in Section 2, an exhibit's `primary` surface (Section
|
|
||||||
+31.3) — or, when `surfaces` is absent or empty, the exhibit's ordinary entry
|
|
||||||
+point — MUST remain fully and unconditionally usable standalone, with no
|
|
||||||
+dependency on XZBT-NGN, on a contract session, or on any other surface.
|
|
||||||
+
|
|
||||||
+A non-primary surface SHOULD remain directly usable without XZBT-NGN. This
|
|
||||||
+contract does not require every non-primary surface to be usable in complete
|
|
||||||
+isolation from the exhibit's other documents; an exhibit MAY have a
|
|
||||||
+non-primary surface depend on another of its own documents being present, as
|
|
||||||
+an exhibit-internal implementation consequence of Section 31.7, provided that
|
|
||||||
+dependency is never on XZBT-NGN itself.
|
|
||||||
+
|
|
||||||
+### 31.9 Non-goals
|
|
||||||
+
|
|
||||||
+This section defines discovery and identification of presentation surfaces
|
|
||||||
+only. It does not define, and MUST NOT be extended by implementations to
|
|
||||||
+imply:
|
|
||||||
+
|
|
||||||
+- casting or remote display protocols;
|
|
||||||
+- network display endpoints or device classes;
|
|
||||||
+- an assignment mechanism between a surface and a physical or logical
|
|
||||||
+ display;
|
|
||||||
+- any change to session, state, revision, or event semantics beyond the
|
|
||||||
+ cross-references added in Sections 7, 9.4, 13, 14.1, 14.4, 15, 16.6, 17,
|
|
||||||
+ 20, 23, 25, and 29 of this document.
|
|
||||||
+
|
|
||||||
+Those concerns are reserved for future contract or XZBT-NGN work and are
|
|
||||||
+explicitly out of scope for Contract 5.3.
|
|
||||||
+
|
|
||||||
+---
|
|
||||||
+
|
|
||||||
+## 32. Version 5.3 Summary
|
|
||||||
+
|
|
||||||
+Contract 5.3 is Contract 5.2 plus one optional, additive capability:
|
|
||||||
+presentation surfaces (Section 31). No existing normative requirement is
|
|
||||||
+weakened, removed, or reinterpreted. An exhibit or host that implements
|
|
||||||
+nothing in Section 31 is unaffected and remains conformant. The architectural
|
|
||||||
+rule from Section 30 is unchanged: the exhibit exposes what it can do, the
|
|
||||||
+contract defines how that is described and invoked, and XZBT-NGN decides how
|
|
||||||
+to orchestrate it — now including, optionally, orchestrating which of an
|
|
||||||
+exhibit's several presentation surfaces is currently shown.
|
|
||||||
+
|
|
||||||
+---
|
|
||||||
+
|
|
||||||
+## 39. Changelog (5.2 → 5.3)
|
|
||||||
+
|
|
||||||
+This section exists only in 5.3 and has no 5.2 counterpart.
|
|
||||||
+
|
|
||||||
+**Added:**
|
|
||||||
+
|
|
||||||
+- `surfaces` OPTIONAL field on `describe.result` (Section 7).
|
|
||||||
+- Section 31, Presentation Surfaces: definition, descriptor schema, the
|
|
||||||
+ `primary` invariant and its three conformant forms, URL resolution,
|
|
||||||
+ validation/backward-compatibility rules, registry governance, the
|
|
||||||
+ state/interaction guarantee, standalone-use requirements, and explicit
|
|
||||||
+ non-goals.
|
|
||||||
+- Section 28.8, recording the versioning rationale for this addition.
|
|
||||||
+- Cross-reference sentences in Sections 5.2 (hello response commentary),
|
|
||||||
+ 9.4, 13, 14.1, 14.4, 15, 16.6, 17, 20, 23, 25, 29, and 30, each noting how
|
|
||||||
+ the existing normative rule in that section extends to, or is unaffected
|
|
||||||
+ by, presentation surfaces. None of these cross-references change the
|
|
||||||
+ normative requirement already stated in 5.2 for that section.
|
|
||||||
+
|
|
||||||
+**Changed:**
|
|
||||||
+
|
|
||||||
+- Header metadata (document version, compatibility statement).
|
|
||||||
+- Illustrative `"xzbt"` and `contract.minor` values in JSON examples updated
|
|
||||||
+ from `"5.2"` / `2` to `"5.3"` / `3` throughout, for internal consistency
|
|
||||||
+ within this document. This is cosmetic within the example payloads and
|
|
||||||
+ does not alter any example's normative meaning.
|
|
||||||
+
|
|
||||||
+**Removed:** nothing. No 5.2 requirement is weakened, deleted, or
|
|
||||||
+reinterpreted by this document.
|
|
||||||
+
|
|
||||||
+**Not changed:** Sections 1–4, 6, 8.2–8.3, 10–12, 18–19, 21–22, 24, 26–27,
|
|
||||||
+28.1–28.7 carry no 5.3-specific content and are reproduced from 5.2
|
|
||||||
+unmodified except for the cosmetic example-version updates noted above.
|
|
||||||
@@ -13,9 +13,12 @@ pass. Haunted House reports conformant values, and publishing validation passes.
|
|||||||
Steps 6.1–6.3 established Contract 5.3 surface discovery and interoperability.
|
Steps 6.1–6.3 established Contract 5.3 surface discovery and interoperability.
|
||||||
Step 6.4 adds local presentation panes; see the
|
Step 6.4 adds local presentation panes; see the
|
||||||
[Step 6.4 report](docs/architecture/XZBT-NGN-Step6.4-Local-Surfaces.md).
|
[Step 6.4 report](docs/architecture/XZBT-NGN-Step6.4-Local-Surfaces.md).
|
||||||
Step 6.6 validates the reference exhibits, and Step 6.7 adds the SciFi-XZBT
|
Step 6.5 synchronization is satisfied by existing implementation and later evidence.
|
||||||
Observation surface, including regenerated packaged-build verification; live
|
Step 6.6 validates reference exhibits, Step 6.7 adds the SciFi-XZBT Observation
|
||||||
NGN Observation verification remains outstanding — see the
|
surface, and Step 6.8 validates multi-surface behavior. Step 6 is complete with
|
||||||
|
documented non-blocking follow-up at the Contract 5.3 accepted baseline `f163de2`
|
||||||
|
and closed at tag `step-6-complete` — see the
|
||||||
|
[Step 6.10 closure report](docs/reference/XZBT-NGN-Step6.10-Closure-Report.md) and
|
||||||
[Step 6.7 closure report](docs/reference/XZBT-NGN-Step6.7-Closure-Report.md).
|
[Step 6.7 closure report](docs/reference/XZBT-NGN-Step6.7-Closure-Report.md).
|
||||||
|
|
||||||
## Run locally
|
## Run locally
|
||||||
@@ -127,9 +130,12 @@ discovery and local rendering (Section 31) are implemented and exercised by the
|
|||||||
Museum Gallery reference exhibit, and the SciFi-XZBT reference exhibit declares
|
Museum Gallery reference exhibit, and the SciFi-XZBT reference exhibit declares
|
||||||
a console surface plus an Observation surface (Step 6.7B); the other maintained
|
a console surface plus an Observation surface (Step 6.7B); the other maintained
|
||||||
exhibits do not declare multiple surfaces. Surface errors stay within the
|
exhibits do not declare multiple surfaces. Surface errors stay within the
|
||||||
affected pane. Remote/cast display assignment remains deferred. Shared-state
|
affected pane. Remote/cast display assignment remains deferred. Multi-surface
|
||||||
synchronization proof remains Step 6.5; this step adds no host-side surface
|
state synchronization (Step 6.5) is satisfied by the single-authority state
|
||||||
communication.
|
core, snapshot/revision attachment, and owner-mediated mutation routing proven
|
||||||
|
across reference exhibits. Step 6.8 multi-surface behavior is complete and
|
||||||
|
accepted, with a single unreproduced renegotiation noted as non-blocking
|
||||||
|
follow-up.
|
||||||
|
|
||||||
Not implemented: casting/display endpoints, MIDI, MCP/webhooks,
|
Not implemented: casting/display endpoints, MIDI, MCP/webhooks,
|
||||||
scenarios/recording, telemetry acquisition, multi-exhibit orchestration,
|
scenarios/recording, telemetry acquisition, multi-exhibit orchestration,
|
||||||
|
|||||||
@@ -17,8 +17,11 @@ failures and their evidence remain below as historical context, not current gate
|
|||||||
Baseline: NGN HEAD `76928f7`, clean at initial inspection. Read the Contract 5.2,
|
Baseline: NGN HEAD `76928f7`, clean at initial inspection. Read the Contract 5.2,
|
||||||
Implementation Plan 5.2, Authoring Guide 5.2, Step 4 report/review, README/AGENTS,
|
Implementation Plan 5.2, Authoring Guide 5.2, Step 4 report/review, README/AGENTS,
|
||||||
source, fixtures and completion devlog. The owner supplied `docs/implementation_plan.md`
|
source, fixtures and completion devlog. The owner supplied `docs/implementation_plan.md`
|
||||||
and `docs/walkthrough.md` during the run; these accepted triage/completion notes
|
and `docs/walkthrough.md` during the run (since relocated to
|
||||||
were read and preserved. Their permissive metadata interpretation matches this
|
`docs/reference/XZBT-NGN-Step4-Review-Triage.md` and
|
||||||
|
`docs/reference/XZBT-NGN-Step4-Triage-Walkthrough.md`, which reflect their actual
|
||||||
|
Step 4 triage content); these accepted triage/completion notes were read and
|
||||||
|
preserved. Their permissive metadata interpretation matches this
|
||||||
implementation. Their existing fixture copy notice was confirmed present.
|
implementation. Their existing fixture copy notice was confirmed present.
|
||||||
|
|
||||||
The Step 4 UI already accepted same-origin paths without source edits. Its gaps
|
The Step 4 UI already accepted same-origin paths without source edits. Its gaps
|
||||||
@@ -191,11 +194,11 @@ were introduced. No SciFi internals were used to infer NGN behavior.
|
|||||||
- `STEP5-MVP-COMPLETION-REPORT.md` (new): this report.
|
- `STEP5-MVP-COMPLETION-REPORT.md` (new): this report.
|
||||||
|
|
||||||
The owner's newly supplied `docs/implementation_plan.md` and `docs/walkthrough.md`
|
The owner's newly supplied `docs/implementation_plan.md` and `docs/walkthrough.md`
|
||||||
remain unmodified. Production host/session implementation, transport and server
|
(now under `docs/reference/`) remain unmodified. Production host/session
|
||||||
were not changed during closure. The earlier follow-up changed only SciFi's
|
implementation, transport and server were not changed during closure. The earlier
|
||||||
contract adapter externally; closure makes no external source changes. Section R
|
follow-up changed only SciFi's contract adapter externally; closure makes no
|
||||||
lists the final fixture, devlog, test, and evidence changes. Nothing was staged,
|
external source changes. Section R lists the final fixture, devlog, test, and
|
||||||
committed or pushed.
|
evidence changes. Nothing was staged, committed or pushed.
|
||||||
|
|
||||||
# M. Known limitations
|
# M. Known limitations
|
||||||
|
|
||||||
|
|||||||
@@ -163,3 +163,6 @@ missing-page or timeout testing.
|
|||||||
architecture was introduced.
|
architecture was introduced.
|
||||||
|
|
||||||
All Step 6.4 acceptance categories pass. Step 6.5 has not been implemented.
|
All Step 6.4 acceptance categories pass. Step 6.5 has not been implemented.
|
||||||
|
*(Adjudication note: Step 6.5 was subsequently adjudicated as satisfied by existing
|
||||||
|
implementation and later evidence at the Step 6.10 completion gate; see the
|
||||||
|
[Step 6.10 closure report](../reference/XZBT-NGN-Step6.10-Closure-Report.md).)*
|
||||||
|
|||||||
@@ -0,0 +1,178 @@
|
|||||||
|
# XZBT-NGN Step 6.10 — Completion and Closure Report
|
||||||
|
|
||||||
|
**Date:** 2026-09-15
|
||||||
|
**Status:** STEP 6 COMPLETE WITH DOCUMENTED NON-BLOCKING FOLLOW-UP
|
||||||
|
**Technical Baseline:** 163de264388f1e411cf9e54f26f72a254888afd (contract-5.3-accepted-baseline)
|
||||||
|
**Closure Tag:** step-6-complete
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Executive Summary and Closure Disposition
|
||||||
|
|
||||||
|
Following the completion and formal adjudication of the Step 6.10 completion gate, **XZBT-NGN Step 6 is complete and closed with documented non-blocking follow-up**.
|
||||||
|
|
||||||
|
All required Step 6 implementation, adaptation, integration, and verification tasks are finished. No further Step 6 implementation work remains.
|
||||||
|
|
||||||
|
The accepted technical baseline for Contract 5.3 multi-surface architecture is frozen at:
|
||||||
|
* **Commit:** 163de264388f1e411cf9e54f26f72a254888afd
|
||||||
|
* **Tag:** contract-5.3-accepted-baseline
|
||||||
|
|
||||||
|
This closure administration pass performs documentation and provenance reconciliation only. No application source code, automated test code, fixture implementation, protocol definition, or runtime logic is altered.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Milestone Dispositions
|
||||||
|
|
||||||
|
All Step 6 milestones have reached final adjudication and acceptance:
|
||||||
|
|
||||||
|
| Milestone | Disposition | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| **Step 6.1** | Complete | Multi-surface architectural model defined and documented (XZBT-Multi-Surface-Model-Step6.1.md). |
|
||||||
|
| **Step 6.2** | Complete | Multi-surface reference prototype validated against Museum Gallery. |
|
||||||
|
| **Step 6.3** | Complete | Surface discovery protocol and catalog validation implemented and verified. |
|
||||||
|
| **Step 6.4** | Complete | Local presentation panes integrated into NGN operator UI without additional contract sessions. |
|
||||||
|
| **Step 6.5** | **Satisfied by existing implementation and later evidence** | Multi-surface state synchronization proof adjudicated satisfied (see §3). |
|
||||||
|
| **Step 6.6** | Complete and accepted | Reference exhibits validated under Contract 5.3. |
|
||||||
|
| **Step 6.7** | Complete and accepted | SciFi-XZBT Observation surface adapted, packaged build verified, live 8-point verification passed. |
|
||||||
|
| **Step 6.8** | **Complete and accepted** | Multi-surface behavior against SciFi-XZBT validated; single unreproduced renegotiation noted as follow-up (see §4). |
|
||||||
|
| **Step 6.9** | **Complete** | Architectural and protocol conformance review passed across all 18 review areas (see §5). |
|
||||||
|
| **Step 6.95** | **Complete** | Verification evidence and cross-document references reconciled. |
|
||||||
|
| **Step 6.10** | **Complete** | Formal completion gate passed: Step 6 closed. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Step 6.5 Adjudication: Synchronization Proof
|
||||||
|
|
||||||
|
Step 6.5 was adjudicated by the Step 6.10 completion gate as:
|
||||||
|
|
||||||
|
> **SATISFIED BY EXISTING IMPLEMENTATION AND LATER EVIDENCE**
|
||||||
|
|
||||||
|
The requirement for shared-state synchronization across surfaces was satisfied by the verified architecture and evidence rather than requiring a hypothetical multi-host topology:
|
||||||
|
|
||||||
|
1. **Authoritative Exhibit State Core:** A single state core maintains all authoritative exhibit state, revision counters (stateRevision), and mutation dispatch.
|
||||||
|
2. **Snapshot and Revision on Attachment:** When a secondary surface attaches, it immediately receives a full immutable state snapshot stamped with the current stateRevision.
|
||||||
|
3. **Ongoing State and Event Propagation:** Owner-mediated mutations and events broadcast monotonically to all attached surfaces.
|
||||||
|
4. **Owner-Routed Secondary Interactions:** Interactions initiated on secondary presentation surfaces do not mutate state directly; they are routed through the owner's authority chokepoint (pplyMutation).
|
||||||
|
5. **Clean Detach and Reopen Lifecycle:** Detaching and reattaching surfaces preserves monotonic participant counts without ratcheting or state corruption.
|
||||||
|
6. **Cross-Document Evidence:** Cross-document presentation synchronization was proven in Museum Gallery (Step 6.6) and independently verified in SciFi-XZBT across separate browsing contexts (Step 6.7/6.8).
|
||||||
|
|
||||||
|
No requirement exists or was ever specified for multiple NGN instances controlling a single exhibit.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Step 6.8 Completion and Accepted Status
|
||||||
|
|
||||||
|
Step 6.8 (multi-surface behavior against SciFi-XZBT) is **complete and accepted**.
|
||||||
|
|
||||||
|
The handshake gating mismatch identified during Step 6.8 preparation (where exact-string advisory envelope checks dropped xzbt: '5.3') was resolved in commit 745912e, verified by automated regression tests, and confirmed in live browser testing.
|
||||||
|
|
||||||
|
### Residual Observation (Non-Blocking Follow-Up)
|
||||||
|
|
||||||
|
During live multi-surface testing in Step 6.8, one session renegotiation was observed once. This event:
|
||||||
|
* could not be reproduced under repeated testing,
|
||||||
|
* had no architectural defect or protocol violation identified,
|
||||||
|
* preserved exhibit state throughout,
|
||||||
|
* recovered cleanly without operator intervention, and
|
||||||
|
* remains documented as a non-blocking follow-up observation.
|
||||||
|
|
||||||
|
This observation is not characterized as fully explained, definitively benign, operator error, or a known race condition, as no definitive root cause was isolated. It does not block Step 6 completion.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Architectural Review and Invariants (Step 6.9 Summary)
|
||||||
|
|
||||||
|
A comprehensive architectural and protocol conformance review covering 18 functional areas confirmed that the Step 6 implementation conforms to Contract 5.3 and adheres to all architectural constraints.
|
||||||
|
|
||||||
|
### Core Architectural Conclusions
|
||||||
|
|
||||||
|
* **Generic NGN Core:** The NGN host core (src/**) contains zero exhibit-specific or SciFi-specific code. All controls and surfaces are descriptor-driven.
|
||||||
|
* **Exhibit-Scoped Semantics:** All exhibit-specific logic (e.g. Starship visualizer, LCARD interface, Kokoro TTS, WebLLM) resides exclusively within exhibit and fixture code.
|
||||||
|
* **Single-Owner Authority:** All mutations flow through a single chokepoint (ExhibitHost.request()). Surfaces cannot establish independent contract sessions or bypass owner authority.
|
||||||
|
* **Non-Authoritative Surfaces:** Presentation surfaces are purely observational/presentational; they have no host transport or session authority.
|
||||||
|
* **Monotonic State Convergence:** State snapshots and revisions (stateRevision) advance monotonically; late-joining and reconnected surfaces converge immediately to current state.
|
||||||
|
* **Session Identity Protection:** Out-of-session and stale messages are rejected by session ID gating.
|
||||||
|
* **Fail-Closed Orphan Handling:** Orphaned surfaces (such as an Observation surface loaded without an active owner instance ID) enter an inert waiting state without inventing local authority.
|
||||||
|
* **Presentation and Surface Lifecycle Separation:** Opening an Observation surface does not alter the console overlay flag (iew.observation), maintaining distinct lifecycles.
|
||||||
|
* **Owner-Scoped Generative and Audio Subsystems:** Generative AI (WebLLM), neural voice (Kokoro), and Web Audio (AudioContext) run exclusively within the console owner frame; surfaces instantiate none of these heavy resources.
|
||||||
|
* **Contract 5.3 Coherence:** Full Contract 5.3 conformance is maintained with verified backward compatibility for Contract 5.2 exhibits.
|
||||||
|
* **Test Verification:** All 154 automated tests and all 24 focused SciFi surface tests pass cleanly.
|
||||||
|
* **No Blocking Defects:** No blocking architectural defect was found.
|
||||||
|
|
||||||
|
### Verified Architectural Invariants
|
||||||
|
|
||||||
|
| Invariant | Status | Evidence |
|
||||||
|
|---|---|---|
|
||||||
|
| 1. Single authority for mutations | **VERIFIED** | All mutations route through ExhibitHost.request() and exhibit owner |
|
||||||
|
| 2. State immutability & revision tracking | **VERIFIED** | Snapshots are immutable; revisions advance monotonically |
|
||||||
|
| 3. Exhibit-generic NGN core | **VERIFIED** | Zero exhibit-specific code in src/** |
|
||||||
|
| 4. Surface presentation-only semantics | **VERIFIED** | Surfaces have no host transport, session authority, or mutation rights |
|
||||||
|
| 5. Same-origin security boundary | **VERIFIED** | Same-origin enforced across frames, URLs, and postMessage transports |
|
||||||
|
| 6. Contract 5.3 conformance | **VERIFIED** | All 12 Contract 5.3 conformance requirements satisfied |
|
||||||
|
| 7. Backward compatibility with 5.2 | **VERIFIED** | Contract 5.2 exhibits negotiate and function without regression |
|
||||||
|
| 8. Error isolation and recovery | **VERIFIED** | Surface-level errors stay within the pane; host session remains healthy |
|
||||||
|
| 9. Descriptor-driven rendering | **VERIFIED** | UI dynamically renders targets advertised in describe catalog |
|
||||||
|
| 10. Graceful degradation | **VERIFIED** | Invalid descriptors are safely discarded while valid entries are preserved |
|
||||||
|
| 11. Presentation/surface lifecycle independence | **VERIFIED** | Surface open/close does not toggle console overlay state |
|
||||||
|
| 12. Session identity & orphan fail-closed | **VERIFIED** | Stale traffic is rejected; orphaned surfaces remain inert |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Verification Evidence Summary
|
||||||
|
|
||||||
|
The technical baseline 163de2 is verified by the following test and live browser evidence:
|
||||||
|
|
||||||
|
* **Full Automated Test Suite:** **154 / 154** tests passing (
|
||||||
|
pm test /
|
||||||
|
ode --test).
|
||||||
|
- Connection and URL validation: 8 tests
|
||||||
|
- Host negotiation and state management: 32 tests
|
||||||
|
- Surface discovery and descriptor validation: 44 tests
|
||||||
|
- Local surface frame lifecycle: 20 tests
|
||||||
|
- PostMessage transport interop: 7 tests
|
||||||
|
- Reference exhibit integration: 43 tests
|
||||||
|
* **Focused SciFi Observation Surface Suite:** **24 / 24** tests passing (
|
||||||
|
ode --test tests/scifi-surfaces.test.js).
|
||||||
|
* **Live Museum Gallery Evidence:** Multi-surface presentation validated in live browser sessions (Step 6.2 and Step 6.6).
|
||||||
|
* **Live SciFi-XZBT 8-Point Verification:** Passed all eight live criteria:
|
||||||
|
1. Connected and synchronized as Contract 5.3 with two-surface descriptor catalog.
|
||||||
|
2. Observation pane opened with correct geometry and visible controls.
|
||||||
|
3. Observation pane showed no return controls, remained inert to background clicks, and did not alter console state.
|
||||||
|
4. Presentation targets converged across console and pane with advancing stateRevision.
|
||||||
|
5. Reload and close/reopen returned pane to current state without participant ratcheting.
|
||||||
|
6. Console WATCH EXPERIENCE affected only console overlay, leaving the Observation pane independent.
|
||||||
|
7. Observation frame instantiated no WebLLM, Kokoro, or AudioContext.
|
||||||
|
8. Transient events appeared simultaneously; disconnect/reconnect gave clean pane release and rediscovery; orphan URL presented inert waiting state without authority.
|
||||||
|
* **Packaging Verification:** Regenerated single-file standalone artifact verified for structural inlining (13 assets inlined, zero external references) and valid served-path handshake.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Blocking Items
|
||||||
|
|
||||||
|
**None.** There are no unresolved blocking defects, contract violations, or outstanding architectural blockers for Step 6.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Documented Non-Blocking Follow-Up Items
|
||||||
|
|
||||||
|
The following items are retained as non-blocking follow-up items for future operational observation or testing. None of these items block Step 6 closure:
|
||||||
|
|
||||||
|
1. **Unreproduced Session Renegotiation:**
|
||||||
|
The single unreproduced session renegotiation observed during Step 6.8 testing remains tracked for ongoing observation.
|
||||||
|
2. **Packaged Offline Direct Interaction:**
|
||||||
|
Opening the packaged dist/ artifact directly over ile:// and exercising hotkeys, WATCH EXPERIENCE, and audio playback has not been conclusively operator-verified (structural inlining and boot have been verified).
|
||||||
|
3. **Audible Sound Duplication and Quality:**
|
||||||
|
Auditory confirmation that audio is not duplicated between console and Observation pane, and that playback quality remains clear during concurrent surface display, requires sustained human listening.
|
||||||
|
4. **Generated AI Announcement Timing:**
|
||||||
|
Subjective timing quality and cadence of local AI-generated voice announcements appearing across surfaces requires sustained operator listening.
|
||||||
|
5. **Long-Running Ambient-Event Coexistence:**
|
||||||
|
Observation over an extended multi-hour session to confirm that ambient visual and audio events coexist without drift or missed events.
|
||||||
|
|
||||||
|
None of these items are represented as passed; they remain open, documented non-blocking follow-up observations.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Final Conclusion
|
||||||
|
|
||||||
|
Step 6 has satisfied all requirements of the Contract 5.3 multi-surface milestone. No further implementation work is required for Step 6.
|
||||||
|
|
||||||
|
XZBT-NGN Step 6 is formally closed at tag step-6-complete on top of accepted technical baseline 163de264388f1e411cf9e54f26f72a254888afd.
|
||||||
@@ -1,10 +1,12 @@
|
|||||||
# XZBT-NGN Step 6.7 — Closure Report
|
# XZBT-NGN Step 6.7 — Closure Report
|
||||||
|
|
||||||
**Status: not fully closed.** As of 2026-09-15, Step 6.7's implementation, its
|
**Status: accepted.** As of 2026-09-15, Step 6.7 is closed and
|
||||||
handshake defect resolution, the automated baseline, and the packaged
|
`f163de264388f1e411cf9e54f26f72a254888afd` is frozen as the accepted Contract
|
||||||
standalone-build verification are complete. The live NGN Observation
|
5.3 baseline by the annotated tag `contract-5.3-accepted-baseline`. The full
|
||||||
verification (Step 6.7B report §15, steps 1–13) has not been performed and is
|
automated suite, the SciFi surface smoke suite, packaged standalone verification,
|
||||||
the only remaining item. Step 6.8 has not been started.
|
and the live eight-point NGN verification have all passed. *(Note: Step 6.8 was
|
||||||
|
subsequently completed and accepted, and Step 6 is closed at Step 6.10; see the
|
||||||
|
[Step 6.10 closure report](XZBT-NGN-Step6.10-Closure-Report.md).)*
|
||||||
|
|
||||||
- Step 6.7A (design, no code): [architecture report](../architecture/XZBT-NGN-Step6.7A-SciFi-Observation-Surface.md)
|
- 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)
|
- Step 6.7B (implementation): [implementation report](XZBT-NGN-Step6.7-SciFi-Surface-Adaptation.md)
|
||||||
@@ -23,8 +25,10 @@ closed:
|
|||||||
3. Source/fixture provenance for the SciFi-XZBT fixture — re-verified, and
|
3. Source/fixture provenance for the SciFi-XZBT fixture — re-verified, and
|
||||||
extended with the packaging record (§5).
|
extended with the packaging record (§5).
|
||||||
|
|
||||||
Not closed by this report: live browser verification of the Observation
|
The final two fixture-level presentation corrections are included in the
|
||||||
surface through NGN (6.7B report §15, steps 1–13) — see §9.
|
accepted baseline: the embedded Observation surface owns its NGN pane geometry,
|
||||||
|
and an orphaned Observation URL presents an inert waiting state without
|
||||||
|
creating authority.
|
||||||
|
|
||||||
## 2. Step 6.7 delivery summary
|
## 2. Step 6.7 delivery summary
|
||||||
|
|
||||||
@@ -175,6 +179,7 @@ Re-verified after the packaging pass:
|
|||||||
| `tests/postmessage-interop.test.js` | **7 / 7** (was 2 / 7) |
|
| `tests/postmessage-interop.test.js` | **7 / 7** (was 2 / 7) |
|
||||||
| `tests/scifi-surfaces.test.js` (inside the full run) | 24 / 24 |
|
| `tests/scifi-surfaces.test.js` (inside the full run) | 24 / 24 |
|
||||||
| `tests/local-surfaces.test.js` (inside the full run) | 20 / 20 |
|
| `tests/local-surfaces.test.js` (inside the full run) | 20 / 20 |
|
||||||
|
| SciFi Observation surface smoke suite | **24 / 24** pass |
|
||||||
| SciFi-XZBT contract harness | 21 / 21 |
|
| SciFi-XZBT contract harness | 21 / 21 |
|
||||||
| SciFi-XZBT real-adapter suite | 32 / 32 |
|
| SciFi-XZBT real-adapter suite | 32 / 32 |
|
||||||
| `python devlog_editor.py --validate` | devlog is valid |
|
| `python devlog_editor.py --validate` | devlog is valid |
|
||||||
@@ -202,31 +207,53 @@ commit was requested):
|
|||||||
The handshake correction that this report closes was committed earlier as part
|
The handshake correction that this report closes was committed earlier as part
|
||||||
of `745912e` ("Steps 6.4-6.7B …"), pushed to `origin/main`.
|
of `745912e` ("Steps 6.4-6.7B …"), pushed to `origin/main`.
|
||||||
|
|
||||||
## 9. Remaining work
|
## 9. Accepted live verification
|
||||||
|
|
||||||
**Step 6.7 remains open for one item: live NGN Observation verification**
|
The final live NGN verification passed these eight points:
|
||||||
(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.
|
1. The SciFi fixture connected and synchronized as Contract 5.3 with its expected target catalog and two-surface descriptor set.
|
||||||
2. Confirm the Surfaces panel lists exactly two entries (`surface.console` primary, no Open button; `surface.observation`).
|
2. The Observation pane opened into the current universe and preset, filled its NGN pane at the intended presentation geometry, and retained visible controls.
|
||||||
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.
|
3. The pane showed no return controls, stayed inert to background clicks, and did not black out the console or change `view.observation`.
|
||||||
4. Confirm the console does not black out and `view.observation` stays `false`.
|
4. The seven presentation targets converged across console and pane with advancing `stateRevision`.
|
||||||
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`.
|
5. Reload and close/reopen returned the pane to current state without participant-count ratcheting.
|
||||||
6. Reload the pane; confirm it returns to current (not default) state, and close/reopen does not ratchet the participant count.
|
6. WATCH EXPERIENCE affected only the console overlay; the separate Observation pane remained independent.
|
||||||
7. Press WATCH EXPERIENCE; confirm the pane is unaffected and `view.observation` toggles only the console overlay.
|
7. The Observation frame remained non-authoritative: no WebLLM/Kokoro activity, `window.generativeExperience`, or `AudioContext` was created there.
|
||||||
8. Inspect the pane's frame: no WebLLM/Kokoro network activity, no `window.generativeExperience`, no `AudioContext`.
|
8. Transient activity events appeared on console and pane at the same moment; disconnect/reconnect gave clean pane release and rediscovery; standalone two-window attachment (`index.html?surface=observation&xi=<real id>` with no NGN present) mirrored correctly; and the orphan URL (`?surface=observation&xi=nonexistent`) showed the inert waiting state and created no local authority.
|
||||||
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:
|
The console's existing 16:9-lock checkbox behavior is pre-existing presentation
|
||||||
|
behavior, not a Contract 5.3 or Observation-surface authority defect. The
|
||||||
|
accepted embedding correction is deliberately scoped to prevent that console
|
||||||
|
overlay behavior from escaping into the embedded NGN pane.
|
||||||
|
|
||||||
- Step 6.8 has not been started.
|
Acceptance above is not gated on §10: none of the deferred items bear on
|
||||||
- SciFi-XZBT's working tree remains uncommitted (its contract work, including
|
Contract 5.3 compliance, surface authority, or the correction this report
|
||||||
the adapter correction, is untracked in that repository); the packaged
|
closes.
|
||||||
artifact therefore reflects an uncommitted tree. A decision on committing
|
|
||||||
that repository is pending.
|
## 10. Deferred operator verification (non-blocking)
|
||||||
- The retained pre-6.7B artifact `dist/SciFiAmbientDisplay_Va723f46=1.html`
|
|
||||||
should not be distributed.
|
Four checks from the 6.7B report §15 acceptance procedure call for sustained
|
||||||
|
human observation (audio quality, felt timing) rather than a scripted pass/fail,
|
||||||
|
and were not exercised in this pass. They do not block Contract 5.3 acceptance
|
||||||
|
above and are tracked here to be performed separately by an operator:
|
||||||
|
|
||||||
|
1. **Packaged single-file/offline behavior** — open the packaged `dist/`
|
||||||
|
artifact directly (`file://`, no server) and interact with it directly:
|
||||||
|
hotkeys, WATCH EXPERIENCE, and audio playback (report §15, steps 11 and 14).
|
||||||
|
Only the packaged boot and structural inlining were verified in this pass
|
||||||
|
(§4); direct offline interaction was not.
|
||||||
|
2. **Audible sound duplication/quality** — with the Observation pane open
|
||||||
|
alongside the console, confirm audio is not audibly duplicated between the
|
||||||
|
two and that playback quality is unaffected by the pane's presence.
|
||||||
|
3. **Generated AI announcement timing** — confirm AI-generated announcements
|
||||||
|
remain acceptably timed (not delayed or overlapping) as they appear on both
|
||||||
|
console and pane (report §15, step 9 covered simultaneity; felt timing
|
||||||
|
quality was not separately assessed).
|
||||||
|
4. **Longer-running ambient-event coexistence** — over a longer session than
|
||||||
|
this pass exercised, confirm ambient/transient events continue to
|
||||||
|
coexist correctly across console and pane without drift, duplication, or
|
||||||
|
missed events.
|
||||||
|
|
||||||
|
*(Note: Step 6.8 was subsequently completed and accepted with an unreproduced
|
||||||
|
session renegotiation tracked as non-blocking follow-up; Step 6 is closed at
|
||||||
|
Step 6.10.)* The retained pre-6.7B artifact
|
||||||
|
`dist/SciFiAmbientDisplay_Va723f46=1.html` should not be distributed.
|
||||||
|
|||||||
@@ -219,4 +219,6 @@ green (154/154); the packaged single-file build has been regenerated and
|
|||||||
verified (fixture-consistent, structurally and behaviorally checked). See the
|
verified (fixture-consistent, structurally and behaviorally checked). See the
|
||||||
[Step 6.7 closure report](XZBT-NGN-Step6.7-Closure-Report.md). What remains
|
[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
|
before Step 6.7 can be marked complete is the live NGN Observation
|
||||||
verification in report §15, steps 1–13.
|
verification in report §15, steps 1–13. *(Subsequent update: live verification
|
||||||
|
subsequently passed, Step 6.8 was completed and accepted, and Step 6 is closed
|
||||||
|
at Step 6.10; see the [Step 6.10 closure report](XZBT-NGN-Step6.10-Closure-Report.md).)*
|
||||||
|
|||||||
@@ -156,3 +156,30 @@ Verification of the regenerated artifact (raw output in
|
|||||||
`e.origin` as `"null"` for `file://` documents while `window.location.origin`
|
`e.origin` as `"null"` for `file://` documents while `window.location.origin`
|
||||||
is `file://`). That is the adapter's designed same-origin/self safety
|
is `file://`). That is the adapter's designed same-origin/self safety
|
||||||
filter, not a defect; NGN attaches exhibits over `http://` only.
|
filter, not a defect; NGN attaches exhibits over `http://` only.
|
||||||
|
|
||||||
|
## Accepted Contract 5.3 baseline (2026-09-15)
|
||||||
|
|
||||||
|
`f163de264388f1e411cf9e54f26f72a254888afd` is the accepted Contract 5.3
|
||||||
|
baseline, marked by the annotated tag `contract-5.3-accepted-baseline`.
|
||||||
|
The NGN full suite passed **154/154**, and the SciFi Observation surface smoke
|
||||||
|
suite passed **24/24**. The final live eight-point NGN verification also passed,
|
||||||
|
including pane geometry, synchronized presentation state, lifecycle handling,
|
||||||
|
console-only heavy subsystems, standalone attachment, and the inert orphan
|
||||||
|
waiting state.
|
||||||
|
|
||||||
|
This baseline adds two fixture-local integration corrections after the earlier
|
||||||
|
source-to-fixture resync: `css/style.css` clears the console overlay's centered
|
||||||
|
16:9 geometry when Observation is embedded in an NGN pane, and `js/app.js`
|
||||||
|
presents an inert waiting state after an owner-attachment timeout. They do not
|
||||||
|
create a second authority or alter the upstream exhibit's contract behavior.
|
||||||
|
|
||||||
|
The console's existing 16:9-lock checkbox behavior is pre-existing and
|
||||||
|
unrelated to these corrections. It remains console presentation behavior; the
|
||||||
|
embedded-surface override is intentionally limited to keeping that behavior
|
||||||
|
from affecting NGN pane geometry.
|
||||||
|
|
||||||
|
Step 6.7 and Step 6.8 are complete and accepted, and Step 6.5 state synchronization
|
||||||
|
is satisfied by existing implementation and later evidence. Non-blocking operator
|
||||||
|
checks and the unreproduced session renegotiation observation are tracked
|
||||||
|
separately. Step 6 is closed at Step 6.10 (see
|
||||||
|
`docs/reference/XZBT-NGN-Step6.10-Closure-Report.md`).
|
||||||
|
|||||||
Reference in New Issue
Block a user