@bitcobblers/wod-wiki-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1075 @@
+/**
+ * Canonical ownership vocabulary for metric visibility decisions.
+ *
+ * This is intentionally separate from {@link MetricOrigin}, which still carries
+ * legacy producer/state detail used by existing callers.
+ *
+ * Ordered from lowest to highest ownership precedence.
+ */
+type MetricOwnershipLayer = 'parser' | 'dialect' | 'user-plan' | 'runtime' | 'user-entry';
+/**
+ * Canonical low->high ownership chain used by characterization tests and
+ * ownership resolution work.
+ */
+declare const METRIC_OWNERSHIP_LAYER_CHAIN: readonly MetricOwnershipLayer[];
+/**
+ * Compatibility map from the current mixed-purpose `origin` field into the
+ * canonical ownership-layer vocabulary.
+ */
+declare const LEGACY_ORIGIN_TO_OWNERSHIP_LAYER: Record<MetricOrigin, MetricOwnershipLayer>;
+interface MetricWithOptionalOwnershipLayer extends IMetric {
+    readonly ownershipLayer?: MetricOwnershipLayer;
+}
+interface MetricOwnershipQuery {
+    readonly types?: readonly (IMetric['type'])[];
+    readonly layers?: readonly MetricOwnershipLayer[];
+}
+type MetricOwnershipOutcome = 'visible' | 'hidden-by-layer' | 'hidden-by-suppressor' | 'suppressor';
+interface MetricOwnershipResolvedContribution {
+    readonly metric: IMetric;
+    readonly type: IMetric['type'];
+    readonly layer: MetricOwnershipLayer;
+    readonly outcome: MetricOwnershipOutcome;
+}
+interface MetricOwnershipPromotionCandidate {
+    readonly metric: IMetric;
+    readonly type: IMetric['type'];
+    readonly layer: MetricOwnershipLayer;
+    readonly reason: 'shadowed-by-higher-layer' | 'suppressed';
+    readonly blockedByLayer?: MetricOwnershipLayer;
+}
+interface MetricOwnershipTypeExplanation {
+    readonly type: IMetric['type'];
+    readonly winnerLayer?: MetricOwnershipLayer;
+    readonly suppressed: boolean;
+    readonly entries: readonly MetricOwnershipResolvedContribution[];
+}
+interface MetricOwnershipLedger {
+    raw(query?: MetricOwnershipQuery): IMetric[];
+    visible(query?: MetricOwnershipQuery): IMetric[];
+    byLayer(query?: MetricOwnershipQuery): Partial<Record<MetricOwnershipLayer, IMetric[]>>;
+    promotionCandidates(query?: MetricOwnershipQuery): MetricOwnershipPromotionCandidate[];
+    explain(query?: MetricOwnershipQuery): MetricOwnershipTypeExplanation[];
+}
+declare function getMetricOwnershipLayer(origin: MetricOrigin | undefined): MetricOwnershipLayer;
+
+/**
+ * Origin of a metric - where it was created and its current state.
+ *
+ * Source origins:
+ * - 'parser': Created by the parser from source text
+ * - 'compiler': Synthesized by a compiler strategy
+ * - 'dialect': Synthesized by a dialect policy before runtime
+ * - 'runtime': Generated during execution (e.g., elapsed time)
+ * - 'user': Collected from user input (e.g., actual reps completed)
+ *
+ * Value states:
+ * - 'collected': Value has been collected and populated
+ * - 'hinted': Value is a hint or suggestion not strictly enforced
+ * - 'tracked': Value is actively being tracked during execution
+ * - 'analyzed': Value is derived from analysis
+ * - 'analyzed-estimated': Value is derived from estimation
+ * - 'execution': Generated by runtime execution
+ * - 'user-plan': Planned override set by user before execution
+ */
+type MetricAction = 'suppress';
+type MetricOrigin = 'parser' | 'compiler' | 'dialect' | 'runtime' | 'user' | 'collected' | 'hinted' | 'tracked' | 'analyzed' | 'analyzed-estimated' | 'execution' | 'user-plan';
+type Origin = MetricOrigin;
+interface IMetric {
+    readonly image?: string;
+    readonly value?: unknown;
+    /**
+     * The metric type. Use a `MetricType` enum value for standard types, or any
+     * string for custom derived metrics produced by enrichment processes
+     * (e.g. `'speed'`, `'pace'`, `'rep-rate'`, `'power'`).
+     */
+    readonly type: MetricType | string;
+    /** Backward-compatible alias for type */
+    readonly metricType?: MetricType | string;
+    readonly origin: MetricOrigin;
+    readonly unit?: string;
+    /**
+     * Visibility instruction. The only live value is `'suppress'`, which hides
+     * all metrics of this type from display (resolved by the ownership ledger).
+     * Most metrics carry no action (undefined = passive).
+     */
+    readonly action?: MetricAction;
+    /**
+     * Block key that created/owns this metric.
+     * Present for runtime and user-collected metrics.
+     */
+    readonly sourceBlockKey?: string;
+    /**
+     * Timestamp when this metric was created/recorded.
+     * Present for runtime and user-collected metrics.
+     */
+    readonly timestamp?: Date;
+    /**
+     * Processor-attached structured payload. Summary processors (e.g. TIS) hang
+     * derivation metadata (effortSlug, effortDiscipline, effortIntensityTier,
+     * component scores) on the projection value metric; fact normalization reads
+     * it back out. Pure data — survives the stored-logs round-trip.
+     */
+    readonly metadata?: Record<string, unknown>;
+    /** Optional explicit ownership layer for legacy compatibility */
+    readonly ownershipLayer?: MetricOwnershipLayer;
+    /** Optional human-readable name or label */
+    readonly name?: string;
+}
+/**
+ * Metric type enumeration.
+ *
+ * Time-related terms follow the glossary in docs/architecture/time-terminology.md:
+ * - **Duration** (Parser)  — planned target from the script (e.g., "5:00" -> 300 000 ms)
+ * - **Time / Spans** (Block) — the raw TimeSpan[] start/stop recordings a block tracks
+ * - **TimeStamp** (Runtime) — system Date.now() when a message is logged
+ * - **Elapsed** (Runtime)  — Σ(end - start) of each span segment (active time, excludes pauses)
+ * - **Total** (Runtime)    — lastEnd - firstStart (wall-clock bracket, includes pauses)
+ */
+declare enum MetricType {
+    /**
+     * **Duration** (Core) — parser-defined planned target.
+     *
+     * A metric defined by the CodeStatement during parsing (e.g., "5:00" -> 300 000 ms).
+     * It can be a time (duration) or a placeholder to be resolved.
+     * Owned by the parser — the runtime reads it but never computes it.
+     */
+    Duration = "duration",
+    /**
+     * **Spans** (Core) — raw start/stop TimeSpan[] recordings.
+     *
+     * Source-of-truth data recorded using the runtime clock.
+     * Each span represents a continuous period of active (unpaused) execution.
+     * These can be recorded at runtime or back-filled during analytics.
+     */
+    Spans = "spans",
+    /**
+     * **SystemTime** (Core) — real system time (Date.now()) when a message is logged.
+     *
+     * Ground-truth wall-clock reference (timestamp) associated with system time metrics.
+     * Independent of the runtime clock.
+     */
+    SystemTime = "system-time",
+    /** Live timer state written into block memory by the count-up/count-down timer behaviors. */
+    Time = "time",
+    /** Active elapsed time — Σ(end - start) of active spans; derived during analytics. */
+    Elapsed = "elapsed",
+    /** Total wall-clock bracket (lastEnd - firstStart) for a block; derived during analytics. */
+    Total = "total",
+    Rep = "rep",
+    Effort = "effort",
+    Distance = "distance",
+    Rounds = "rounds",
+    CurrentRound = "current-round",
+    Action = "action",
+    Increment = "increment",
+    Group = "group",
+    Text = "text",
+    Resistance = "resistance",
+    Sound = "sound",
+    System = "system",
+    Label = "label",
+    Lap = "lap",
+    Metric = "metric",
+    /**
+     * **Hint** (Core) — a semantic marker emitted by a dialect or the parser.
+     *
+     * Dot-namespaced string markers (e.g. `workout.amrap`, `behavior.required_timer`)
+     * that strategies and the label composer query to drive compilation decisions.
+     * Hints are metrics so they flow through the single ownership channel, but they
+     * are excluded from display resolution and from runtime block fragments.
+     */
+    Hint = "hint",
+    /** Generic custom metric bucket for parser-owned property metrics. */
+    Custom = "custom",
+    Volume = "volume",
+    Intensity = "intensity",
+    Load = "load",
+    Work = "work",
+    /** Per-set Reps in Reserve (real-time, strength) */
+    RIR = "rir",
+    /** Post-session subjective effort rating (0–10) */
+    SessionRPE = "session-rpe",
+    /** Session RPE x total minutes */
+    SessionLoad = "session-load",
+    /** Normalized MET ((Activity METs ÷ METmax) x 100) */
+    METScore = "met-score",
+    /** Training Intensity Score (composite) */
+    TIS = "tis",
+    /** Runtime-layer calculated metric emitted from declarative formulas */
+    Calculated = "calculated",
+    /**
+     * **Choice** (Parser) — a pipe-separated OR expression.
+     *
+     * Emitted by Fusion when a pipe separates two homogeneous alternatives
+     * (same MetricType on both sides). Carries `alternatives: IMetric[]`.
+     * Resolved in the Pre-Run Wizard before the JIT compiles: the chosen
+     * alternative is written at origin `user-plan` into the Statement's
+     * MetricContainer, shadowing this group via ownership-layer precedence.
+     * Never reaches compiled Blocks or display output once resolved.
+     */
+    Choice = "choice"
+}
+/**
+ * Concrete helper class implementing IMetric
+ */
+declare class Metric implements IMetric {
+    readonly type: MetricType | string;
+    readonly metricType?: MetricType | string;
+    readonly value?: unknown;
+    readonly origin: MetricOrigin;
+    readonly unit?: string;
+    readonly action?: MetricAction;
+    readonly image?: string;
+    readonly sourceBlockKey?: string;
+    readonly timestamp?: Date;
+    readonly metadata?: Record<string, unknown>;
+    readonly name?: string;
+    readonly ownershipLayer?: MetricOwnershipLayer;
+    constructor(typeOrName: MetricType | string, valueOrType?: unknown, originOrValue?: unknown, unit?: string, origin?: MetricOrigin | string, action?: MetricAction | string, image?: string);
+    toNumber(): number;
+}
+
+/**
+ * Filter configuration for metric retrieval.
+ */
+interface MetricFilter {
+    /** Only include metrics with these origins */
+    origins?: MetricOrigin[];
+    /** Only include these metric types */
+    types?: (MetricType | string)[];
+    /** Exclude these metric types */
+    excludeTypes?: (MetricType | string)[];
+}
+/**
+ * Unified contract for any data object that provides displayable metrics.
+ *
+ * Implemented by CodeStatement, OutputStatement, and MetricContainer.
+ * Consumed directly by UI components.
+ *
+ * All metric access goes through this interface, ensuring:
+ * 1. Consistent precedence resolution
+ * 2. Multi-metric-per-type support
+ * 3. Origin-aware filtering
+ * 4. Source-type-agnostic UI rendering
+ */
+interface IMetricSource {
+    /**
+     * Unique identifier for React keys and tracking.
+     */
+    readonly id: string | number;
+    /**
+     * Get the "display-ready" metrics after precedence resolution.
+     *
+     * For each MetricType present, returns metrics from the highest-
+     * precedence origin tier. Multiple metrics of the same type within
+     * the winning tier are preserved (e.g., 3 rep metrics for 21-15-9).
+     *
+     * @param filter Optional filter to restrict which metrics are returned
+     */
+    getDisplayMetrics(filter?: MetricFilter): IMetric[];
+    /**
+     * Get the highest-precedence single metric of a given type.
+     *
+     * Precedence order: user-entry > runtime > user-plan > dialect > parser
+     *
+     * @param type The metric type to look up
+     * @returns The winning metric, or undefined if none exist
+     */
+    getMetric(type: MetricType | string): IMetric | undefined;
+    /**
+     * Get ALL metrics of a given type, ordered by precedence (highest first).
+     *
+     * Use when multiple metrics of the same type are meaningful
+     * (e.g., rep scheme 21-15-9, multiple actions in a complex).
+     */
+    getAllMetricsByType(type: MetricType | string): IMetric[];
+    /**
+     * Check if any metric of this type exists (at any precedence level).
+     */
+    hasMetric(type: MetricType | string): boolean;
+    /**
+     * Access the raw, unfiltered metrics for debugging or advanced use.
+     * No precedence resolution applied.
+     */
+    readonly rawMetrics: IMetric[];
+}
+
+interface ICodeMetadata {
+    line: number;
+    startOffset: number;
+    endOffset: number;
+    columnStart: number;
+    columnEnd: number;
+    length: number;
+    raw?: string;
+}
+declare class CodeMetadata implements ICodeMetadata {
+    line: number;
+    startOffset: number;
+    endOffset: number;
+    length: number;
+    columnStart: number;
+    columnEnd: number;
+    raw: string;
+    constructor(line: number, startOffset: number, endOffset: number, length: number, columnStart?: number, columnEnd?: number, raw?: string);
+}
+
+/**
+ * MetricContainer — a typed collection for `IMetric` objects.
+ *
+ * Provides lookup, add, remove, merge, and iteration operations over a
+ * flat `IMetric[]` array. Standard way to work with metric collections on
+ * `ICodeStatement`, `IRuntimeBlock`, and `OutputStatement`.
+ *
+ * Numeric indexes are mirrored for backwards compatibility with legacy
+ * `metrics[0]` call sites.
+ */
+declare class MetricContainer implements IMetricSource, Iterable<IMetric> {
+    [index: number]: IMetric;
+    private _metrics;
+    private _indexedLength;
+    private readonly _resolver;
+    readonly id: string | number;
+    constructor(metrics?: IMetric[] | MetricContainer, id?: string | number);
+    /**
+     * Create a container from an existing metric array, MetricContainer, or
+     * a deserialized plain object.
+     */
+    static from(metrics: IMetric[] | MetricContainer | undefined | unknown, id?: string | number): MetricContainer;
+    /** Create an empty container. */
+    static empty(id?: string | number): MetricContainer;
+    /** Create a defensive copy of this container. */
+    clone(id?: string | number): MetricContainer;
+    /** All metrics in insertion order. Returns a defensive copy. */
+    get all(): readonly IMetric[];
+    /** Number of metrics in the container. */
+    get length(): number;
+    /** Alias for length */
+    get size(): number;
+    /** Whether the container has no metrics. */
+    get isEmpty(): boolean;
+    /**
+     * Get all metrics of a given MetricType / name, sorted by ownership layer
+     * (highest precedence first).
+     */
+    getByType(type: MetricType | string): IMetric[];
+    /**
+     * Get the highest-precedence metric of a given type/name, or undefined.
+     */
+    getFirst(type: MetricType | string): IMetric | undefined;
+    /**
+     * Lookup a metric by type or name.
+     */
+    get(type: MetricType | string): IMetric | undefined;
+    /** Whether any metric of the given type/name exists. */
+    has(type: MetricType | string): boolean;
+    hasMetric(type: MetricType | string): boolean;
+    getDisplayMetrics(filter?: MetricFilter): IMetric[];
+    getMetric(type: MetricType | string): IMetric | undefined;
+    getAllMetricsByType(type: MetricType | string): IMetric[];
+    get rawMetrics(): IMetric[];
+    getAll(): IMetric[];
+    /**
+     * Get all metrics matching the given origin.
+     */
+    getByOrigin(origin: MetricOrigin): IMetric[];
+    /**
+     * Apply the standard precedence resolution algorithm.
+     */
+    resolve(filter?: MetricFilter): IMetric[];
+    /** Append one or more metrics. */
+    add(...metrics: IMetric[]): this;
+    /**
+     * Remove metrics matching a predicate.
+     * Returns the removed metrics.
+     */
+    remove(predicate: (m: IMetric) => boolean): IMetric[];
+    /**
+     * Remove all metrics of a given type.
+     * Returns the removed metrics.
+     */
+    removeByType(type: MetricType | string): IMetric[];
+    /** Remove all metrics. */
+    clear(): this;
+    /**
+     * Replace all metrics of a given type with new ones.
+     */
+    replaceByType(type: MetricType | string, ...replacements: IMetric[]): IMetric[];
+    /**
+     * Merge another container (or raw array) into this one.
+     */
+    merge(other: MetricContainer | IMetric[] | {
+        metrics: MetricContainer;
+    }): this;
+    /** Iterate over all metrics. */
+    [Symbol.iterator](): Iterator<IMetric>;
+    /** Filter metrics, returning a new array. */
+    filter(predicate: (m: IMetric) => boolean): IMetric[];
+    /** Map metrics to a new array. */
+    map<T>(fn: (m: IMetric, index: number) => T): T[];
+    /** Flat-map metrics to a new array. */
+    flatMap<T>(fn: (m: IMetric, index: number) => T | readonly T[]): T[];
+    /** Find the first metric matching a predicate. */
+    find(predicate: (m: IMetric) => boolean): IMetric | undefined;
+    /** Whether any metric matches the predicate. */
+    some(predicate: (m: IMetric) => boolean): boolean;
+    /** Whether all metrics match the predicate. */
+    every(predicate: (m: IMetric) => boolean): boolean;
+    /** Return a mutable copy of the underlying array. */
+    toArray(): IMetric[];
+    /** Spread-friendly: returns the underlying array (no copy). */
+    get raw(): IMetric[];
+    private syncIndexProperties;
+    toString(): string;
+}
+
+interface ICodeStatement extends IMetricSource {
+    id: number;
+    parent?: number;
+    children: number[][];
+    exerciseId?: string;
+    metrics: MetricContainer;
+    isLeaf?: boolean;
+    meta: CodeMetadata;
+    metricMeta: Map<IMetric, CodeMetadata>;
+    line?: number;
+    text?: string;
+    raw?: string;
+    dialect?: string;
+}
+declare abstract class CodeStatement implements ICodeStatement, IMetricSource {
+    abstract id: number;
+    abstract parent?: number;
+    abstract children: number[][];
+    abstract meta: CodeMetadata;
+    abstract metrics: MetricContainer;
+    abstract metricMeta: Map<IMetric, CodeMetadata>;
+    abstract isLeaf?: boolean;
+    exerciseId?: string;
+    line?: number;
+    text?: string;
+    raw?: string;
+    dialect?: string;
+    hasMetric(type: MetricType | string): boolean;
+    getDisplayMetrics(filter?: MetricFilter): IMetric[];
+    getMetric(type: MetricType | string): IMetric | undefined;
+    getAllMetricsByType(type: MetricType | string): IMetric[];
+    get rawMetrics(): IMetric[];
+    private get metricContainer();
+}
+declare class ParsedCodeStatement extends CodeStatement {
+    id: number;
+    parent?: number;
+    children: number[][];
+    meta: CodeMetadata;
+    private _metrics;
+    metricMeta: Map<IMetric, CodeMetadata>;
+    isLeaf?: boolean;
+    get metrics(): MetricContainer;
+    set metrics(metrics: MetricContainer | IMetric[]);
+    constructor(init?: Partial<ParsedCodeStatement>);
+}
+
+/**
+ * TimeSpan represents a discrete start/stop segment of time.
+ *
+ * Core keeps this as a pure data shape with zero runtime dependencies.
+ */
+interface TimeSpan {
+    started: number;
+    ended?: number;
+}
+
+/**
+ * Output statement types indicating what kind of result this represents.
+ *
+ * - 'segment': A timed portion of execution (e.g., a round, an effort interval)
+ * - 'milestone': A notable event during execution (e.g., halfway point, personal record)
+ * - 'system': Debug/diagnostic output from lifecycle events
+ * - 'event': Tracks external stimuli or internal triggers
+ * - 'group': Identified segment with children
+ * - 'load': Initial script state
+ * - 'compiler': Behavior configuration and setup
+ * - 'analytics': Output generated by the analytics engine
+ */
+type OutputStatementType = 'segment' | 'milestone' | 'completion' | 'metric' | 'system' | 'event' | 'group' | 'load' | 'compiler' | 'analytics';
+/**
+ * IOutputStatement extends ICodeStatement to represent runtime-generated output.
+ *
+ * This is the return type of execution — what "came out" of running a statement.
+ */
+interface IOutputStatement extends ICodeStatement, IMetricSource {
+    readonly id: number;
+    readonly outputType: OutputStatementType;
+    readonly timeSpan: TimeSpan;
+    readonly sourceStatementId?: number;
+    readonly sourceBlockKey: string;
+    readonly stackLevel: number;
+    readonly metrics: MetricContainer;
+    readonly metricMeta: Map<IMetric, CodeMetadata>;
+    readonly completionReason?: string;
+    readonly statement?: ICodeStatement;
+    readonly timestamp?: number;
+}
+/**
+ * Options for creating an OutputStatement.
+ */
+interface OutputStatementOptions {
+    /** Output type classification */
+    outputType: OutputStatementType;
+    /** Execution timing */
+    timeSpan: TimeSpan;
+    /** The block key that produced this output */
+    sourceBlockKey?: string;
+    /** Stack level (depth) when this output was emitted */
+    stackLevel?: number;
+    /** The source statement ID (optional) */
+    sourceStatementId?: number;
+    /** Runtime-collected metrics */
+    metrics?: MetricContainer | IMetric[];
+    /** Map of metrics to metadata */
+    metricMeta?: Map<IMetric, CodeMetadata>;
+    /** Reason the block completed (e.g., 'user-advance', 'forced-pop') */
+    completionReason?: string;
+    /** Parent output statement ID (for hierarchy) */
+    parent?: number;
+    /** Child output statement groups (for hierarchy) */
+    children?: number[][];
+}
+/**
+ * Concrete implementation of IOutputStatement.
+ */
+declare class OutputStatement implements IOutputStatement, IMetricSource {
+    private static nextId;
+    readonly id: number;
+    readonly outputType: OutputStatementType;
+    readonly timeSpan: TimeSpan;
+    readonly sourceStatementId?: number;
+    readonly sourceBlockKey: string;
+    readonly stackLevel: number;
+    readonly metrics: MetricContainer;
+    readonly metricMeta: Map<IMetric, CodeMetadata>;
+    readonly completionReason?: string;
+    readonly parent?: number;
+    readonly children: number[][];
+    readonly isLeaf: boolean;
+    readonly meta: CodeMetadata;
+    readonly statement?: ICodeStatement;
+    readonly timestamp?: number;
+    constructor(optionsOrStatement: OutputStatementOptions | ICodeStatement, metricsArg?: MetricContainer | IMetric[], timestamp?: number);
+    getDisplayMetrics(filter?: MetricFilter): IMetric[];
+    getMetric(type: MetricType | string): IMetric | undefined;
+    getAllMetricsByType(type: MetricType | string): IMetric[];
+    hasMetric(type: MetricType | string): boolean;
+    get rawMetrics(): IMetric[];
+    /**
+     * Reset the ID counter (useful for testing)
+     */
+    static resetIdCounter(startAt?: number): void;
+}
+
+interface IMetricContainer extends IMetricSource {
+    metrics: MetricContainer;
+    clone(): IMetricContainer;
+    merge(other: IMetricContainer | MetricContainer): this;
+}
+type SummaryStage = 'estimate' | 'summary';
+interface IMetricSummary extends IMetricContainer {
+    readonly stage: SummaryStage;
+    readonly sourceId: string | number;
+    readonly producedAt: Date;
+}
+interface IEstimate extends IMetricSummary {
+    readonly stage: 'estimate';
+}
+interface ISummary extends IMetricSummary {
+    readonly stage: 'summary';
+    readonly spans: IOutputStatement[];
+}
+
+/**
+ * Unified resolver for metric ownership precedence.
+ *
+ * Implements the canonical 5-tier ownership ledger resolution:
+ * parser -> dialect -> user-plan -> runtime -> user-entry
+ */
+interface IMetricOwnershipResolver {
+    /** Resolve display-ready metrics, applying optional type/layer filters. */
+    resolve(metrics: readonly IMetric[], filter?: MetricFilter): IMetric[];
+    /** Resolve the single winning metric of a given type, or undefined. */
+    resolveOne(metrics: readonly IMetric[], type: MetricType | string): IMetric | undefined;
+    /** Resolve all metrics of a given type, sorted by ownership tier (highest first). */
+    resolveAll?(metrics: readonly IMetric[], type: MetricType | string): IMetric[];
+}
+
+/**
+ * Tag-Identity Registry Contract
+ *
+ * Single source of truth for dialect fence tags and runnable state,
+ * as defined in docs/adr/dialect-block-alignment.md and docs/adr/language-pack-api.md.
+ */
+interface IDialectTagDescriptor {
+    /** Canonical fence tag (e.g. 'time', 'climb', 'wod') */
+    readonly tag: string;
+    /** Optional fence aliases (e.g. ['whiteboard', 'wod']) */
+    readonly aliases?: readonly string[];
+    /** Optional human-readable name */
+    readonly name?: string;
+    /** Whether blocks using this dialect produce runnable executions */
+    readonly runnable?: boolean;
+}
+
+declare function createMetricOwnershipLedger(metrics: readonly IMetric[]): MetricOwnershipLedger;
+
+/**
+ * Ownership layer rank for a metric (0 = lowest = parser, 4 = highest = user-entry).
+ * Higher rank wins.
+ */
+declare function ownershipRank(metric: IMetric): number;
+/**
+ * Single-path resolver wrapping `MetricOwnershipLedger` + legacy filter translation.
+ */
+declare class OwnershipResolver implements IMetricOwnershipResolver {
+    resolve(metrics: readonly IMetric[], filter?: MetricFilter): IMetric[];
+    resolveOne(metrics: readonly IMetric[], type: MetricType | string): IMetric | undefined;
+    resolveAll(metrics: readonly IMetric[], type: MetricType | string): IMetric[];
+}
+
+interface IDuration {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+    original?: number;
+}
+declare class Duration implements IDuration {
+    original?: number | undefined;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+    constructor(original?: number | undefined);
+}
+declare class SpanDuration extends Duration {
+    constructor(spans: TimeSpan[]);
+}
+
+interface IBlockKey {
+    readonly value: string;
+    toString(): string;
+    valueOf(): string;
+    equals(other: IBlockKey): boolean;
+}
+declare class BlockKey implements IBlockKey {
+    readonly value: string;
+    constructor(value?: string);
+    toString(): string;
+    valueOf(): string;
+    equals(other: IBlockKey): boolean;
+}
+
+/**
+ * Result of dialect analysis on a statement.
+ */
+interface DialectAnalysis {
+    /**
+     * Metrics emitted by the dialect: hint markers plus any dialect-specific
+     * values.
+     */
+    metrics?: MetricContainer;
+}
+/**
+ * Dialect interface for semantic marker generation.
+ */
+interface IDialect {
+    /** Unique dialect identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /**
+     * Optionally rewrite the statement's metrics in place before analyze.
+     */
+    transform?(statement: ICodeStatement): void;
+    /**
+     * Analyze a statement and return emitted metrics (hint markers + values).
+     */
+    analyze(statement: ICodeStatement): DialectAnalysis;
+}
+
+/**
+ * Status of a display entry in the execution lifecycle
+ */
+type DisplayStatus = 'pending' | 'active' | 'completed' | 'failed' | 'skipped';
+/**
+ * Visual size configurations for display components
+ */
+type VisualizerSize = 'compact' | 'normal' | 'focused';
+/**
+ * Filter configuration for metrics within display entries
+ */
+interface VisualizerFilter {
+    /** Only show metrics with these origins. If undefined, show all. */
+    allowedOrigins?: MetricOrigin[];
+    /** Hide metrics of these types (overrides allowedOrigins) */
+    typeOverrides?: Record<string, boolean>;
+    /** Hide specific named metrics (overrides everything) */
+    nameOverrides?: Record<string, boolean>;
+}
+
+/**
+ * Configuration for a single graph/metric to be displayed
+ */
+interface AnalyticsGraphConfig {
+    id: string;
+    label: string;
+    unit: string;
+    color: string;
+    dataKey: string;
+    icon?: string;
+}
+/**
+ * Grouping of analytics graphs
+ */
+interface AnalyticsGroup {
+    id: string;
+    name: string;
+    icon?: string;
+    graphs: AnalyticsGraphConfig[];
+}
+interface Segment {
+    id: number;
+    name: string;
+    type: string;
+    startTime: number;
+    endTime: number;
+    /** Wall-clock start time in milliseconds since epoch */
+    absoluteStartTime?: number;
+    /** Duration (Intent) - Parser-defined planned target in seconds */
+    duration?: number;
+    /** Elapsed (Active) - pause-aware active time in seconds */
+    elapsed: number;
+    /** Total (Wall-clock) - total time from first start to last end in seconds */
+    total: number;
+    parentId: number | null;
+    depth: number;
+    metric: Record<string, number>;
+    lane: number;
+    /** Raw time spans from the output statement (seconds relative to workout start) */
+    spans?: {
+        started: number;
+        ended?: number;
+    }[];
+    /** Optional metrics carried from runtime spans for visualization */
+    metrics?: MetricContainer;
+}
+
+/**
+ * Plain-data snapshot of a runtime OutputStatement safe for JSON / IndexedDB
+ * round-trips. Class methods and non-serialisable fields (Set, Map,
+ * MetricContainer instances) are intentionally excluded.
+ *
+ * The live->stored converter `toStoredOutputStatement` lives in `@bitcobblers/wod-wiki-lang`
+ * because it requires the hint evaluation protocol.
+ */
+interface StoredOutputStatement {
+    readonly id?: number;
+    readonly line?: number;
+    readonly text?: string;
+    readonly dialect?: string;
+    readonly outputType?: OutputStatementType;
+    readonly timeSpan?: {
+        started: number;
+        ended?: number;
+    };
+    /** Flat IMetric array — MetricContainer class not needed after serialisation. */
+    readonly metrics: IMetric[] | {
+        name?: string;
+        type?: string;
+        value?: unknown;
+        unit?: string;
+        origin?: string;
+    }[];
+    /** Plain string array — Set<string> does not survive JSON serialisation. */
+    readonly hints?: string[];
+    readonly sourceBlockKey?: string;
+    readonly stackLevel?: number;
+    readonly parent?: number;
+    readonly sourceStatementId?: number;
+    readonly completionReason?: string;
+    readonly timestamp?: number;
+}
+/**
+ * Results from a completed workout.
+ */
+interface WorkoutResults {
+    /** When workout started */
+    startTime: number;
+    /** When workout ended */
+    endTime: number;
+    /** Total elapsed time (ms) */
+    duration?: number;
+    /** Rounds completed (for rounds-based workouts) */
+    roundsCompleted?: number;
+    /** Total rounds (for rounds-based workouts) */
+    totalRounds?: number;
+    /** Reps completed (for rep-based workouts) */
+    repsCompleted?: number;
+    /**
+     * Plain-data runtime output log — safe for IndexedDB storage and JSON
+     * round-trips. Populated by serialising live IOutputStatement values via
+     * `toStoredOutputStatement()` at workout completion.
+     *
+     * Single stream holding ALL tiers: Tier 0 (raw tracking) + Tier 1 (inline
+     * annotations) + Tier 2 (summary outputs, outputType 'analytics').
+     */
+    logs?: StoredOutputStatement[];
+    /** Whether workout was completed or stopped early */
+    completed: boolean;
+}
+
+type SegmentDataType = 'script' | 'youtube' | 'markdown' | 'header' | 'frontmatter' | 'wod' | 'title' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+type NoteKind = 'note' | 'template' | 'playground' | 'journal';
+interface Note {
+    id: string;
+    title: string;
+    slug?: string;
+    pageId?: string;
+    createdAt: number;
+    type?: NoteKind;
+    sourceId?: string;
+    catalog?: string;
+    tags?: string[];
+}
+interface Page {
+    id: string;
+    date?: string;
+    slug?: string;
+    title?: string;
+    createdAt: number;
+}
+type TagType = 'template' | 'playground' | 'qualification' | 'notebook' | 'general';
+interface Tag {
+    id: string;
+    label: string;
+    type?: TagType;
+    createdAt: number;
+}
+interface NoteTag {
+    id: string;
+    noteId: string;
+    tagId: string;
+}
+interface NoteSegment {
+    id: string;
+    version: number;
+    noteId: string;
+    position?: number;
+    pageId?: string;
+    dataType: SegmentDataType;
+    data: unknown;
+    rawContent: string;
+    createdAt: number;
+    updatedAt?: number;
+    isHistory?: boolean;
+}
+interface BlockIndexRow {
+    /** Composite key: `${noteId}:${segmentId}:${segmentVersion}` */
+    id: string;
+    noteId: string;
+    segmentId: string;
+    segmentVersion: number;
+    position?: number;
+    dataType: string;
+    blockContentId?: string;
+    rawContent: string;
+    noteTitle: string;
+    createdAt: number;
+    isStatic?: boolean;
+    sourceId?: string;
+}
+type ResultOrigin = 'journal' | 'playground';
+interface WorkoutResult {
+    id: string;
+    segmentId?: string;
+    segmentVersion?: number;
+    noteId: string;
+    blockId?: string;
+    blockContentId?: string;
+    version?: number;
+    origin?: ResultOrigin;
+    pageId?: string;
+    data: WorkoutResults;
+    createdAt: number;
+}
+interface Attachment {
+    id: string;
+    noteId: string;
+    pageId?: string;
+    resultId?: string;
+    mimeType: string;
+    label: string;
+    data: ArrayBuffer | string;
+    timeSpan: {
+        start: number;
+        end: number;
+    };
+    createdAt: number;
+}
+interface AnalyticsDataPoint {
+    id: string;
+    noteId: string;
+    blockContentId?: string;
+    origin?: ResultOrigin;
+    pageId?: string;
+    grain?: 'segment' | 'summary' | 'rollup';
+    effortSlug?: string;
+    discipline?: string;
+    intensityTier?: string;
+    grade?: string;
+    segmentId: string;
+    segmentVersion: number;
+    resultId: string;
+    type: string;
+    value: unknown;
+    unit?: string;
+    label: string;
+    metricKey?: string;
+    metricLabel?: string;
+    metricUnit?: string;
+    timestamp: number;
+    createdAt: number;
+}
+
+/**
+ * State of a WOD block
+ */
+type ScriptBlockState = 'idle' | 'parsing' | 'parsed' | 'error' | 'starting' | 'running' | 'paused' | 'completed' | 'stopped';
+/**
+ * Parse error information
+ */
+interface ParseError {
+    message: string;
+    line?: number;
+    column?: number;
+    token?: unknown;
+    excerpt?: string;
+    severity?: 'error' | 'warning' | 'info';
+}
+/** Workout fence tags — `time` is runnable, `log` is recorded */
+type FenceDialect = 'time' | 'log';
+/** Ordered list of recognised workout fence tags */
+declare const VALID_FENCE_DIALECTS: FenceDialect[];
+/**
+ * Run affordance for a fence base tag:
+ * `'time'` -> `'run'` (runnable) · `'log'` -> `'log'` (log-mode runtime) · else `null`.
+ */
+declare function runAffordance(baseTag: string): 'run' | 'log' | null;
+/** Section types the editor can parse and render */
+type SectionType = 'title' | 'markdown' | 'time' | 'log' | 'frontmatter' | 'embed';
+/** Workout section types — the runnable/recorded fence tags */
+type WorkoutSectionType = Extract<SectionType, FenceDialect>;
+/** Type guard for workout sections */
+declare function isWorkoutSectionType(type: SectionType): type is WorkoutSectionType;
+/** Typed front matter subtypes */
+type FrontMatterSubtype = 'default' | 'youtube' | 'strava' | 'amazon' | 'file' | 'effort';
+/**
+ * Represents a single WOD block within the markdown document
+ */
+interface ScriptBlock {
+    /** Unique identifier for this block */
+    id: string;
+    /** Content-stable identity */
+    contentId?: string;
+    /** Workout fence tag ('time' runnable / 'log' recorded) */
+    dialect?: FenceDialect;
+    /** Sport suffix from the fence */
+    sport?: string;
+    /** Line number where ```time/```log appears (0-indexed) */
+    startLine: number;
+    /** Line number where closing ``` appears (0-indexed) */
+    endLine: number;
+    /** Raw text content of the WOD block */
+    content: string;
+    /** Parsed statements (populated after parsing) */
+    statements?: ICodeStatement[];
+    /** Parse errors, if any */
+    errors?: ParseError[];
+    /** Execution state */
+    state: ScriptBlockState;
+    /** Collected workout data (after completion) */
+    results?: WorkoutResults;
+    /** Block version */
+    version: number;
+    /** Creation timestamp */
+    createdAt: number;
+}
+/**
+ * A single section in the document — the atomic unit of display and editing.
+ */
+interface Section {
+    id: string;
+    contentId?: string;
+    type: SectionType;
+    rawContent: string;
+    displayContent: string;
+    startLine: number;
+    endLine: number;
+    lineCount: number;
+    level?: number;
+    sport?: string;
+    scriptBlock?: ScriptBlock;
+    properties?: Record<string, string>;
+    frontmatterType?: FrontMatterSubtype;
+    embed?: {
+        type: 'image' | 'link' | 'youtube';
+        label: string;
+        url: string;
+        isImage: boolean;
+    };
+    version: number;
+    createdAt: number;
+    deleted?: boolean;
+}
+/**
+ * The full document as an ordered section list.
+ */
+interface SectionDocument {
+    sections: Section[];
+    totalLines: number;
+    activeSectionId: string | null;
+}
+
+/**
+ * Notebook Types
+ *
+ * A notebook is a named, tag-based collection of workout entries.
+ */
+interface Notebook {
+    id: string;
+    name: string;
+    description: string;
+    icon: string;
+    createdAt: number;
+    lastEditedAt: number;
+}
+declare const NOTEBOOK_TAG_PREFIX = "notebook:";
+declare const toNotebookTag: (notebookId: string) => string;
+declare const fromNotebookTag: (tag: string) => string | null;
+declare const isNotebookTag: (tag: string) => boolean;
+
+/**
+ * Represents a parsed workout script
+ */
+interface IScript {
+    source: string;
+    statements: ICodeStatement[];
+    errors?: ParseError[];
+    getIds(ids: (number | string)[]): ICodeStatement[];
+    getId(id: number | string): ICodeStatement | undefined;
+    getAt(index: number): ICodeStatement | undefined;
+}
+
+export { type AnalyticsDataPoint, type AnalyticsGraphConfig, type AnalyticsGroup, type Attachment, type BlockIndexRow, BlockKey, CodeMetadata, CodeStatement, type DialectAnalysis, type DisplayStatus, Duration, type FenceDialect, type FrontMatterSubtype, type IBlockKey, type ICodeMetadata, type ICodeStatement, type IDialect, type IDialectTagDescriptor, type IDuration, type IEstimate, type IMetric, type IMetricContainer, type IMetricOwnershipResolver, type IMetricSource, type IMetricSummary, type IOutputStatement, type IScript, type ISummary, LEGACY_ORIGIN_TO_OWNERSHIP_LAYER, METRIC_OWNERSHIP_LAYER_CHAIN, Metric, type MetricAction, MetricContainer, type MetricFilter, type MetricOrigin, type MetricOwnershipLayer, type MetricOwnershipLedger, type MetricOwnershipOutcome, type MetricOwnershipPromotionCandidate, type MetricOwnershipQuery, type MetricOwnershipResolvedContribution, type MetricOwnershipTypeExplanation, MetricType, type MetricWithOptionalOwnershipLayer, NOTEBOOK_TAG_PREFIX, type Note, type NoteKind, type NoteSegment, type NoteTag, type Notebook, type Origin, OutputStatement, type OutputStatementOptions, type OutputStatementType, OwnershipResolver, type Page, type ParseError, ParsedCodeStatement, type ResultOrigin, type ScriptBlock, type ScriptBlockState, type Section, type SectionDocument, type SectionType, type Segment, type SegmentDataType, SpanDuration, type StoredOutputStatement, type SummaryStage, type Tag, type TagType, type TimeSpan, VALID_FENCE_DIALECTS, type VisualizerFilter, type VisualizerSize, type WorkoutResult, type WorkoutResults, type WorkoutSectionType, createMetricOwnershipLedger, fromNotebookTag, getMetricOwnershipLayer, isNotebookTag, isWorkoutSectionType, ownershipRank, runAffordance, toNotebookTag };