Eve library

V2 Oshun Adapter

Other

Revision 1

On this page

@v2/oshun-adapter is the Node-side adapter that lets V2 react to approved Oshun event-bus messages without letting network output enter deterministic gameplay simulation.

Subscriptions#

The adapter registers exact @oshun/event-bus subscriptions for:

  • hathor.dialogue.ready
  • hathor.world.published
  • isis.asset.generated
  • isis.asset.cooked
  • bellona.artifact.cooked
  • maat.balance.recommendation
  • kuanyin.action.taken

Each handler validates the incoming payload before it crosses the V2 boundary. Accepted events become V2OshunReactionEnvelope records with deterministicGameplay: false and sideChannel: "v2-services.non-deterministic". The Unreal runtime can consume those records for UI, content import, narrative availability, or moderation surfaces, but rollback and frame simulation must continue to ignore them.

bellona.artifact.cooked events are only actionable when their payload tags include at least one v2.* tag. Accepted Bellona reactions include an unreal.asset.reimport request for the cooked Content/Generated/ asset so the editor-side cook bridge can reimport changed .uasset / .umap outputs. Bellona artifacts for other games or shared packages are acknowledged without enqueueing a V2 reaction.

isis.asset.generated events are only actionable when their tags begin with v2.cosmetic., v2.stage., or v2.decal.. Accepted Isis reactions enqueue a bellona.cook.enqueue request for @bellona/unreal, target Content/Generated/Isis, preserve Isis provenance, and keep the request rollbackSafe: true. Before a V2 shipping asset can reach that cook request, the payload must include a passed v2.isis.generated-asset.shipping-quality-gate attestation for the exact source contentHash. The gate is launch-blocking and requires package results from @isis/anomaly-detection, @themis/music-shield, @themis/visual-shield, @themis/text-shield, @themis/video-shield, @themis/design-shield, and @kuanyin/precognition. Missing, failed, blocked, or planned_unavailable results are dead-lettered before Bellona cook can accept the asset. Generated Isis assets for other products are acknowledged without enqueueing a V2 reaction.

hathor.world.published events enqueue a hathor.loreCompiler.exportDataTables request for @hathor/lore-compiler. The request targets /Game/V2/Generated/Hathor and carries only the immutable world id, SHA-256 version hash, source event id, and publication URI needed to compile V2 datatables. Publication metadata can remain on the non-deterministic side-channel payload for authoring/audit use, but it is excluded from the rollback-safe compiler request and gameplay world refs.

Failure Behavior#

Malformed payloads are sent to the event-bus dead-letter path with a validation summary and are not acknowledged as successful work.

If the V2 reaction sink is unavailable, the handler calls nack() with the configured retry delay and does not acknowledge the event. This leaves the event eligible for replay once the sink is healthy again.

Successful handling enqueues one V2 reaction envelope and then calls ack().

Shared Platform Wiring#

The adapter depends on the shared Oshun packages from the first commit of this service surface:

  • @oshun/event-bus for subscriptions.
  • @oshun/identity for service/admin authorization checks.
  • @oshun/audit-platform for append-only adapter audit records.
  • @oshun/data-residency for residency-zone normalization from event metadata.
  • @oshun/config/features feature flags, including ENABLE_V2_OSHUN_ADAPTER.
  • @oshun/logging for structured adapter logs.
  • @oshun/metrics for Prometheus counters and handler-duration histograms.
  • @oshun/tracing for consumer spans around handler execution.

The adapter does not define local replacements for these platform surfaces.