Labyricorn/XZBT-NGN

Fork 0

generated from Labyricorn/labyricorn-project-template

Files

T

Labyricorn 446bf3533e Post Step 4 Completion

2026-09-14 07:57:18 -07:00

16 KiB

Raw Blame History

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:

host or attach to one SciFi-XZBT instance;
complete contract handshake;
request describe;
render discovered capabilities and targets;
request state;
invoke and set selected targets;
receive and display events;
display sequence and state revision;
detect and recover synchronization loss;
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:

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:

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:

request initial state.get;
record stateRevision;
apply normalized state/selection events;
track event sequence;
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:

ui
midi
hotkey

Optional:

host

Normally excluded:

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:

{
  "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:

ui
midi
hotkey

Optional:

host

Normally excluded:

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:

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:

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.

16 KiB Raw Blame History