Post Step 4 Completion

2026-09-14 07:57:18 -07:00
parent db973a86f3
commit 446bf3533e
52 changed files with 32034 additions and 3 deletions
@@ -0,0 +1,855 @@
+# 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.