Uzume Domain — Technical Specifications

Named after Ame-no-Uzume-no-Mikoto — the Shinto goddess who performed the first show in recorded mythology — Uzume is the Oshun platform for everything that happens between "the doors open" and "the last cable is struck."

This document specifies the implemented Uzume domain as it exists in libs/uzume/. Uzume is a library-only domain: there are no apps/uzume/ or services/uzume/ directories. It consists of 21 TypeScript libraries plus one Rust/WASM workspace (uzume-protocol-engines).

This is the authoritative low-level reference for engineers working on Uzume. For a conceptual introduction to what each subsystem does and why it exists, see features.md. For the layered architecture and design patterns, see architecture.md. Every type, enum, schema, table, event, constant, and protocol described below is traceable to source files under libs/uzume/.

1. Library Inventory#

All 22 packages exist under libs/uzume/. The table below is the definitive package manifest — use it to find the path and npm name for any library. Note that @uzume/protocol-engines is the npm wrapper for the Rust workspace; the native module published separately as @uzume/protocol-native.

The Rust workspace npm wrapper is published as @uzume/protocol-engines; its native module crate (uzume-node-bridge) builds the npm package @uzume/protocol-native.

Each subsystem library exposes a UzumeLibraryMetadata constant (e.g. UZUME_CORE_METADATA, UZUME_LUMINA_METADATA, UZUME_BROADCAST_METADATA) and a corresponding getUzume<Subsystem>Metadata() accessor returning { id, subsystem, description }.

1.1 Subsystem Engine Counts#

Each subsystem library is a flat collection of independent *-engine.ts modules re-exported from src/index.ts. Each engine is a self-contained domain-specific implementation — not a generic service. The counts below are source modules, excluding index.ts and test files. They provide a useful signal for code review: a library where the count does not match likely has an engine missing from src/index.ts.

@uzume/core and @uzume/nexus follow a different shape (core: typed modules; nexus: a metadata-only package — see §11).

2. Technology Stack#

The table below records every technology choice that affects how the domain is built, tested, and deployed. The key design decision is the TypeScript/Rust split: TypeScript for domain logic and coordination, Rust for anything that requires deterministic timing or high-throughput packet processing. The Rust workspace release profile (lto = true, codegen-units = 1, opt-level = "s") is tuned for binary size and performance on embedded and server targets, not compilation speed.

@uzume/core depends on the shared packages @oshun/database, @oshun/errors, @oshun/logging, plus nats, drizzle-orm, and zod. Subsystem libraries declare @uzume/core as a peerDependency (workspace:*).

The Rust workspace release profile uses lto = true, codegen-units = 1, opt-level = "s". Shared crate dependencies: serde, serde_json, thiserror, wasm-bindgen, js-sys, serde-wasm-bindgen, tokio (full features), bytes, napi/napi-derive/napi-build, midir.

3. Core Domain Types (@uzume/core/types)#

The core domain types define the shared vocabulary for the entire Uzume surface: what a show is, what a cue is, what a venue is, and how production departments are represented. These types are the contracts that subsystem libraries build on top of, and that consuming applications receive back.

Domain types are exported through the @uzume/core/types subpath (src/types/index.ts). They are not part of the package root export — the root src/index.ts exports config, database, errors, event-bus, logging, and utils only. This separation means a subsystem that only needs types does not pull in the NATS client and database ORM.

src/types/index.ts re-exports: department, cue, protocol-audio, protocol-automation-safety, protocol-control, protocol-dmx, protocol-equipment, protocol-gdtf, protocol-maintenance, protocol-mvr, protocol-patched-fixture, show, timeline, venue.

Every interface below has a matching Zod schema and a parse* helper. The parse* helpers throw with a descriptive message if validation fails — they are the recommended entry points for untrusted external data.

3.1 Department (department.ts)#

The Department enum is the organizational backbone of Uzume: it classifies who owns a given cue, resource, budget line, or alert. Every cue list belongs to a department, every budget allocation belongs to a department, and the event bus routes alerts to department dashboards. The DepartmentReadinessState enum tracks the real-time operational state of a department during a show — used by the stage manager's cue display to show which departments are ready to receive a "Go."

Department enum — 18 values:

lighting, audio, video, automation, effects, scenic, stage_management, production, safety, xr, audience, wardrobe, previz, scheduling, electrical, communication, network, ai.

DepartmentReadinessState enum — 7 values: not_ready, prepping, standby, ready, active, blocked, offline.

DepartmentAlertSeverity union: info | warning | critical | safety-critical.

Validation: DepartmentConfigSchema rejects committedAmount > allocatedAmount. Helpers: parseDepartmentConfig, parseDepartmentStatus, isDepartment, isDepartmentReady, hasBlockingDepartmentAlerts.

3.2 Cue (cue.ts)#

The Cue is the fundamental unit of show execution — an instruction to a department to change something at a specific time or trigger. Cues have a trigger mechanism (CueTriggerType), a lifecycle state (CueState), and a map of parameter changes to apply to target devices. The CueList groups cues into a sequence, tracks which cue is active, and enforces consistency between cueCount and the actual list length.

CueTriggerType enum — 6 values: manual, follow, auto_follow, timecode, midi, osc.

CueState enum — 6 values: standby, go, running, complete, skipped, disabled.

CueParameterValue is a recursive union: string | number | boolean | null | CueParameterMap | CueParameterValue[]; CueParameterMap is Record<string, CueParameterValue>.

CueList fields: id (UUID), department, sequenceNumber, label, cueCount, activeCueIndex (≥ −1), cues[].

Validation rules:

• Cue: isEnabled must be false when state === disabled.
• CueList: cueCount must equal cues.length; activeCueIndex must be -1 for an empty list and otherwise point to an existing cue.

Helpers: parseCue, parseCueList, cueNumberToSortableValue, sortCuesByNumber, isCueReadyToExecute, getNextCue.

3.3 Show (show.ts)#

The Show type is the root aggregate for a production in Uzume: it carries the show's identity, creative team, production dates, venue assignments, and configuration (which subsystems are enabled, how cues are numbered, what timecode format is used). The ShowStatus lifecycle mirrors the real phases of a production from planning through archiving.

