@seriousgaming/sdk 0.0.0-stage → 1.0.0-alpha.1

package/lib/build/signatures.d.ts

@@ -0,0 +1,372 @@
+import { Participant, SignatureCallbacks } from './callbacks.js';
+import type { ContextDeletePath } from './context-merge.js';
+import type { GameTeamMode } from './resource-schema.js';
+/**
+ * Which kind of run a function is executing in.
+ *
+ * `'session'` is the game being played. `'walkthrough'` is a disposable run
+ * alongside it, used to demonstrate the game before or during play: one team,
+ * one participant, always from tick 0, isolated from the session it sits
+ * beside.
+ *
+ * A walkthrough is a solo run of something built for a group. Logic may use
+ * this to synthesise the social context that is genuinely absent (other teams
+ * on a leaderboard, teammates in a presence list), and to suppress spoilers and
+ * side effects. It must not change the mechanics of the team being driven: a
+ * walkthrough that plays differently teaches the wrong game.
+ */
+export type RunKind = 'session' | 'walkthrough';
+/**
+ * How a session runs its teams (§5.2): the game's `teams.mode`.
+ *
+ * Only the two the game declares, and no third for a session that happens to
+ * hold one team: §20.1 admits only these, and a one-team session is read off
+ * `teams.length`, not off the mode.
+ */
+export type SessionMode = GameTeamMode;
+/**
+ * Which viewer a player surface is being rendered for (§13.3).
+ *
+ * - `'participant'`: a team member who joined the session. Has a caller
+ *   identity and appears in the team roster.
+ * - `'observer'`: a facilitator peeking at a team's live player surface without
+ *   joining. Has no caller identity and is absent from the roster and
+ *   presence. Still sees the live surface and, on a permissive host, may
+ *   drive it.
+ */
+export type ViewerRole = 'participant' | 'observer';
+/**
+ * The facts true of the whole run, delivered to every call into game logic
+ * whether it runs inside the tick loop or outside it.
+ *
+ * {@link RunMeta} adds the tick for logic that runs as part of one. Hooks,
+ * endpoints and validators receive this shape alone: none of them runs as part
+ * of a tick, so there is no tick being executed to name.
+ */
+export interface LogicMeta {
+    /**
+     * The active session locale (e.g. 'en', 'ar'). Session-wide, not per
+     * participant: every participant in a session shares one locale. Use it
+     * when generating prose (for example via `callbacks.generateText`) that
+     * should be produced in the session's language.
+     */
+    locale: string;
+    /**
+     * A session-wide random seed, stable for the life of the session and across
+     * a re-run of the same tick.
+     *
+     * Logic functions may be invoked more than once for one logical tick, so a
+     * live `Math.random()` is unsafe: two runs of the same tick disagree and
+     * only the last is durable.
+     *
+     * Derive instead. {@link deriveSeed} combines this with whatever identifies
+     * the thing being seeded, and {@link seededRandom} turns the result into a
+     * generator:
+     *
+     * ```ts
+     * const random = seededRandom(deriveSeed(meta.seed, meta.index, 'opening-hand'));
+     * ```
+     *
+     * Freeze a derived value into context if later ticks need the same one,
+     * rather than re-deriving it from parts that may have changed.
+     */
+    seed: string;
+    /**
+     * Whether this is the game being played or a walkthrough beside it.
+     *
+     * Host-supplied and identical on every surface of one run, so a decision
+     * the engine takes on it and a decision a user interface takes on it cannot
+     * disagree. A host that predates walkthroughs reports `'session'`, which is
+     * also the value every existing game behaves correctly on.
+     *
+     * ```ts
+     * const rivals = meta.runKind === 'walkthrough'
+     *     ? demonstrationRivals(meta.seed)
+     *     : context.market.rivals;
+     * ```
+     */
+    runKind: RunKind;
+    /**
+     * When this operation started, in milliseconds since the epoch: the tick,
+     * the hook dispatch, the endpoint call or the validator run this call is
+     * part of. Fixed by the host before the first logic call of the operation,
+     * so every call in it (every team's `Run` in one tick, and the tick
+     * controller after it) reads the same value, and a re-run of the same
+     * operation reads it again.
+     *
+     * Use it instead of `Date.now()`, which differs between a tick and its
+     * re-run and is not offered by every runtime (§3.2):
+     *
+     * ```ts
+     * const placedAt = meta.now;
+     * const ageMs = meta.now - context.orders.PlacedAt;
+     * ```
+     *
+     * Freeze it into context if a later operation needs the same instant.
+     */
+    now: number;
+}
+/**
+ * `meta` for logic that runs as part of a tick: the engine's `Init` and `Run`,
+ * the aggregate forms of both, and tick-controller logic.
+ */
+export interface RunMeta extends LogicMeta {
+    /**
+     * The tick being executed, resolved before the function runs: `0` in
+     * `Init`, and 1-based in `Run`, so the first `Run` of a session sees `1`
+     * and the last `Run` of a `ticks: 10` game sees `10`.
+     *
+     * Deliberately one ahead of the `completedTicks` a user interface reads,
+     * which counts the ticks already completed (§9.3).
+     */
+    tick: number;
+}
+/**
+ * `meta` for a function that runs against one team's context: `Init`, `Run`,
+ * and tick-controller logic.
+ *
+ * The rule is one sentence: **`teamId` and `index` name the team whose context
+ * is in `context`.** In independent mode that is the team being ticked. In
+ * shared-state mode the tick controller runs once for the session with team 0's
+ * context, so it reads team 0's identity, which is what it was given.
+ *
+ * `RunAggregate` and `InitAggregate` receive plain {@link RunMeta}: they run
+ * across every team at once, so there is no single team to name, and each
+ * team's identity is already on its entry in `teams`.
+ */
+export interface TeamRunMeta extends RunMeta {
+    /**
+     * The team this call is running for, e.g. `'team-1'`. The same identifier
+     * `RunAggregate` sees in its `teams` array, and the same one a session
+     * surface keys `SessionData` by. Opaque and stable for the session: never
+     * parse it or build one from an index, and key ordinal logic on `index`
+     * instead (§5.6). A single-team game's one team has an ordinary id too:
+     * one id space, so a value keyed off this in the engine can be looked up
+     * by a surface.
+     */
+    teamId: string;
+    /**
+     * The team's stable, session-lifetime index. Assigned at team creation
+     * (dense 0..N-1 at session start) and never reassigned: a removal leaves a
+     * gap, and a team added later takes the lowest unused index. Use it, not
+     * array position, to key anything per team.
+     */
+    index: number;
+}
+export interface LogicFunctionArgs<TContext, TSettings, TCallbacks = SignatureCallbacks> {
+    context: TContext;
+    /**
+     * The settings resources this resource declared in `settings`, keyed by
+     * identifier: resolved from their defaults, the active scenario and the
+     * session's overrides, and fixed when play starts (§8). Read-only.
+     */
+    settings: TSettings;
+    meta: TeamRunMeta;
+    /**
+     * The participants on the team this call is running for, taken when the
+     * operation started (§10.2). A tick controller sees the participants of
+     * every team in its `teams`. Read-only, and a copy per call, so changing
+     * it changes nothing: only a lifecycle operation (a join, a rename, a
+     * move) changes the roster.
+     *
+     * ```ts
+     * const present = participants.filter((p) => p.connected).length;
+     * ```
+     */
+    participants: readonly Readonly<Participant>[];
+    callbacks: TCallbacks;
+}
+/**
+ * What engine and hook logic returns: the state it writes, named by kind.
+ *
+ * `capabilities` is a patch over the context the function received, merged one
+ * level deep, exactly as the whole result was before it was wrapped. Naming the
+ * kind leaves room for other outputs beside it, and the runtime refuses any
+ * top-level key it does not know, so a result written in the old flat shape
+ * fails rather than losing its writes.
+ */
+export interface LogicResult<TContext> {
+    capabilities: TContext;
+    /**
+     * Paths to remove once `capabilities` is folded in, with the same rules as
+     * a UI's `deletes`: segments joined by `.` (`'orders.Open.o-17'`), or an
+     * array of segments where a key could contain a dot. A path that does not
+     * resolve is not an error. Each must sit under a capability the resource
+     * declares in `writes`; one under a capability it only reads fails the
+     * call. Use it to drop an entry from a keyed map without rebuilding the
+     * whole variable.
+     */
+    deletes?: ContextDeletePath[];
+}
+/**
+ * The arguments of the engine's own functions: everything logic receives, plus
+ * the engine's private memory.
+ *
+ * `state` is whatever the engine last returned under `state`, and `undefined`
+ * until it first returns one (so always in `Init`). The engine is its only
+ * writer and its only reader: no surface, hook, validator or endpoint ever
+ * sees it. It is snapshotted and rewound with the tick, so undo and reset put
+ * it back exactly as they put back capabilities.
+ */
+export interface EngineFunctionArgs<TContext, TSettings, TCallbacks = SignatureCallbacks, TState = never> extends LogicFunctionArgs<TContext, TSettings, TCallbacks> {
+    /**
+     * Optional in the type so a test calling `Run` directly need not pass it;
+     * the runtime always does, as `undefined` before the first write.
+     */
+    state?: TState;
+}
+/**
+ * What the engine's `Init` and `Run` return: the capabilities they write and,
+ * optionally, the engine's private memory.
+ *
+ * `state` replaces the previous state whole; leave it out to keep the previous
+ * one. It must be JSON-serialisable (plain objects, arrays, strings, finite
+ * numbers, booleans and `null`), which the runtime checks.
+ *
+ * Typed by `TState` rather than a schema: the engine is the only writer and the
+ * only reader, so the compiler checks it end to end.
+ */
+export interface EngineResult<TContext, TState = never> extends LogicResult<TContext> {
+    state?: TState;
+}
+export type InitializationFunction<TContext, TSettings, TCallbacks = SignatureCallbacks, TState = never> = (args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>) => Promise<EngineResult<TContext, TState>>;
+/**
+ * What the engine's `Run` returns: an {@link EngineResult}, plus whether the
+ * game is now over for this team.
+ */
+export interface RunResult<TContext, TState = never> extends EngineResult<TContext, TState> {
+    /**
+     * `true` ends the game for the team this call ran for: no further ticks,
+     * as a tick controller's `complete` does. Per team in independent mode;
+     * in shared-state mode one team's completion ends it for every team,
+     * because they share one clock. An undo of the completing tick clears it.
+     * `false` and absence are the same: completion cannot be withdrawn here.
+     */
+    complete?: boolean;
+}
+export type RunFunction<TContext, TSettings, TCallbacks = SignatureCallbacks, TState = never> = (args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>) => Promise<RunResult<TContext, TState>>;
+/**
+ * One step of an engine that splits its `Init` or `Run` into several functions.
+ *
+ * A step takes the engine's arguments and returns the next context, flat, so
+ * steps chain by passing one's output to the next; only the exported `Init` or
+ * `Run` wraps the final context in `{ capabilities }`, and returns any `state`.
+ * A step may read `state`; its type defaults to `unknown`, so a step that
+ * ignores it accepts whatever the engine keeps.
+ */
+export type StepFunction<TContext, TSettings, TCallbacks = SignatureCallbacks, TState = unknown> = (args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>) => Promise<TContext>;
+export interface TickControllerResult {
+    /** False disables automatic ticking: ticks are manual only. */
+    enabled: boolean;
+    /**
+     * Milliseconds until the next automatic tick, a whole number within the
+     * §11.8 bounds (30 seconds to 7 days). Needed when `enabled` is true and
+     * there is no `nextTickAt`; beside a `nextTickAt` it is only a display
+     * hint, and a controller with the timer off may leave it out.
+     */
+    intervalMs?: number;
+    /**
+     * When the next tick should fire (epoch milliseconds, UTC). When set and
+     * `enabled` is true, the runtime uses it instead of `intervalMs`. If it is
+     * in the past the runtime fires one tick immediately, then re-evaluates.
+     */
+    nextTickAt?: number;
+    /** When true, the game is permanently complete: no further ticks will be allowed. */
+    complete?: boolean;
+}
+export interface TickControllerFunctionArgs<TContext, TSettings, TCallbacks = SignatureCallbacks> extends LogicFunctionArgs<TContext, TSettings, TCallbacks> {
+    /**
+     * The teams this evaluation covers, sorted by stable index: every team in
+     * a shared-state game, the one team being evaluated in independent mode,
+     * and the one team in a single-team game. Always present, so a controller
+     * can say which team it is waiting on by `teamId` or `index` even after a
+     * team has been removed and the indexes have a gap.
+     */
+    teams: AggregateFunctionTeam<TContext>[];
+    /**
+     * Whether the session's waiting room is currently open — players are seeing
+     * the game's waiting room UI instead of its game UIs.
+     *
+     * The flag pauses nothing by itself. A game that wants automatic ticks to
+     * stop while players wait returns `enabled: false` when this is true;
+     * a game whose simulation should keep advancing in the background ignores
+     * it. Deciding here rather than in the runtime keeps the policy with the
+     * author, who is the only one who knows which of the two their game is.
+     */
+    waitingRoomOpen: boolean;
+}
+export type GetTickControllerFunction<TContext, TSettings, TCallbacks = SignatureCallbacks> = (args: TickControllerFunctionArgs<TContext, TSettings, TCallbacks>) => Promise<TickControllerResult>;
+export interface AggregateFunctionTeam<TTeamContext, TTeamState = never> {
+    teamId: string;
+    /**
+     * Platform-assigned, session-stable team index. Assigned at team creation
+     * (dense 0..N-1 at session start) and never reassigned: removals leave a
+     * gap, later-added teams take the lowest unused index. The same team has
+     * the same index here, in the player teams context, and in the
+     * session teams context. `teams.defaultNames` entries are applied
+     * by this index.
+     */
+    index: number;
+    /**
+     * This team's context. For an aggregate engine function, its own
+     * capabilities (team and private scope): shared-scope capabilities are not
+     * repeated here, and arrive once, in `shared`. For a tick controller, the
+     * team's context as the controller's own `context` would hold it.
+     */
+    context: TTeamContext;
+    /** This team's engine state, as `Run` sees it (see {@link EngineFunctionArgs}). */
+    state?: TTeamState;
+}
+/**
+ * The session's shared store, as an aggregate function sees it: one value per
+ * shared-scope capability the engine declared, whatever the number of teams.
+ */
+export interface AggregateFunctionShared<TSharedContext, TSharedState = never> {
+    context: TSharedContext;
+    /**
+     * The engine's session-wide private memory: one value for the session,
+     * written under `shared.state` by an aggregate function in a shared-state
+     * or single-team session.
+     */
+    state?: TSharedState;
+}
+export interface RunAggregateFunctionArgs<TTeamContext, TSharedContext, TSettings, TCallbacks = SignatureCallbacks, TTeamState = never, TSharedState = never> {
+    shared: AggregateFunctionShared<TSharedContext, TSharedState>;
+    teams: AggregateFunctionTeam<TTeamContext, TTeamState>[];
+    /**
+     * The settings resources this resource declared in `settings`, keyed by
+     * identifier: resolved from their defaults, the active scenario and the
+     * session's overrides, and fixed when play starts (§8). Read-only.
+     */
+    settings: TSettings;
+    meta: RunMeta;
+    /**
+     * The participants of every team in `teams`, taken when the operation
+     * started (§10.2): every participant in the session whenever every team
+     * is passed. Group by `teamId` to join them to their team. Read-only.
+     */
+    participants: readonly Readonly<Participant>[];
+    callbacks: TCallbacks;
+}
+/**
+ * An aggregate engine's result. Each level names what it writes the same way a
+ * team's `Run` does: every `teams` entry has the shape of a `Run` result, in
+ * the order the teams were passed, and `shared` carries the session's
+ * shared-scope capabilities. A shared capability is written through `shared`
+ * alone; one in a `teams` entry fails the call.
+ */
+export interface RunAggregateResult<TTeamContext, TSharedContext, TTeamState = never, TSharedState = never> {
+    shared: EngineResult<Partial<TSharedContext>, TSharedState>;
+    teams: EngineResult<TTeamContext, TTeamState>[];
+}
+/**
+ * `RunAggregate`'s result: each level may also report completion, as `Run`'s
+ * `complete` does. A `teams` entry's ends the game for that team; `shared`'s
+ * for every team at once.
+ */
+export interface RunAggregateTickResult<TTeamContext, TSharedContext, TTeamState = never, TSharedState = never> {
+    shared: RunResult<Partial<TSharedContext>, TSharedState>;
+    teams: RunResult<TTeamContext, TTeamState>[];
+}
+export type RunAggregateFunction<TTeamContext, TSharedContext, TSettings, TCallbacks = SignatureCallbacks, TTeamState = never, TSharedState = never> = (args: RunAggregateFunctionArgs<TTeamContext, TSharedContext, TSettings, TCallbacks, TTeamState, TSharedState>) => Promise<RunAggregateTickResult<TTeamContext, TSharedContext, TTeamState, TSharedState>>;
+export type InitAggregateFunction<TTeamContext, TSharedContext, TSettings, TCallbacks = SignatureCallbacks, TTeamState = never, TSharedState = never> = (args: RunAggregateFunctionArgs<TTeamContext, TSharedContext, TSettings, TCallbacks, TTeamState, TSharedState>) => Promise<RunAggregateResult<TTeamContext, TSharedContext, TTeamState, TSharedState>>;

