PolyhydraGames.Eventing.Streaming 0.1.0-preview.158

polyhydra-eventing

Shared Polyhydra event contracts, envelopes, routing primitives, and event-wall integration prototypes.

PostOffice for delivery. Events for facts. Event Wall for visibility.

This repository captures the cross-application eventing layer for ChannelCheevos-adjacent systems including channel-cheevos, cc-sidecar, twitch-relay, and dev-forge.

Provider libraries can pin the PolyhydraGames.Eventing.Conformance package and run ProviderConformanceSuite.Run against their registration and sample events. The public ProviderConformanceInput accepts canonical Eventing registrations, envelope JSON, command pairs, schema catalog entries, and a health/capability projection. See the provider portfolio and language-neutral conformance fixtures.

The core idea is to keep strong types inside each application boundary while using strongly structured contracts across process, language, and app boundaries.

Starting direction

• C# first, because the current Polyhydra and ChannelCheevos ecosystem tends that way.
• JSON-schema friendly, so TypeScript, shell tools, dashboards, and sidecars can participate later.
• Additive to existing PostOffice / mailbox patterns rather than a hard replacement.
• Event keys are stable routing identities; payloads carry dynamic data.

Concepts

Eventing v1 uses one stable wire contract across local, test, staging, and production deployments. Environments are isolated instances with distinct credentials and event stores; applications own their payload shapes and domain behavior. See ADR 0004 for the compatibility and isolation rules.

Event key

Canonical format:

<producer>:<domain>:<entity>:<action>

Examples:

channel-cheevos:auth:user:logged-in
channel-cheevos:context:streamer:missing
twitch-relay:eventsub:reward:redeemed
cc-sidecar:overlay:widget:shown
dev-forge:event-wall:event:received

Rules:

• lowercase
• kebab-case segments
• exactly four segments
• event actions should be past tense when possible
• no IDs, display names, secrets, or arbitrary runtime values in the key
• dynamic values belong in the payload or metadata

Event envelope

The envelope answers:

What happened, where did it happen, who emitted it, and who might care?

PostOffice relationship

The older mailbox/envelope model is still useful for delivery-oriented flows.

• PostOffice asks: where should this message go?
• Eventing asks: what happened?
• Event Wall asks: how do we see, debug, and route what happened?

Repository layout

src/
  PolyhydraGames.Eventing.Abstractions/
    Contracts/
    Routing/
    PolyhydraGames.Eventing.Abstractions.csproj
  PolyhydraGames.Eventing.Ikemen/
    Payloads/
    PolyhydraGames.Eventing.Ikemen.csproj

tests/
  PolyhydraGames.Eventing.Ikemen.Tests/

docs/
  architecture/
  adr/
  examples/

Package boundaries

• PolyhydraGames.Eventing.Abstractions is the game-agnostic core. It owns envelopes, keys, addresses, severity, and routing interfaces.
• PolyhydraGames.Eventing.Ikemen is the Ikemen/LiveLancero dialect. It owns Ikemen-specific event key constants and payload contracts without polluting the core abstractions package.

Registry model

The shared registry model is documented in docs/architecture/registry-architecture.md. It defines app registrations, produced/consumed capabilities, schema descriptors, exact compatibility matching, and payload validation boundaries.

Typed packages are optional SDKs over the same string/schema runtime contract. See docs/examples/optional-sdk-pattern.md for the typed helper and raw JSON shapes side by side.

Ecosystem activity goals

The repository-level goals for safely projecting activity from independent Polyhydra products into diagnostics, ChannelCheevos, achievements, and presentation surfaces are documented in docs/architecture/ecosystem-activity-goals.md. They cover privacy, ordering, replay, idempotent side effects, derived interpretations, theatrical narration, and a bounded synthetic compatibility fixture. The existing provider interoperability checklist remains in docs/capabilities/interop-edge-cases.md.

Current status

Seed project. The first implementation target is a small contracts package with tests and examples before wiring this into ChannelCheevos, cc-sidecar, twitch-relay, or Dev-Forge. The first domain extension package is PolyhydraGames.Eventing.Ikemen.

Validation

Run the full local validation path with:

dotnet restore PolyhydraGames.Eventing.slnx --ignore-failed-sources -p:NuGetAudit=false
dotnet build PolyhydraGames.Eventing.slnx --configuration Release --no-restore
dotnet test PolyhydraGames.Eventing.slnx \
  --configuration Release \
  --no-build \
  --collect:"XPlat Code Coverage"

The GitHub Actions workflow runs the same build/test path, uploads TRX and Cobertura coverage artifacts, packs the libraries, verifies them from a clean consumer, and can publish packages on tags or explicit manual dispatch.

NuGet publishing

The CI workflow packs these nuget.org-ready libraries:

• PolyhydraGames.Eventing.Abstractions
• PolyhydraGames.Eventing.ExchangeCore
• PolyhydraGames.Eventing.Ikemen
• PolyhydraGames.Eventing.InMemory
• PolyhydraGames.Eventing.Sqlite

Stable package publishes run on v* tags and target NuGet.org. Manual dispatches can publish an explicitly prerelease package_version to the organization GitHub Packages feed; stable versions are rejected from that manual/private channel. Packages and SHA-256 checksums are retained as workflow evidence.

nuget.org publishing uses Trusted Publishing. Configure a nuget.org policy with:

• Repository Owner: Polyhydra-Games
• Repository: polyhydra-eventing
• Workflow File: ci.yml

If the nuget.org Trusted Publishing policy creator username differs from the GitHub repository owner, set a repository variable named NUGET_USER to the nuget.org policy creator username.

Host image publishing

Every published host image receives the full source commit as an immutable tag. main also advances latest, while v* releases receive the Git tag as an additional immutable release pointer. The workflow retains the resolved tags and pushed OCI digest as an image-provenance artifact for deployment and rollback records.

Observability

Seq logging is optional for the ASP.NET Core host. Set SEQ_URL or SEQ_ADDRESS to the Seq ingestion endpoint, and set SEQ_API_KEY only when the target Seq instance requires one.

Host authorization

The host fails startup outside an explicit local fixture boundary unless its JWT contract is complete. Configure these non-secret settings through the deployment environment:

• Auth__Enabled=true
• Auth__Authority — issuer owned by the identity-provider operator
• Auth__Audience — Eventing resource audience owned by the service operator

Scopes are deliberately separate: eventing.producer writes events, eventing.reader reads Event Wall projections, and eventing.registry-admin manages registry and schema routes. /health and the data-free /debug/events authentication shell are anonymous; every event, registry, and schema data route still requires its corresponding scope. Auth__AllowUnauthenticatedLocal=true is accepted only in Development or Testing; it is an explicit local-fixture opt-in and never a production fallback. Consumer migration, issuer provisioning, and deployment are separate operations.

Publish-Readiness Smoke

Run a deterministic host-level smoke from a single entrypoint:

bash scripts/verify-eventing-smoke.sh

Artifacts are written to artifacts/eventing-smoke/. The script is safe to run repeatedly on the same checkout and does not persist host state.