ShowType enum — 8 values: theatre, concert, festival, corporate, ceremony, broadcast, immersive, touring.

ShowStatus enum — 8 values: planning, pre-production, tech, dress, preview, running, closed, archived.

CueNumberingMode enum — 4 values: numeric, decimal, departmental, custom.

SmpteFrameRate (show.ts): literal union 24 | 25 | 29.97 | 30.

Validation: every departmentList entry must appear in enabledSubsystems; dropFrame is valid only with frameRate 29.97 or 30.

Helpers: parseShow, isShowType, normalizeShowConfiguration (de-dupes department lists), isShowActive (true for tech/dress/preview/running).

3.4 Timeline (timeline.ts)#

The Timeline type maps show events to SMPTE timecode frame positions. This is what allows lighting cues, video triggers, and automation moves to be locked to an audio or video timecode source — everything that happens at a given timecode position is grouped into a TimelineEvent. Markers and regions provide editorial annotations that do not trigger execution. The timecode arithmetic helpers implement the SMPTE drop-frame correction that affects 29.97 fps timecode, which is the standard for NTSC broadcast.

TimelineFrameRate: 24 | 25 | 29.97 | 30.

TimelineEventType union: cue_trigger | cue_complete | manual_note | automation_checkpoint | safety_checkpoint.

Validation: frames must be ≤ round(frameRate) − 1; dropFrame valid only for 29.97/30; TimelineRegion.endFrame ≥ startFrame.

Timecode arithmetic helpers (all SMPTE-aware, drop-frame-correct for 30 fps): parseSmpteTimecode, formatSmpteTimecode, timecodeToFrames, framesToTimecode, convertFramesBetweenRates, convertTimecodeRate, addTimecodes, subtractTimecodes, parseTimeline, normalizeTimeline.

3.5 Venue (venue.ts)#

The Venue type stores the physical and technical specification of a performance space. The technical sub-types (HouseLightingSystem, HouseAudioSystem, VenueNetworkInfrastructure) record what is permanently installed at the venue so that a touring production knows what it needs to bring versus what it can use in-house. The access sub-types (DockAccessHours, ElevatorCapacity, HallwayDimensions) capture the physical logistics of getting equipment in and out.

VenueType enum — 8 values: proscenium, thrust, arena, traverse, black_box, outdoor, stadium, custom.

Helpers: parseVenue, isVenueType, supportsHeavyRigging (default min SWL 1000 kg), getMaxFloorLoadKgPerSquareMeter, hasProtocolAtPatchPanel.

4. Protocol Type Specifications (@uzume/core/types)#

The protocol types define the low-level wire format structures that Uzume uses to communicate with physical hardware. These are distinct from the domain types in §3 — they represent the byte-level concepts (universes, channels, packets, device UIDs) rather than the production-management concepts (shows, cues, venues). Each protocol module defines constants, interfaces, validation rules, and helpers for one or two related protocols.

4.1 DMX512 (protocol-dmx.ts)#

DMX512 is the ANSI E1.11 standard for lighting control: a serial protocol that delivers 512 channel values (each 0–255) per universe at up to 44 Hz. Art-Net and sACN are IP transports for DMX universes — they carry the same 512-channel payload over UDP, enabling much larger channel counts and network distances than physical DMX cabling. RDM (Remote Device Management, ANSI E1.20) is a bidirectional extension of DMX that allows console-to-fixture parameter queries and commands.

Constants: DMX_CHANNEL_COUNT = 512, SACN_UNIVERSE_MIN = 1, SACN_UNIVERSE_MAX = 63999.

Validation: DMXPatch rejects footprints overrunning channel 512; ArtNetConfig requires targetIpAddress when mode === unicast; SACNConfig requires multicastGroup to equal the computed group for its universe.

Helpers: createDMXUniverse, setDmxChannel (value 0–255), getDmxChannel, computeSacnMulticastGroup (239.255.<hi>.<lo>), parseDMXPatch, parseArtNetConfig, parseSACNConfig, parseRDMDevice.

4.2 Control Protocols (protocol-control.ts)#

OSC (Open Sound Control), MIDI, and SMPTE timecode are the three most common show control protocols beyond DMX. OSC is an address-pattern-based message protocol (similar to HTTP URLs) used widely by audio consoles, video servers, and custom control systems. MIDI Show Control (MSC) is a MIDI extension specifically designed for theatrical cue triggering. Timecode (LTC and MTC) carries the master clock signal that all timecode-locked cues chase.

OSCArgument discriminated union — 8 variants: int32, float32, string, blob (Uint8Array), true, false, nil, timetag.

MIDIMessageType union — 6 values: note_on, note_off, cc, program_change, sysex, msc.

MSCCommandFormat union — 8 values: lighting, sound, machinery, video, projection, process_control, pyro, all.

MSCCommandType union — 7 values: go, stop, resume, timed_go, set, fire, all_off.

TimecodeFrameRate union — 5 values: 24, 25, 29.97df, 29.97ndf, 30 (string literals). TimecodeType union: ltc | mtc.

Validation: MSC non-all_off commands require cueNumber; note_on/note_off/ cc require exactly 2 data bytes; program_change exactly 1; sysex must be 0xF0 … 0xF7; msc type requires an mscCommand. Timecode frames capped per frame rate (23/24/29/29/29).

Helpers: parseOSCMessage, parseMIDIMessage, parseMSCCommand, parseTimecode, parseTimecodeString, formatTimecode, midiStatusByte.

4.3 Network Audio (protocol-audio.ts)#

Dante is Audinate's proprietary network audio protocol — the most widely deployed standard in professional live sound — while AES67 is the interoperability layer that allows Dante devices to talk to competing systems (Q-SYS, RAVENNA, Livewire). Both route audio over standard Ethernet but require PTP (Precision Time Protocol) synchronization to within a few microseconds to avoid audible glitches. WirelessMicrophone represents the RF and battery telemetry that wireless systems report back to the mixing position.

Constants: DANTE_MAX_CHANNELS = 1024, AES67_PTP_DOMAIN_MIN = 0, AES67_PTP_DOMAIN_MAX = 127.

