Bundle Quickstart

Historia's trusted bundle hosts the game runtime and workflow engine. Creators customize the typed workflows it executes; they do not author lifecycle handlers or use the substrate runtime SDK.

Build behavior in workflows

Creators author typed workflow generators in the Workflow Editor. A workflow receives a trigger-specific context, yields only the commands offered by its module, and resumes with each command result. Start with the current generated default rather than recreating entry points or command schemas from documentation.

Workflow code does not access substrate state, persistence, process globals, timers, provider credentials, or background tasks. Use injected deterministic helpers and yield typed executor commands for every effect.

Host and game seam

The current product composes platform and game UI in-process through GameToPlatformCommand, which today runs one way: the game reports, the platform presents. That TypeScript contract is intentionally not an iframe wire protocol. Persisted or transport-crossing values still use strict versioned data contracts, including SystemCard v1; a future iframe transport would additionally require runtime decoders, origin checks, handshake/version negotiation, correlation, and timeouts.

The ownership split is strict:

• the platform owns connection and participation state, moderation standing, billing and AI settings, settings modals, terminal overlays, and other host chrome;
• the game owns map, chat, actions, advisor gameplay, and typed requests across the seam;
• the game cannot pass callbacks or arbitrary UI instructions to the platform.

SystemActionRef is a closed allowlist: retryTask, openAiSettings, or openBilling. openAiSettings and openBilling are settings intents resolved by the platform host; they do not grant modal or account access to game code. retryTask is a request, not execution: the host sends the opaque task key back to the game host, which validates it against a durable failure before invoking an existing retry primitive. Unknown versions, action names, tabs, and extra fields fail strict boundary validation.

Call platform capabilities through typed commands

Workflows do not receive provider credentials, direct database access, or the substrate context. Yield the typed command offered by the current workflow module. The trusted Historia bundle maps that command onto the platform gateway and validates the service result before gameplay consumes it.

Local build loop

1. Change the smallest relevant workflow function while preserving its generated entry points.
2. Run npm run generate:default-workflows after workflow source or contract changes.
3. From backend/, run pnpm typecheck (every workspace project, the creator workflow sources, and the bundle) and pnpm typecheck:tests (the bundle's tests, which are checked under their own project). Then pnpm --filter @pax-backend/bundle-historia-default build.
4. Run pnpm validate-workflows plus focused behavioral tests.
5. Seed the local substrate and exercise the changed workflow or gateway call end to end.

Source contracts

• bundle manifest
• bundle entry point
• workflow engine contract
• generated workflow manifest
• typed in-process host/game commands
• versioned SystemCard and closed actions