XZBT-NGN/docs/contract/XZBT-Exhibit-Contract-Specification-v5.3.md

XZBT Exhibit Contract Specification

Version 5.3

Status: Proposed normative specification Document version: 5.3 Contract family: XZBT Exhibit Contract Compatibility major: 5 Supersedes: Version 5.2, additively. No existing normative requirement from 5.2 has been removed, weakened, or reinterpreted. Contract 5.3 adds presentation-surface provisions and surface-related cross-references as documented in Section 39. Primary consumers: XZBT-compatible exhibits and XZBT-NGN Exhibit Engine

---

1. Purpose

The XZBT Exhibit Contract defines a stable, discoverable language through which an external host can inspect, observe, and control an XZBT-compatible exhibit.

The architecture is deliberately separated into three concerns:

• Exhibit: presentation, native controls, audio, visuals, simulation, and exhibit-specific behavior.
• Contract: the shared control and observation language.
• Exhibit Engine: orchestration, recording, integration, networking, authoring, packaging, and administration.

The contract does not require XZBT-NGN to exist for an exhibit to operate.

An exhibit implementing this contract remains a complete independently usable artifact.

---

2. Governing Architectural Rule

An XZBT-compatible exhibit MUST remain operable without XZBT-NGN.

Connection to XZBT-NGN is additive.

The exhibit exposes addressable capabilities and state.

XZBT-NGN decides how to coordinate, automate, integrate, record, schedule, and package those capabilities.

The contract MUST NOT be expanded merely to move Exhibit Engine responsibilities into the exhibit.

---

3. Roles

3.1 Exhibit responsibilities

An exhibit owns:

• visual presentation;
• audio presentation;
• simulation and ambience;
• native UI;
• local input handling;
• internal state;
• exhibit-specific actions;
• standalone behavior;
• exhibit-native speech rendering;
• exhibit-native sound rendering;
• exhibit-native visual effects.

3.2 Exhibit Engine responsibilities

XZBT-NGN may:

• discover an exhibit;
• inspect capabilities and targets;
• request state;
• invoke actions;
• set exposed values;
• observe normalized events;
• record operator activity;
• execute scenarios;
• author timelines;
• expose webhooks;
• manage authentication and authorization;
• connect external systems;
• map telemetry;
• package authored experiences;
• administer one or more exhibits.

---

4. Transport Independence

The contract defines semantics and normalized message envelopes, not one mandatory transport.

Permitted transports may include:

• same-origin postMessage;
• trusted wrapper bindings;
• local WebSocket transport;
• local application IPC;
• future host-specific bindings.

The exhibit MUST NOT need to know whether a request originated from a webhook, Streamer.bot, simulator, telemetry source, administrative UI, scenario engine, or other integration.

NGN translates external sources into contract operations.

---

5. Session and Handshake

A host MUST establish a contract session before sending control operations through a negotiated transport.

A standalone exhibit MUST NOT depend on this handshake for normal operation.

hello is the only contract message that MAY be sent without a sessionId.

Every other request MUST carry a valid sessionId issued by the exhibit. Missing or unknown session identifiers MUST be rejected with INVALID_SESSION.

5.1 Host hello

{
  "xzbt": "5.3",
  "type": "hello",
  "requestId": "req-001",
  "host": {
    "name": "XZBT-NGN",
    "version": "0.1.0"
  },
  "supportedContractMajors": [5]
}

5.2 Exhibit hello response