AudioSampleRate: 44100 | 48000 | 88200 | 96000 | 176400 | 192000. AudioBitDepth: 16 | 24 | 32. DanteLatencySettingMs: 0.25 | 0.5 | 1 | 2 | 5 | 10.

Validation: a Dante route cannot loop a channel to itself; subscription destinationDevice must match the owning DanteDevice.name; AES67Stream multicastAddress must be in 224.0.0.0/4.

Helpers: parseDanteRoute, parseDanteDevice, parseAES67Stream, parseWirelessMicrophone, parseSpeakerPosition, validateDanteRouteForDevices, computeWirelessMicBatteryClass (critical <15%, low <35%, else ok).

4.4 Video (protocol-video.ts)#

The video protocol types cover both the signal format layer (SDI frame rates and formats, NDI streams) and the application layer (LED panel mapping, projection surface geometry, media asset metadata). SDI is the traditional uncompressed digital video standard for broadcast; NDI is NewTek's IP-based alternative that routes video over standard Ethernet. LEDProcessor represents the Brompton, Megapixel, or other LED management hardware that sits between the media server and the LED panels.

VideoFrameRate: 23.976 | 24 | 25 | 29.97 | 30 | 50 | 59.94 | 60 | 120. VideoColorSpace: bt709 | bt2020 | srgb | dci-p3 | display-p3 | acescg. SDIFormat: HD | 3G | 6G | 12G. MediaCodec: prores | dnxhr | h264 | h265 | av1 | vp9 | jpeg2000 | notchlc | hap.

Validation: SDI embedded-audio channel limit per format (HD/3G 16, 6G 32, 12G 64); LEDProcessor panel ports must be ≤ outputCount and panelId unique; ProjectionSurface uvMapping length must equal meshVertices length.

Helpers: parseNDISource, parseSDISignal, parseLEDProcessor, parseProjectionSurface, parseMediaAsset, estimateVideoBandwidthMbps, mediaAssetFrameCount, mediaAssetAspectRatio.

4.5 Automation and Safety (protocol-automation-safety.ts)#

Automation safety types represent the physical safety infrastructure that governs moving equipment. A MotionAxis is an individual motorized axis (one chain hoist, one flying rail, one turntable) with position and velocity ranges enforced by the control system. A LoadCell is a weighing transducer attached to a rigging point that reports the actual load in real time — critical for detecting overloads before a structural failure. The SafetyPLC (Programmable Logic Controller) is the hardware safety layer that enforces emergency stop logic independently of the show control software.

MotionAxisType: hoist | fly | turntable | lift | track | custom. MotionAxisStatus: idle | moving | fault | e_stopped. LoadCellStatus: normal | warning | alarm | fault. SafetyPlcState: run | stopped | fault. GPIODirection: input | output.

Validation: axis currentPosition within positionRange; idle/e_stopped axes must have near-zero velocity; custom type requires customTypeLabel; LoadCell.alarmThresholdKg ≤ ratedCapacityKg with status/load coherence checks; SafetyPLC cannot be run while emergencyStopActive.

Helpers: parseMotionAxis, parseLoadCell, parseSafetyPLC, parseGPIOPin, motionAxisTravelPercent, loadCellUtilizationPercent, evaluateLoadCellStatus, canEnableSafetyOutputs.

4.6 Equipment (protocol-equipment.ts)#

The equipment types form the inventory backbone of the domain. The Equipment type is a discriminated union keyed on EquipmentCategory — each category selects a distinct specification interface with category-appropriate fields (e.g. LightingFixtureSpec has DMX footprint and fixture type; RiggingHoistSpec has rated capacity and chain speed). The isSafetyCriticalEquipment helper identifies equipment that requires additional inspection rigor.

EquipmentCategory enum — 24 values: lighting_fixture, lighting_accessory, audio_speaker, audio_console, audio_microphone, audio_wireless, audio_processing, video_display, video_projector, video_processor, video_camera, rigging_hoist, rigging_truss, rigging_hardware, effects_pyro, effects_atmospheric, effects_laser, scenic_element, electrical_distro, electrical_cable, communication_intercom, communication_radio, network_switch, network_cable.

Equipment<C> extends EquipmentBase (id, name, manufacturer, model, serialNumber, status ∈ available|in_use|maintenance|retired, location?, tags[]) and adds category plus a specification whose shape is selected by category via EquipmentSpecificationByCategory. Each of the 24 categories has a distinct typed specification (e.g. LightingFixtureSpec, RiggingHoistSpec, EffectsLaserSpec, NetworkSwitchSpec).

EquipmentRecord is the discriminated union over all 24 typed equipment shapes.

Helpers: parseEquipment, parseEquipmentList, isEquipmentCategory, estimateEquipmentPowerDrawWatts, isSafetyCriticalEquipment (true for rigging hoists/hardware, pyro, electrical distro).

4.7 Maintenance (protocol-maintenance.ts)#

Maintenance records in live entertainment are not optional paperwork — they are the legal basis for operating equipment above audiences. A chain hoist that has not had a load test in the past year may not be legally rigged in many jurisdictions. The MaintenanceComplianceSummary aggregate is what a production manager or insurance auditor reviews to confirm a production's equipment is in compliance.

MaintenanceInspectionType: visual | functional | load_test | electrical_test | calibration.

MaintenanceResult discriminated union: { pass } | { conditional_pass, notes } | { fail, notes? }.

Helpers: parseMaintenanceRecord, parseMaintenanceRecordList, isMaintenanceRecordOverdue, isMaintenanceRecordDueSoon, listOverdueMaintenanceRecords, generateMaintenanceComplianceSummary (deduplicates to the latest record per equipment/inspection-type pair).

4.8 GDTF (protocol-gdtf.ts)#

GDTF (General Device Type Format) is the open standard — developed jointly by MA Lighting, Robe, and the GDTF group — for describing the complete capabilities of a lighting fixture in a machine-readable file. A GDTF file (.gdtf, a ZIP archive) contains the fixture's DMX modes, physical dimensions, wheel contents, and geometry hierarchy. The parseGDTFFixtureArchive function reads these archives directly, which is what enables Lumina to ingest any manufacturer's GDTF file without custom code.