package/lib/build/signatures.js

@@ -0,0 +1 @@
+export {};

package/lib/build/speech.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Speech Generation Types
+ *
+ * Provides provider-agnostic text-to-speech for the engine, hooks, tick controllers
+ * and user interfaces. Game code describes the utterance via a small set of
+ * role-based voice presets; the runtime decides which provider, model and
+ * voice executes the call. The synthesised audio is persisted as a blob and
+ * the returned asset reference (`blob:<id>`) can be played from a UI
+ * (`getAssetUrl`) or read in the engine (`readAsset`).
+ */
+import type { LLMTier } from './llm.js';
+/**
+ * Role-based voice preset. The runtime maps the preset to a concrete provider
+ * voice. Game code only ever passes the preset name. The five values below are
+ * the recommended starting set; runtimes may accept additional preset names.
+ *
+ * - `neutral`   — warm, balanced, unobtrusive
+ * - `narrator`  — engaging, gravitas, draws the listener in
+ * - `announcer` — clear, authoritative, broadcast-style
+ * - `executive` — confident, weighty, commands attention
+ * - `coach`     — encouraging, warm, reassuring
+ *
+ * If a requested preset is not configured, the runtime falls back to
+ * `neutral`; if that is also unconfigured, it falls back to the provider's
+ * own default voice.
+ */
+export type GenerateSpeechVoice = 'neutral' | 'narrator' | 'announcer' | 'executive' | 'coach';
+/**
+ * Audio container format for synthesised speech.
+ */
+export type GenerateSpeechFormat = 'mp3' | 'wav' | 'opus';
+/**
+ * Options for synthesising speech.
+ */
+export interface GenerateSpeechRequest {
+    /**
+     * The text to read aloud. Plain text — SSML and provider-specific tags
+     * are intentionally not supported in v1.
+     */
+    text: string;
+    /**
+     * Voice preset name. Defaults to `'neutral'`. See {@link GenerateSpeechVoice}.
+     * Any string is accepted; unknown presets fall back to `neutral`.
+     */
+    voice?: GenerateSpeechVoice | string;
+    /**
+     * Capability tier (`quick` / `standard` / `expert`). Mirrors {@link LLMTier};
+     * the runtime maps each tier to a provider model. Defaults to `'quick'`.
+     */
+    tier?: LLMTier;
+    /**
+     * Output audio container. Defaults to `'mp3'`.
+     */
+    format?: GenerateSpeechFormat;
+    /**
+     * Optional BCP-47 language hint (e.g. `'en-GB'`, `'fr-FR'`). Advisory; the
+     * provider may ignore it.
+     */
+    languageHint?: string;
+    /**
+     * Playback speed multiplier in the range `0.5` to `2.0`. The runtime
+     * clamps to whatever range the configured provider supports.
+     */
+    speed?: number;
+}
+/**
+ * Response from a speech-synthesis call. The audio bytes are persisted as a
+ * blob; play them from a UI via `<audio src={callbacks.getAssetUrl(reference)} />`
+ * or read the raw bytes in the engine via `callbacks.readAsset(reference)`.
+ */
+export interface GenerateSpeechResponse {
+    /**
+     * Asset reference for the synthesised audio, of the form `blob:<id>`.
+     * Resolve via `getAssetUrl` (UI) or `readAsset` (engine).
+     */
+    reference: string;
+    /**
+     * MIME type of the audio (e.g. `'audio/mpeg'`, `'audio/wav'`, `'audio/ogg'`).
+     */
+    mimeType: string;
+    /**
+     * Best-effort audio duration in milliseconds. Not all providers return this.
+     */
+    durationMs?: number;
+    /**
+     * Number of characters the provider billed for this synthesis. Useful for
+     * observability and budgeting.
+     */
+    charactersBilled?: number;
+}
+/**
+ * Function for synthesising speech.
+ *
+ * Can be called with a bare string (shorthand for `{ text: '...' }`) or a
+ * full options object:
+ *
+ * ```typescript
+ * await callbacks.generateSpeech('Welcome to the simulation.');
+ * await callbacks.generateSpeech({ text: '...', voice: 'narrator' });
+ * ```
+ */
+export type GenerateSpeechFunction = (request: GenerateSpeechRequest | string) => Promise<GenerateSpeechResponse>;

