Gateway and Public Services

Transport envelope

Platform capabilities are URL services invoked through c.api.invoke or c.api.invokeStream. Historia exposes those methods as gameCtx.apiInvoke and gameCtx.apiInvokeStream.

const invoke = await gameCtx.apiInvoke(kind, args, options);
if (!invoke.ok) throw new Error(`gateway transport failed: ${invoke.error}`);
const businessResult = validateServiceResult(invoke.result);

invoke.ok reports gateway transport delivery. Only after it is true does invoke.result contain the service's business envelope. Retain the transport envelope, branch on invoke.ok, read business data only from invoke.result, and pass that value through the service's canonical strict result validator. A business { ok: false, ... } result can arrive through a successful transport.

Trusted context

The gateway authenticates the bundle and stamps game identity, bundle identity, triggering session claims, run/trace context, and any idempotency key. Do not duplicate trusted fields such as gameId in creator-controlled arguments. Services strictly validate the remaining arguments.

AI-family services require deterministic attempt identity. Redelivery with the same identity and request replays or reattaches; the same identity with changed arguments fails. A deliberate retry uses a new identity and explicit lineage.

Supported creator services

• ai.chat.v1 — platform-resolved AI slots, normalized tools, and explicit retry lineage.
• compress.v1 — strict text-in/summary-out compression.
• compress.v2 — type-aware compression with retention metadata.

The explicit public service manifest is the authority for this list.

Public versus host-internal services

Local development registers additional URL-service routes used by the first-party host and Historia bundle. The seed script is deployment plumbing, not public API authority. A route existing in the repository also does not make it creator-supported.

In particular, translate.v1 has a local-development registration but no production registration declared in this repository, so it is not in the public manifest or creator reference. The same rule applies to moderation, settings, participation, projection, flag-search, billing, catalog, and advisor-capability routes: creators must not invoke them directly. This docs change does not provision or register any service.

Bundles never call provider endpoints directly and never receive platform credentials.