# V2 Oshun Adapter

`@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.