GDTF (General Device Type Format) fixture profiles. GDTFWheelType: color | gobo. GDTFGeometryType: base | yoke | head | beam | pixel_group | other.

Parsers (real implementations, not stubs): parseGDTFFixtureXml parses GDTF description.xml via an in-module XML tree parser; parseGDTFFixtureArchive extracts a .gdtf ZIP archive (handles stored and DEFLATE-compressed entries via node:zlib); parseGDTFFixtureFile reads from disk.

4.9 MVR (protocol-mvr.ts)#

MVR (My Virtual Rig) is the show-file exchange format that GDTF-based software uses to transfer a complete lighting design between tools — from the CAD design application (Vectorworks Spotlight) to the lighting console (grandMA3) to Uzume. An MVR file is a ZIP archive containing a GDTF file per fixture and a scene XML. Uzume implements full bidirectional MVR exchange: it can both import designs from other tools and export its own for use in external software.

MVR (My Virtual Rig) scene exchange. MVRLayerType: fixtures | trusses | scenic | focus_points. MVRSourceApplication: vectorworks_spotlight | grandma3 | capture | uzume | other.

Validation: every entity's layerId must reference a layer of the matching type; focusPointId references must exist; group memberIds must reference existing scene entities.

MVR exchange (full bidirectional implementation): parseMVRSceneXml, parseMVRSceneArchive, parseMVRSceneFile, serializeMVRSceneXml, serializeMVRSceneArchive (writes a stored-mode ZIP), writeMVRSceneFile, parseMVRScene.

4.10 Patched Fixture (protocol-patched-fixture.ts)#

The patched fixture is the runtime representation of a real lighting fixture that has been assigned a physical DMX address in the patch. It bridges the static GDTF fixture profile (what the fixture is capable of) with the live production context (where it is, which DMX address it uses, what its current parameters are). The revision counter on PatchedFixture enables optimistic concurrency: two operators cannot silently overwrite each other's parameter changes.

Bridges GDTF profiles into a placed, patched, live fixture.

Validation: modeName must exist in gdtfFixture.dmxModes; the patched mode must not overrun channel 512.

Helpers: parsePatchedFixture, createPatchedFixture (de-dupes groups, sets revision 0), applyPatchedFixtureRealtimeUpdate (merges and increments revision), patchedFixtureChannelFootprint, patchedFixturePatchEndAddress.

5. Event Bus (@uzume/core/event-bus)#

The event bus is the coordination mechanism that allows subsystem libraries to react to each other's state changes without importing one another. When the stage manager calls a cue in @uzume/koru, it publishes a cue.trigger event; @uzume/lumina, @uzume/sonos, and any other subscribed subsystem each receive that event and take action independently. This is what makes subsystem isolation possible at the architecture level.

The event bus is a NATS-backed publish/subscribe layer. Exported from src/event-bus/index.ts: types, transport, in-memory-transport, uzume-nats-event-bus.

5.1 Event Types and Subjects#

There are 6 event types. Each type has a constant name, a string type value embedded in the envelope, and a NATS subject used for routing. The table below maps all three for easy lookup when writing publishers or subscribers.

5.2 Event Payload Schemas#

Each event type has a Zod schema in UZUME_EVENT_PAYLOAD_SCHEMAS that validates the payload at publish and subscribe boundaries. The schemas are the contract between publishers and subscribers — if a field is missing or of the wrong type, NATS delivery still succeeds but Zod validation will throw before the subscriber processes the event. The table below lists each schema and its key payload fields.

5.3 Envelope, Priority, Delivery#

The delivery guarantee is selected automatically from the event priority: a safety-critical event uses guaranteed delivery (request/ack with retry) while informational events use best-effort. This means safety alerts cannot be silently dropped by a NATS connection issue without triggering retries, while routine status updates do not add ack latency.

UZUME_EVENT_PRIORITIES: informational | operational | safety-critical. UZUME_DELIVERY_GUARANTEES: best-effort | guaranteed.

UzumeEventEnvelope<T> fields: eventId, type, subject, occurredAt, correlationId?, sourceSubsystem?, priority, deliveryGuarantee, payload.

UzumePublishOptions: correlationId?, sourceSubsystem?, priority?, guaranteedRetryLimit?, retryDelayMs?, ackTimeoutMs?. UzumeSubscriptionOptions: queueGroup?.

5.4 Transports and Bus#

Two transport implementations share the same UzumeNatsTransport interface: the production transport wraps a real NATS connection, while the in-memory transport runs entirely in-process for unit tests and embedded scenarios. Switching between them requires only changing the transport constructor call — the bus and all subscriber code remain identical.

• UzumeNatsTransport interface — publish, request, subscribe, close.
• NatsJsUzumeTransport — production transport wrapping a real nats connection; createNatsJsUzumeTransport(config) connects with UzumeNatsConnectionConfig (servers, name?, token?, user?, password?, timeoutMs?, default timeout 5000 ms).
• InMemoryUzumeNatsTransport — in-process transport implementing the same interface for tests and embedded use.
• UzumeNatsEventBus — typed bus over a transport. publish selects best-effort vs guaranteed delivery from event priority; guaranteed events use request/ack with retry (default guaranteedRetryLimit 3, guaranteedRetryDelayMs 100, guaranteedAckTimeoutMs 1000). Public methods: publish, subscribe, close.

6. Persistence — Drizzle ORM Schema (@uzume/core/database)#

All persistence for the Uzume domain lives in @uzume/core. Concentrating the database schema in one library avoids fragmentation across 22 separate schemas and prevents subsystem libraries from creating implicit cross-schema dependencies. Subsystem libraries are stateless computation libraries; they return values to the consuming application, which decides what to persist.

The PostgreSQL schema namespace is uzume (pgSchema('uzume')). Exported from src/database/index.ts: schema, migration definitions/index/service, and seeds.

6.1 PostgreSQL Enums (19)#

The following 19 enums are created in the uzume schema. They are listed here with their value count so that a schema diff can confirm completeness.

