Bellona Domain — Technical Specifications

Build Orchestration, Asset Interchange, Engine Bridge, and Remote-Control Platform

This document specifies what the Bellona domain actually implements in the Oshun monorepo. Every schema, field, enum value, command, and event listed below is traceable to source code under libs/bellona/* and apps/bellona/*. Items named in a design backlog but not yet present in code are explicitly labelled (planned).

1. Domain Layout#

Bellona is an Nx domain. It has 34 libraries under libs/bellona/ and 12 applications under apps/bellona/. There is no services/bellona/ directory.

1.1 Libraries (libs/bellona/)#

The following table is the complete, authoritative list of Bellona libraries. Each row shows the directory name, its NPM package identifier, and a brief summary of its role.

1.2 Applications (apps/bellona/)#

The following table is the complete, authoritative list of Bellona applications.

1.3 Implementation Status#

All 34 libraries and 11 of 12 apps contain real TypeScript (or C++) source files. libs/bellona/sdk-cpp and apps/bellona/render-api ship without a package.json but contain implementation source. The @bellona/blender-agent and @bellona/unity-agent packages are implemented, not planned — every module in their runtime catalogs carries status: 'implemented'.

The remote-control subsystem (remote-protocol, mcp-gateway, control-room, remote-gateway, remote-host) is a self-described "walking skeleton" / scaffold layer: source and tests exist, and the apps' own package.json descriptions call them walking-skeleton services.

2. Database Schema#

Bellona has a single PostgreSQL database that persists all build jobs, artifacts, bridge sessions, worker registrations, and audit records. The schema is managed by Prisma and lives entirely in the bellona datasource.

Database: PostgreSQL ORM: Prisma (prisma-client-js generator) Schema file: libs/bellona/database/prisma/schema.prisma (673 lines) Generated client output: libs/bellona/database/src/generated/client Datasource env var: BELLONA_DATABASE_URL Preview features: fullTextSearch, fullTextIndex Migration: libs/bellona/database/prisma/migrations/20260416000000_phase_8_bellona_initial/

The schema declares 11 models and 14 enums.

2.1 Models#

Build (builds)#

The central record for a build job. It tracks every aspect of the job's lifecycle: current status, which platforms to target, which assets to include, which worker is processing it, error details if it fails, and timing for performance analysis.

Relations: artifacts (BuildArtifact[]), logs (BuildLog[]), exports (ExportJob[]). Indexes: status, priority, projectId, userId, organizationId, workerId, createdAt, [status, priority], [projectId, status], deletedAt.

BuildArtifact (build_artifacts)#

Output files produced by a build, stored in S3-compatible object storage. The storageBucket and storageKey together form the canonical address for retrieving the artifact. The checksum enables content-addressable cache lookups.

Unique: [storageBucket, storageKey]. Indexes: buildId, platform, createdAt, expiresAt, deletedAt. No updatedAt field.

BuildLog (build_logs)#

Structured log entries emitted during build execution. Each entry captures the emitting component (source), the pipeline step (step), and a severity level alongside the message text, enabling structured querying for debugging.

Indexes: buildId, level, timestamp. No updatedAt field.

ExportJob (export_jobs)#

An export packaging job that wraps build artifacts into a downloadable engine-native format. The format enum selects the packaging strategy; the downloadUrl is a presigned URL provided once the export is COMPLETED.

Relations: build (Build?). Indexes: status, projectId, buildId, userId, organizationId, format, createdAt, expiresAt, deletedAt.

EngineProject (engine_projects)#

A record of a generated engine project scaffold — the set of files and configurations generated for a specific engine and platform combination. The settings JSON field holds engine-specific configuration that does not fit into the normalized columns.

Indexes: projectId, engine, status, userId, organizationId, createdAt, deletedAt.

BridgeSession (bridge_sessions)#

A session record for a live connection between the Bellona platform and a game engine editor. Tracks connection state (via status), sync progress (via syncedAssetCount), and the heartbeat timestamp used to detect dead sessions.

Relations: conflicts (SyncConflict[]). Indexes: projectId, engine, status, userId, organizationId, createdAt, lastHeartbeat, deletedAt.

SyncConflict (sync_conflicts)#

An asset version conflict detected during bidirectional sync, where the same asset was modified independently on both the Oshun side (localVersion) and the engine side (remoteVersion). The resolution field records how the conflict was resolved once a decision is made.

Indexes: sessionId, assetId, createdAt.

BuildWorker (build_workers)#

Registration record for a build worker node. Each worker declares its capabilities at registration time (jobTypes, platforms, engines) so the scheduler can route jobs only to workers capable of processing them. The lastHeartbeat timestamp is used to detect dead workers.

Unique: hostname. Indexes: status, lastHeartbeat.

AssetCache (asset_cache)#

Cached metadata for assets imported from other domains (Isis, Hathor), scoped per project. Storing this metadata locally avoids round-trips to the upstream domain's asset store for every build. The engineData JSON column holds engine-specific derived data, such as pre-computed import settings.

Unique: [projectId, assetId]. Indexes: projectId, type, updatedAt.

BuildTemplate (build_templates)#

A reusable build configuration that captures a complete set of build settings so teams do not need to re-specify platform combinations, optimization levels, and engine settings for every build. Templates can be marked as the organization default with isDefault.

Indexes: isActive, organizationId.

AuditLog (audit_log)#

An immutable audit trail for all entity changes within the Bellona database. Every mutation to a tracked entity produces an audit record that stores the actor, the before state, the after state, and the diff. The requestId correlates an audit entry back to the originating HTTP request.

Indexes: [entityType, entityId], userId, action, createdAt. No updatedAt field.

2.2 Enumerations#

The 14 enums below define all categorical values used throughout the schema. Every enum value is referenced by at least one model column above.

2.3 Schema Conventions#

The following conventions apply uniformly across all 11 models, ensuring consistency that simplifies queries and ORM integration.

• All primary keys use CUID (@default(cuid()), @db.VarChar(25)).
• Every model has createdAt; eight models have updatedAt (@updatedAt). BuildArtifact, BuildLog, and AuditLog do not have updatedAt.
• Build, BuildArtifact, ExportJob, EngineProject, BridgeSession carry a deletedAt soft-delete timestamp.
• size / totalSize use BigInt to support files larger than 2 GB.
• metadata, engineData, settings, previousState, newState, changes, and details are PostgreSQL jsonb.
• Array fields (assetIds, modules, plugins, platforms, engines, tags, warnings, dependencies, jobTypes) are PostgreSQL arrays.
• BuildWorker.hostname is unique; AssetCache is unique on [projectId, assetId]; BuildArtifact is unique on [storageBucket, storageKey].

3. Build / Export Job Lifecycle#

3.1 Build Status State Machine#

The BuildStatus enum drives the complete build lifecycle from submission to final outcome. A build enters PENDING when enqueued, moves to QUEUED when a worker picks it up, and progresses to RUNNING while the worker executes. It then either reaches COMPLETED, FAILED (retryable up to maxRetries), or CANCELLED by user request.

PENDING ──> QUEUED ──> RUNNING ──> COMPLETED
                          │
                          ├──────> FAILED      (retryable up to maxRetries)
                          └──────> CANCELLED   (user request)

A build's retryCount increments on transient failure until it reaches maxRetries (default 3). The build-worker job queue (JobStatus: pending, queued, running, completed, failed, cancelled) mirrors this lifecycle at the worker level.

3.2 Export Status State Machine#

Export jobs follow a simpler lifecycle. Once COMPLETED, a presigned download URL is generated that expires at expiresAt, at which point the job status transitions to EXPIRED.

PENDING ──> PROCESSING ──> COMPLETED ──> EXPIRED   (after expiresAt)
                              │
                              └────────> FAILED

3.3 Worker Status State Machine#

A build worker's status reflects its current operational mode. Normal operation cycles through OFFLINE → IDLE → BUSY. The PAUSED, STOPPING, and STOPPED states support controlled drains during deployments. Dead workers are identified when their lastHeartbeat becomes stale.

BuildWorker.status transitions across OFFLINE → IDLE → BUSY during normal operation, and PAUSED, STOPPING, STOPPED during controlled drains.

3.4 Job Priority#

The build-worker priority queue (apps/bellona/build-worker/src/queues/job-queue.ts) orders pending jobs by numeric priority: critical=4, high=3, normal=2, low=1. Higher-priority jobs are always dequeued before lower-priority ones regardless of submission order.

4. Build API (apps/bellona/build-api)#

The Build API is a Node.js module, not an HTTP server. It exposes a programmatic lifecycle API and subscribes to cross-domain events. It does not bind a TCP port itself; the 4005 port number is the documented domain assignment (libs/bellona/README.md) used by sibling services.

4.1 Programmatic API#

@bellona/build-api exports the following entry points from index.ts. The initialize() function is the only required setup step — it wires the cache, queues, and event subscriptions. After that, the module stays alive processing events passively.

import {
  initialize,
  shutdown,
  getCacheService,
  getBuildCacheService,
  isHealthy,
  getHealthStatus,
} from '@bellona/build-api';

await initialize();

const health = await getHealthStatus();
// {
//   status: 'healthy' | 'degraded' | 'unhealthy',
//   cache: boolean,
//   uptime: number,
//   cacheStats?: { hitRate: number, totalEntries: number }
// }

const cache = getCacheService(); // BuildCacheService

await shutdown();

initialize() performs three steps in order:

1. Constructs the BuildCacheService (Redis-backed content-addressable cache)
2. Initializes a dedicated Redis connection for job queues
3. Wires cross-domain event handlers via @bellona/event-handlers

On startup the process logs "Service ready and listening for events" and stays alive to process events; it does not accept HTTP requests.

4.2 Cache Service exports#

@bellona/build-api also exports BuildCacheService, createBuildCacheService, setBuildCacheService, clearBuildCacheService, and the BuildCacheServiceConfig type. The cache service supports content-addressable storage, compression, deduplication, in-memory + Redis tiers, and Redis PubSub invalidation.

4.3 Type surface#

The module re-exports a large typed surface from types.ts. The types are organized into the following groups:

• Branded IDs — BuildJobId, ArtifactId, ProjectId, AssetId, ContentHash (and their constructors createBuildJobId, createArtifactId, createProjectId, createAssetId, createContentHash)
• Job types — BuildJob, BuildJobType, BuildJobStatus, BuildJobPriority, BuildError, BuildProgress
• Artifact types — Artifact, ArtifactType, ArtifactMetadata, TargetPlatform, TargetEngine
• Cache types — CachedArtifact, CachedBuildJob, CacheEntry, CacheEntryMetadata, CacheLookupResult, CacheStats, CacheConfig
• Build input types — BuildInput, TextureBuildInput, MeshBuildInput, ShaderBuildInput, AudioBuildInput, AnimationBuildInput
• Dependency types — DependencyNode, DependencyGraph
• Event types — BuildEvent, BuildEventType
• Config types — BuildApiConfig, BuildApiHealth

4.4 Job-queue adapters#

main.ts builds a BuildQueueInterface and ExportQueueInterface. When REDIS_URL is set, jobs are persisted in Redis (bellona:queue:* keys: a job hash, a priority-scored :pending sorted set, and a per-project index set). When REDIS_URL is unset, an in-memory Map is used as a fallback. The build queue supports enqueue, getStatus, and cancel; the export queue supports enqueue and getStatus.

5. Build Worker (apps/bellona/build-worker)#

A poll-based background processor. The JobQueue class is a priority queue with poll-based dequeue (pollInterval default 1000 ms, concurrency default 1).

5.1 Worker types#

JobType is the union asset-bake | validate | engine-project-generate | export-package. Each job type has a dedicated worker module under apps/bellona/build-worker/src/workers/:

5.2 Worker type surface#

build-worker/types.ts declares branded IDs (JobId, WorkerId, ProjectId, AssetId), JobType, JobStatus, JobPriority, and per-job-type request and result types:

• asset-bake — AssetBakeRequest / AssetBakeResult / AssetBakeJob (with TextureBakeOptions, ModelBakeOptions, AudioBakeOptions, AnimationBakeOptions)
• validate — ValidationRequest / ValidationResult / ValidateJob (with ValidationSeverity, ValidationType, ValidationIssue)
• Format unions — AssetFormat, TextureFormat, ModelFormat, CompressionQuality

6. Render API (apps/bellona/render-api)#

An internal Node.js module (no HTTP port, no package.json) providing render-job caching, GPU queueing, and output validation.

import {
  initialize,
  shutdown,
  getCacheService,
  getRenderCacheService,
  isHealthy,
  getHealthStatus,
} from '@bellona/render-api';

6.1 Components#

The render-api is composed of three service components, each with factory and singleton accessor functions:

• RenderCacheService — Redis-backed render cache (createRenderCacheService, setRenderCacheService, clearRenderCacheService, config type RenderCacheServiceConfig).
• OutputValidator — render output quality validation (createOutputValidator, getOutputValidator, setOutputValidator), with ValidationSeverity, ValidationCategory, ValidationIssue, OutputValidationResult, JobValidationResult, ValidationOptions.
• GpuRenderQueue — GPU device allocation and queued job management (createGpuRenderQueue, getGpuRenderQueue, setGpuRenderQueue, clearGpuRenderQueue), with GpuDevice, GpuAllocationRequest, GpuAllocation, QueuedJob, GpuQueueStats, GpuQueueEvents, GpuQueueConfig.

6.2 Type surface#

render-api/types.ts declares the following types for render job management:

• Job and output — RenderJobId, RenderOutputId, RenderJob, RenderOutput, RenderConfig, RenderSettings, RenderProgress, RenderError
• Classification — RenderEngine, OutputFormat, QualityPreset, RenderStatus
• Animation — AnimationSettings, FrameRange, Resolution
• Cache — CachedRenderJob, CachedRenderOutput, RenderCacheMetadata, RenderCacheStats
• Queue — RenderQueueItem, RenderQueueStatus
• Events — RenderEvent, RenderEventType
• Config — RenderApiConfig
• ID constructors — createRenderJobId, createRenderOutputId

7. WebSocket Bridge Protocol#

The four engine bridge apps (bridge-blender, bridge-godot, bridge-unreal, bridge-unity) all build on @bellona/bridge-core (createBridgeServer). The protocol follows the same pattern for every engine: a handshake and ping command are registered first (identical across all bridges), followed by engine-specific commands.

7.1 Connection endpoints#

Ports default to 9001–9004 and host to localhost in each app's main.ts.

7.2 Common commands#

Every bridge registers these two commands regardless of engine. handshake establishes mutual version identification; ping verifies liveness.

The bridge-core server emits connection, disconnection, command, and error events.

7.3 Engine command sets#

The engine-specific commands registered by each bridge app are listed below. Implementation of each command lives in the corresponding engine adapter library.

The Unity, Unreal, Godot, and Blender command implementations live in @bellona/unity, @bellona/unreal, @bellona/godot, and @bellona/blender respectively.

7.4 Blender bridge session tracking#

bridge-blender is the only bridge that publishes cross-domain events. On connection and disconnection it calls BellonaEventPublisher.publishSessionStarted and publishSessionEnded (see §9). The other bridges track sessions in the database but do not emit cross-domain events.

8. Remote-Control Subsystem#

A browser-first remote-control layer for operating engine hosts, desktop applications, and headless browsers from a web operator console. The apps' package.json descriptions identify the gateway and host as "walking skeleton" services.

8.1 @bellona/remote-protocol#

Canonical protocol contracts for the entire remote-control subsystem. This library defines the type system and namespace structure that all three remote apps share.

Exports: BELLONA_REMOTE_PROTOCOL_PACKAGE_NAME, BELLONA_REMOTE_PROTOCOL_VERSION (0.1.0), BELLONA_REMOTE_PROTOCOL_SCHEMA_STATUS (version-negotiation), and createBellonaRemoteProtocolDescriptor(). The library is partitioned into contract modules: actor, audit, blender, browser, command, common, device, desktop, dry-run, logging, namespaces, policy, result, schema-registry, session, state, stream, unreal, version, plus browser-compensating-actions and desktop-compensating-actions.

The REMOTE_COMMAND_NAMESPACE constant defines 13 command namespaces: device, session, stream, agent, state, blender, unreal, browser, desktop, file, process, approval, diagnostic.

8.2 @bellona/mcp-gateway#

Remote-control MCP gateway server and local stdio transport. Ships a bellona-mcp-gateway binary (src/stdio-cli.js). Modules include stdio-server, remote-control-tools, remote-control-resources, auth-session, command-remediation, mcp-composition-rules, and an agent control layer with the following modules: agent-capability-memory, agent-autonomous-stop-criteria, agent-deep-integration-evals, agent-dry-run-cost-time-estimator, agent-dry-run-impact-summary, agent-dry-run-planners, agent-handoff-paths, agent-long-running-jobs, agent-mutation-locking, agent-preflight-checks, agent-tool-selection-policy, agent-visual-verification-policy.

8.3 Remote-control apps#

The control-room is gated behind the VITE_BELLONA_CONTROL_ROOM_ENABLED environment flag.

8.4 Phase 180 Roadmap Contract#

The remote-control subsystem is governed by the Phase 180 roadmap: the operating checklist is TODOS/phase-180.md (180.C canonical sequential checklist), the expanded requirements live in TODOS/phase-180-reference.md (180.R / 180.0–180.20, including the 180.19 acceptance criteria), and the audit of known scope gaps is TODOS/phase-180-gaps.md. The implementation tracker required by 180.C.01 lives at docs/domains/bellona/extras/remote-control/implementation-tracker.md.

Planned target layout not yet present in the repo:

Binding protocol rules from Phase 180: command schemas live only in libs/bellona/remote-protocol and are imported by gateway, host, MCP, adapters, tests, and docs (single source of truth); Blender/Unreal/browser debug and control ports remain localhost-only on the host; deep typed adapters must be preferred over desktop fallback; and no privileged path (arbitrary shell, arbitrary Blender Python, Unreal console, desktop control, or real browser profiles) may ship before policy, approval, and audit primitives are complete.

9. Events#

9.1 Events Published#

@bellona/event-publisher exposes BellonaEventPublisher with eight typed publish methods. The event-type string constants are defined in @oshun/contracts (libs/contracts/src/events/bellona.ts).

The table below shows each event, its publish method, and the key fields in its contract Zod schema payload.

The publisher also exports payload types (BellonaSessionStartedPayload, BellonaSessionEndedPayload, BellonaBuildStartedPayload, BellonaBuildProgressPayload, BellonaBuildCompletedPayload, BellonaExportStartedPayload, BellonaExportReadyPayload, BellonaAssetSyncedPayload) and the GameEngine, BuildPlatform, BuildStatus types, plus getBellonaEventPublisher, createBellonaEventPublisher, resetBellonaEventPublisher.

9.2 Events Consumed#

@bellona/event-handlers defines BELLONA_SUBSCRIPTIONS — four cross-domain subscriptions that drive Bellona's automated build reactions. Each handler receives the event payload and enqueues the appropriate build or export job.

setupBellonaEventHandlers accepts an eventBus, a consumerGroup, a BuildQueueInterface, an ExportQueueInterface, an optional logger, and an optional metrics config. Handler execution metrics are collected through @oshun/metrics via withMetrics / HandlerStatsTracker.

9.3 Event Bus Transport#

The event bus is @oshun/event-bus, which is Redis-backed (it imports ioredis). build-api/main.ts constructs the bus with createEventBus({ redisUrl, sourceDomain: 'bellona', keyPrefix: 'oshun:events', persistence: true, eventTtl: 86400, ... }).

10. Asset Interchange (@bellona/interchange)#

The interchange library exposes a format conversion pipeline (import → validate → transform → export) under src/{gltf,fbx,usd,transform,validation}. @bellona/interchange-models provides the shared data schemas.

10.1 AssetFormat union#

The AssetFormat type (interchange/src/types.ts) defines 13 3D-asset format values. This is the complete list of formats the interchange pipeline can process on the import side:

gltf, glb, usd, usda, usdc, usdz, fbx, obj, abc (Alembic), ply, stl, dae (Collada), blend.

10.2 ImageFormat union#

The ImageFormat type defines 9 image format values used for texture interchange:

png, jpg, jpeg, webp, exr, hdr, tga, bmp, tiff.

10.3 @bellona/asset-export#

A planning layer that sits on top of the interchange pipeline. Rather than executing conversions, it produces export plans and manifests that describe what conversions are needed and whether each target is ready or blocked.

Exports:

• BELLONA_ASSET_EXPORT_FORMATS — the supported export target formats: usd, usda, usdc, usdz, gltf, glb, fbx
• BellonaAssetExportStatus union — ready / needs-attention / blocked
• Planning functions — evaluateBellonaAssetExportTarget, evaluateBellonaAssetExportPlan, buildBellonaAssetExportManifest, createBellonaAssetExportTarget, createBellonaAssetExportPlan

Plan evaluation produces per-target readiness ratios, blocking/warning issue counts, and a checksum/package manifest.

11. Cross-Domain Integration (@bellona/integration)#

The integration library is the translation boundary between Oshun domain models and engine-native artifacts. It exports four factory functions, each producing a specialized consumer or compiler instance.

• createHathorConsumer — imports lore content (worlds, quests, dialogue) from Hathor world-publication events, with a configurable default engine and output directory.
• createLoreCompiler — compiles lore content for a target engine at a configurable optimization level.
• createIsisConsumer — imports generated assets from Isis, optionally auto-converting them.
• createAssetConverter — converts raw assets to engine-native formats via the interchange pipeline.

12. CLI (apps/bellona/cli)#

A Commander.js CLI. The program name is bellona (apps/bellona/cli/src/index.ts). Seven top-level commands are registered:

The global --api-key option and --api-url resolution use the BELLONA_API_KEY / BELLONA_API_URL / BELLONA_BUILD_API_URL environment variables.

13. TypeScript SDK (@bellona/client)#

@bellona/client provides a typed client. The README shows createBellonaClient({ baseUrl }) with namespaced operations (e.g. client.exports.create, client.exports.onProgress, client.exports.waitForCompletion).

14. C++ Native SDK (@bellona/sdk-cpp)#

libs/bellona/sdk-cpp contains C++ SDK sources (no package.json). It targets native engine plugins and build-machine agents that cannot host a Node.js runtime.

15. Configuration and Environment Variables#

15.1 Build API#

15.2 Render API#

15.3 Bridge Services#

15.4 CLI#

15.5 Control Room#

16. Integration Points#

16.1 Upstream Domains That Trigger Bellona#

The event-driven integration model means no upstream domain calls Bellona over HTTP. Instead, each domain publishes an event and Bellona's event handlers react asynchronously.

16.2 Shared Infrastructure Dependencies#

17. V2 Reciprocal Tasks (Backlog)#

The following items are tracked in the Bellona backlog as reciprocal dependencies of the sister-monorepo V2 fighting-game project.

17.1 BellonaUnrealRuntime (planned)#

• Task ID: BELLONA-UE-RUNTIME-V2-001
• Owner: Bellona Runtime Integrations
• ETA: 2026-06-30

Today the Unreal adapter ships an editor-only plugin at libs/bellona/unreal/plugin/BellonaUnrealEditor/. The runtime-shipped companion plugin BellonaUnrealRuntime is not yet implemented — no BellonaUnrealRuntime directory exists under libs/bellona/unreal/plugin/.

When the runtime plugin is built it will live, like its editor sibling, under Bellona ownership at libs/bellona/unreal/plugin/BellonaUnrealRuntime/. This is the single source of truth for the plugin. V2 must not create V2/ue/Plugins/BellonaUnrealRuntime/ as a parallel copy. The V2 monorepo consumes the Bellona-owned plugin once it ships rather than forking a runtime module of its own; a V2-side check-v2-bellona-runtime-gates.py CI check fails the build if a BellonaUnrealRuntime plugin directory appears under V2/ue/Plugins/.

Until the runtime plugin lands, the Editor-time BellonaUnrealEditor remains available and it is the only Bellona Unreal plugin in either tree; all V2 author/cook workflows (including the frame-snap Live Link handoff in §17.2) run through it. V2 runtime-dependent surfaces stay gated by the @oshun/config feature flags ENABLE_V2_BELLONA_RUNTIME_HOT_RELOAD, ENABLE_V2_BELLONA_RUNTIME_ASSET_IMPORT, and ENABLE_V2_BELLONA_LIVE_COSMETIC_DELIVERY (all default false in libs/shared/config/src/features.ts).

Planned scope: a runtime UE module (no editor-only dependencies) that ships in cooked V2 builds for runtime hot-reload of Bellona-cooked artifacts, ad-hoc runtime asset import on non-rollback surfaces, live cosmetic delivery, and provenance metadata handoff — each gated behind the corresponding feature flag above until the Bellona Runtime Integrations team marks the plugin production-ready.

17.2 Aja frame-snap Live Link#

• Task ID: BELLONA-MOCAP-V2-FRAME-SNAP-001

This task is implemented in @bellona/mocap under src/frame-snap/. That module defines:

• Constants BELLONA_MOCAP_FRAME_SNAP_ROUTE (@aja -> @bellona/mocap -> @bellona/unreal), BELLONA_MOCAP_FRAME_SNAP_TARGET_FPS (60), and BELLONA_MOCAP_FRAME_SNAP_TOLERANCE_SECONDS (0.0005).
• Types BellonaFrameSnapClip, BellonaFrameSnapNotifySegmentKind, BellonaFrameSnapNotifySegmentInput, BellonaFrameSnapNotifySegment, BellonaFrameSnapExportRequest, BellonaFrameSnapLiveLinkManifest (with BellonaFrameSnapManifestClip, BellonaFrameSnapManifestFramePolicy, BellonaFrameSnapManifestLiveLink, BellonaFrameSnapManifestQualityGates), and the BellonaFrameSnapError class.
• Functions createBellonaFrameSnapLiveLinkExport, normalizeBellonaNotifySegments, snapBellonaSecondsToFrame.

@bellona/mocap resamples Aja-retargeted skeleton clips to 60 Hz, assigns integer frame numbers, normalizes notify segments to integer 60 Hz boundaries, and rejects sub-frame segments. @bellona/unreal receives the editor-only Live Link handoff for import/cook.

The contract route, written with the canonical arrow notation used by the V2 docs, is @aja → @bellona/mocap → @bellona/unreal. Every notify segment carries alignment: 'integer-60hz-frame-boundaries', so the manifest's gameplay windows land on deterministic integer frames. The V2 consumer of this manifest is @v2/aja-bellona-livelink-export (Aja spec §11A.1).

Like the rest of the V2 Bellona surface, this path is author/cook-time only: the manifest sets runtimeLiveLinkPluginRequired: false, the handoff is editorOnlyHandoff, and runtime Live Link plugins remain disabled in shipped V2 builds. Gameplay runs against the cooked, frame-snapped AnimSequence, not a live Link stream — consistent with §17.1, where the runtime plugin is gated until BellonaUnrealRuntime ships.

18. Acceptance Criteria#

The Bellona domain meets its specification when all of the following conditions hold. Each criterion maps directly to a testable behavior.

1. The Prisma schema migrates cleanly via prisma migrate dev / prisma migrate deploy, producing the 11 documented tables with the documented indexes and constraints.
2. @bellona/build-api initialize() stands up the build cache, the Redis job queues (or the in-memory fallback when REDIS_URL is unset), and the four cross-domain event subscriptions; getHealthStatus() reports healthy.
3. The build-worker priority queue dequeues jobs by priority and dispatches each JobType to its dedicated worker module.
4. Each of the four bridge apps starts a bridge-core WebSocket server on its documented port and registers handshake, ping, and the engine-specific command set (6 / 9 / 11 / 14 commands).
5. bridge-blender publishes bellona.session.started / bellona.session.ended on connect / disconnect.
6. @bellona/event-publisher publishes the eight bellona.* events with payloads conforming to the @oshun/contracts Zod schemas, over the Redis-backed event bus.
7. @bellona/event-handlers consumes hathor.world.published, isis.asset.generated, yemaya.build.requested, and yemaya.export.requested, enqueueing builds/exports.
8. The bellona CLI exposes the seven documented commands.
9. The interchange pipeline imports, validates, transforms, and exports the 13 AssetFormat values per its export-capability matrix.