generated from Labyricorn/labyricorn-project-template
856 lines
16 KiB
Markdown
856 lines
16 KiB
Markdown
# XZBT-NGN Exhibit Engine Implementation Plan
|
|
## Version 5.2
|
|
|
|
**Status:** Architectural implementation plan
|
|
**Product:** XZBT-NGN
|
|
**Product identity:** XZBT-NGN Exhibit Engine
|
|
**Dependency:** XZBT Exhibit Contract 5.2
|
|
**Current implementation state:** Not yet implemented
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
XZBT-NGN is the host, orchestration, integration, recording, authoring, administration, and packaging environment for XZBT-compatible exhibits.
|
|
|
|
It does not replace the exhibit.
|
|
|
|
It extends it.
|
|
|
|
Version 5.2 assumes no legacy NGN implementation and treats the XZBT Exhibit Contract as the architectural dependency NGN must follow.
|
|
|
|
---
|
|
|
|
## 2. Product Boundary
|
|
|
|
The intended ecosystem is:
|
|
|
|
### Free standalone exhibit
|
|
|
|
A complete independently usable experience.
|
|
|
|
### Free packaged authored experience
|
|
|
|
A self-running artifact exported by NGN that may contain scenario data and a compact runtime.
|
|
|
|
### Premium XZBT-NGN Exhibit Engine
|
|
|
|
Provides:
|
|
|
|
- hosting;
|
|
- orchestration;
|
|
- recording;
|
|
- scenario authoring;
|
|
- webhooks;
|
|
- telemetry connectors;
|
|
- external automation;
|
|
- administration;
|
|
- packaging;
|
|
- remote control;
|
|
- integrations.
|
|
|
|
The commercial value comes from added capability, not intentional degradation of free exhibits.
|
|
|
|
---
|
|
|
|
## 3. Primary Responsibilities
|
|
|
|
NGN owns:
|
|
|
|
- contract session management;
|
|
- exhibit discovery;
|
|
- capability cataloging;
|
|
- state synchronization;
|
|
- event monitoring;
|
|
- scenario runtime;
|
|
- scenario recording;
|
|
- timeline authoring;
|
|
- webhook endpoints;
|
|
- connector framework;
|
|
- telemetry mapping;
|
|
- automation;
|
|
- administration;
|
|
- diagnostics;
|
|
- packaging;
|
|
- distribution support;
|
|
- future multi-exhibit orchestration.
|
|
|
|
---
|
|
|
|
## 4. Contract-First Rule
|
|
|
|
NGN MUST interact with exhibits through the XZBT Exhibit Contract target surface.
|
|
|
|
Direct exhibit-specific escape hatches are development diagnostics, not architecture.
|
|
|
|
NGN MUST dynamically discover targets.
|
|
|
|
Core NGN MUST NOT hard-code SciFi-XZBT target vocabulary.
|
|
|
|
---
|
|
|
|
## 5. Initial MVP
|
|
|
|
The first useful NGN proves only the contract boundary.
|
|
|
|
It should:
|
|
|
|
1. host or attach to one SciFi-XZBT instance;
|
|
2. complete contract handshake;
|
|
3. request `describe`;
|
|
4. render discovered capabilities and targets;
|
|
5. request state;
|
|
6. invoke and set selected targets;
|
|
7. receive and display events;
|
|
8. display sequence and state revision;
|
|
9. detect and recover synchronization loss;
|
|
10. log errors.
|
|
|
|
This milestone exists before scenario authoring, recording, webhooks, or connectors.
|
|
|
|
---
|
|
|
|
## 6. Exhibit Hosting
|
|
|
|
NGN SHOULD be able to host compatible HTML exhibits from a stable local origin.
|
|
|
|
Hosting enables:
|
|
|
|
- same-origin communication;
|
|
- controlled dependency delivery;
|
|
- predictable asset paths;
|
|
- future local Web3D hosting;
|
|
- packaging support;
|
|
- browser receiver support.
|
|
|
|
Hosting is not required for the ordinary standalone artifact.
|
|
|
|
---
|
|
|
|
## 7. Session Management
|
|
|
|
NGN maintains one logical contract session per connected exhibit instance.
|
|
|
|
Track:
|
|
|
|
- exhibit identity;
|
|
- contract version;
|
|
- session ID;
|
|
- registry revision;
|
|
- state revision;
|
|
- expected event sequence;
|
|
- capabilities;
|
|
- target descriptors;
|
|
- current state;
|
|
- connection status.
|
|
|
|
When a new session is established, reset expected event sequence and session-scoped correlation state.
|
|
|
|
---
|
|
|
|
## 8. Discovery Catalog
|
|
|
|
NGN builds its control catalog from `describe`.
|
|
|
|
Generic UI mapping:
|
|
|
|
```text
|
|
range -> slider / numeric control
|
|
state -> state editor / toggle where appropriate
|
|
selection -> dropdown / list
|
|
impulse -> trigger control
|
|
```
|
|
|
|
`kind: impulse` is sufficient to infer invokability.
|
|
|
|
Exhibit-provided labels may drive UI display.
|
|
|
|
Core behavior does not depend on presentation hints.
|
|
|
|
---
|
|
|
|
## 9. Registry Revision Handling
|
|
|
|
NGN records `registryRevision` from `describe`.
|
|
|
|
On `registry.changed`, NGN MUST schedule a fresh `describe`.
|
|
|
|
Use a short debounce so a burst of registry changes results in one rediscovery.
|
|
|
|
Recommended initial debounce:
|
|
|
|
```text
|
|
100 ms
|
|
```
|
|
|
|
If the exhibit uses a fixed registry, ordinary context changes should not trigger rediscovery.
|
|
|
|
---
|
|
|
|
## 10. State Synchronization
|
|
|
|
NGN keeps a local mirror of contract-visible persistent state.
|
|
|
|
Synchronization strategy:
|
|
|
|
1. request initial `state.get`;
|
|
2. record `stateRevision`;
|
|
3. apply normalized state/selection events;
|
|
4. track event sequence;
|
|
5. resynchronize on uncertainty.
|
|
|
|
Resync triggers include:
|
|
|
|
- event sequence gap;
|
|
- state revision gap that cannot be explained by one received mutation transaction;
|
|
- reconnect/new session;
|
|
- explicit `registry.changed` requiring rediscovery;
|
|
- configurable synchronization timeout;
|
|
- parse/validation failure on a state event.
|
|
|
|
On resync, request fresh `state.get`.
|
|
|
|
---
|
|
|
|
## 11. Feedback-Loop Prevention
|
|
|
|
NGN respects authoritative event `source`.
|
|
|
|
Default recorder sources:
|
|
|
|
```text
|
|
ui
|
|
midi
|
|
hotkey
|
|
```
|
|
|
|
Optional:
|
|
|
|
```text
|
|
host
|
|
```
|
|
|
|
Normally excluded:
|
|
|
|
```text
|
|
scenario
|
|
internal
|
|
system
|
|
```
|
|
|
|
Scenario playback does not record itself by default.
|
|
|
|
Host-triggered integrations do not recursively retrigger identical integrations unless explicitly configured.
|
|
|
|
---
|
|
|
|
## 12. Scenario Model
|
|
|
|
A scenario is an NGN-owned orchestration document.
|
|
|
|
The ordinary exhibit does not need to understand the document.
|
|
|
|
A scenario may include:
|
|
|
|
- timed state changes;
|
|
- impulses;
|
|
- speech;
|
|
- waits;
|
|
- marks;
|
|
- tracks;
|
|
- ramps;
|
|
- holds;
|
|
- conditions;
|
|
- repetition;
|
|
- random variation;
|
|
- external signals;
|
|
- transitions;
|
|
- metadata;
|
|
- required capabilities;
|
|
- cleanup policy.
|
|
|
|
---
|
|
|
|
## 13. Scenario Format
|
|
|
|
Scenario schema is distinct from the XZBT Exhibit Contract.
|
|
|
|
It references canonical contract target IDs.
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"format": "xzbt-scenario",
|
|
"version": 1,
|
|
"requires": ["speech"],
|
|
"timeline": [
|
|
{
|
|
"at": 0,
|
|
"op": "set",
|
|
"target": "view.observation",
|
|
"value": true
|
|
},
|
|
{
|
|
"at": 2000,
|
|
"op": "invoke",
|
|
"target": "speech.say",
|
|
"args": {
|
|
"text": "Approaching docking perimeter."
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Scenario data is inert data.
|
|
|
|
It MUST NOT contain arbitrary executable JavaScript, CSS, selectors, or host-language expressions.
|
|
|
|
The scenario format should eventually receive its own specification.
|
|
|
|
---
|
|
|
|
## 14. Scenario Validation
|
|
|
|
Before playback, validate:
|
|
|
|
- scenario schema;
|
|
- target existence;
|
|
- target kind;
|
|
- writable/invokable semantics;
|
|
- required capability state;
|
|
- value ranges;
|
|
- selection options;
|
|
- optional exhibit/product compatibility constraints.
|
|
|
|
Invalid operations should be surfaced before playback where possible.
|
|
|
|
---
|
|
|
|
## 15. Scenario Clock
|
|
|
|
NGN owns the live scenario clock.
|
|
|
|
Initial support:
|
|
|
|
- millisecond timing;
|
|
- pause/resume;
|
|
- marks;
|
|
- loops;
|
|
- holds.
|
|
|
|
Later support may include:
|
|
|
|
- variable speed;
|
|
- repeat regions;
|
|
- musical timing;
|
|
- advanced conditions.
|
|
|
|
Browser-hosted exhibit timing is application-level timing, not sample-accurate show control.
|
|
|
|
---
|
|
|
|
## 16. State Capture and Cleanup
|
|
|
|
Scenario playback may capture relevant initial state.
|
|
|
|
Cleanup policy may:
|
|
|
|
- leave final state;
|
|
- restore captured state;
|
|
- restore selected targets only.
|
|
|
|
Impulse targets are never restorable.
|
|
|
|
Persistent state targets are restorable by default unless the exhibit explicitly sets `restorable: false`.
|
|
|
|
---
|
|
|
|
## 17. Scenario Recorder
|
|
|
|
NGN records normalized exhibit events using canonical target IDs.
|
|
|
|
Default sources:
|
|
|
|
```text
|
|
ui
|
|
midi
|
|
hotkey
|
|
```
|
|
|
|
Optional:
|
|
|
|
```text
|
|
host
|
|
```
|
|
|
|
Normally excluded:
|
|
|
|
```text
|
|
scenario
|
|
internal
|
|
system
|
|
```
|
|
|
|
The recorder never stores internal SciFi-XZBT IDs.
|
|
|
|
---
|
|
|
|
## 18. Recorder Compression
|
|
|
|
Continuous controls may generate many events.
|
|
|
|
Later compression may include:
|
|
|
|
- threshold reduction;
|
|
- sample reduction;
|
|
- ramp fitting;
|
|
- minimum time interval.
|
|
|
|
This is deferred optimization, not MVP behavior.
|
|
|
|
---
|
|
|
|
## 19. Timeline Authoring
|
|
|
|
Future authoring may support:
|
|
|
|
- tracks;
|
|
- marks;
|
|
- ranges;
|
|
- impulses;
|
|
- speech;
|
|
- ramps;
|
|
- holds;
|
|
- loops;
|
|
- conditions;
|
|
- external triggers;
|
|
- annotations;
|
|
- metadata.
|
|
|
|
The first editor can be much simpler.
|
|
|
|
---
|
|
|
|
## 20. Webhook Engine
|
|
|
|
Webhooks terminate at NGN.
|
|
|
|
NGN handles:
|
|
|
|
- authentication;
|
|
- authorization;
|
|
- validation;
|
|
- rate limiting;
|
|
- routing;
|
|
- logging;
|
|
- translation.
|
|
|
|
Webhook actions may target:
|
|
|
|
- exhibit contract operations;
|
|
- NGN scenario controls;
|
|
- telemetry mappings;
|
|
- connector commands.
|
|
|
|
The standalone exhibit never needs an HTTP listener.
|
|
|
|
---
|
|
|
|
## 21. Connector Framework
|
|
|
|
NGN may later provide connectors for:
|
|
|
|
- Streamer.bot;
|
|
- OBS-related systems;
|
|
- REST;
|
|
- MQTT;
|
|
- serial devices;
|
|
- MIDI;
|
|
- simulators;
|
|
- game servers;
|
|
- home automation;
|
|
- future MCP integrations.
|
|
|
|
Connectors normalize external inputs into:
|
|
|
|
- exhibit contract operations;
|
|
- NGN scenario controls;
|
|
- NGN telemetry updates.
|
|
|
|
---
|
|
|
|
## 22. Telemetry Mapping
|
|
|
|
Structured telemetry is optional per exhibit.
|
|
|
|
NGN MUST discover whether telemetry targets actually exist.
|
|
|
|
It must not assume that SciFi-XZBT has fictional telemetry fields merely because the contract supports them.
|
|
|
|
When writable telemetry exists, NGN may provide:
|
|
|
|
- scaling;
|
|
- unit conversion;
|
|
- clamping;
|
|
- smoothing;
|
|
- update-rate control;
|
|
- stale-data policy;
|
|
- ownership lease renewal;
|
|
- fallback to simulation.
|
|
|
|
---
|
|
|
|
## 23. Telemetry Staleness
|
|
|
|
For external telemetry mappings, NGN SHOULD define stale-data behavior.
|
|
|
|
Options may include:
|
|
|
|
- keep last value;
|
|
- mark stale;
|
|
- release ownership;
|
|
- return to exhibit simulation;
|
|
- invoke fallback value.
|
|
|
|
The mapping configuration should make this explicit.
|
|
|
|
---
|
|
|
|
## 24. Speech Integration
|
|
|
|
NGN may send explicit text to an exhibit's `speech.say` target.
|
|
|
|
Potential sources include:
|
|
|
|
- scenario text;
|
|
- webhook payload;
|
|
- generated dialogue;
|
|
- simulator data;
|
|
- operator input.
|
|
|
|
NGN does not reproduce the exhibit's speech engine.
|
|
|
|
---
|
|
|
|
## 25. Scenario Packaging
|
|
|
|
NGN SHOULD eventually generate self-running packaged HTML experiences.
|
|
|
|
Concept:
|
|
|
|
```text
|
|
Base Exhibit
|
|
+
|
|
Scenario Data
|
|
+
|
|
Compact Scenario Runtime
|
|
+
|
|
Required Embedded Configuration
|
|
|
|
|
v
|
|
Packaged HTML
|
|
```
|
|
|
|
The packaged artifact may run without NGN.
|
|
|
|
---
|
|
|
|
## 26. Shared Scenario Runtime Core
|
|
|
|
Live and packaged playback MUST share one scenario-runtime core.
|
|
|
|
The runtime MUST drive the exhibit through the same canonical target surface used in live NGN operation.
|
|
|
|
It MUST NOT bypass contract semantics by calling arbitrary exhibit internals.
|
|
|
|
The runtime transport is pluggable:
|
|
|
|
```text
|
|
live NGN -> host transport / postMessage
|
|
packaged HTML -> direct in-process contract adapter
|
|
```
|
|
|
|
This keeps scenario semantics aligned while avoiding unnecessary host-bridge overhead inside a packaged artifact.
|
|
|
|
---
|
|
|
|
## 27. Compact Packaged Runtime
|
|
|
|
The exported runtime includes only execution functionality needed by the package.
|
|
|
|
It may include:
|
|
|
|
- scenario clock;
|
|
- set/invoke dispatch;
|
|
- waits;
|
|
- marks;
|
|
- loops;
|
|
- required conditions;
|
|
- cleanup logic.
|
|
|
|
It does not include:
|
|
|
|
- authoring UI;
|
|
- recorder;
|
|
- webhook server;
|
|
- connector framework;
|
|
- NGN administration;
|
|
- multi-exhibit management.
|
|
|
|
---
|
|
|
|
## 28. Packaged Exhibit Contract Access
|
|
|
|
A packaged exhibit retains the same canonical exhibit target surface.
|
|
|
|
The embedded runtime is a local consumer of that surface.
|
|
|
|
External host attachment may remain available if the base exhibit supports it, but is not required for packaged scenario execution.
|
|
|
|
---
|
|
|
|
## 29. Package Size Discipline
|
|
|
|
The compact scenario runtime should remain small relative to the exhibit.
|
|
|
|
Packaging SHOULD report:
|
|
|
|
- base exhibit size;
|
|
- runtime size;
|
|
- scenario-data size;
|
|
- final package size.
|
|
|
|
No hard numeric limit is imposed in v5.2, but the runtime SHOULD NOT approach the size of the base exhibit unless a future capability explicitly justifies it.
|
|
|
|
---
|
|
|
|
## 30. Administration
|
|
|
|
Future NGN administration may include:
|
|
|
|
- installed exhibits;
|
|
- running exhibits;
|
|
- session health;
|
|
- discovered capabilities;
|
|
- target catalog;
|
|
- current state;
|
|
- action testing;
|
|
- scenarios;
|
|
- webhook configuration;
|
|
- connectors;
|
|
- telemetry mappings;
|
|
- logs;
|
|
- packaging tools.
|
|
|
|
---
|
|
|
|
## 31. Security
|
|
|
|
Because NGN may expose local or network services, it owns the heavier trust boundary.
|
|
|
|
Eventually address:
|
|
|
|
- authentication;
|
|
- authorization;
|
|
- webhook tokens;
|
|
- origin restrictions;
|
|
- input validation;
|
|
- rate limiting;
|
|
- connector permissions;
|
|
- bind-address defaults;
|
|
- TLS guidance;
|
|
- secret storage;
|
|
- audit logging;
|
|
- least privilege.
|
|
|
|
The exhibit still validates every contract message.
|
|
|
|
---
|
|
|
|
## 32. Network Defaults
|
|
|
|
NGN SHOULD default to safe local binding.
|
|
|
|
Network exposure must be explicit.
|
|
|
|
A premium feature must not accidentally become an unauthenticated LAN or Internet control surface.
|
|
|
|
---
|
|
|
|
## 33. Logging and Diagnostics
|
|
|
|
NGN should maintain structured logs for:
|
|
|
|
- session connection;
|
|
- version negotiation;
|
|
- describe results;
|
|
- registry changes;
|
|
- state resync;
|
|
- scenario actions;
|
|
- webhook requests;
|
|
- connector errors;
|
|
- capability failures;
|
|
- packaging operations.
|
|
|
|
Logging should support diagnosis without requiring browser developer tools.
|
|
|
|
---
|
|
|
|
## 34. Version Compatibility
|
|
|
|
Track separately:
|
|
|
|
- NGN application version;
|
|
- XZBT contract version;
|
|
- exhibit product version;
|
|
- scenario format version;
|
|
- registry revision;
|
|
- state revision.
|
|
|
|
These are distinct concepts.
|
|
|
|
---
|
|
|
|
## 35. Implementation Phases
|
|
|
|
### Phase 0 - Contract harness
|
|
|
|
Build a small synthetic exhibit and host test harness for XZBT Contract 5.2.
|
|
|
|
### Phase 1 - Single exhibit host
|
|
|
|
Host SciFi-XZBT and establish a session.
|
|
|
|
### Phase 2 - Dynamic discovery UI
|
|
|
|
Render capabilities, targets, state, and events.
|
|
|
|
### Phase 3 - State synchronization
|
|
|
|
Implement revision and sequence tracking plus resync behavior.
|
|
|
|
### Phase 4 - Minimal scenario runtime
|
|
|
|
Support timed `set` / `invoke` operations and cleanup.
|
|
|
|
### Phase 5 - Recorder
|
|
|
|
Capture canonical operator events.
|
|
|
|
### Phase 6 - Scenario persistence and basic editing
|
|
|
|
Save/load scenario documents and provide basic editing.
|
|
|
|
### Phase 7 - Webhooks
|
|
|
|
Add authenticated external triggers.
|
|
|
|
### Phase 8 - Telemetry connector framework
|
|
|
|
Only after at least one exhibit exposes structured writable telemetry.
|
|
|
|
### Phase 9 - Integration adapters
|
|
|
|
Add Streamer.bot and other useful adapters.
|
|
|
|
### Phase 10 - Packaging
|
|
|
|
Export self-running HTML using the shared runtime core.
|
|
|
|
### Phase 11 - Advanced authoring
|
|
|
|
Add richer timeline features, ramps, conditions, musical timing, and repeat regions.
|
|
|
|
### Phase 12 - Multi-exhibit engine
|
|
|
|
Add orchestration across multiple sessions when justified.
|
|
|
|
---
|
|
|
|
## 36. MVP Acceptance Criteria
|
|
|
|
NGN MVP succeeds when:
|
|
|
|
- one SciFi-XZBT exhibit can be hosted or attached;
|
|
- contract handshake succeeds;
|
|
- `describe` renders dynamically;
|
|
- current state is displayed;
|
|
- representative state can be changed;
|
|
- representative impulses can be triggered;
|
|
- events are displayed with source and sequence;
|
|
- state revision changes are tracked;
|
|
- reconnect resets sequence expectations;
|
|
- lost synchronization triggers fresh `state.get`;
|
|
- registry changes trigger debounced rediscovery;
|
|
- no SciFi-specific target vocabulary is hard-coded into core NGN logic.
|
|
|
|
---
|
|
|
|
## 37. Scenario Milestone Acceptance Criteria
|
|
|
|
The first scenario milestone succeeds when:
|
|
|
|
- a simple scenario document loads;
|
|
- target references validate against `describe`;
|
|
- timed set/invoke operations execute;
|
|
- scenario-origin events do not recursively record themselves;
|
|
- initial-state restore works for restorable targets;
|
|
- abort cleanup is predictable;
|
|
- the same runtime core can be used by the packager.
|
|
|
|
---
|
|
|
|
## 38. Packaging Milestone Acceptance Criteria
|
|
|
|
Packaging succeeds when:
|
|
|
|
- a base exhibit and scenario combine into one distributable HTML;
|
|
- the package runs without NGN;
|
|
- the scenario runtime drives the canonical target surface;
|
|
- no authoring/admin/webhook stack is included;
|
|
- live and packaged runtime behavior matches for supported operations;
|
|
- package size is reported;
|
|
- the ordinary exhibit remains independently usable outside the package process.
|
|
|
|
---
|
|
|
|
## 39. Deferred Features
|
|
|
|
Intentionally deferred:
|
|
|
|
- musical timing;
|
|
- complex condition language;
|
|
- multi-exhibit synchronization;
|
|
- distributed receivers;
|
|
- cloud orchestration;
|
|
- advanced telemetry transforms;
|
|
- generic plugin marketplace;
|
|
- arbitrary scripting;
|
|
- sample-accurate show control.
|
|
|
|
---
|
|
|
|
## 40. Architectural Rule
|
|
|
|
Use the same test for every proposed feature.
|
|
|
|
**Does the exhibit need it to remain a complete standalone exhibit?**
|
|
|
|
Then it may belong in the exhibit.
|
|
|
|
**Does it coordinate, automate, connect, record, author, distribute, or externally control exhibits?**
|
|
|
|
Then it belongs primarily in XZBT-NGN.
|
|
|
|
---
|
|
|
|
## 41. Version 5.2 Summary
|
|
|
|
Version 5.2 preserves the Version 5 architecture and hardens the implementation boundary.
|
|
|
|
The first responsibility of NGN remains proving reliable discovery, observation, synchronization, and control.
|
|
|
|
Scenario authoring, webhooks, telemetry, integrations, and packaging all build on that verified contract surface.
|