show_status (8), department_type (7: lighting, audio, video, automation, effects, scenic, stage_management), cue_target_type (6), cue_trigger_type (manual, timecode, follow, auto), equipment_condition (5), ownership_status (4), maintenance_result (pass, fail, needs_attention), assignment_type (show, truck, warehouse), certification_status (4), purchase_order_status (6), contract_status (5), settlement_status (4), inspection_result (3), incident_severity (4), incident_status (4), certification_log_status (4), safety_document_approval_status (4), safety_audit_event_type (insert, update, delete, state_change).

6.2 Tables (24)#

UZUME_CORE_TABLES enumerates all 24 tables. Every table carries a UUID primary key (defaultRandom()), JSONB metadata where applicable, and timestamp columns. Drizzle relations() are defined for every table, and InferSelectModel/InferInsertModel types are exported per table (e.g. Venue/NewVenue, Show/NewShow, Cue/NewCue).

6.3 Migrations#

There is a single bootstrap migration that creates the entire schema from scratch. This design means the schema has one authoritative starting state — incremental migrations are added only when the schema evolves after initial deployment. The migration tracking table and advisory lock ensure that concurrent application startup does not run the migration twice.

definitions.ts defines the single bootstrap migration 20260210120000_uzume_core_schema ("uzume core schema bootstrap"), with full CREATE/DROP SQL for the schema, the 19 enums, all 24 tables, and indexes. UZUME_CORE_MIGRATIONS lists it; getUzumeCoreMigrations, registerUzumeCoreMigrations integrate with the @oshun/database MigrationRunner.

service.ts provides UzumeCoreMigrationService and createUzumeCoreMigrationService, migrateUzumeCoreUp, migrateUzumeCoreDown, resolveUzumePostgresConfigFromEnv. The migration tracking table is public.uzume_schema_migrations; the advisory lock id is 620001.

6.4 Seeds#

seeds/generator.ts exports generateUzumeSeedDataset with UzumeSeedGeneratorOptions, UzumeSeedSummary, and UzumeSeedDataset, producing reference data for the schema.

7. Errors (@uzume/core/errors)#

The error system serves two purposes that go beyond a simple exception hierarchy. First, it routes errors to the correct department dashboard so that a lighting error surfaces to the lighting operator's display, not the sound board. Second, it escalates safety-critical errors through dedicated channels (audible and visual alerts) to ensure they are not silently swallowed. These requirements are why the error system is more complex than a simple throw new Error().

Exported from src/errors/index.ts: error-codes, error-framework, error-routing, safety-escalation, uzume-error.

7.1 Error Codes#

UZUME_ERROR_SUBSYSTEMS — 19 subsystems: LUMINA, SONOS, PRISM, KINESIS, PYRA, SCENA, KORU, NEXUS, ATLAS, AEGIS, AURORA, ECHO, VESTIS, PREVIZ, CHRONOS, TESLA, HERMES, FORGE, MUSE.

UzumeErrorCode is the template-literal type ${Subsystem}-${ThreeDigitCode} (e.g. LUMINA-042, sequence 001–999). Helpers: isUzumeErrorCode, createUzumeErrorCode, parseUzumeErrorCode.

7.2 UzumeError#

UZUME_ERROR_SEVERITIES: info | warning | critical | safety-critical.

UzumeError extends @oshun/errors' OshunError and adds subsystem, uzumeCode, severity, errorId (UUID), escalationRequired, plus isSafetyCritical(). UzumeOperationalContext carries showId?, venueId?, cueListId?, cueId?, deviceId?, operatorId?. Default code is <subsystem>-900; safety-critical severity defaults escalationRequired to true. Helpers: isUzumeError, toUzumeError.

7.3 Error Routing and Escalation#

error-routing.ts: UzumeErrorRouter routes errors to department dashboards. UzumeDepartmentDashboard has 17 values; SUBSYSTEM_DASHBOARD_MAP maps each of the 19 subsystems to a primary dashboard. buildUzumeDashboardRoutes adds a show_control route for critical errors and safety + stage_management routes for safety-critical errors. Topics follow uzume.dashboard.<dashboard>.errors.

safety-escalation.ts: UzumeSafetyEscalationService escalates safety-critical errors across UzumeSafetyEscalationChannels. UZUME_SAFETY_ALERT_MODES: audible | visual. The result reports delivered/failed channels and covered/missing alert modes.

error-framework.ts: UzumeErrorFramework (and createUzumeErrorFramework) ties routing, escalation, and logging together with UzumeErrorFrameworkConfig.

8. Configuration (@uzume/core/config)#

The configuration schema is designed for fail-fast startup: all required environment variables are validated and typed at boot time so that a missing UZUME_NATS_SERVERS is discovered before the first cue fires, not during the show. Feature flags allow a consuming application to enable only the subsystems it needs, which also drives which NATS subscriptions are established at startup.

config/env.ts defines UzumeConfigSchema (a Zod transform of an environment schema). Environment variables:

The transform shapes config into database, redis, nats, objectStorage, and features sections. loadUzumeConfig parses and caches; on failure it throws an aggregated message. Helpers: resetUzumeConfigCache, isUzumeFeatureEnabled, types UzumeConfig, UzumeFeatureKey.

9. Logging (@uzume/core/logging)#

Structured logging with subsystem context allows log aggregation systems to filter events by subsystem (LUMINA, AEGIS, etc.) and correlate related events across subsystems using the UzumeCorrelationContext. This is essential for diagnosing show-time incidents where events from multiple subsystems are interleaved in the log stream.

logging/uzume-logger.ts provides structured logging with subsystem context. UzumeSubsystem is a union of subsystem names; UzumeCorrelationContext and UzumeLogOutputTarget describe correlation propagation and output targets. UzumeSubsystemLogger is the per-subsystem logger; UzumeLoggingConfig and UzumeLoggingInfrastructure configure it; createUzumeLoggingInfrastructure builds the logging stack.

10. Utilities (@uzume/core/utils)#

The utilities module is a collection of pure computation functions that multiple subsystem libraries need. They are kept in @uzume/core rather than in the subsystem libraries to avoid duplication and to ensure that, for example, every subsystem's SMPTE timecode arithmetic uses the same drop-frame-correct implementation.