package/lib/build/speech.js

@@ -0,0 +1,11 @@
+/**
+ * Speech Generation Types
+ *
+ * Provides provider-agnostic text-to-speech for the engine, hooks, tick controllers
+ * and user interfaces. Game code describes the utterance via a small set of
+ * role-based voice presets; the runtime decides which provider, model and
+ * voice executes the call. The synthesised audio is persisted as a blob and
+ * the returned asset reference (`blob:<id>`) can be played from a UI
+ * (`getAssetUrl`) or read in the engine (`readAsset`).
+ */
+export {};

package/lib/build/tick-validation.d.ts

@@ -0,0 +1,23 @@
+import type { TickControllerResult } from './signatures.js';
+/**
+ * Options for {@link validateTickControllerResult}.
+ */
+export interface ValidateTickResultOptions {
+    /**
+     * Override for "now" in ms since epoch, used to evaluate the effective
+     * cadence of a scheduled (`nextTickAt`) result. Defaults to `Date.now()`.
+     */
+    now?: number;
+}
+/**
+ * Validate a runtime `TickControllerResult` against the §11.8–§11.9 contract.
+ *
+ * Returns `null` when the result is valid, or a human-readable error message
+ * that names the limit, cites SPECIFICATION.md §11, and points at the helper to
+ * use (never at an exported symbol). The message is suitable for surfacing to
+ * authors at authoring time, in the dev server, or in the build step.
+ *
+ * The builders in `scheduling.ts` call this, so an invalid result is refused
+ * at authoring time rather than at the first tick.
+ */
+export declare function validateTickControllerResult(result: Pick<TickControllerResult, 'intervalMs' | 'nextTickAt'>, options?: ValidateTickResultOptions): string | null;