{
  "xzbt": "5.3",
  "type": "hello.result",
  "requestId": "req-001",
  "sessionId": "sess-7f2a",
  "exhibit": {
    "product": "scifi-xzbt",
    "version": "implementation-defined",
    "build": "implementation-defined"
  },
  "contract": {
    "major": 5,
    "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

Every request, response, and event transmitted through the contract MUST use a normalized envelope.

6.1 Request

{
  "xzbt": "5.3",
  "type": "invoke",
  "requestId": "req-1042",
  "sessionId": "sess-7f2a",
  "target": "sfx.console-beep",
  "args": {}
}

A set request MAY additionally contain an options object when the target explicitly declares supported options.

6.2 Response

{
  "xzbt": "5.3",
  "type": "invoke.result",
  "requestId": "req-1042",
  "sessionId": "sess-7f2a",
  "ok": true
}

6.3 Error response

{
  "xzbt": "5.3",
  "type": "error",
  "requestId": "req-1042",
  "sessionId": "sess-7f2a",
  "ok": false,
  "error": {
    "code": "UNKNOWN_TARGET",
    "message": "The requested target is not registered."
  }
}

When a malformed message cannot be parsed well enough to recover requestId or sessionId, either field MAY be null.

6.4 Correlation

requestId MUST be unique within a host session.

Responses MUST echo the corresponding requestId.

Events are asynchronous and do not require a requestId, but SHOULD include a correlationId when directly caused by a specific request.

6.5 Version field

The xzbt field is advisory metadata for diagnostics.

The negotiated session contract major/minor is authoritative after handshake.

---

7. Describe

The host MUST be able to request a complete machine-readable description.

Request:

{
  "xzbt": "5.3",
  "type": "describe",
  "requestId": "req-010",
  "sessionId": "sess-7f2a"
}

Response:

{
  "xzbt": "5.3",
  "type": "describe.result",
  "requestId": "req-010",
  "sessionId": "sess-7f2a",
  "exhibit": {
    "product": "scifi-xzbt",
    "version": "implementation-defined",
    "build": "implementation-defined"
  },
  "contract": {
    "major": 5,
    "minor": 3
  },
  "registryRevision": 1,
  "stateRevision": 27,
  "capabilities": [],
  "targets": [],
  "surfaces": []
}

describe is authoritative for the current session.

The capabilities array is a snapshot of current capability states at the time of the response.

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

External contract target IDs use a canonical dotted namespace.

Examples:

transport.playing
transport.muted
mix.master
view.observation
view.viewport-frame
event.alert-red
alert.active
sfx.console-beep
speech.say
telemetry.engine.temperature

8.1 Grammar

A target ID MUST:

• use lowercase ASCII letters, digits, hyphens, and dots;
• begin with a lowercase letter;
• contain one or more dot-separated segments;
• not contain whitespace;
• not contain empty segments;
• not be interpreted as a JavaScript property path.

Recommended grammar:

[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.

Target IDs SHOULD NOT be renamed casually.

Deprecated targets SHOULD remain discoverable long enough for hosts to migrate.

8.3 Internal mapping and normalization

An exhibit MAY map canonical external IDs to existing internal IDs.

Example:

mix.master -> master-vol

Mapping is not always a rename.

Example:

transport.playing -> absolute-state adapter around existing transport logic

An exhibit MUST NOT implement an externally visible persistent state target merely by blindly toggling an existing control.

A conforming exhibit may need to build a normalization layer before its existing internals can satisfy the contract.

---

9. Target Descriptor

Each target returned by describe MUST include enough metadata for a generic host to inspect and operate it.

Base descriptor:

{
  "id": "mix.master",
  "label": "Master Volume",
  "kind": "range",
  "readable": true,
  "writable": true,
  "restorable": true,
  "category": "mix",
  "unit": null,
  "requires": ["audio"]
}

requires references capability IDs from Section 17.

When a required capability is not usable, the target remains discoverable but MUST NOT be operated successfully. A generic host SHOULD present it as unavailable rather than removing it.

Additional fields depend on kind.

9.1 Range

{
  "id": "mix.master",
  "kind": "range",
  "min": 0,
  "max": 1,
  "step": 0.01
}

9.2 State

{
  "id": "view.observation",
  "kind": "state",
  "valueType": "boolean"
}

9.3 Selection

{
  "id": "universe.selected",
  "kind": "selection",
  "options": [
    {"value": "starfleet", "label": "Starflight Command"},
    {"value": "whataverse", "label": "Whataverse"}
  ]
}

Values in examples are illustrative except where a profile document explicitly declares them normative.

9.4 Impulse

{
  "id": "event.alert-red",
  "kind": "impulse",
  "readable": false,
  "writable": false,
  "restorable": false
}

A target with kind: "impulse" is invokable.

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 clarifies Contract 5.2; it does not introduce Contract 5.3. Missing arguments MUST be tolerated as an empty array for backward compatibility. New 5.2 exhibits SHOULD explicitly emit arguments: [] for argumentless impulses.

{
  "id": "speech.say",
  "kind": "impulse",
  "readable": false,
  "writable": false,
  "restorable": false,
  "category": "speech",
  "requires": ["speech"],
  "arguments": [
    {"name": "text", "type": "string", "required": true, "maxLength": 2000}
  ]
}

Each argument descriptor has:

Field	Requirement
name	REQUIRED string, unique within the target
type	REQUIRED: string, number, integer, or boolean
required	REQUIRED boolean
label	OPTIONAL human-readable string
description	OPTIONAL human-readable string
enum	OPTIONAL array of allowed literal values
min, max	OPTIONAL number
step	OPTIONAL positive number
minLength, maxLength	OPTIONAL non-negative integer

Invoke args MUST be an object. Every argument with required: true MUST be present. Undeclared keys MUST be rejected with INVALID_VALUE. Values MUST match the declared type, and all declared enum, bounds, step, and length constraints MUST be enforced.

NGN MAY generate controls directly from this metadata and MUST NOT infer undocumented arguments. NGN MUST still surface an impulse with an unsupported future argument type and report its schema as unsupported rather than inventing behavior.

Established examples: speech.say declares required string text with maxLength: 2000; the established impulse form of display.ticker declares required string text with maxLength: 512. Argumentless actions, including speech.generate-announcement and argumentless event/sound impulses, declare arguments: []. These examples do not establish a host target inventory.

---

10. Target Kinds

The base contract defines four kinds.

10.1 State

Persistent value such as boolean, string, or bounded scalar.

10.2 Range

Persistent bounded numeric state.

10.3 Selection

Persistent value selected from a declared set.

10.4 Impulse

Non-persistent action or event.

Impulse targets MUST NOT appear in a restorable state snapshot as current state.

---

11. Invoke

invoke performs an impulse.

{
  "xzbt": "5.3",
  "type": "invoke",
  "requestId": "req-200",
  "sessionId": "sess-7f2a",
  "target": "sfx.console-beep",
  "args": {}
}

The exhibit MUST validate the target and arguments before execution.

Arguments MUST be validated against the declared target schema where such a schema exists.

Unexpected argument keys SHOULD be rejected.

A successful invoke response means that the operation was accepted for execution, not necessarily that a long-running effect has completed.

---

12. Set

set changes writable persistent state.

{
  "xzbt": "5.3",
  "type": "set",
  "requestId": "req-201",
  "sessionId": "sess-7f2a",
  "target": "mix.master",
  "value": 0.75
}

A successful state-changing set MUST result in a normalized state update.

A successful no-op set MUST NOT increment stateRevision.

---

13. State Snapshot

The host MUST be able to request externally meaningful persistent state.

Request:

{
  "xzbt": "5.3",
  "type": "state.get",
  "requestId": "req-300",
  "sessionId": "sess-7f2a"
}

Response:

{
  "xzbt": "5.3",
  "type": "state.result",
  "requestId": "req-300",
  "sessionId": "sess-7f2a",
  "stateRevision": 28,
  "values": {
    "transport.playing": true,
    "transport.muted": false,
    "mix.master": 0.75,
    "view.observation": true,
    "universe.selected": "starfleet",
    "preset.selected": "tng-bridge"
  }
}

Only readable persistent targets belong in values.

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

The exhibit MUST maintain a monotonically increasing stateRevision for externally observable persistent state.

14.1 Mutation transaction

One top-level contract-visible mutation operation is one mutation transaction, unless the exhibit explicitly opens a larger transaction for a coherent multi-value operation.

Examples of one transaction may include:

• one host set;
• one UI slider change;
• one MIDI mutation;
• one universe change that also selects a default preset;
• one preset selection that updates several exposed values.

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:

1. compute and commit the transaction;
2. increment stateRevision exactly once if externally visible state changed;
3. emit resulting state.changed / selection.changed events carrying that revision.

14.3 No-op behavior

A transaction that produces no externally visible state change MUST NOT increment stateRevision.

14.4 Why both revision and sequence exist

stateRevision tracks committed persistent-state history.

Event sequence tracks delivery order of all emitted contract events, including impulses and errors.

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

Normalized events MUST identify the authoritative source of the action when known.

Base values:

ui
midi
hotkey
host
scenario
internal
system

A source property supplied by a host command MUST be ignored.

The receiving bridge assigns the authoritative source.

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

A conforming XZBT 5.2 exhibit MUST publish normalized events for contract-visible operations.

Base event types include:

state.changed
action.executed
selection.changed
capability.changed
registry.changed
error

Example:

{
  "xzbt": "5.3",
  "type": "state.changed",
  "sessionId": "sess-7f2a",
  "sequence": 144,
  "timestamp": 1799781200123,
  "stateRevision": 29,
  "target": "mix.master",
  "value": 0.82,
  "source": "midi"
}

Impulse example:

{
  "xzbt": "5.3",
  "type": "action.executed",
  "sessionId": "sess-7f2a",
  "sequence": 145,
  "timestamp": 1799781200234,
  "target": "sfx.console-beep",
  "args": {},
  "source": "ui"
}

16.1 Sequence

Event sequence MUST increase monotonically within one session.

It is session-scoped and resets when a new sessionId is issued.

A host MUST reset its expected sequence after reconnect.

16.2 Correlation

When an event is caused directly by a host request, it SHOULD include the request's requestId as correlationId.

16.3 Selection events

A successful change to a Selection-kind target SHOULD emit selection.changed.

16.4 Errors

Request-scoped errors MUST be returned as responses.

An exhibit MAY additionally publish an error event for observability.

If published, it SHOULD carry the same source and correlationId as the rejected request.

16.5 Recorder behavior

NGN recording SHOULD normally record operator-originated events such as ui, midi, and hotkey.

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

Capabilities are discoverable and stateful.

Descriptor example:

{
  "id": "speech",
  "state": "available"
}

Base states:

unsupported
available
loading
ready
busy
error

Definitions:

• unsupported: the exhibit does not implement the capability.
• available: implemented, but not necessarily initialized.
• loading: initialization is in progress.
• ready: usable now.
• busy: currently occupied but still operational.
• error: initialization or operation failed.

A capability may change state during a session.

Capability changes MUST emit capability.changed.

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

An exhibit with speech support SHOULD expose:

speech.say

Example:

{
  "xzbt": "5.3",
  "type": "invoke",
  "requestId": "req-410",
  "sessionId": "sess-7f2a",
  "target": "speech.say",
  "args": {
    "text": "Engineering reports reactor output at eighty-seven percent."
  }
}

The exhibit controls synthesis and playback.

NGN supplies content.

The contract does not require a specific TTS engine or a speech queue.

If the exhibit has a usable fallback synthesis path while its preferred path is loading, it MAY accept speech.say through that fallback.

A successful speech.say response means accepted for playback, not playback completed.

---

19. Sound and Visual Events

Exhibit-native sound and visual actions SHOULD be exposed as impulse targets where useful.

Examples:

sfx.console-beep
sfx.warning-tone
event.alert-red
event.ship-arrival

State and impulse semantics MUST remain distinct.

For example:

event.alert-red

may be an impulse, while:

alert.active

may represent current persistent alert state.

NGN requests the action.

The exhibit owns its implementation.

---

20. Safe Text Injection

An exhibit MAY expose safe text surfaces such as:

display.ticker

Text MUST be handled as data.

The contract MUST NOT permit arbitrary:

• HTML;
• JavaScript;
• CSS;
• selectors;
• executable expressions.

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

Telemetry support is OPTIONAL.

The contract defines how telemetry is represented if an exhibit exposes structured telemetry. It does not require every exhibit to implement telemetry.

A telemetry target descriptor SHOULD declare:

• identifier;
• label;
• value type;
• unit;
• minimum and maximum where applicable;
• writable status;
• update expectations if useful.

Example:

{
  "id": "telemetry.engine.temperature",
  "label": "Engine Temperature",
  "kind": "range",
  "valueType": "number",
  "unit": "celsius",
  "readable": true,
  "writable": true,
  "restorable": false
}

Existing SciFi-XZBT telemetry-like presentation is primarily audio activity and ticker text rather than a structured numeric telemetry model.

Therefore structured writable telemetry in SciFi-XZBT is a new exhibit feature, not merely exposure of an existing data object.

It may be implemented incrementally and is not required for the first contract-compatible milestone.

---

22. Telemetry Ownership

Writable telemetry MAY support source ownership.

Recommended modes:

simulation
external

An external update MAY include a lease duration:

{
  "xzbt": "5.3",
  "type": "set",
  "requestId": "req-520",
  "sessionId": "sess-7f2a",
  "target": "telemetry.engine.temperature",
  "value": 482.7,
  "options": {
    "ownership": "external",
    "ttlMs": 5000
  }
}

After lease expiration, the exhibit MAY return to simulated ownership.

The exact telemetry lease mechanism remains optional in 5.2, unchanged in 5.3.

A simple explicit release mechanism is also acceptable.

---

23. Registry Revision

registryRevision represents the current set and metadata of discoverable targets.

It SHOULD increment when targets or descriptor metadata actually change during a session.

A registry.changed event MUST notify the host when the revision changes.

The host then re-runs describe.

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

Implementations SHOULD use stable machine-readable error codes.

Recommended base codes include:

UNSUPPORTED_VERSION
INVALID_MESSAGE
INVALID_SESSION
UNKNOWN_TARGET
INVALID_VALUE
INVALID_ARGUMENTS
CAPABILITY_UNAVAILABLE
TARGET_READ_ONLY
TARGET_NOT_INVOKABLE
TARGET_NOT_SETTABLE
INTERNAL_ERROR

Human-readable error text is advisory.

Hosts SHOULD branch on codes, not message strings.

---

25. Security Boundary

The contract MUST NOT provide arbitrary code execution.

Target IDs MUST NOT be interpreted as property traversal.

Contract payloads MUST NOT permit raw executable markup.

The exhibit contract MUST NOT provide a primitive for fetching arbitrary URLs.

External networking belongs to the host or to explicitly defined exhibit-native functionality.

Both host and exhibit MUST validate incoming messages.

Internet-facing authentication and authorization belong to XZBT-NGN, not the standalone exhibit.

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

The XZBT Exhibit Contract does not require a general-purpose scenario engine in the standalone exhibit.

A scenario is an orchestration concept.

XZBT-NGN may execute scenarios by issuing contract operations over time.

A separately packaged exhibit may contain:

• authored scenario data;
• a compact runtime;
• only the functionality necessary to execute that packaged scenario.

The ordinary standalone exhibit does not need to load arbitrary scenario files.

Scenario data MUST remain inert data and MUST NOT be interpreted as arbitrary executable code.

---

27. Extensibility

The base contract is exhibit-generic.

A castle exhibit could expose:

weather.rain
fireplace.intensity
event.drawbridge
sfx.thunder

A train exhibit could expose:

engine.throttle
brake.pressure
event.whistle
telemetry.speed

NGN discovers these targets dynamically.

---

28. Versioning

28.1 Contract major

Breaking protocol changes require a new contract major.

28.2 Contract minor

Backward-compatible additions may increase the minor version.

28.3 Exhibit version

Exhibit product version is independent from contract version.

28.4 Registry revision

Registry revision is runtime target metadata and does not imply a contract version change.

28.5 State revision

stateRevision is a runtime state-history counter and is not a protocol version.

28.6 Scenario format

Scenario format versioning is owned by XZBT-NGN and is outside the Exhibit Contract.

28.7 Additive targets

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

An exhibit is minimally XZBT Contract 5.2 compatible when it supports:

• compatible handshake;
• normalized message envelope;
• describe;
• at least one discoverable target;
• state.get for readable persistent targets;
• stateRevision;
• normalized responses;
• normalized event emission;
• session event sequencing;
• command validation;
• version reporting.

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

Version 5.2 keeps the Version 5 architecture intact while tightening implementation semantics.

The key rule remains:

The exhibit exposes what it can do.

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 and validation order

surfaces (Section 7) has exactly three conformant top-level 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. Evaluated using the deterministic validation order below.

A host MUST evaluate a non-empty surfaces array in the following order:

1. Validate each individual surface descriptor against Section 31.2 and Section 31.4.
2. Discard individually invalid entries (Section 31.5); retain only the valid entries as the working set.
3. Evaluate the primary invariant against the working set, not against the original array:
   • If the working set is empty (every entry was individually invalid), treat surfaces as if it were absent (form 1).
   • If the working set contains exactly one entry with primary: true, that entry is the primary surface and the working set is the conformant surface catalog for this describe.result.
   • If the working set contains zero entries with primary: true, or more than one, the surface catalog as a whole is malformed: the host MUST reject the entire working set (not just the offending entries), fall back to treating surfaces as absent (form 1), and SHOULD report a diagnostic.

This order is intentional and normative: the primary invariant is always evaluated after individually-invalid entries have already been discarded, so that one malformed entry cannot be mistaken for a missing or duplicate primary among otherwise-valid entries, and so that discarding a malformed entry can deterministically change whether the invariant holds.

The primary surface, once determined by this process, is the surface a Section-31-aware host that provides no operator surface selection 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 Individual entry validation

A host MUST validate each surface entry independently, as step 1 of the order defined in Section 31.3. An entry missing a required field, using an invalid id (Section 8.1), or specifying a url that fails Section 31.4 is individually invalid; the host SHOULD skip only that entry, log a diagnostic, and continue evaluating the remainder of surfaces. Individual entry validation never by itself invalidates the whole array — only the structural primary evaluation performed afterward, against the surviving valid entries (Section 31.3, steps 2–3), can do that.

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 is an exhibit implementation detail outside this contract's normative scope.

The normative requirement on interaction is narrower than "every native interaction becomes a public target": any surface-originated interaction that changes contract-visible persistent state or executes a contract-visible action MUST obey the same mutation, revision, source, and event semantics (Sections 14, 15, 16) as the equivalent operation originating from the exhibit's primary UI or through a contract set/invoke (Section 14.1). A surface-local interaction that does not change contract-visible state and does not execute a contract-visible action — purely presentational interaction confined to that surface — remains exhibit-internal and is outside this contract's scope; this contract does not require it to have a corresponding target.

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) — the supersedes wording was tightened during the pre-6.2 cleanup pass to state plainly that no existing 5.2 requirement was removed, weakened, or reinterpreted, rather than characterizing which sections happened to receive cross-references.
• 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.
• Section 31.3 was restructured, during the same cleanup pass, into an explicit, deterministic validation order (validate individual entries → discard invalid ones → evaluate the primary invariant against the surviving set) so that a discarded individually-invalid entry cannot leave the primary determination ambiguous. Section 31.5 was narrowed to cover only individual-entry validation and now cross-references 31.3 for the structural primary evaluation, rather than restating it. This is a clarification of Revision 2's intent, not a new rule.
• Section 31.7's interaction requirement was narrowed from "every successful surface interaction behaves like set/invoke" to the intended scope: this requirement applies only to interactions that change contract-visible state or execute a contract-visible action. Purely surface-local, non-contract-visible interaction is explicitly out of scope and is not required to have a corresponding target.
• Section 31.3's reference to "a host with no surface-specific UI" was reworded to "a Section-31-aware host that provides no operator surface selection," to avoid it being read as covering a host that ignores Section 31 entirely.

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.