Exported from src/utils/index.ts: dmx, protocol-address, safety-calculations, smpte-timecode, unit-conversion.

10.1 smpte-timecode.ts#

SMPTE timecode arithmetic is subtle: 29.97 drop-frame timecode skips frame numbers 0 and 1 at the start of each minute (except every 10th minute) to compensate for the 0.1% difference between 30 and 29.97 fps. Getting this wrong causes timecode-locked cues to drift by 3.6 seconds per hour. The functions below handle drop-frame correction transparently.

SmpteFrameRate (24|25|29.97|30), TimecodeRoundingMode (round|floor|ceil|trunc), SmpteTimecode, TimecodeConversionOptions. Functions: parseSmpteTimecode, formatSmpteTimecode, timecodeToTotalFrames, totalFramesToTimecode, convertSmpteTimecodeFrameRate, addSmpteTimecodes, subtractSmpteTimecodes, multiplySmpteTimecode, compareSmpteTimecodes, createSmpteTimecodeRange.

10.2 dmx.ts#

DMX merge (HTP = highest-takes-priority, LTP = latest-takes-priority) is the mechanism for combining DMX output from multiple sources — the operator desk, a timecode playback system, and an effects engine may all be writing to the same universe simultaneously. mergeDmxUniverseSources produces the merged output; captureDmxSnapshot records the state for later comparison or restore.

Constants DMX_UNIVERSE_MIN = 1, DMX_UNIVERSE_MAX = 65535. DmxMergeMode (htp|ltp), DmxFadeCurve. Interfaces for patch entries, conflicts, source state, merged state, snapshots, and fades. Functions include detectDmxPatchConflicts, mergeDmxUniverseSources, captureDmxSnapshot, calculateDmxFade, calculateDmxUniverseFadeSnapshot, plus validators.

10.3 safety-calculations.ts#

These functions implement the structural and electrical load calculations that appear in rigging permit documentation and power distribution design. They are based on standard engineering formulas (ASCE 7 for wind load, standard bridle geometry for point loads) and return a SafetyStatus so callers can distinguish between confirmed safe, confirmed over-capacity, and capacity-unknown cases.

SafetyStatus (within_limit|over_capacity|capacity_not_provided). Structural, electrical, and environmental load math: calculatePointLoad, calculateDistributedLoad, calculateBridleLegTension, calculateSinglePhaseElectricalLoad, calculateThreePhaseElectricalLoad, calculateVerticalCableWeight, calculateWindLoadAsce7Simplified.

10.4 protocol-address.ts#

Protocol address strings follow different conventions in different tools and console displays (e.g., 1.001 vs 1/1 vs U1C1 for DMX universe 1 channel 1). These helpers parse human-readable address strings into typed structs and format typed structs back to canonical strings, insulating the rest of the codebase from the fragmentation.

DMX/Art-Net/sACN/Dante/NDI/IP-subnet/MIDI address parsing and formatting (e.g. parseDmxAddressString, artNetPortAddress, parseSacnUniverse, parseDanteChannelString, parseIpSubnet, midiNoteNumberToName, parseMidiCcString).

10.5 unit-conversion.ts#

Distance/weight/angle conversions, fractional-inch formatting, DMX↔degrees and DMX↔Kelvin conversions, single/three-phase power math (watts/VA/amps), and audio-level conversions (dBu/dBV/dBFS/dBSPL, Pa).

11. @uzume/nexus#

@uzume/nexus is the intended TypeScript entry point for the show control protocol bridge. The current TypeScript implementation is a metadata-only package: src/index.ts exports UZUME_NEXUS_METADATA and getUzumeNexusMetadata() and nothing else. The protocol-bridging behavior its description refers to is fully implemented in the Rust uzume-protocol-engines workspace and consumed by TypeScript applications via the napi-rs native module and the WASM control surface. The split exists because the protocol engines require sub-microsecond precision that Node.js cannot provide — moving them to Rust was a deliberate performance decision, not an implementation gap.

12. Rust Protocol Engines (@uzume/protocol-engines)#

The Rust workspace is the performance foundation of Uzume. It is a Cargo workspace at libs/uzume/protocol-engines/ (resolver = "2", edition 2021) with six crates organized into three layers: the shared type definitions (uzume-protocol-types), the timing and orchestration logic (uzume-timing-core), the network I/O engines (uzume-network-io), and two platform bridges that expose the workspace to TypeScript and browser environments. The integration test crate validates cross-crate behavior.

12.1 uzume-protocol-types#

This crate defines the shared types used across all other crates in the workspace. Keeping them in a separate crate avoids circular dependencies between uzume-timing-core and uzume-network-io, both of which need DMX, MIDI, OSC, and timecode types.

Constants: DMX_UNIVERSE_CHANNEL_COUNT = 512, DMX_MAX_UNIVERSES = 65535, DMX_MIN_REFRESH_HZ = 44.0, DMX_MAX_REFRESH_HZ = 100.0, RDM_MAX_UID = 0xFFFFFFFFFFFF, RDM_DEFAULT_REDISCOVERY_INTERVAL_MICROS = 30_000_000, RDM_MAX_LABEL_LENGTH = 32, DMX_RECORDING_MAGIC = b"UZDMXREC", DMX_RECORDING_FORMAT_VERSION = 1.

ProtocolTypeError enumerates the crate's error variants (invalid DMX length/channel/universe/refresh-rate/source-metadata, RDM UID/PID/parameter errors, recording I/O and data errors, MIDI channel, OSC address, timecode).

DMX: DMXUniverse (fixed 512-channel buffer); DmxMergeMode (Htp/Ltp/Priority); DmxUniverseManager merges per-channel writes from multiple tracked sources (DmxChannelSource, DmxChannelWrite) and exposes DmxUniverseSnapshots. DMX recording: DmxRecording, DmxRecordingSession, DmxPlaybackEngine with a binary on-disk format, delta frames, timecode-locked seek, and live-vs-recorded A/B comparison (DmxAbComparisonReport).

