generated from Labyricorn/labyricorn-project-template
Compare commits
3
Commits
step-6-complete
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 Labyricorn
|
5075394f2a | ||
|
Labyricorn
|
835d966e75 | ||
|
Labyricorn
|
7249b33fca |
@@ -2,26 +2,71 @@ _model: project
|
||||
---
|
||||
schema_version: 1
|
||||
---
|
||||
project_id: labyricorn-project-template
|
||||
project_id: xzbt-ngn
|
||||
---
|
||||
title: Labyricorn Project Template
|
||||
title: XZBT-NGN Exhibit Engine
|
||||
---
|
||||
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
|
||||
---
|
||||
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
|
||||
---
|
||||
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.
|
||||
@@ -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,
|
||||
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`
|
||||
and `docs/walkthrough.md` during the run; these accepted triage/completion notes
|
||||
were read and preserved. Their permissive metadata interpretation matches this
|
||||
and `docs/walkthrough.md` during the run (since relocated to
|
||||
`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.
|
||||
|
||||
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.
|
||||
|
||||
The owner's newly supplied `docs/implementation_plan.md` and `docs/walkthrough.md`
|
||||
remain unmodified. Production host/session implementation, transport and server
|
||||
were not changed during closure. The earlier follow-up changed only SciFi's
|
||||
contract adapter externally; closure makes no external source changes. Section R
|
||||
lists the final fixture, devlog, test, and evidence changes. Nothing was staged,
|
||||
committed or pushed.
|
||||
(now under `docs/reference/`) remain unmodified. Production host/session
|
||||
implementation, transport and server were not changed during closure. The earlier
|
||||
follow-up changed only SciFi's contract adapter externally; closure makes no
|
||||
external source changes. Section R lists the final fixture, devlog, test, and
|
||||
evidence changes. Nothing was staged, committed or pushed.
|
||||
|
||||
# M. Known limitations
|
||||
|
||||
|
||||
Reference in New Issue
Block a user