@bitcobblers/wod-wiki-lang 0.1.0

package/dist/browserRuntimeNow-SxxdmtB7.d.cts

@@ -0,0 +1,2350 @@
+import { ICodeStatement, ParseError, MetricContainer, IMetric, BlockKey, TimeSpan as TimeSpan$1, OutputStatementType, MetricType, IOutputStatement, MetricOrigin } from '@bitcobblers/wod-wiki-core';
+
+interface IScript {
+    source: string;
+    statements: ICodeStatement[];
+    errors?: ParseError[] | undefined;
+    getIds(ids: number[]): ICodeStatement[];
+    getId(id: number): ICodeStatement | undefined;
+    getAt(index: number): ICodeStatement | undefined;
+}
+declare class WhiteboardScript implements IScript {
+    source: string;
+    statements: ICodeStatement[];
+    errors: ParseError[] | undefined;
+    private _idMap?;
+    constructor(source: string, statements: ICodeStatement[], errors?: ParseError[]);
+    /**
+     * Gets the ID-to-statement Map, building it lazily on first access.
+     * Provides O(1) lookups instead of O(n) find() calls.
+     */
+    private getIdMap;
+    /**
+     * Resolves multiple statement IDs to statements.
+     * Uses cached Map for O(n) performance instead of O(n²).
+     */
+    getIds(ids: number[]): ICodeStatement[];
+    /**
+     * Resolves a single statement ID to a statement.
+     * Uses cached Map for O(1) performance instead of O(n).
+     */
+    getId(id: number): ICodeStatement | undefined;
+    /**
+     * Gets a statement by its array index.
+     */
+    getAt(index: number): ICodeStatement | undefined;
+    /**
+     * Flattens grouped children (number[][]) and resolves to statements.
+     * Convenience wrapper for getIds(children.flat()).
+     */
+    getFlatChildren(children: number[][]): ICodeStatement[];
+    /**
+     * Resolves grouped children while preserving group structure.
+     * Maps each number[] group to ICodeStatement[] group.
+     */
+    getChildGroups(children: number[][]): ICodeStatement[][];
+}
+
+/**
+ * Canonical discipline vocabulary — the single source of truth for effort
+ * disciplines across the resolver, the TIS factor table, fact-row tags, the
+ * WQL tag dictionary, and UI filters.
+ *
+ * The vocabulary is the 10 values used by the bundled catalog
+ * (markdown/efforts/<discipline>/<slug>.md, 53 efforts). Earlier factor-table
+ * keys ('resistance', 'yoga', 'cardio', 'hiit') and the 'weightlifting' /
+ * 'monostructural' examples in storage docs were stale text — no live effort
+ * ever carried them.
+ */
+declare const EFFORT_DISCIPLINES: readonly ["bodyweight", "cycling", "gymnastics", "kettlebell", "recovery", "rowing", "running", "strength", "swimming", "walking"];
+type EffortDiscipline = (typeof EFFORT_DISCIPLINES)[number];
+declare function isEffortDiscipline(value: unknown): value is EffortDiscipline;
+/**
+ * TIS discipline multiplier per canonical discipline. Loaded modalities
+ * (strength + the loaded-skill pair kettlebell/gymnastics) score 1.2;
+ * recovery absorbs the retired 'yoga' case at 0.9; the monostructural five
+ * and bodyweight take the 1.0 default. Unknown/absent disciplines fall back
+ * to 1.0 — the historical behavior for every non-'strength' value.
+ */
+declare const DISCIPLINE_FACTORS: Record<EffortDiscipline, number>;
+/** Factor for an arbitrary discipline string; 1.0 when absent or unknown. */
+declare function disciplineFactorFor(discipline: string | undefined): number;
+
+/**
+ * Effort Registry — Core Types
+ *
+ * First-class domain entity system for exercise effort definitions.
+ * Centralizes effort metadata (MET, discipline, aliases) and supports
+ * user-defined derivations with coefficient chains and hard overrides.
+ */
+
+type EffortRegistrySource = 'bundled' | 'user' | 'synthetic-unresolved';
+/** Origins that hold real registry records (synthetic-unresolved entries are
+ * resolver phantoms, never listed) — the WQL `origin:` filter vocabulary. */
+declare const EFFORT_REGISTRY_ORIGINS: readonly ["bundled", "user"];
+/** Intensity tiers, low → high — the WQL `intensity:` filter vocabulary. */
+declare const INTENSITY_TIERS: readonly ["low", "moderate", "high"];
+type IntensityTier = (typeof INTENSITY_TIERS)[number];
+interface EffortBaseAttributes {
+    /** Metabolic equivalent of task */
+    met: number;
+    /** Broad discipline category — canonical vocabulary in `./disciplines`. */
+    discipline?: EffortDiscipline;
+    /** TIS discipline multiplier. When omitted, resolver derives it from discipline. */
+    disciplineFactor?: number;
+    /** Qualitative intensity bucket */
+    intensityTier?: IntensityTier;
+}
+interface EffortDerivation {
+    /** Slug of the parent effort this was cloned from */
+    parentSlug?: string;
+    /** Multiplicative modifiers applied to numeric base attributes */
+    coefficients?: Record<string, number>;
+    /** Explicit replacement values for specific attributes */
+    hardOverrides?: Record<string, unknown>;
+}
+/**
+ * Canonical effort entity.
+ *
+ * The slug is the durable identity boundary. Display labels and aliases
+ * may vary, but references should point at the slug.
+ */
+interface IEffort {
+    /** UUID */
+    id: string;
+    /** Canonical identifier — unique, lowercase, hyphenated */
+    slug: string;
+    /** Primary human-readable name */
+    label: string;
+    /** Alternative names for fuzzy matching */
+    aliases: string[];
+    /** Canonical effort attributes */
+    baseAttributes: EffortBaseAttributes;
+    /** Where this record came from */
+    registrySource: EffortRegistrySource;
+    /** Clone-based derivation metadata (user efforts only) */
+    derivation?: EffortDerivation;
+    /** ISO timestamp */
+    createdAt?: string;
+    /** ISO timestamp */
+    updatedAt?: string;
+    /** Free-form markdown description / notes */
+    body?: string;
+    /**
+     * Compiler hints attached to any block resolved to this effort. Consumed by
+     * strategies exactly like dialect-emitted hints — see `CONSUMED_HINTS` in
+     * `core/metrics/hints.ts`. Use sparingly: any key not in `CONSUMED_HINTS`
+     * is currently inert (analytics-only). For effort-specific metadata, prefer
+     * a domain metric.
+     */
+    hints?: Record<string, unknown>;
+}
+interface IEffortRegistry {
+    resolve(slug: string): IEffort | null;
+    list(): readonly IEffort[];
+    listByOrigin(origin: EffortRegistrySource): readonly IEffort[];
+    upsert(effort: IEffort): Promise<void>;
+    delete(slug: string): Promise<void>;
+    loadBundled(): Promise<void>;
+}
+interface EffortResolutionOptions {
+    /** Attribute metrics from /effort/:slug query params or logged execution metrics. */
+    modifiers?: Record<string, string>;
+    /** Fuzzy-match threshold override. */
+    threshold?: number;
+}
+type EffortResolvedFrom = 'user' | 'bundled' | 'default';
+/**
+ * Effective effort instance after alias lookup, derivation, modifiers,
+ * hard overrides, fallback policy, and discipline-factor calculation.
+ */
+interface ResolvedEffort {
+    /** Effective effort copy; baseAttributes reflect the resolved values. */
+    effort: IEffort;
+    /** Original registry definition before effective attributes were materialized. */
+    definition: IEffort;
+    slug: string;
+    label: string;
+    met: number;
+    /** Effective attributes mirrored for legacy metric consumers. */
+    baseAttributes: EffortBaseAttributes;
+    discipline?: EffortDiscipline;
+    disciplineFactor: number;
+    intensityTier?: IntensityTier;
+    modifiers: Record<string, string>;
+    registrySource: EffortRegistrySource;
+    resolvedFrom: EffortResolvedFrom;
+    isEstimated: boolean;
+}
+interface IEffortResolver {
+    /** Exact slug lookup */
+    resolveBySlug(slug: string): IEffort | null;
+    /** Exact alias lookup */
+    resolveByAlias(label: string): IEffort | null;
+    /**
+     * Fuzzy alias matching with configurable threshold.
+     * Returns a synthetic unresolved effort when no match is found
+     * (analytics continuity — never returns null).
+     */
+    resolveFuzzy(label: string, options?: {
+        threshold?: number;
+    }): IEffort;
+    /** Resolve a label/slug into an effective effort instance. */
+    resolveEffort(label: string, options?: EffortResolutionOptions): ResolvedEffort;
+    /** Materialize an already-found effort definition into an effective instance. */
+    resolveDefinition(effort: IEffort, options?: EffortResolutionOptions): ResolvedEffort;
+    /** All registered efforts (bundled + user) */
+    list(): readonly IEffort[];
+}
+interface EffortResolverOptions {
+    /** Default MET for synthetic unresolved efforts */
+    defaultMet?: number;
+    /** Default fuzzy-match threshold (Levenshtein distance) */
+    defaultThreshold?: number;
+}
+declare const DEFAULT_RESOLVER_OPTIONS: Required<EffortResolverOptions>;
+
+/**
+ * Minimal executable runtime action shape.
+ *
+ * Describes what {@link IRuntimeActionable.do}/{@link IRuntimeActionable.doAll}
+ * actually require — an object with a string `type` discriminator AND a
+ * `do()` method that the executor can invoke. Typing the queue surface
+ * through this primitive ensures callers cannot enqueue a non-executable
+ * object that would crash the action loop.
+ *
+ * `IRuntimeAction` extends this primitive (adding the optional `target`
+ * and `payload` fields, plus a richer return type for chained child
+ * actions).
+ *
+ * Lives in the same file as {@link IRuntimeActionable} (rather than its
+ * own module) so neither primitive needs to import the other — that would
+ * create an internal cycle inside the primitives layer itself.
+ */
+interface IRuntimeActionLike {
+    /** Type discriminator for the action. */
+    readonly type: string;
+    /**
+     * Execute the action against the runtime context. Implementations may
+     * return additional actions (see `IRuntimeAction.do`) — the primitive
+     * shape only requires that the method exists.
+     */
+    do(runtime: IRuntimeActionable): unknown;
+}
+/**
+ * Minimal primitive abstraction representing the runtime context that can
+ * queue runtime actions.
+ *
+ * Both {@link IScriptRuntime} and {@link IEventBus} depend on this primitive
+ * (or a stronger primitive that extends it) instead of each other. This
+ * breaks the cycles between `IRuntimeAction ↔ IScriptRuntime` and
+ * `IEventBus ↔ IScriptRuntime`.
+ *
+ * Actions are typed structurally through {@link IRuntimeActionLike} — an
+ * executable shape requiring both a `type` discriminator and a `do()`
+ * method. This keeps the primitives layer free of back-references into the
+ * broader contracts (it does NOT import `IRuntimeAction`) while still
+ * forcing queued actions to be executable so the action loop cannot crash
+ * on a structurally-typed but inert object.
+ *
+ * Concretely the runtime is always an `IScriptRuntime`, but typing through
+ * this primitive prevents the contract-layer cycle.
+ */
+interface IRuntimeActionable {
+    /**
+     * Execute a single action at the next available opportunity.
+     */
+    do(action: IRuntimeActionLike): void;
+    /**
+     * Execute multiple actions in order, internalizing reverse-push for LIFO
+     * processing. The first action in the array will execute first.
+     */
+    doAll(actions: IRuntimeActionLike[]): void;
+}
+
+/**
+ * Interface for actions that can be performed by the runtime in response to events.
+ *
+ * Actions return child actions instead of pushing them onto the runtime directly.
+ * The ExecutionContext collects returned actions and pushes them onto its internal
+ * LIFO stack, ensuring depth-first processing without actions needing to know
+ * about stack mechanics.
+ *
+ * Extends {@link IRuntimeActionLike} so the queue surface
+ * ({@link IRuntimeActionable.do}/{@link IRuntimeActionable.doAll}) accepts
+ * `IRuntimeAction` instances. The `do()` method receives the runtime via the
+ * {@link IRuntimeActionable} primitive instead of `IScriptRuntime`. This
+ * breaks the cycle `IRuntimeAction ↔ IScriptRuntime`. Concrete
+ * implementations are free to narrow their parameter type to `IScriptRuntime`
+ * (method bivariance allows this), and callers always pass an
+ * `IScriptRuntime` since `IScriptRuntime extends IRuntimeActionable`.
+ */
+interface IRuntimeAction extends IRuntimeActionLike {
+    /** Type of action to perform */
+    type: string;
+    /** Target of the action (optional) */
+    target?: string;
+    /** Action payload/data */
+    payload?: unknown;
+    /**
+     * Executes the action within the given runtime context.
+     *
+     * Returns child actions that should be executed next. The ExecutionContext
+     * pushes returned actions onto its LIFO stack for depth-first processing.
+     * Actions should NOT call runtime.do() or runtime.doAll() — just return
+     * the actions they want executed.
+     *
+     * @returns Array of child actions to execute, or void/empty array for none
+     */
+    do(runtime: IRuntimeActionable): IRuntimeAction[] | void;
+}
+
+/**
+ * A reference to a memory location that can be passed between components.
+ * This allows processes to reference memory without directly coupling to it.
+ *
+ * Note: The concrete `TypedMemoryReference` implementation lives in
+ * `src/runtime/impl/TypedMemoryReference.ts` to keep this contracts file
+ * free of implementation code and to break the
+ * `IMemoryReference ↔ IRuntimeMemory` cycle.
+ */
+interface IMemoryReference {
+    readonly id: string;
+    readonly ownerId: string;
+    readonly type: string;
+    readonly visibility: 'public' | 'private' | 'inherited';
+    /**
+     * Get the current value in an untyped manner.
+     * Useful for debugging and generic operations.
+     * @returns The current value or undefined
+     */
+    value(): unknown;
+    /**
+     * List of active subscriptions for this memory reference.
+     * Readonly access for debugging and inspection.
+     */
+    readonly subscriptions: ReadonlyArray<IMemorySubscription<unknown>>;
+}
+interface IMemorySubscription<T> {
+    readonly id: string;
+    readonly callback: (newValue: T | undefined, oldValue: T | undefined) => void;
+    readonly memoryId: string;
+    readonly createdAt: Date;
+}
+interface SubscriptionOptions {
+    immediate?: boolean;
+    throttle?: number;
+}
+
+/**
+ * Search criteria for finding memory references.
+ * Uses only the basic properties, not methods.
+ */
+type MemorySearchCriteria = {
+    id: string | null;
+    ownerId: string | null;
+    type: string | null;
+    visibility: 'public' | 'private' | 'inherited' | null;
+};
+/**
+ * The main runtime memory interface that manages separate memory from the execution stack.
+ * This enables debugging and state inspection independently of program execution flow.
+ *
+ * Note: Memory events (allocate, set, release) are dispatched by BlockContext,
+ * not by RuntimeMemory directly. This keeps the memory system pure and decoupled
+ * from the event system.
+ */
+interface IRuntimeMemory {
+    /**
+     * Allocates a new memory location and returns a reference to it.
+     * This memory will be automatically cleaned up when the associated stack item is removed.
+     */
+    allocate<T>(type: string, ownerId: string, initialValue?: T, visibility?: 'public' | 'private' | 'inherited'): TypedMemoryReference<T>;
+    /**
+     * Gets a memory reference by its ID.
+     * Returns undefined if the reference doesn't exist or has been cleaned up.
+     */
+    get<T>(reference: TypedMemoryReference<T>): T | undefined;
+    /**
+     * Sets the value of a memory reference.
+     * Throws an error if the reference is invalid.
+     **/
+    set<T>(reference: TypedMemoryReference<T>, value: T): void;
+    /**
+     * Searches for memory references that match the given criteria.
+     * Returns an array of matching references (empty if none found).
+     * the search is based on any non-null fields in the criteria object.
+     */
+    search(criteria: MemorySearchCriteria): IMemoryReference[];
+    /**
+     * Manually releases a memory reference and all its children.
+     * This is automatically called when stack items are removed.
+     */
+    release(reference: IMemoryReference): void;
+}
+
+declare class TypedMemoryReference<T> implements IMemoryReference {
+    private readonly _memory;
+    readonly ownerId: string;
+    readonly type: string;
+    visibility: 'public' | 'private' | 'inherited';
+    id: string;
+    private _subscriptions;
+    constructor(_memory: IRuntimeMemory, ownerId: string, type: string, visibility?: 'public' | 'private' | 'inherited');
+    /**
+     * Get the current value in an untyped manner.
+     * Implements IMemoryReference.value() for debugging and inspection.
+     */
+    value(): unknown;
+    /**
+     * Readonly access to subscriptions list.
+     * Implements IMemoryReference.subscriptions for debugging and inspection.
+     */
+    get subscriptions(): ReadonlyArray<IMemorySubscription<unknown>>;
+    get(): T | undefined;
+    set(value: T): void;
+    /**
+     * Subscribe to changes in this memory reference.
+     * @param callback Function to call when the value changes
+     * @param options Subscription options (immediate, throttle)
+     * @returns Unsubscribe function
+     */
+    subscribe(callback: (newValue: T | undefined, oldValue: T | undefined) => void, options?: SubscriptionOptions): () => void;
+    /**
+     * Unsubscribe from changes by subscription ID.
+     * @param subscriptionId The ID of the subscription to remove
+     */
+    unsubscribe(subscriptionId: string): void;
+    /**
+     * Check if this reference has any active subscribers.
+     * @returns true if there are active subscribers
+     */
+    hasSubscribers(): boolean;
+    /**
+     * Notify all subscribers of a value change.
+     * This is called internally by RuntimeMemory.
+     * @internal
+     */
+    notifySubscribers(newValue: T | undefined, oldValue: T | undefined): void;
+}
+
+/**
+ * Enum for type-safe memory allocation in the runtime system.
+ * Prevents typos and provides IDE autocomplete support.
+ */
+declare enum MemoryTypeEnum {
+    /**
+     * Display stack state - Full UI display hierarchy state
+     * Type: IDisplayStackState (timer stack, card stack, workout state)
+     */
+    DISPLAY_STACK_STATE = "displaystack",
+    /**
+     * Action stack state - Available actions surfaced to UI
+     * Type: ActionStackState
+     */
+    ACTION_STACK_STATE = "actions",
+    /**
+     * Timer state prefix - use as `timer:${blockId}`
+     * Type: TimerState
+     */
+    TIMER_PREFIX = "timer:",
+    /**
+     * Handler prefix - use as `handler:${id}`
+     * Type: IEventHandler
+     */
+    HANDLER_PREFIX = "handler:",
+    /**
+     * Target reps for the current round/block
+     * Type: number
+     */
+    METRIC_REPS = "metric:reps",
+    /**
+     * Anchor for cross-block references
+     * Type: IAnchorValue
+     */
+    ANCHOR = "anchor"
+}
+
+/**
+ * The structure of the value stored within an anchor reference.
+ * An anchor's value is a meta-entry that describes how to find the actual data,
+ * rather than being the data itself.
+ *
+ * This enables dynamic data source resolution and decouples UI components
+ * from specific memory reference implementations.
+ *
+ * @example
+ * ```typescript
+ * // Anchor pointing to a timer's time spans
+ * const anchorValue: IAnchorValue = {
+ *   searchCriteria: {
+ *     ownerId: 'stopwatch-block-id',
+ *     type: MemoryTypeEnum.TIMER_TIME_SPANS,
+ *     id: null,
+ *     visibility: null
+ *   }
+ * };
+ * ```
+ */
+interface IAnchorValue {
+    /**
+     * Search criteria used to find the target memory reference(s).
+     * This is passed to IRuntimeMemory.search() to resolve the anchor.
+     *
+     * Typically specifies ownerId and type to locate the data source.
+     * Can be updated at runtime to dynamically change what the anchor points to.
+     */
+    searchCriteria: Partial<MemorySearchCriteria>;
+}
+
+/**
+ * BlockContext provides memory allocation and access for a runtime block.
+ *
+ * Design Principles:
+ * - Strategy-owned: Created by strategies before block creation
+ * - Constructor-injected: Passed to behaviors during instantiation
+ * - Explicit cleanup: Consumer must call release() after block disposal
+ *
+ * @example
+ * ```typescript
+ * // Strategy allocates memory
+ * const context = new BlockContext(runtime, blockId);
+ * const timerRef = context.allocate<TimeSpan[]>('timer-time-spans', [], 'public');
+ *
+ * // Behavior receives memory via constructor
+ * const behavior = new TimerBehavior(timerRef);
+ *
+ * // Consumer handles cleanup
+ * block.dispose();
+ * block.context.release();
+ * ```
+ */
+interface IBlockContext {
+    /**
+     * Unique identifier for the owning block.
+     * Used to track memory ownership in RuntimeMemory.
+     */
+    readonly ownerId: string;
+    /**
+     * The ID of the exercise this block is executing.
+     * Used for metric collection and exercise definition lookup.
+     */
+    readonly exerciseId: string;
+    /**
+     * All memory references allocated by this context.
+     * Readonly array to prevent external modification.
+     */
+    readonly references: ReadonlyArray<IMemoryReference>;
+    /**
+     * Allocate memory for this block's state.
+     *
+     * @param type Memory type identifier from MemoryTypeEnum or custom string
+     * @param initialValue Optional initial value for the memory
+     * @param visibility 'public' for cross-block access, 'private' for internal use
+     * @returns Typed memory reference for accessing the allocated memory
+     * @throws Error if context has been released
+     */
+    allocate<T>(type: MemoryTypeEnum | string, initialValue?: T, visibility?: 'public' | 'private'): TypedMemoryReference<T>;
+    /**
+     * Get the first memory reference of a specific type.
+     *
+     * @param type Memory type identifier from MemoryTypeEnum or custom string
+     * @returns Memory reference or undefined if not found
+     */
+    get<T>(type: MemoryTypeEnum | string): TypedMemoryReference<T> | undefined;
+    /**
+     * Get all memory references of a specific type.
+     * Useful when multiple memory entries of the same type exist.
+     *
+     * @param type Memory type identifier to search for
+     * @returns Array of matching memory references (empty if none found)
+     */
+    getAll<T>(type: string): TypedMemoryReference<T>[];
+    /**
+     * Set the value of a memory reference and dispatch a memory:set event.
+     * Use this method instead of ref.set() to ensure events are dispatched.
+     *
+     * @param reference The memory reference to update
+     * @param value The new value to set
+     * @throws Error if context has been released
+     */
+    set<T>(reference: TypedMemoryReference<T>, value: T): void;
+    /**
+     * Release all allocated memory references.
+     * Must be called by consumer after block disposal.
+     *
+     * This method is idempotent - calling multiple times is safe.
+     * After release, allocate() will throw an error.
+     */
+    release(): void;
+    /**
+     * Check if this context has been released.
+     *
+     * @returns true if release() has been called
+     */
+    isReleased(): boolean;
+    /**
+     * Get or create an anchor reference with a stable ID.
+     *
+     * Anchors are special memory references that act as named pointers
+     * to other memory references. They enable UI components to subscribe
+     * to data without knowing the specific data source.
+     *
+     * If an anchor with the given ID already exists (from any owner),
+     * it returns the existing reference. Otherwise, it creates a new one.
+     *
+     * Anchors are always allocated with 'public' visibility so they can
+     * be found by UI components across the application.
+     *
+     * @param anchorId Stable, semantic ID for the anchor (e.g., 'anchor-main-workout-clock')
+     * @returns Typed memory reference for the anchor
+     * @throws Error if context has been released
+     *
+     * @example
+     * ```typescript
+     * const anchor = context.getOrCreateAnchor('anchor-main-clock');
+     * anchor.set({
+     *   searchCriteria: {
+     *     ownerId: timerBlockId,
+     *     type: MemoryTypeEnum.TIMER_TIME_SPANS
+     *   }
+     * });
+     * ```
+     */
+    getOrCreateAnchor(anchorId: string): TypedMemoryReference<IAnchorValue>;
+}
+
+/**
+ * Base interface for runtime events that can be handled by the system.
+ */
+interface IEvent {
+    /** Name/type of the event */
+    name: string;
+    /** Timestamp when the event occurred */
+    timestamp: Date;
+    /** Additional event data */
+    data?: unknown;
+}
+
+/**
+ * Tags for memory locations. A block can have multiple locations with the same tag.
+ * Tags replace the previous MemoryType keys but are no longer unique per block.
+ *
+ * Fragment tags follow the `metrics:*` namespace convention and are classified
+ * into three visibility tiers:
+ *
+ * | Tier      | Tags                                     | Purpose                          |
+ * |-----------|------------------------------------------|----------------------------------|
+ * | display   | `metrics:display`                       | Shown on UI cards                |
+ * | result    | `metric:result`                        | Block output collected on pop    |
+ * | promote   | `metric:promote`, `metric:rep-target` | Inherited by child blocks       |
+ * | private   | `metric:tracked`, `metric:label`      | Internal behavior state          |
+ *
+ * @see MetricVisibility for classification helpers.
+ */
+type MemoryTag = 'time' | 'round' | 'children:status' | 'completion' | 'display' | 'controls' | 'metrics' | 'metric:display' | 'metric:promote' | 'metric:rep-target' | 'metric:result' | 'metric:tracked' | 'metric:label' | 'metric:hint' | 'metric:next';
+/**
+ * A single memory location in a block's memory list.
+ *
+ * Memory locations are the fundamental unit of state storage in the runtime.
+ * Multiple locations with the same tag can coexist, enabling:
+ * - Multiple timers per block
+ * - Multiple display rows per block (metrics:display)
+ * - Multiple round counters
+ *
+ * All memory values are MetricContainer instances — metrics are the universal currency.
+ */
+interface IMemoryLocation {
+    /** Discriminator tag — multiple locations can share the same tag */
+    readonly tag: MemoryTag;
+    /** The metrics data stored at this location */
+    readonly metrics: MetricContainer;
+    /** Subscribe to changes at this location */
+    subscribe(listener: (newValue: MetricContainer, oldValue: MetricContainer) => void): () => void;
+    /** Update the metrics at this location */
+    update(metrics: MetricContainer | IMetric[]): void;
+    /** Dispose of this location and notify subscribers */
+    dispose(): void;
+}
+/**
+ * Concrete implementation of a memory location.
+ *
+ * Provides observable state storage with subscription management.
+ * When disposed, sends empty array to all subscribers for cleanup.
+ */
+declare class MemoryLocation implements IMemoryLocation {
+    readonly tag: MemoryTag;
+    private _listeners;
+    private _metrics;
+    private _isDisposed;
+    constructor(tag: MemoryTag, initialFragments?: MetricContainer | IMetric[]);
+    get metrics(): MetricContainer;
+    update(metrics: MetricContainer | IMetric[]): void;
+    subscribe(listener: (nv: MetricContainer, ov: MetricContainer) => void): () => void;
+    dispose(): void;
+}
+
+/**
+ * MetricVisibility.ts - Categorizes metrics memory tags by visibility level.
+ *
+ * All `metrics:*` memory tags carry typed metrics on runtime blocks.
+ * This module introduces a three-tier visibility classification so the UI,
+ * JIT compiler, and runtime can treat metrics memory consistently:
+ *
+ * | Visibility | Purpose | Example tags |
+ * |------------|---------|-------------|
+ * | `display`  | Shown on the workout card in the UI (one row per location) | `metrics:display` |
+ * | `result`   | Block output metric collected when the block is popped | `metric:result` |
+ * | `promote`  | Promoted/inherited by child blocks during compilation | `metric:promote`, `metric:rep-target` |
+ * | `private`  | Internal behavior state; hidden from UI in normal mode | `metric:tracked`, `metric:label` |
+ *
+ * In **debug mode** the UI shows all three tiers, each with a distinguishing
+ * icon so developers can inspect the full memory surface of every block.
+ */
+
+/**
+ * The four visibility tiers for metrics memory tags.
+ */
+type MetricVisibility = 'display' | 'result' | 'promote' | 'private';
+/**
+ * Returns the visibility tier for a given memory tag.
+ *
+ * - Known `metrics:*` tags are mapped via the static sets above.
+ * - Any unknown `metric:*` tag defaults to `'private'`.
+ * - Non-metric tags (e.g., `'timer'`, `'round'`) return `undefined`.
+ */
+declare function getMetricVisibility(tag: MemoryTag): MetricVisibility | undefined;
+/**
+ * Returns `true` if the tag belongs to a metrics namespace.
+ */
+declare function isFragmentTag(tag: MemoryTag): boolean;
+/**
+ * Filter memory tags by visibility tier.
+ */
+declare function filterTagsByVisibility(tags: readonly MemoryTag[], visibility: MetricVisibility): MemoryTag[];
+/**
+ * Unicode icon for each visibility tier.
+ * Used in debug mode UI to label each metrics row.
+ */
+declare const VISIBILITY_ICONS: Record<MetricVisibility, string>;
+/**
+ * Short label for each visibility tier (used in debug badges).
+ */
+declare const VISIBILITY_LABELS: Record<MetricVisibility, string>;
+
+/**
+ * Minimal block reference primitive consumed by {@link IBehaviorContext}.
+ *
+ * `IRuntimeBlock` extends this primitive with runtime-side lifecycle methods
+ * (`mount`, `next`, `unmount`, `dispose`). Defining the consumer-facing
+ * surface here lets `IBehaviorContext` reference a block without importing
+ * `IRuntimeBlock`, which in turn breaks the cycle:
+ *
+ *   IBehaviorContext → IRuntimeBlock → IRuntimeBehavior → IBehaviorContext
+ *
+ * The shape includes the full surface that behavior implementations use
+ * through `ctx.block.*`, but intentionally avoids importing
+ * `IRuntimeBehavior` (which depends on `IBehaviorContext`). The `behaviors`
+ * array is therefore typed as opaque objects here and refined to
+ * `readonly IRuntimeBehavior[]` on `IRuntimeBlock` itself.
+ */
+interface IBlockRef {
+    /** Unique identifier for this block instance. */
+    readonly key: BlockKey;
+    /** Source code location identifiers. */
+    readonly sourceIds: number[];
+    /** Type discriminator for UI display and logging. */
+    readonly blockType?: string;
+    /** Human-readable label for the block. */
+    readonly label: string;
+    /** The execution context for this block (memory allocation/cleanup). */
+    readonly context: IBlockContext;
+    /** Whether this block has completed execution. */
+    readonly isComplete: boolean;
+    /** Reason the block completed, if any. */
+    readonly completionReason?: string;
+    /**
+     * Read-only view of the behaviors attached to the block.
+     *
+     * Intentionally typed as opaque objects in the primitive layer to avoid
+     * importing `IRuntimeBehavior` (which would re-introduce a cycle through
+     * `IBehaviorContext`). `IRuntimeBlock` refines this to
+     * `readonly IRuntimeBehavior[]`.
+     */
+    readonly behaviors: ReadonlyArray<{
+        readonly constructor: Function;
+    }>;
+    /** Push a memory location onto the block's memory list. */
+    pushMemory(location: IMemoryLocation): void;
+    /** Get all memory locations matching the given tag. */
+    getMemoryByTag(tag: MemoryTag): IMemoryLocation[];
+    /** Get all memory locations owned by this block. */
+    getAllMemory(): IMemoryLocation[];
+    /** Get all metrics memory locations matching a given visibility tier. */
+    getMetricMemoryByVisibility(visibility: MetricVisibility): IMemoryLocation[];
+    /** Mark the block as complete (idempotent). */
+    markComplete(reason?: string): void;
+}
+
+/**
+ * TimeSpan represents a discrete segment of a block's **Time** — a single
+ * start/stop recording within the spans collection.
+ *
+ * Multiple TimeSpans allow for pause/resume tracking.
+ *
+ * Note: The `.duration` getter computes the length of this individual span
+ * (end − start). This differs from the glossary term **Duration**, which
+ * refers to the parser-defined planned target. To avoid confusion, prefer
+ * the term "span length" when discussing individual span measurements.
+ *
+ * @see docs/architecture/time-terminology.md
+ */
+
+declare class TimeSpan implements TimeSpan$1 {
+    started: number;
+    ended?: number | undefined;
+    constructor(started: number, ended?: number | undefined);
+    static fromJSON(json: any): TimeSpan;
+    /**
+     * Create a TimeSpan from Date objects (legacy support/compatibility)
+     */
+    static fromDates(start: Date, end?: Date): TimeSpan;
+    /**
+     * Length of this individual span in milliseconds.
+     * Uses current time if the span is still open.
+     *
+     * Note: Not to be confused with the glossary term "Duration" which
+     * refers to the parser-defined planned target (DurationMetric).
+     */
+    get duration(): number;
+    /**
+     * Whether the span is currently open (no end time).
+     */
+    get isOpen(): boolean;
+    get startDate(): Date;
+    get endDate(): Date | undefined;
+}
+
+/**
+ * INowProvider — the only seam for "what time is it" in the runtime.
+ * Events, actions, and behaviors that need a timestamp take a now-fn
+ * in their constructor; the runtime passes its single provider down.
+ * Tests pass a frozen clock so the timeline is deterministic.
+ */
+interface INowProvider {
+    now(): Date;
+    nowMs(): number;
+}
+/** Default provider: reads wall clock. */
+declare const wallClockNow: INowProvider;
+/** A provider that always returns the same Date (for tests). */
+declare function frozenNow(at: Date): INowProvider;
+
+/**
+ * IRuntimeClock provides time tracking for the runtime.
+ *
+ * It maintains a list of time spans created by start/stop calls,
+ * and provides:
+ * - `currentDate`: Current wall-clock time as a Date
+ * - `elapsed`: Total milliseconds of running time (sum of all spans)
+ * - `start()`/`stop()`: Control methods that return timestamps for event creation
+ *
+ * Renamed from `now` → `currentDate` to free the `now()` method for the INowProvider seam.
+ * Callers should use `clock.now()` for the provider contract, `clock.currentDate` for the raw Date.
+ */
+interface IRuntimeClock extends INowProvider {
+    /** Current wall-clock time as a Date */
+    readonly currentDate: Date;
+    /** Total elapsed milliseconds while running (sum of all completed spans + current running span) */
+    readonly elapsed: number;
+    /** Whether the clock is currently running (has an open span) */
+    readonly isRunning: boolean;
+    /** All time spans tracked by this clock */
+    readonly spans: ReadonlyArray<TimeSpan>;
+    /** Start the clock, returns the start timestamp for event creation */
+    start(): Date;
+    /** Stop the clock, returns the stop timestamp for event creation */
+    stop(): Date;
+}
+
+/**
+ * Runtime context surface required by {@link IEventBus} dispatchers,
+ * handlers, and callbacks.
+ *
+ * Extends {@link IRuntimeActionable} (so callers can queue follow-up
+ * actions) with the minimal accessors the event bus actually consumes:
+ *
+ * - `stack` — used for handler scope filtering ('active' vs 'bubble' vs
+ *   'global'). Only the keys are needed, so the shape is intentionally
+ *   minimal and does not import `IRuntimeStack` / `IRuntimeBlock`.
+ * - `errors` — used by `dispatch()` to short-circuit handler chains when
+ *   a previous handler pushed a `RuntimeError`.
+ * - `handle(event)` — used by `emit()` to route the event back through
+ *   the runtime's own dispatch flow.
+ *
+ * Defining this primitive (instead of typing the bus parameters as the
+ * looser {@link IRuntimeActionable}) prevents the
+ * `IEventBus ↔ IScriptRuntime` cycle while keeping the contract
+ * type-accurate so callers cannot pass a stub that only provides
+ * `do()`/`doAll()` and crash at runtime when the bus reaches for
+ * `runtime.stack`.
+ */
+
+/** Minimal stack snapshot accessor used by event-scope filtering. */
+interface IEventDispatchStack {
+    /** The current (top-of-stack) block reference, if any. */
+    readonly current: {
+        readonly key: {
+            toString(): string;
+        };
+    } | undefined;
+    /** Block keys for every block on the stack, bottom-to-top. */
+    readonly keys: ReadonlyArray<{
+        toString(): string;
+    }>;
+}
+interface IEventDispatchContext extends IRuntimeActionable {
+    /** Stack accessor used for handler scope filtering. */
+    readonly stack: IEventDispatchStack;
+    /**
+     * Optional list of accumulated runtime errors. The bus uses
+     * `errors.length` to short-circuit handler chains.
+     */
+    readonly errors?: ReadonlyArray<unknown>;
+    /**
+     * Route an event back through the runtime's own dispatch flow.
+     * Used by `IEventBus.emit()`.
+     */
+    handle(event: {
+        readonly name: string;
+        readonly timestamp: Date;
+        readonly data?: unknown;
+    }): void;
+}
+
+/**
+ * Interface for handling runtime events and producing actions.
+ * Each handler is responsible for a specific type of event processing.
+ *
+ * Handlers return an array of actions to execute. An empty array means
+ * the handler did not handle the event or has no actions to perform.
+ *
+ * For error handling, use the ErrorAction to push errors to runtime.errors.
+ *
+ * The runtime is typed as the {@link IEventDispatchContext} primitive so
+ * handlers can rely on the stack accessors / `do()` / `handle()` surface
+ * the bus already requires, without importing `IScriptRuntime` and
+ * re-introducing the contract-layer cycle. Concrete handler implementations
+ * are free to narrow their parameter type to `IScriptRuntime`.
+ */
+interface IEventHandler {
+    /** Unique identifier for this handler */
+    readonly id: string;
+    /** Name of the handler for logging/debugging */
+    readonly name: string;
+    /**
+     * Handles the event and returns an array of actions to execute.
+     * @param event The event to handle
+     * @param runtime Runtime context for event processing (primitive form)
+     * @returns Array of actions to execute (empty if event not handled)
+     */
+    handler(event: IEvent, runtime: IEventDispatchContext): IRuntimeAction[];
+}
+
+/**
+ * Simple callback type for UI event listeners that don't produce actions.
+ *
+ * Receives an {@link IEventDispatchContext} — the same primitive used by
+ * {@link IEventBus.dispatch} — so callbacks can rely on the stack
+ * accessors and `handle()` / `do()` surface the bus already requires.
+ * This avoids importing `IScriptRuntime` (which would re-introduce the
+ * `IEventBus ↔ IScriptRuntime` cycle) while keeping the contract
+ * type-accurate. Concrete callbacks are free to narrow the parameter type
+ * to `IScriptRuntime`.
+ */
+type EventCallback = (event: IEvent, runtime: IEventDispatchContext) => void;
+/**
+ * Handler scope determines when a handler receives events.
+ *
+ * - 'active' (default): Only fires when the owner block is the current/active block on the stack.
+ * - 'bubble': Fires when the owner block is anywhere on the stack (allows parent listening).
+ * - 'global': Always fires regardless of stack state (for runtime-level handlers).
+ */
+type HandlerScope = 'active' | 'bubble' | 'global';
+/**
+ * Options for registering an event handler.
+ */
+interface EventHandlerOptions {
+    /** Handler priority (higher priority handlers execute first). Default: 0 */
+    priority?: number;
+    /** Handler scope determining when it receives events. Default: 'active' */
+    scope?: HandlerScope;
+}
+interface IEventBus {
+    /**
+     * Register a full event handler that can produce runtime actions.
+     * Used for runtime-internal event processing.
+     *
+     * @param eventName - The event name to listen for ('*' for all events)
+     * @param handler - The event handler
+     * @param ownerId - The owner block ID (used for scope filtering and cleanup)
+     * @param options - Handler options including priority and scope
+     * @returns Unsubscribe function
+     */
+    register(eventName: string, handler: IEventHandler, ownerId: string, options?: EventHandlerOptions): () => void;
+    /**
+     * Register a simple callback for event notifications.
+     * Used for UI components that need to react to events without producing actions.
+     * Returns an unsubscribe function.
+     */
+    on(eventName: string, callback: EventCallback, ownerId: string): () => void;
+    unregisterById(handlerId: string): void;
+    unregisterByOwner(ownerId: string): void;
+    /**
+     * Dispatch an event and return the resulting actions without executing them.
+     * Used internally when actions need special handling.
+     *
+     * @param runtime - The runtime context. Typed as the
+     * {@link IEventDispatchContext} primitive so the implementation can rely
+     * on `stack` (for scope filtering) and `errors` (for early-exit) without
+     * importing `IScriptRuntime` and re-introducing the
+     * `IEventBus ↔ IScriptRuntime` cycle.
+     */
+    dispatch(event: IEvent, runtime: IEventDispatchContext): IRuntimeAction[];
+    /**
+     * Dispatch an event and execute all resulting actions immediately.
+     * This is the primary entry point for event handling.
+     *
+     * @param event - The event to dispatch
+     * @param runtime - The runtime context. Typed as the
+     * {@link IEventDispatchContext} primitive so the implementation can call
+     * `runtime.handle(event)` without importing `IScriptRuntime`.
+     */
+    emit(event: IEvent, runtime: IEventDispatchContext): void;
+    /**
+     * Dispose of all handlers and callbacks, releasing all references.
+     * Call this during runtime cleanup to prevent memory leaks.
+     */
+    dispose(): void;
+}
+
+/**
+ * Unsubscribe function returned by subscribe().
+ */
+type Unsubscribe$1 = () => void;
+/**
+ * Event types that behaviors can subscribe to.
+ */
+type BehaviorEventType = 'tick' | 'next' | 'timer:complete' | 'pause' | 'resume' | '*';
+/**
+ * Listener function for behavior event subscriptions.
+ */
+type BehaviorEventListener = (event: IEvent, ctx: IBehaviorContext) => IRuntimeAction[];
+/**
+ * Options for subscribing to events.
+ */
+interface SubscribeOptions {
+    /**
+     * Handler scope for this subscription.
+     * - `'active'` (default): Only fires when this block is the active (top-of-stack) block
+     * - `'bubble'`: Fires when this block is anywhere on the stack (parent hears child events)
+     * - `'global'`: Always fires regardless of stack state
+     */
+    scope?: HandlerScope;
+}
+/**
+ * Options for emitting an output statement.
+ */
+interface OutputOptions {
+    /** Human-readable label for the output */
+    label?: string;
+    /**
+     * Reason the block completed.
+     *
+     * Propagated to OutputStatement so downstream consumers can distinguish:
+     * - `'user-advance'` — self-pop (user clicked next)
+     * - `'forced-pop'` — parent-pop (parent timer expired, etc.)
+     * - `'timer-expired'` — block's own timer completed
+     */
+    completionReason?: string;
+}
+/**
+ * IBehaviorContext is the unified context object passed to behavior lifecycle hooks.
+ *
+ * It provides everything a behavior needs to interact with the runtime:
+ * - Access to the block and clock
+ * - Event subscription during mount (for tick, next, etc.)
+ * - Output emission at any lifecycle point
+ * - Typed memory access
+ * - Block completion control
+ *
+ * ## Design Philosophy
+ *
+ * This context replaces the old `(block, clock)` tuple with a richer API that:
+ * 1. **Enables event subscription**: Behaviors can register for tick/next events during mount
+ * 2. **Supports output emission**: Behaviors emit IOutputStatements at any lifecycle point
+ * 3. **Provides typed memory**: Read and write to block-owned memory with type safety
+ * 4. **Separates events from outputs**: Events are coordination, outputs are reporting
+ *
+ * @example
+ * ```typescript
+ * class TimerBehavior implements IRuntimeBehavior {
+ *   onMount(ctx: IBehaviorContext) {
+ *     // Subscribe to tick events
+ *     ctx.subscribe('tick', (event, ctx) => {
+ *       const [timerLoc] = ctx.getMemoryByTag('time');
+ *       if (timer?.elapsed >= timer?.duration) {
+ *         ctx.markComplete('timer:complete');
+ *       }
+ *       return [];
+ *     });
+ *
+ *     // Emit segment started output
+ *     ctx.emitOutput('segment', [timerFragment], { label: '5:00 countdown' });
+ *
+ *     return [];
+ *   }
+ *
+ *   onUnmount(ctx: IBehaviorContext) {
+ *     // Emit a milestone marking this behavior's own completion. The block's
+ *     // final 'segment' output (carrying completionReason) is emitted separately
+ *     // by the runtime when the block pops — behaviors should not emit their own
+ *     // 'segment'/'completion'-shaped output on unmount; see ReportOutputBehavior
+ *     // for the canonical pattern (write result memory, let the pop emit the segment).
+ *     ctx.emitOutput('milestone', [elapsedFragment], { label: 'Timer Complete' });
+ *     return [];
+ *   }
+ * }
+ * ```
+ */
+interface IBehaviorContext {
+    /** The block this behavior is attached to */
+    readonly block: IBlockRef;
+    /** Current runtime clock */
+    readonly clock: IRuntimeClock;
+    /**
+     * Current stack level (depth) of the block.
+     * 0 = root block, 1 = first child, etc.
+     */
+    readonly stackLevel: number;
+    /**
+     * Subscribe to runtime events.
+     *
+     * Subscriptions are automatically cleaned up when the block unmounts.
+     * By default, the listener only fires when this block is the active block.
+     * Use `{ scope: 'bubble' }` to receive events when a child block is active
+     * (e.g., parent timer tracking ticks while children execute).
+     *
+     * @param eventType The event type to subscribe to ('tick', 'next', etc.)
+     * @param listener The callback to invoke when the event fires
+     * @param options Optional settings including handler scope
+     * @returns Unsubscribe function (usually not needed as cleanup is automatic)
+     *
+     * @example
+     * ```typescript
+     * onMount(ctx) {
+     *   // Active scope (default) — only fires when this block is on top
+     *   ctx.subscribe('next', (event, ctx) => {
+     *     return [];
+     *   });
+     *
+     *   // Bubble scope — fires even when a child block is active
+     *   ctx.subscribe('tick', (event, ctx) => {
+     *     // Track timer even when child effort blocks are executing
+     *     return [];
+     *   }, { scope: 'bubble' });
+     * }
+     * ```
+     */
+    subscribe(eventType: BehaviorEventType, listener: BehaviorEventListener, options?: SubscribeOptions): Unsubscribe$1;
+    /**
+     * Emit an event to the runtime event bus.
+     *
+     * Use this for **coordination** — triggering reactions in other parts of the system.
+     * For example: 'timer:started', 'timer:complete', 'pause', 'resume'.
+     *
+     * @param event The event to emit
+     */
+    emitEvent(event: IEvent): void;
+    /**
+     * Emit an output statement.
+     *
+     * Use this for **reporting** — recording what happened during execution.
+     * Output statements are collected by the runtime and made available to UI/history.
+     *
+     * Output can be emitted at any lifecycle point:
+     * - onMount: 'segment' started
+     * - onNext: 'segment' per iteration, 'milestone' events
+     * - onUnmount: write final results to memory (see ReportOutputBehavior) rather
+     *   than emitting directly — the runtime emits exactly one 'segment' output per
+     *   block pop, carrying those results plus a `completionReason` field
+     *
+     * @param type The type of output ('segment', 'milestone', 'metric', 'label')
+     * @param metrics The data metrics that make up this output
+     * @param options Optional metadata (label)
+     *
+     * @example
+     * ```typescript
+     * // Emit a segment for round 3
+     * ctx.emitOutput('segment', [
+     *   { metricType: MetricType.Rounds, value: 3, origin: 'runtime' }
+     * ], { label: 'Round 3 of 5' });
+     *
+     * // Emit a milestone marking a notable event mid-execution
+     * ctx.emitOutput('milestone', [
+     *   { metricType: MetricType.Duration, value: elapsed, origin: 'runtime' }
+     * ], { label: 'Halfway' });
+     * ```
+     */
+    emitOutput(type: OutputStatementType, metrics: MetricContainer | IMetric[], options?: OutputOptions): void;
+    /**
+     * Push a new memory location with metrics data onto the block's memory list.
+     *
+     * This creates a new MemoryLocation internally and returns it for potential updates.
+     * Multiple locations with the same tag can coexist on the same block.
+     *
+     * @param tag The memory tag (e.g., 'timer', 'metric:display')
+     * @param metric The metric array to store at this location
+     * @returns The created memory location for optional further manipulation
+     *
+     * @example
+     * ```typescript
+     * // Push timer metrics
+     * ctx.pushMemory('time', [timerFragment]);
+     *
+     * // Push display row (metrics:display)
+     * ctx.pushMemory('metric:display', [timerFrag, actionFrag, effortFrag]);
+     * ```
+     */
+    pushMemory(tag: MemoryTag, metrics: MetricContainer | IMetric[]): IMemoryLocation;
+    /**
+     * Get all memory locations matching the given tag.
+     * Delegates to block.getMemoryByTag — use this inside behaviors instead of
+     * the deprecated getMemory() shim.
+     */
+    getMemoryByTag(tag: MemoryTag): IMemoryLocation[];
+    /**
+     * Update the first matching memory location with new metrics data.
+     *
+     * Convenience method for updating existing memory without managing references.
+     * If no location with the given tag exists, this is a no-op.
+     *
+     * @param tag The memory tag to update
+     * @param metrics The new metrics array
+     *
+     * @example
+     * ```typescript
+     * // Update timer metrics with new elapsed time
+     * ctx.updateMemory('time', [updatedTimerMetric]);
+     * ```
+     */
+    updateMemory(tag: MemoryTag, metrics: MetricContainer | IMetric[]): void;
+    /**
+     * Declare that this block (via one of its behaviors) provides the named
+     * capability. Other behaviors on the same block can then coordinate with
+     * the declarer via `hasCapability` instead of string-inspecting
+     * `behaviors[i].constructor.name`.
+     *
+     * Capabilities are block-scoped: they are declared during `onMount`
+     * and consulted at any lifecycle hook. Declaring an unknown capability
+     * is a no-op (capabilities are loose strings, not an enum).
+     *
+     * @param cap Capability identifier (e.g. `'childSelection'`)
+     */
+    declareCapability(cap: string): void;
+    /**
+     * Returns true if the named capability was declared on this block.
+     *
+     * Use this to coordinate between behaviors that share a block without
+     * importing each other or relying on `constructor.name`.
+     *
+     * @param cap Capability identifier (e.g. `'childSelection'`)
+     */
+    hasCapability(cap: string): boolean;
+    /**
+     * Returns the Set used to store declared capabilities.  Internal callers
+     * (e.g. `RuntimeBlock.inspectNext`) pass this back to a fresh
+     * `BehaviorContext` so that all contexts for the same block observe the
+     * same capabilities without coupling the inspection context to a
+     * specific owner.
+     */
+    getCapabilities(): Set<string>;
+    /**
+     * Mark the block as complete.
+     *
+     * When marked complete, the block will be popped from the stack
+     *
+     * @param reason Optional reason for completion (for debugging/history)
+     */
+    markComplete(reason?: string): void;
+}
+
+/**
+ * Generic, composable behavior contract applied to runtime blocks.
+ *
+ * New Design (Phase 2+): behaviors interact purely via IBehaviorContext.
+ *
+ * Design goals:
+ * - Constructor-configurable: concrete behaviors can accept arbitrary args in their constructors.
+ * - Context-driven: every hook receives IBehaviorContext.
+ * - Optional hooks: implement only what you need.
+ */
+interface IRuntimeBehavior {
+    /**
+     * Called when the owning block is mounted.
+     * Use ctx.subscribe() to listen for events and ctx.emitOutput() for initial reports.
+     * Use ctx.pushMemory() to initialize block state.
+     */
+    onMount(ctx: IBehaviorContext): IRuntimeAction[];
+    /**
+     * Called when parent.next() is invoked (child completed or manual advance).
+     *
+     * This is the signal to advance the block's internal state (e.g., next round).
+     * If the block is finished, call ctx.markComplete().
+     */
+    onNext(ctx: IBehaviorContext): IRuntimeAction[];
+    /**
+     * Called when the owning block is about to be unmounted.
+     * Use ctx.emitOutput() to report final completion fragments.
+     * Subscriptions are automatically cleaned up *after* this method returns.
+     */
+    onUnmount(ctx: IBehaviorContext): IRuntimeAction[];
+    /**
+     * Called when the block is being disposed.
+     * Final cleanup hook.
+     */
+    onDispose(ctx: IBehaviorContext): void;
+    /**
+     * Legacy API: called when a block is pushed onto the stack.
+     * Superseded by onMount. Retained for backward-compatible mock behaviors.
+     */
+    onPush?(block: any, clock: any): IRuntimeAction[];
+    /**
+     * Legacy API: called when a block is popped from the stack.
+     * Superseded by onUnmount. Retained for backward-compatible mock behaviors.
+     */
+    onPop?(block: any, clock: any): IRuntimeAction[];
+}
+
+/**
+ * Lifecycle options propagated through block mount / next / unmount calls.
+ *
+ * Lives in the primitives layer (rather than `IRuntimeBlock.ts`) so that
+ * `IScriptRuntime` can reference it without importing the full
+ * `IRuntimeBlock` interface — breaking the cycle
+ * `IRuntimeBlock ↔ IScriptRuntime`.
+ */
+interface BlockLifecycleOptions$1 {
+    /** Start timestamp when the block was pushed onto the stack. */
+    startTime?: Date;
+    /** Completion timestamp when the block was popped from the stack. */
+    createdAt?: Date;
+    /** Current timestamp for the operation (onNext, etc). */
+    now?: Date;
+    /**
+     * Clock to use for this lifecycle operation.
+     *
+     * If provided, this clock is passed to behaviors and child operations,
+     * allowing consistent timing during execution chains (pop → next → push).
+     *
+     * Use `SnapshotClock.at(clock, time)` to freeze time during an execution chain:
+     * - When a timer expires at T₁, create a snapshot at T₁
+     * - Pass the snapshot through pop → parent.next → child push
+     * - All operations see T₁ as `clock.now`, ensuring no timing gaps
+     *
+     * If not provided, defaults to `runtime.clock`.
+     */
+    clock?: IRuntimeClock;
+}
+
+/**
+ * Re-export of the primitives `BlockLifecycleOptions` for backward
+ * compatibility with existing import sites that pull this type from
+ * `IRuntimeBlock`.
+ */
+type BlockLifecycleOptions = BlockLifecycleOptions$1;
+/**
+ * The decision reached by an inspectNext() call.
+ *
+ * `complete` is true if the behavior chain marked the block complete.
+ * `reason` is the human-readable reason (mirrors CompletionReason).
+ * `actions` is the action list that a follow-up next() call would dispatch.
+ * The actions are exactly the ones the auto-pop in next() would queue.
+ */
+interface CompletionDecision {
+    readonly complete: boolean;
+    readonly reason?: string;
+    readonly actions: readonly IRuntimeAction[];
+}
+/**
+ * Represents a runtime block that can be executed within the WOD runtime stack.
+ *
+ * ## Lifecycle Management
+ *
+ * Lifecycle pattern:
+ * - Blocks initialize in constructors and register resources
+ * - RuntimeStack.push() validates and stores blocks
+ * - RuntimeStack.pop() orchestrates unmount → dispose → context.release → parent.next
+ * - Blocks must implement dispose/unmount, but callers no longer manually dispose popped blocks
+ *
+ * ## Performance Requirements
+ * - All lifecycle methods should complete within 50ms
+ * - Stack operations should be optimized for frequent push/pop cycles
+ * - Memory usage should be minimized during execution
+ */
+interface IRuntimeBlock extends IBlockRef {
+    /**
+     * Execution timing metadata propagated by the runtime (start/completion timestamps).
+     * Implementations can rely on RuntimeStack/PushBlockAction to set this.
+     */
+    executionTiming?: BlockLifecycleOptions;
+    /**
+     * Unique identifier for this block instance.
+     * Used for tracking and debugging purposes.
+     */
+    readonly key: BlockKey;
+    /**
+     * Source code location identifiers.
+     * Links block to original workout script positions.
+     */
+    readonly sourceIds: number[];
+    /**
+     * Type discriminator for UI display and logging.
+     * Enables identification of block types (Timer, Rounds, Effort, etc.).
+     */
+    readonly blockType?: string;
+    /**
+     * Human-readable label for the block.
+     * Computed from the block's Label metrics in metrics:display memory.
+     * Falls back to blockType or 'Block' if no Label metric exists.
+     * e.g., "Round 1 of 3", "21 Reps", "For Time"
+     */
+    readonly label: string;
+    /**
+     * The execution context for this block.
+     * Manages memory allocation and cleanup.
+     */
+    readonly context: IBlockContext;
+    /**
+     * Called when this block is pushed onto the runtime stack.
+     * Sets up initial state and registers event listeners.
+     *
+     * Note: Event registration and resource allocation should happen here,
+     * not in the constructor, to ensure they are active only while mounted.
+     *
+     * @param runtime The runtime context (typed as the IRuntimeActionable primitive
+     *                to break the cycle through IScriptRuntime)
+     * @param options Lifecycle timing data (start time)
+     * @returns Array of runtime actions to execute after mount
+     */
+    mount(runtime: IRuntimeActionable, options?: BlockLifecycleOptions): IRuntimeAction[];
+    /**
+     * Called to advance the block's execution state.
+     *
+     * Triggers:
+     * 1. **Automatic**: Called by RuntimeStack when a child block is popped (child completion).
+     * 2. **Manual**: Called by NextAction when user manually acts (e.g., skips block).
+     * 3. **Timer**: Called by TimerBehavior when a timer completes (implicit next).
+     *
+     * Responsibilities:
+     * - Determine the next step in the block's execution flow.
+     * - If block has children (e.g., loops), push the next child.
+     * - If block is simple (e.g., single movement), mark itself complete.
+     * - If block is a timer, handle timer completion logic.
+     *
+     * @param runtime The runtime context (typed as the IRuntimeActionable primitive
+     *                to break the cycle through IScriptRuntime)
+     * @param options Lifecycle timing data (completion timestamp if triggered by child pop)
+     * @returns Array of runtime actions representing next execution steps (e.g., PushBlock, MarkComplete)
+     */
+    next(runtime: IRuntimeActionable, options?: BlockLifecycleOptions): IRuntimeAction[];
+    /**
+     * Inspect what the next() call would do, WITHOUT dispatching.
+     *
+     * PURE READ. Does not mutate _isComplete, does not register any
+     * side effects on the runtime, does not emit any events. Runs the
+     * behavior onNext chain against a temporary BehaviorContext and
+     * returns the decision the chain reached.
+     *
+     * Use this to ask "what would happen if I called next() right now?"
+     * without paying for the side effects. The cast sender can pre-emptively
+     * dim the next block; analytics can explain "why did this block end?"
+     * from the decision trail; tests can assert on the decision without
+     * touching state.
+     *
+     * @param runtime The runtime context (typed as the IRuntimeActionable primitive
+     *                to break the cycle through IScriptRuntime)
+     * @param options Lifecycle timing data (completion timestamp if triggered by child pop)
+     * @returns The completion decision: { complete, reason?, actions }
+     */
+    inspectNext(runtime: IRuntimeActionable, options?: BlockLifecycleOptions): CompletionDecision;
+    /**
+     * Called when this block is popped from the runtime stack.
+     * Handles completion logic, cleanup, and resource disposal.
+     *
+     * Note: This method MUST unsubscribe from events and dispose
+     * memory entries to complete any active observables.
+     *
+     * @param runtime The runtime context (typed as the IRuntimeActionable primitive
+     *                to break the cycle through IScriptRuntime)
+     * @param options Lifecycle timing data (completion timestamp)
+     * @returns Array of runtime actions to execute after unmount
+     */
+    unmount(runtime: IRuntimeActionable, options?: BlockLifecycleOptions): IRuntimeAction[];
+    /**
+     * Cleans up any resources held by this block.
+     *
+     * ## Critical Requirements
+     * - MUST be called by consumer after popping from stack
+     * - Should complete within 50ms for performance
+     * - Must handle being called multiple times safely
+     * - Should not throw exceptions during cleanup
+     *
+     * ## Resource Management
+     * - Close file handles, network connections
+     * - Unregister event listeners and callbacks
+     * - Release memory references and clear caches
+     * - Dispose of child objects and dependencies
+     *
+     * @param runtime The runtime context (typed as the IRuntimeActionable primitive
+     *                to break the cycle through IScriptRuntime)
+     * @throws Never - Should handle all cleanup errors internally
+     */
+    dispose(runtime: IRuntimeActionable): void;
+    /**
+     * Gets a specific behavior by type from the behaviors array.
+     * @param behaviorType Constructor/class of the behavior to find
+     * @returns The behavior instance or undefined if not found
+     */
+    getBehavior<T extends IRuntimeBehavior>(behaviorType: new (...args: any[]) => T): T | undefined;
+    /**
+     * Read-only list of all behaviors attached to this block.
+     * Useful for debug/inspection UIs.
+     */
+    readonly behaviors: readonly IRuntimeBehavior[];
+    /**
+     * Push a new memory location onto the block's memory list.
+     * Multiple locations with the same tag can coexist.
+     */
+    pushMemory(location: IMemoryLocation): void;
+    /**
+     * Merge a set of compiler hints (e.g. from an effort markdown file) into
+     * the block. Hints are stored as `MetricType.Hint` metrics in a
+     * `metric:hint` memory location.
+     *
+     * IMPORTANT: unlike dialect-emitted hints (which are attached to the
+     * *statement* before `JitCompiler.compile()` runs, and so are visible to
+     * `hasHint`/`getHints` calls inside strategy `match()`/`apply()`), hints
+     * merged here land on the *block* — which only exists after compilation.
+     * They currently do NOT reach any strategy decision; `hasHint`/`getHints`
+     * never read from block memory. See
+     * docs/architectural-cleanup-tier-3-extensibility.md §3.3 verification
+     * notes for the full explanation. Use sparingly: any hint key not in
+     * `CONSUMED_HINTS` (see `core/metrics/hints.ts`) is analytics-only even
+     * when the read-path gap above is fixed. For effort-specific metrics,
+     * prefer a domain metric.
+     */
+    mergeHints(hints: Readonly<Record<string, unknown>>): void;
+    /**
+     * Get all memory locations matching the given tag.
+     * Returns an empty array if no locations match.
+     *
+     * @param tag The memory tag to filter by
+     * @returns Array of memory locations with the given tag
+     */
+    getMemoryByTag(tag: MemoryTag): IMemoryLocation[];
+    /**
+     * Get all memory locations owned by this block.
+     * Returns the full memory list in insertion order.
+     *
+     * @returns Array of all memory locations
+     */
+    getAllMemory(): IMemoryLocation[];
+    /**
+     * Get all metrics memory locations matching a given visibility tier.
+     *
+     * Fragment tags follow the `metrics:*` namespace convention and are
+     * classified into three visibility tiers: `'display'`, `'promote'`,
+     * and `'private'`. This method filters all memory locations to those
+     * with metrics tags belonging to the specified tier.
+     *
+     * @param visibility The visibility tier to filter by
+     * @returns Array of memory locations in the requested tier
+     *
+     * @example
+     * ```typescript
+     * // Get metrics visible in the UI card
+     * const displayLocs = block.getMetricMemoryByVisibility('display');
+     *
+     * // Get all tiers for debug view
+     * const all = (['display', 'promote', 'private'] as const)
+     *   .flatMap(v => block.getMetricMemoryByVisibility(v));
+     * ```
+     */
+    getMetricMemoryByVisibility(visibility: MetricVisibility): IMemoryLocation[];
+    /**
+     * Indicates whether this block has completed execution.
+     * When true, the stack will pop this block during its next completion sweep.
+     *
+     * @remarks
+     * - Set by behaviors when their completion condition is met
+     * - Read by the stack after action/event processing
+     * - Once true, should not be reset to false
+     */
+    readonly isComplete: boolean;
+    /**
+     * The reason this block was completed, if any.
+     *
+     * Set by `markComplete(reason)`. Common values:
+     * - `'user-advance'` — user clicked next (self-pop)
+     * - `'forced-pop'` — parent popped this block (e.g., timer expiry)
+     * - `'timer-expired'` — block's own timer completed
+     * - `'rounds-complete'` — all rounds finished
+     *
+     * Available during `onUnmount` so output behaviors can include
+     * completion context in the emitted output.
+     */
+    readonly completionReason?: string;
+    /**
+     * Marks the block as complete. Idempotent - subsequent calls have no effect.
+     * Called by behaviors when their completion condition is met.
+     *
+     * @param reason Optional reason for completion (for debugging/history)
+     */
+    markComplete(reason?: string): void;
+}
+
+/**
+ * Runtime error information.
+ * Captured errors are stored in the runtime's error list for centralized handling.
+ */
+interface RuntimeError {
+    /** The error that occurred */
+    error: Error;
+    /** Where the error occurred (block ID, handler ID, etc.) */
+    source: string;
+    /** When the error occurred */
+    timestamp: Date;
+    /** Additional context about the error */
+    context?: unknown;
+    blockKey?: string;
+}
+
+type StackEvent = {
+    type: 'push';
+    block: IRuntimeBlock;
+    depth: number;
+    blocks: readonly IRuntimeBlock[];
+} | {
+    type: 'pop';
+    block: IRuntimeBlock;
+    depth: number;
+    blocks: readonly IRuntimeBlock[];
+} | {
+    type: 'initial';
+    blocks: readonly IRuntimeBlock[];
+};
+type StackListener = (event: StackEvent) => void;
+/**
+ * Unsubscribe function returned by subscription methods.
+ */
+type Unsubscribe = () => void;
+/**
+ * Snapshot of the runtime stack state at the time of a stack mutation.
+ *
+ * Pushed to UI observers via `IScriptRuntime.subscribeToStack()` on every
+ * push/pop/clear operation. Contains everything the UI needs to render
+ * the current state in a single object.
+ */
+interface StackSnapshot {
+    /** The event that caused this snapshot */
+    type: 'push' | 'pop' | 'clear' | 'initial';
+    /** Current stack blocks (bottom-to-top), frozen at event time */
+    blocks: readonly IRuntimeBlock[];
+    /** The block that was pushed/popped (undefined on 'clear'/'initial') */
+    affectedBlock?: IRuntimeBlock;
+    /** Stack depth after the event */
+    depth: number;
+    /** Timestamp from the runtime clock */
+    clockTime: Date;
+}
+type StackObserver = (snapshot: StackSnapshot) => void;
+interface IRuntimeStack {
+    readonly blocks: readonly IRuntimeBlock[];
+    readonly count: number;
+    readonly current: IRuntimeBlock | undefined;
+    readonly keys: BlockKey[];
+    push(block: IRuntimeBlock): void;
+    pop(): IRuntimeBlock | undefined;
+    clear(): void;
+    /**
+     * Subscribe to stack changes.
+     * New subscribers will immediately receive an 'initial' event with the current stack state.
+     */
+    subscribe(listener: StackListener): () => void;
+}
+
+type FenceDialect = string;
+
+/**
+ * Shared descriptor for all analytics processors.
+ *
+ * Defines applicability rules: which fence dialects (the `wod`/`log`/`plan`
+ * code-fence language a block was written in) the processor is eligible for,
+ * and which metrics must be present in the authored script for the processor
+ * to activate.
+ *
+ * Note: the descriptor field is named `fenceTypes` (not `dialects`) to make
+ * clear this is the **fence** axis only. Sport-specific filtering is
+ * expressed via `requiredMetrics` (e.g. `ClimbMetricType.Grade` for
+ * Climb-only processors). See Tier 3 §3.1.
+ */
+interface IAnalyticsProcessorDescriptor {
+    readonly id: string;
+    /**
+     * Allow-list of fence dialects this processor is eligible for.
+     * Omit or leave undefined to allow all fence dialects.
+     */
+    readonly fenceTypes?: readonly FenceDialect[];
+    /**
+     * Metrics that must ALL be present in the authored script for this
+     * processor to activate (AND semantics).
+     * Omit or leave undefined when applicability cannot be expressed
+     * with a simple metric list (e.g. disjunctive conditions).
+     *
+     * Typed `MetricType | string` (matching `IMetric.type`'s own type) so a
+     * custom dialect's domain metric type (e.g. `ClimbMetricType.Grade`,
+     * a plain string constant, not a `MetricType` enum member) can be used
+     * here directly — this was already the documented example above before
+     * the type was widened to actually allow it.
+     */
+    readonly requiredMetrics?: readonly (MetricType | string)[];
+}
+
+/**
+ * Realtime processor contract.
+ *
+ * Applied to every output statement as it is emitted. Used for
+ * per-segment metric derivation (e.g. pace, power enrichment).
+ */
+interface IRealtimeProcessor extends IAnalyticsProcessorDescriptor {
+    process(output: IOutputStatement): IOutputStatement;
+}
+
+/**
+ * Generic result structure for projection engine calculations.
+ *
+ * Provides a standardized format for all analytical projections,
+ * making results self-describing and easy to consume by UI components.
+ */
+interface ProjectionResult {
+    /** Human-readable name of the projection (e.g., "Total Volume", "Average Power") */
+    name: string;
+    /** Calculated value */
+    value: number;
+    /** Unit of measurement (e.g., "kg", "watts", "calories") */
+    unit: string;
+    /** Associated metric type for UI categorization (optional) */
+    metricType?: MetricType | string;
+    /** Time span over which this projection was calculated */
+    timeSpan: TimeSpan$1;
+    /**
+     * Origin of the projection value.
+     * Defaults to 'analyzed' when not specified.
+     * Use 'analyzed-estimated' when the value was computed with fallback
+     * assumptions (e.g. population-average METmax when VO2max is unknown).
+     */
+    origin?: MetricOrigin;
+    /** Optional additional metadata for the projection */
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Summary processor contract.
+ *
+ * Applied to the accumulated output history. Used for multi-segment
+ * aggregation and projection (e.g. total reps, total distance, volume).
+ */
+interface ISummaryProcessor extends IAnalyticsProcessorDescriptor {
+    summarize(outputs: IOutputStatement[]): ProjectionResult[];
+}
+
+interface IAnalyticsEngine {
+    /** Register a realtime processor. */
+    addRealtimeProcessor(processor: IRealtimeProcessor): void;
+    /** Register a summary processor. */
+    addSummaryProcessor(processor: ISummaryProcessor): void;
+    /**
+     * Wire a sink for live analytics outputs. The sink receives the full
+     * projection snapshot (ephemeral, display-only) each time projections
+     * change — never appended one-at-a-time, and never persisted. Persistence
+     * of the final values happens once via {@link finalize}.
+     */
+    setLiveOutputEmitter(emit: (outputs: IOutputStatement[]) => void): void;
+    /** Run enrichment on a single output, then fire live projection update */
+    run(output: IOutputStatement): IOutputStatement;
+    /** Final projection pass — returns analytics output statements for summary */
+    finalize(): IOutputStatement[];
+}
+
+/**
+ * Configuration for method interception behavior.
+ * Defined here (in runtime/contracts) so that both production runtime
+ * code and the testing layer can reference it without creating a
+ * runtime → testing circular dependency.
+ */
+type InterceptMode = 'passthrough' | 'spy' | 'override' | 'ignore';
+/**
+ * Configuration for TestableBlock behavior.
+ * Used by IRuntimeOptions to allow debug-mode block wrapping.
+ */
+interface TestableBlockConfig {
+    /** Custom ID for easy identification in visualizations */
+    testId?: string;
+    /** Custom label override for display purposes */
+    labelOverride?: string;
+    /** Mode for mount() interception */
+    mountMode?: InterceptMode;
+    /** Custom mount implementation when mode is 'override' */
+    mountOverride?: (runtime: IRuntimeActionable) => IRuntimeAction[];
+    /** Mode for next() interception */
+    nextMode?: InterceptMode;
+    /** Custom next implementation when mode is 'override' */
+    nextOverride?: (runtime: IRuntimeActionable) => IRuntimeAction[];
+    /** Mode for inspectNext() interception */
+    inspectNextMode?: InterceptMode;
+    /** Custom inspectNext implementation when mode is 'override' */
+    inspectNextOverride?: (runtime: IRuntimeActionable) => CompletionDecision;
+    /** Mode for unmount() interception */
+    unmountMode?: InterceptMode;
+    /** Custom unmount implementation when mode is 'override' */
+    unmountOverride?: (runtime: IRuntimeActionable) => IRuntimeAction[];
+    /** Mode for dispose() interception */
+    disposeMode?: InterceptMode;
+    /** Custom dispose implementation when mode is 'override' */
+    disposeOverride?: (runtime: IRuntimeActionable) => void;
+}
+
+/**
+ * Factory function type for wrapping blocks in debug mode.
+ * Receives the original block and returns a wrapped version.
+ */
+type BlockWrapperFactory = (block: IRuntimeBlock, config?: TestableBlockConfig) => IRuntimeBlock;
+/**
+ * Configuration options for ScriptRuntime initialization.
+ * These options control debugging, logging, and testing capabilities.
+ */
+interface IRuntimeOptions {
+    /**
+     * Enable debug mode for the runtime.
+     * When true:
+     * - All blocks pushed to the stack are automatically wrapped with TestableBlock
+     * - Additional lifecycle events are logged
+     */
+    debugMode?: boolean;
+    /**
+     * Custom factory for wrapping blocks when debugMode is true.
+     * If not provided, uses the default TestableBlock wrapper with spy mode.
+     */
+    blockWrapperFactory?: BlockWrapperFactory;
+    /**
+     * Default configuration for TestableBlock wrappers.
+     * Applied to all blocks wrapped in debug mode unless overridden.
+     */
+    defaultTestableConfig?: Partial<TestableBlockConfig>;
+    /**
+     * Enable console logging for runtime debug output.
+     * Automatically set to true when debugMode is true.
+     */
+    enableLogging?: boolean;
+    /**
+     * Custom log handler for debug events.
+     * If provided, called in addition to console logging.
+     */
+    onDebugLog?: (event: DebugLogEvent) => void;
+    /**
+     * Maximum depth for nested actions within a single execution turn.
+     * Defaults to 20 if not specified.
+     */
+    maxActionDepth?: number;
+}
+/**
+ * Types of debug log events
+ */
+type DebugLogEventType = 'block-wrapped' | 'block-mount' | 'block-next' | 'block-unmount' | 'block-dispose' | 'stack-push' | 'stack-pop' | 'memory-allocate' | 'memory-release' | 'event-handled';
+/**
+ * Debug log event structure
+ */
+interface DebugLogEvent {
+    type: DebugLogEventType;
+    timestamp: number;
+    blockKey?: string;
+    blockType?: string;
+    details?: Record<string, any>;
+}
+interface RuntimeStackWrapper {
+    wrap?: (block: IRuntimeBlock, parent?: IRuntimeBlock) => IRuntimeBlock;
+    cleanup?: (block: IRuntimeBlock) => void;
+}
+interface RuntimeStackLogger {
+    debug?: (message: string, details?: Record<string, unknown>) => void;
+    error?: (message: string, error: unknown, details?: Record<string, unknown>) => void;
+}
+interface RuntimeStackHooks {
+    onBeforePush?: (block: IRuntimeBlock, parent?: IRuntimeBlock) => void;
+    onAfterPush?: (block: IRuntimeBlock, parent?: IRuntimeBlock) => void;
+    onBeforePop?: (block: IRuntimeBlock | undefined) => void;
+    onAfterPop?: (block: IRuntimeBlock | undefined) => void;
+    unregisterByOwner?: (ownerKey: string) => void;
+}
+interface RuntimeStackOptions extends IRuntimeOptions {
+    wrapper?: RuntimeStackWrapper;
+    logger?: RuntimeStackLogger;
+    hooks?: RuntimeStackHooks;
+    analyticsOptions?: {
+        effortResolver?: IEffortResolver;
+        userProfile?: {
+            vo2max?: number;
+        };
+    };
+}
+
+/**
+ * AnalyticsContext — shared services injected into the analytics pipeline.
+ *
+ * Provides processors with domain-level resolution capabilities without
+ * direct coupling to registry implementations.
+ *
+ * @see docs/adr/effort-resolution-compile-time.md
+ */
+interface AnalyticsContext {
+    /** Effort resolver for canonical slug and fuzzy alias matching. */
+    effortResolver: IEffortResolver;
+}
+
+interface IJitCompiler {
+    compile(nodes: ICodeStatement[], runtime: IRuntimeActionable): IRuntimeBlock | undefined;
+}
+
+/**
+ * Listener callback for output statement events.
+ */
+type OutputListener = (output: IOutputStatement) => void;
+interface IScriptRuntime extends IRuntimeActionable {
+    options: RuntimeStackOptions;
+    script: WhiteboardScript;
+    eventBus: IEventBus;
+    stack: IRuntimeStack;
+    jit: IJitCompiler;
+    clock: IRuntimeClock;
+    nowProvider: INowProvider;
+    /** Errors collected during runtime execution */
+    errors?: RuntimeError[];
+    /** Optional analytics context for compile-time effort enrichment. */
+    analyticsContext?: AnalyticsContext;
+    /**
+     * Executes an action at the next available opportunity.
+     * Actions are processed in "turns" where time is frozen and
+     * nested actions are allowed up to a recursion limit.
+     */
+    do(action: IRuntimeAction): void;
+    /**
+     * Pushes multiple actions onto the execution stack in the correct order
+     * for LIFO processing. The first action in the array will execute first.
+     *
+     * This method internalizes the reverse-push pattern so callers don't need
+     * to know about LIFO stack mechanics — they just pass actions in the order
+     * they want them executed.
+     *
+     * @param actions Actions to execute, in desired execution order
+     */
+    doAll(actions: IRuntimeAction[]): void;
+    /**
+     * Dispatches an event and executes all resulting actions in a single turn.
+     */
+    handle(event: IEvent): void;
+    /**
+     * Pushes a block onto the runtime stack.
+     * This is a convenience method that wraps PushBlockAction.
+     *
+     * @param block The block to push
+     * @param lifecycle Optional lifecycle options (startTime, etc.)
+     */
+    pushBlock(block: IRuntimeBlock, lifecycle?: BlockLifecycleOptions$1): void;
+    /**
+     * Pops the current block from the runtime stack.
+     * This is a convenience method that wraps PopBlockAction.
+     * Handles the full lifecycle: unmount, pop, dispose, and parent notification.
+     *
+     * @param lifecycle Optional lifecycle options (createdAt, etc.)
+     */
+    popBlock(lifecycle?: BlockLifecycleOptions$1): void;
+    /**
+     * Subscribe to output statements generated during execution.
+     * Listeners are notified when a block unmounts and produces output.
+     *
+     * @param listener Callback invoked for each output statement
+     * @returns Unsubscribe function to stop receiving notifications
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = runtime.subscribeToOutput((output) => {
+     *   console.log(`Block ${output.sourceBlockKey} completed:`, output.outputType);
+     *   console.log('Fragments:', output.metrics);
+     * });
+     * ```
+     */
+    subscribeToOutput(listener: OutputListener): Unsubscribe;
+    /**
+     * Get all output statements generated so far during this execution.
+     * Returns a copy of the internal array.
+     */
+    getOutputStatements(): IOutputStatement[];
+    /**
+     * Ephemeral Tier-2 (running-total) snapshot for live display — the
+     * analytics engine's current projection set, replaced each segment.
+     * Display-only: never persisted to the output log. Optional because only
+     * a concrete runtime with a wired analytics engine produces it; consumers
+     * call it defensively (`runtime.getLiveAnalytics?.()`).
+     */
+    getLiveAnalytics?(): IOutputStatement[];
+    /**
+     * Add an output statement to the collection and notify subscribers.
+     * Used by BehaviorContext to emit outputs at any lifecycle point.
+     *
+     * @param output The output statement to add
+     *
+     * @example
+     * ```typescript
+     * runtime.addOutput(new OutputStatement({
+     *   outputType: 'segment',
+     *   timeSpan: new TimeSpan(start, end),
+     *   sourceBlockKey: block.key.toString(),
+     *   completionReason: 'user-advance',
+     *   metrics: [],
+     * }));
+     * ```
+     */
+    addOutput(output: IOutputStatement): void;
+    /**
+     * Subscribe to stack snapshots. The observer receives a StackSnapshot
+     * on every push/pop/clear event, containing the full stack state,
+     * the affected block, depth, and clock time.
+     *
+     * New subscribers immediately receive an 'initial' snapshot with the
+     * current stack state.
+     *
+     * This is the primary API for UI consumers to react to stack changes.
+     *
+     * @param observer Callback invoked with a StackSnapshot on each stack mutation
+     * @returns Unsubscribe function to stop receiving notifications
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = runtime.subscribeToStack((snapshot) => {
+     *   console.log(`Stack ${snapshot.type}: depth=${snapshot.depth}`);
+     *   if (snapshot.affectedBlock) {
+     *     console.log(`Affected: ${snapshot.affectedBlock.label}`);
+     *   }
+     * });
+     * ```
+     */
+    subscribeToStack(observer: StackObserver): Unsubscribe;
+    /**
+     * Set the analytics engine for the runtime.
+     * The engine will process each output statement as it is added.
+     */
+    setAnalyticsEngine(engine: IAnalyticsEngine): void;
+    /**
+     * Finalize the analytics engine and return any summary output statements.
+     * These statements are also automatically added to the runtime's internal list.
+     */
+    finalizeAnalytics(): IOutputStatement[];
+    dispose(): void;
+}
+
+type RuntimeState = 'idle' | 'running' | 'compiling' | 'completed';
+interface ScriptRuntimeDependencies {
+    stack: IRuntimeStack;
+    clock: IRuntimeClock;
+    eventBus: IEventBus;
+}
+declare class ScriptRuntime implements IScriptRuntime {
+    readonly script: WhiteboardScript;
+    readonly eventBus: IEventBus;
+    readonly clock: IRuntimeClock;
+    readonly stack: IRuntimeStack;
+    readonly jit: IJitCompiler;
+    readonly errors: RuntimeError[];
+    readonly options: RuntimeStackOptions;
+    analyticsContext?: AnalyticsContext;
+    private readonly _output;
+    private readonly _observers;
+    private _activeContext;
+    private readonly _now;
+    private _stackSubscriptionUnsub;
+    private _nextHandlerUnsub;
+    get nowProvider(): INowProvider;
+    private _abortHandlerUnsub;
+    constructor(script: WhiteboardScript, compiler: IJitCompiler, dependencies: ScriptRuntimeDependencies, options?: RuntimeStackOptions, now?: INowProvider);
+    /**
+     * Executes an action within a managed execution context (a "turn").
+     * Actions can queue further actions which will be processed in the same turn.
+     * Time is frozen during the turn.
+     */
+    do(action: IRuntimeAction): void;
+    /** Build the 'initial' snapshot of the current stack. Shared by settle-time
+     *  notification (sync, all observers) and subscribe-time catch-up (deferred,
+     *  new observer only). The two delivery timings differ deliberately — see
+     *  the call sites. */
+    private _buildInitialSnapshot;
+    private _notifyStackSettled;
+    /**
+     * Pushes multiple actions onto the execution stack in the correct order
+     * for LIFO processing. The first action in the array will execute first.
+     *
+     * If called within an active execution context, delegates to it.
+     * Otherwise, wraps in a new context as a composite action.
+     */
+    doAll(actions: IRuntimeAction[]): void;
+    /**
+     * Dispatches an event to the event bus and executes any resulting actions
+     * within a single execution turn.
+     */
+    handle(event: IEvent): void;
+    /**
+     * Subscribe to output statements generated during execution.
+     */
+    subscribeToOutput(listener: OutputListener): Unsubscribe;
+    /**
+     * Get all output statements generated so far.
+     */
+    getOutputStatements(): IOutputStatement[];
+    /**
+     * Ephemeral Tier-2 (running-total) snapshot for live display; never persisted.
+     */
+    getLiveAnalytics(): IOutputStatement[];
+    /**
+     * Add an output statement to the collection and notify subscribers.
+     * Used by BehaviorContext to emit outputs at any lifecycle point.
+     */
+    addOutput(output: IOutputStatement): void;
+    setAnalyticsEngine(engine: IAnalyticsEngine): void;
+    /**
+     * Finalize the analytics engine and return any summary output statements.
+     */
+    finalizeAnalytics(): IOutputStatement[];
+    /**
+     * Subscribe to stack snapshots. The observer receives a StackSnapshot
+     * on every push/pop/clear event. New subscribers immediately receive
+     * an 'initial' snapshot with the current stack state.
+     */
+    subscribeToStack(observer: StackObserver): Unsubscribe;
+    /**
+     * Cleanup method that properly unmounts and disposes all blocks in the stack.
+     */
+    dispose(): void;
+    /**
+     * Pushes a block onto the runtime stack.
+     * This is a convenience method that wraps PushBlockAction.
+     * Also handles hooks, tracking, wrapping, and logging if configured.
+     *
+     * @param block The block to push
+     * @param lifecycle Optional lifecycle options (startTime, etc.)
+     */
+    pushBlock(block: IRuntimeBlock, lifecycle?: BlockLifecycleOptions): void;
+    /**
+     * Pops the current block from the runtime stack.
+     * This is a convenience method that wraps PopBlockAction.
+     * Handles the full lifecycle: unmount, pop, dispose, and parent notification.
+     * Also handles hooks, tracking, wrapping cleanup, and logging if configured.
+     *
+     * @param lifecycle Optional lifecycle options (createdAt, etc.)
+     */
+    popBlock(lifecycle?: BlockLifecycleOptions): void;
+}
+
+/**
+ * Timer direction for count-down vs count-up.
+ */
+type TimerDirection = 'up' | 'down';
+/**
+ * Timer state stored in block memory.
+ *
+ * ## Glossary (docs/architecture/time-terminology.md)
+ * - `spans`      — **Time**: raw TimeSpan[] recordings the block tracks
+ * - `durationMs` — **Duration**: planned target from the parser (e.g., 300 000 ms for "5:00")
+ * - Derived values Elapsed and Total are computed from spans at collection time.
+ */
+interface TimerState {
+    /**
+     * **Time** — raw time segments being tracked.
+     * Source of truth for Elapsed (Σ span durations) and Total (wall-clock bracket).
+     */
+    readonly spans: readonly TimeSpan[];
+    /** **Duration** — planned target in ms from the parser (for countdowns or goals). */
+    readonly durationMs?: number;
+    /** Timer direction preference */
+    readonly direction: TimerDirection;
+    /** Human-readable label for the timer */
+    readonly label: string;
+    /** Timer role for UI prioritization */
+    readonly role?: 'primary' | 'secondary' | 'auto' | 'hidden';
+}
+/**
+ * Round state stored in memory.
+ * Represents current iteration and scale of a loop.
+ */
+interface RoundState {
+    /** Current round number (typically 1-based) */
+    readonly current: number;
+    /** Total number of rounds planned (undefined for unbounded) */
+    readonly total: number | undefined;
+}
+/** Written by ChildSelectionBehavior to children:status memory tag */
+interface ChildrenStatusState {
+    /** Index of the next child to dispatch (0-based) */
+    readonly childIndex: number;
+    /** Total number of child groups */
+    readonly totalChildren: number;
+    /** True when all child groups have been dispatched at least once */
+    readonly allExecuted: boolean;
+    /** True when all dispatched children have completed (popped) */
+    readonly allCompleted: boolean;
+}
+/**
+ * Fragment state stored in memory.
+ *
+ * Fragment groups represent semantic groupings from compilation (e.g., per-round,
+ * per-interval). Each inner array is one group produced by the metrics distributor.
+ * This preserves the multi-dimensional structure through the entire pipeline:
+ * Parser → Strategy → BlockBuilder → FragmentMemory → RuntimeBlock.metrics
+ */
+interface FragmentState {
+    /** Fragment groups — each inner array is a semantic group (e.g., per-round metrics) */
+    readonly groups: readonly MetricContainer[];
+}
+/**
+ * Display-ready metrics state stored in memory.
+ *
+ * Produced by applying precedence resolution to raw metrics groups.
+ * The `resolved` array contains metric after per-type precedence
+ * selection (user > runtime > compiler > parser).
+ */
+interface FragmentDisplayState {
+    /** All raw metrics flattened from groups (before precedence) */
+    readonly metrics: MetricContainer;
+    /** Precedence-resolved metric ready for display */
+    readonly resolved: readonly IMetric[];
+}
+/**
+ * Completion state stored in memory.
+ * Tracks whether a block has completed and why.
+ */
+interface CompletionState {
+    /** Whether block is marked complete */
+    readonly isComplete: boolean;
+    /** Reason for completion */
+    readonly reason?: 'timer-expired' | 'rounds-complete' | 'user-advance' | 'manual' | string;
+    /** Timestamp of completion (epoch ms) */
+    readonly createdAt?: number;
+}
+/**
+ * Display state stored in memory.
+ * UI-facing state for labels and modes.
+ */
+interface DisplayState {
+    /** Current display mode */
+    readonly mode: 'clock' | 'timer' | 'countdown' | 'hidden';
+    /** Primary label */
+    readonly label: string;
+    /** Secondary/subtitle label */
+    readonly subtitle?: string;
+    /** Formatted round string (e.g., "Round 2/5") */
+    readonly roundDisplay?: string;
+    /** Exercise/action being performed */
+    readonly actionDisplay?: string;
+}
+/**
+ * Button style variants for UI rendering.
+ */
+type ButtonVariant = 'primary' | 'secondary' | 'danger' | 'ghost';
+/**
+ * Configuration for a single control button.
+ */
+interface ButtonConfig {
+    /** Unique button identifier */
+    readonly id: string;
+    /** Display label */
+    readonly label: string;
+    /** Button style variant */
+    readonly variant: ButtonVariant;
+    /** Whether button is currently visible */
+    readonly visible: boolean;
+    /** Whether button is enabled (clickable) */
+    readonly enabled: boolean;
+    /**
+     * Event name to emit when clicked.
+     * External systems subscribe to these events to handle user actions.
+     * Examples: 'timer:pause', 'block:next', 'workout:stop'
+     */
+    readonly eventName?: string;
+    /**
+     * Whether this button is pinned (always visible).
+     * Derived from `[:!action]` syntax in Whiteboard scripts.
+     */
+    readonly isPinned?: boolean;
+}
+/**
+ * Buttons state stored in memory.
+ * Represents the current set of control buttons available to the user.
+ *
+ * The UI observes this memory to render action buttons. When buttons are
+ * clicked, the UI emits the corresponding `eventName` as an external event.
+ */
+interface ButtonsState {
+    /** Current button configurations */
+    readonly buttons: readonly ButtonConfig[];
+}
+/**
+ * Union of all valid memory type keys.
+ */
+type MemoryType = 'time' | 'round' | 'children:status' | 'metrics' | 'metric:display' | 'completion' | 'display' | 'controls';
+/**
+ * Registry mapping memory types to their corresponding data shapes.
+ * Enables compile-time type safety when accessing block memory.
+ *
+ * @example
+ * const timer = block.getMemoryByTag('time')[0]; // Returns IMemoryLocation with TimerState
+ */
+interface MemoryTypeMap {
+    'time': TimerState;
+    round: RoundState;
+    'children:status': ChildrenStatusState;
+    metrics: FragmentState;
+    'metric:display': FragmentDisplayState;
+    completion: CompletionState;
+    display: DisplayState;
+    controls: ButtonsState;
+}
+/**
+ * Utility to resolve the value type for a given memory type key.
+ */
+type MemoryValueOf<T extends MemoryType> = MemoryTypeMap[T];
+
+declare global {
+    interface Window {
+        __chromecast_senderClockTimeMs?: () => number;
+    }
+}
+/**
+ * Returns the canonical "now" used for runtime timer interpolation.
+ *
+ * Browser workbench: falls back to Date.now().
+ * Chromecast receiver: uses sender-synchronized clock when available.
+ */
+declare function getRuntimeNowMs(): number;
+/** Creates an INowProvider that reads the browser sender-clock when available. */
+declare function createBrowserRuntimeNow(): INowProvider;
+
+export { type EventHandlerOptions as $, type AnalyticsContext as A, type BehaviorEventType as B, type CompletionDecision as C, type IRuntimeMemory as D, type EffortResolverOptions as E, TypedMemoryReference as F, type MemorySearchCriteria as G, type IMemoryReference as H, type IScript as I, type StackObserver as J, type StackSnapshot as K, type StackListener as L, type MemoryTag as M, MemoryTypeEnum as N, type OutputListener as O, type IAnchorValue as P, type IEventHandler as Q, type ResolvedEffort as R, type SubscribeOptions as S, TimeSpan as T, type Unsubscribe as U, type HandlerScope as V, WhiteboardScript as W, type IScriptRuntime as X, type TestableBlockConfig as Y, type IRuntimeOptions as Z, ScriptRuntime as _, type IEffortResolver as a, type EventCallback as a0, type TimerState as a1, type IRealtimeProcessor as a2, type ISummaryProcessor as a3, type ProjectionResult as a4, type ButtonConfig as a5, type ButtonVariant as a6, type ButtonsState as a7, type ChildrenStatusState as a8, type CompletionState as a9, disciplineFactorFor as aA, filterTagsByVisibility as aB, frozenNow as aC, getMetricVisibility as aD, getRuntimeNowMs as aE, isEffortDiscipline as aF, isFragmentTag as aG, wallClockNow as aH, DEFAULT_RESOLVER_OPTIONS as aa, DISCIPLINE_FACTORS as ab, type DisplayState as ac, EFFORT_DISCIPLINES as ad, EFFORT_REGISTRY_ORIGINS as ae, type EffortBaseAttributes as af, type EffortDerivation as ag, type EffortDiscipline as ah, type EffortResolvedFrom as ai, type FenceDialect as aj, type FragmentDisplayState as ak, type FragmentState as al, type IAnalyticsProcessorDescriptor as am, INTENSITY_TIERS as an, type IntensityTier as ao, MemoryLocation as ap, type MemoryType as aq, type MemoryTypeMap as ar, type MemoryValueOf as as, type RoundState as at, type RuntimeState as au, type ScriptRuntimeDependencies as av, type TimerDirection as aw, VISIBILITY_ICONS as ax, VISIBILITY_LABELS as ay, createBrowserRuntimeNow as az, type IEffortRegistry as b, type IEffort as c, type EffortResolutionOptions as d, type EffortRegistrySource as e, type IRuntimeActionable as f, type IEventBus as g, type IRuntimeStack as h, type IRuntimeClock as i, type IJitCompiler as j, type INowProvider as k, type RuntimeStackOptions as l, type RuntimeError as m, type IEvent as n, type IRuntimeAction as o, type IAnalyticsEngine as p, type IRuntimeBlock as q, type IBehaviorContext as r, type BehaviorEventListener as s, type Unsubscribe$1 as t, type OutputOptions as u, type IMemoryLocation as v, type IRuntimeBehavior as w, type IBlockContext as x, type MetricVisibility as y, type BlockLifecycleOptions as z };