RDM: RdmCommandClass, RdmStandardPid (DISC_UNIQUE_BRANCH, DISC_MUTE, DEVICE_INFO, DMX_START_ADDRESS, IDENTIFY_DEVICE, DEVICE_LABEL, MANUFACTURER_LABEL, SOFTWARE_VERSION_LABEL, SENSOR_VALUE), RdmRequest/ RdmResponse, RdmDiscoveryRange (binary-search splitting), RdmDiscoveredDevice, and RdmEngine (discovery cycles, device tracking, re-discovery interval).

MIDI: MIDIMessage (status/data1/data2?/timestamp_micros) with note_on and control_change constructors (channel 1–16 validated).

OSC: OSCArgument (Int/Float/String/Bool/Blob), OSCMessage (address must start with /, optional timetag).

Timecode: TimecodeRate (Fps24/Fps25/Fps2997/Fps30) with nominal_fps(); TimecodeFrame with total_frames(), from_total_frames, add_frames, and frame-range validation.

12.2 uzume-timing-core#

This is the show's master clock and sequencer. HighPrecisionClock provides the time source; TimerWheel fires scheduled events at the right frame; SmpteTimecodeCounter tracks the running timecode from one of three sources (system clock, incoming LTC audio, incoming MTC MIDI); MasterTimelineEngine coordinates which cues fire at which timecode positions; and the CrossSubsystemCueSequencer fans out a single cue-go event to multiple subsystems simultaneously.

Constants include DMX_MIN_REFRESH_HZ, LTC_BITS_PER_FRAME = 80, MTC_QUARTER_FRAME_COUNT = 8, MIN/MAX_TIMELINE_PLAYBACK_SPEED (0.1–10.0), and discovery/health/failover defaults.

Major components: HighPrecisionClock/HighPrecisionTimestamp, TimerWheel (ScheduledEvent/ScheduledEventKind), SmpteTimecodeCounter and TimecodeSyncEngine (TimecodeSource ∈ system clock / external LTC / external MTC; MtcQuarterFrameDecoder; LTC config), the MasterTimelineEngine (TimelineRole, TimelineTransportState, TimelineSubsystem, loop regions, state recall, dispatch events), the CrossSubsystemCueSequencer (CueGoSource, cross-subsystem cue plans/dispatch), the ShowStateSnapshotEngine, the ProtocolTranslationEngine (rule-based protocol translation with visual mapping graphs and reverse mappings), and show-file commit/merge structures (ShowStateManifest, ShowFileCommit, MergeConflictStrategy, ShowMergeResult).

12.3 uzume-network-io#

This crate owns the UDP/TCP sockets and protocol packet parsers. Art-Net, sACN, and OSC all run over UDP; MIDI Show Control uses a TCP control channel. The output engines format outgoing packets and manage discovery handshakes (Art-Net's ArtPoll/ArtPollReply sequence, sACN's universe discovery mechanism). The MIDI engine integrates with the midir crate for actual MIDI port I/O.

Constants: ARTNET_PORT = 6454, ARTNET_PROTOCOL_VERSION = 14, Art-Net opcodes (ArtDmx 0x5000, ArtPoll 0x2000, ArtPollReply 0x2100, ArtSync 0x5200), ARTNET_MAX_DMX_PAYLOAD = 512, SACN_PORT = 5568, SACN_PRIORITY_MIN/MAX (0/200), SACN_MAX_DMX_PAYLOAD = 512, OSC_DEFAULT_PORT = 8000, MIDI_CLOCK_PPQ = 24.

Components: UdpEndpoint/UdpDatagram (NetworkIoConfig, NetworkIoError), TcpControlServer/TcpControlConnection, Art-Net/sACN/OSC packet parsers (ArtNetPacket, SacnPacket, OscPacket/OscMessagePacket/ OscBundlePacket), the ArtNetOutputEngine and SacnOutputEngine (with discovery: ArtNetDiscoveredDevice, SacnUniverseDiscovery), the OscEngine, the MidiEngine (MidiMessage, MidiClockState, MidiInboundEvent, MidiPortInfo), and the MidiShowControlEngine (MscPacket, MscCommandType, MscTarget, MscTimedGoTime).

12.4 uzume-control-surface-wasm#

This crate is the browser bridge. It exposes a small WASM API surface so that a browser-based control surface (a lighting console running in a tablet browser, for example) can construct and send protocol messages directly — without a server round-trip for each button press. The surface is intentionally minimal to keep the WASM binary small and load-time short.

A wasm-bindgen surface exposing WasmDMXUniverse (setChannel, getChannel, toUint8Array) and the free functions createMidiNoteOn, createOscMessage, and createTimecodeFrame. Built with wasm-pack build crates/uzume-control-surface-wasm --target web --release.

12.5 uzume-node-bridge#

This crate is the server-side Node.js bridge. It compiles to a native .node module via napi-rs and is published as @uzume/protocol-native. TypeScript server code can call UzumeProtocolBridge methods synchronously (they execute in the Node.js thread) for operations that need Rust performance without launching a subprocess. The message history limit (2048 entries) prevents unbounded memory growth in long-running show-control servers.

A napi-rs native module (@uzume/protocol-native). Exposes the UzumeProtocolBridge class with methods for DMX channel I/O (set_universe_channel, get_universe_channel, universe_output), device discovery (discover_devices), timecode sync (sync_timecode_to_system_clock, sync_timecode_external, set_timecode_chase_offset_frames, current_timecode), and OSC/MIDI message send/receive with bounded history (MESSAGE_HISTORY_LIMIT = 2048). napi object types: DiscoveredDevice, TimecodeFrameBinding, OscMessageBinding, MidiMessageBinding.

12.6 Build Commands#

Run these from libs/uzume/protocol-engines/ unless noted. The pnpm aliases (cargo:test, cargo:check, etc.) wrap these commands for use within the Nx monorepo build system.

# All Rust tests
cargo test --workspace          # (npm: cargo:test)
# Integration tests
cargo test -p uzume-integration-tests -- --nocapture   # (npm: cargo:test:integration)
# Workspace check
cargo check --workspace         # (npm: cargo:check)
# WASM control surface
pnpm --filter @uzume/protocol-engines build:wasm
# Node native module
napi build --platform --dts index.d.ts     # (in uzume-node-bridge, npm: build)