package/lib/build/tick-validation.js

@@ -0,0 +1,96 @@
+/**
+ * Effective tick interval bounds, derived from SPECIFICATION.md §11.8: every
+ * conformant runtime guarantees a 30-second floor and a 7-day ceiling on the
+ * *effective cadence* (the gap until the next automatic tick), not merely on
+ * the `intervalMs` display hint.
+ *
+ * These constants are deliberately module-private. Authors build valid results
+ * with `intervalTick()` / `scheduledTick()`, and the contract surface for
+ * runtime implementers is the spec, never an exported magic number.
+ *
+ * This module is internal to the SDK: it is what the builders validate with,
+ * and no entry point exports it. The runtime's copy lives in
+ * `@seriousgaming/sdk-tools/runtime`, and
+ * `tick-validation.parity.test.ts` there holds the two to one table of cases.
+ */
+const MIN_EFFECTIVE_TICK_INTERVAL_MS = 30_000;
+const MAX_EFFECTIVE_TICK_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000; // 604,800,000 (7 days)
+/**
+ * Validate a runtime `TickControllerResult` against the §11.8–§11.9 contract.
+ *
+ * Returns `null` when the result is valid, or a human-readable error message
+ * that names the limit, cites SPECIFICATION.md §11, and points at the helper to
+ * use (never at an exported symbol). The message is suitable for surfacing to
+ * authors at authoring time, in the dev server, or in the build step.
+ *
+ * The builders in `scheduling.ts` call this, so an invalid result is refused
+ * at authoring time rather than at the first tick.
+ */
+export function validateTickControllerResult(result, options) {
+    const { intervalMs, nextTickAt } = result;
+    if (nextTickAt !== undefined &&
+        (typeof nextTickAt !== 'number' || !Number.isFinite(nextTickAt))) {
+        return (`Tick controller nextTickAt must be a finite timestamp in milliseconds; got ${describe(nextTickAt)}. ` +
+            `See the tick controller guide.`);
+    }
+    const now = options?.now ?? Date.now();
+    // The effective cadence is the gap the runtime will actually schedule:
+    // nextTickAt − now in scheduled mode, intervalMs in interval mode (§11.8).
+    const effectiveMs = nextTickAt !== undefined ? nextTickAt - now : (intervalMs ?? NaN);
+    // A nextTickAt at or in the past yields a 0 delay: firing one immediate
+    // catch-up tick is explicitly allowed and exempt from both the floor and the
+    // intervalMs shape rule, since `intervalMs` is only a display hint here
+    // (§11.8/§11.3). The tick controller re-evaluates after the catch-up fires.
+    if (nextTickAt !== undefined && effectiveMs <= 0) {
+        return null;
+    }
+    // Beside a nextTickAt, intervalMs is a display hint and may be absent; when
+    // it is there it is held to the same shape as in interval mode.
+    if ((nextTickAt === undefined || intervalMs !== undefined) &&
+        (typeof intervalMs !== 'number' ||
+            !Number.isFinite(intervalMs) ||
+            !Number.isInteger(intervalMs) ||
+            intervalMs < 1)) {
+        return (`Tick intervalMs must be a finite, positive, whole number of milliseconds; got ${describe(intervalMs)}. ` +
+            `Build interval-based results with intervalTick(intervalMs). See the tick controller guide.`);
+    }
+    if (effectiveMs < MIN_EFFECTIVE_TICK_INTERVAL_MS) {
+        return (`Effective tick cadence of ${duration(effectiveMs)} is below the 30-second minimum ` +
+            `(${MIN_EFFECTIVE_TICK_INTERVAL_MS} ms). Use intervalTick(intervalMs) with at least ` +
+            `${MIN_EFFECTIVE_TICK_INTERVAL_MS}, or schedule nextTickAt further out. See the tick controller guide.`);
+    }
+    if (effectiveMs > MAX_EFFECTIVE_TICK_INTERVAL_MS) {
+        return (`Effective tick cadence of ${duration(effectiveMs)} exceeds the 7-day maximum ` +
+            `(${MAX_EFFECTIVE_TICK_INTERVAL_MS} ms). For longer gaps, set enabled: false and ` +
+            `drive ticks by another means. See the tick controller guide.`);
+    }
+    return null;
+}
+function describe(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'number') {
+        if (Number.isNaN(value))
+            return 'NaN';
+        if (!Number.isFinite(value))
+            return value > 0 ? 'Infinity' : '-Infinity';
+        return String(value);
+    }
+    return typeof value;
+}
+/** `12000 ms (12 seconds)`: the field's own unit, then a reading of it. */
+function duration(ms) {
+    const rounded = Number.isInteger(ms) ? String(ms) : ms.toFixed(1);
+    const seconds = ms / 1000;
+    const human = seconds >= 86_400
+        ? `${round(seconds / 86_400)} days`
+        : seconds >= 3_600
+            ? `${round(seconds / 3_600)} hours`
+            : seconds >= 1
+                ? `${round(seconds)} seconds`
+                : 'under a second';
+    return `${rounded} ms (${human})`;
+}
+function round(value) {
+    return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}