@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.readyhathor.world.publishedisis.asset.generatedisis.asset.cookedbellona.artifact.cookedmaat.balance.recommendationkuanyin.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-busfor subscriptions.@oshun/identityfor service/admin authorization checks.@oshun/audit-platformfor append-only adapter audit records.@oshun/data-residencyfor residency-zone normalization from event metadata.@oshun/config/featuresfeature flags, includingENABLE_V2_OSHUN_ADAPTER.@oshun/loggingfor structured adapter logs.@oshun/metricsfor Prometheus counters and handler-duration histograms.@oshun/tracingfor consumer spans around handler execution.
The adapter does not define local replacements for these platform surfaces.