13. Subsystem Library Surface#

Each of the 19 subsystem libraries (and @uzume/lumina, @uzume/broadcast, etc.) is a flat collection of independent *-engine.ts modules re-exported from src/index.ts alongside the library metadata constant. Subsystem libraries do not import from one another; cross-subsystem coordination flows through the @uzume/core event bus. This section documents two libraries in detail as canonical examples of the module-per-engine pattern. The remaining 17 follow the same structure; per-file inventories live alongside each library's src/index.ts.

The following engine module lists are verified against src/index.ts in each library:

• @uzume/lumina (lighting): fixture-patch-engine, fixture-library-manager, gdtf-parser, mvr-exchange-engine, fixture-parameter-engine, color-engine, gel-library, color-picker-engine, color-consistency-engine, subtractive-mixing-engine, tracking-cue-stack-engine, fade-engine, cue-trigger-engine, multi-cue-list-playback-engine, cue-macro-engine, parametric-effects-engine, pixel-mapping-engine, generative-content-engine, console-integration-bridge, atmospheric-effects-engine.
• @uzume/broadcast: broadcast-switcher-integration-engine, broadcast-multiviewer-management-engine, replay-system-integration-engine, broadcast-graphics-engine, broadcast-audio-split-management-engine, broadcast-multi-platform-streaming-engine, stream-health-monitoring-dashboard-engine, srt-contribution-feed-management-engine, multi-venue-simulcast-distribution-engine, iso-recording-management-engine.

Subsystem engines are domain-specific implementations, not generic CRUD. For example: @uzume/aegis's risk-assessment-engine.ts defines RiskLikelihoodScore/RiskSeverityScore 1–5 scales, RiskLevel, and a probability×severity scoring matrix; @uzume/lumina's fixture-patch-engine.ts consumes @uzume/core/types GDTF/MVR helpers and detects DMX channel patch overlaps.

14. V2 Esports Integration (consumer-side)#

This section documents the V2 esports tooling's consumption of Uzume libraries. It is included in the Uzume specifications because it is the primary external consumer of @uzume/broadcast, @uzume/lumina, and @uzume/prism, and because the integration policies (primary package selection, NDI delegation, rollback isolation) are set at the Uzume boundary.

The V2 esports tooling package @v2/esports-tools (apps/v2/esports-tools/) consumes Uzume libraries — Uzume itself does not depend on V2. Two named contracts live in that package.

V2 Esports Broadcast Pipeline#

esports-broadcast-pipeline.ts imports from @uzume/broadcast and binds it as V2's primary esports broadcast pipeline through buildV2EsportsBroadcastPipeline (binding id v2.esports.uzume-broadcast-pipeline, primary package @uzume/broadcast). The pipeline composes the real broadcast subsystem engines — BroadcastMultiPlatformStreamingEngine, BroadcastSwitcherIntegrationEngine, BroadcastGraphicsEngine, ReplaySystemIntegrationEngine, SrtContributionFeedManagementEngine, and StreamHealthMonitoringDashboardEngine.

The requested-primary type is '@uzume/broadcast' | 'obs' | 'ndi' | 'vmix', but the contract pins standaloneObsAsPrimary: false, standaloneNdiAsPrimary: false, and standaloneVmixAsPrimary: false — @uzume/broadcast is always the program authority and NDI routing is delegated to @uzume/prism. The one piece of OBS that is retained (obsWebSocketRetained: true) is scoped purely to streamer-mode notification suppression: the OBS WebSocket exists only to mute desktop/overlay notifications for on-camera talent, never to drive the program feed. That purpose is fixed by V2_ESPORTS_BROADCAST_OBS_WEBSOCKET_PURPOSE (streamer-mode-notification-suppression-only) and emits the v2.streamer-mode.notifications.suppressed event. The rollback policy is off-rollback-broadcast-operations with mayInfluenceRollback: false.

V2 In-Arena LED + Projection Integration#

arena-led-projection-integration.ts composes @uzume/lumina and @uzume/prism through buildV2ArenaLedProjectionIntegration (binding id v2.esports.uzume-arena-led-projection) for live-tournament in-arena LED walls and projection mapping. Lighting and cue triggering come from @uzume/lumina (PixelMappingEngine, CueTriggerEngine); LED-wall layout, projection mapping, auto-alignment, and video routing come from @uzume/prism (LedWallLayoutDesignerEngine, ProjectionMappingEngine, ProjectionAutoAlignmentEngine, VideoRoutingMatrixEngine), with per-pixel correction generated by generatePerPixelCorrectionMap and aligned panels emitting v2.esports.arena.projection.aligned. Its rollback policy is off-rollback-arena-production-operations.

Both bridges expose mayInfluenceRollback: false — they are presentation/show-control state only and cannot affect deterministic match simulation.

This integration is documented under V2/docs/integration/ and is verified by V2/ue/Tools/check-v2-uzume-broadcast-pipeline.py and check-v2-uzume-arena-led-projection.py.

15. Acceptance Criteria#

These criteria define what "done" means for a change to the Uzume domain. They are ordered from most mechanical (type checking) to most structural (schema consistency). All criteria must pass before a change is merged, not just the ones affected by the specific change — the criteria are a holistic gate.

A change to the Uzume domain is acceptable when:

1. npx tsc --noEmit passes for each modified TypeScript library.
2. npx vitest run passes for each modified library's test files (*.spec.ts / *.test.ts).
3. cargo test --workspace and cargo check --workspace pass for changes to uzume-protocol-engines.
4. New domain objects, enums, or protocol types in @uzume/core/types ship with a matching Zod schema and parse* helper.
5. New event types are registered in UZUME_EVENT_TYPES, UZUME_EVENT_SUBJECTS, UZUME_EVENT_PAYLOAD_SCHEMAS, and UzumeEventPayloadMap together.
6. Database schema changes update schema.ts, the bootstrap migration SQL in definitions.ts, and UZUME_CORE_TABLES.
7. Subsystem engine modules added to a library are re-exported from that library's src/index.ts.