@bitcobblers/wod-wiki-lang 0.43.2153 → 0.44.2155

package/dist/{browserRuntimeNow-M4hQ_DTl.d.cts → browserRuntimeNow-_zhhbzoE.d.cts}

@@ -1,4 +1,4 @@
-import { ReferenceMatchKind, ReferenceRef, ReferenceDiagnostic, ICodeStatement, ParseError, MetricContainer, IMetric, BlockKey, TimeSpan as TimeSpan$1, OutputStatementType, MetricType, IOutputStatement, MetricOrigin } from '@bitcobblers/wod-wiki-core';
+import { ReferenceMatchKind, ReferenceRef, ReferenceDiagnostic, ICodeStatement, ParseError, TagIndex, MetricContainer, IMetric, BlockKey, TimeSpan as TimeSpan$1, OutputStatementType, TagReferenceMetadata, MetricType, IOutputStatement, MetricOrigin } from '@bitcobblers/wod-wiki-core';
 
 /**
  * Canonical discipline vocabulary — the single source of truth for effort
@@ -587,6 +587,260 @@ interface TestableBlockConfig {
     disposeOverride?: (runtime: IRuntimeActionable) => void;
 }
 
+/**
+ * Sound profiles — user-defined rule sets that drive workout audio.
+ *
+ * A profile is a list of rules. Each rule names a **trigger point** (an offset
+ * relative to the block's own duration) and the **sound** to play there. The
+ * profile therefore decides both *when* a sound fires and *what* it is.
+ *
+ * ## Trigger notation
+ *
+ * A trigger is a duration offset written in the whiteboard duration notation,
+ * with a leading anchor that says which end of the block it counts from:
+ *
+ * - `:00` — the **start** of the block (elapsed = 0).
+ * - `-:00` — the **end** of the block (remaining = 0).
+ * - `-:03` — three seconds before the end (remaining).
+ * - `:05:00` — five minutes after the start (elapsed).
+ *
+ * The magnitude accepts every duration spelling the language already
+ * understands — `05:00`, `5:00`, `00:05:00` and `5` all mean the same
+ * duration. The anchor is what distinguishes the two families:
+ *
+ * | Anchor | Counts from | Fires when |
+ * |--------|-------------|------------|
+ * | `:`    | block start | elapsed reaches the offset |
+ * | `-:`   | block end   | remaining falls to the offset |
+ *
+ * Because the offset is relative to the block's own duration, one profile
+ * works for any block length: the same `-:03` rule beeps three seconds
+ * before the end of a 5:00 run and three seconds before the end of a 1:00
+ * rest.
+ */
+/** Which end of the block a trigger counts from. */
+type SoundTriggerAnchor = 'start' | 'end';
+/** A trigger point: an anchor plus an offset from that anchor. */
+interface SoundTriggerPoint {
+    /** Counts from the block's start (`start`) or its end (`end`). */
+    readonly anchor: SoundTriggerAnchor;
+    /** Offset from the anchor, in milliseconds. Never negative. */
+    readonly offsetMs: number;
+}
+/** One rule in a profile: a trigger point plus the sound to play there. */
+interface SoundRule {
+    /** When the sound fires. */
+    readonly trigger: SoundTriggerPoint;
+    /** Name of the sound to play. Resolved against the app's sound table. */
+    readonly sound: string;
+}
+/** A named, user-defined set of sound rules. */
+interface SoundProfile {
+    /** Stable identifier (slug). Unique across profiles. */
+    readonly id: string;
+    /** Human-readable name shown in Settings. */
+    readonly name: string;
+    /** The rules, in declaration order. */
+    readonly rules: readonly SoundRule[];
+}
+/**
+ * Parse a trigger notation into a {@link SoundTriggerPoint}.
+ *
+ * The anchor says which end of the block the offset counts from:
+ *
+ * - `:` — from the block's start (elapsed). This is the default, so the
+ *   magnitude may be written with or without it: `:05:00`, `05:00`,
+ *   `00:05:00` and `5:00` all mean five minutes from the start.
+ * - `-` — from the block's end (remaining). The colon is optional here
+ *   too: `-:03` and `-03` both mean three seconds remaining.
+ *
+ * The magnitude accepts every duration spelling the language already
+ * understands: `5` (seconds), `5:00` (minutes), `00:05:00` (hours).
+ *
+ * @returns the parsed trigger, or `undefined` when the notation is malformed.
+ */
+declare function parseSoundTrigger(notation: string): SoundTriggerPoint | undefined;
+/**
+ * Format a trigger back into its canonical notation.
+ *
+ * `:00` for the start, `-:00` for the end, `-:03` for three seconds before
+ * the end, `:05:00` for five minutes after the start.
+ */
+declare function formatSoundTrigger(trigger: SoundTriggerPoint): string;
+/**
+ * Resolve a profile's rules against a block's duration, dropping any rule
+ * whose trigger point can never be reached.
+ *
+ * - A rule anchored to the **start** measures elapsed time, so it always
+ *   applies — no duration needed.
+ * - A rule anchored to the **end** with no offset means "when the block
+ *   ends", so it always applies too.
+ * - A rule anchored to the **end** with an offset needs a duration to count
+ *   down from. It applies only when the block's duration is known and long
+ *   enough to reach it.
+ *
+ * A rule that cannot be reached is dropped silently — an unreachable trigger
+ * is not an authoring error, it is simply a rule that does not apply to this
+ * block.
+ *
+ * @param profile the profile whose rules to resolve
+ * @param durationMs the block's duration in milliseconds, when known
+ */
+declare function resolveProfileRules(profile: SoundProfile, durationMs: number | undefined): SoundRule[];
+/**
+ * The profile applied when nothing selects one.
+ *
+ * A three-two-one countdown into a completion cue — the behaviour the app
+ * has always implied but never actually played.
+ */
+declare const DEFAULT_SOUND_PROFILE: SoundProfile;
+
+/**
+ * AST for the composed-calculation expression language (spec §2).
+ *
+ * One expression language across all three scopes; scope only changes how
+ * atoms resolve. `wql` atoms are legal in store scope only (executed by
+ * QueryService); stream aggregates (`sum(reps)`) are builtin calls resolved
+ * by the engine, not by this core.
+ */
+type BinaryOp = '+' | '-' | '*' | '/' | '==' | '!=' | '<' | '<=' | '>' | '>=' | 'and' | 'or';
+type ExprNode = {
+    kind: 'literal';
+    value: number;
+} | {
+    kind: 'period';
+    days: number;
+} | {
+    kind: 'string';
+    value: string;
+}
+/** Metric ref, context node (`session.duration`), or library node ref. */
+ | {
+    kind: 'ref';
+    name: string;
+} | {
+    kind: 'call';
+    name: string;
+    args: ExprNode[];
+}
+/** Effort-exclusion filter argument: `without: rest|pause|rest-*`. */
+ | {
+    kind: 'filter';
+    value: string;
+} | {
+    kind: 'unary';
+    op: '-' | 'not';
+    arg: ExprNode;
+} | {
+    kind: 'binary';
+    op: BinaryOp;
+    left: ExprNode;
+    right: ExprNode;
+}
+/** Store-scope WQL selection, e.g. `sum:sessionLoad{} by {day}`. */
+ | {
+    kind: 'wql';
+    aggregator: string;
+    metric: string;
+    filters?: string;
+    groupBy?: string[];
+};
+/** A parsed calc line: `name = expr -> unit when predicate`. */
+interface CalcLine {
+    name: string;
+    expr: ExprNode;
+    unit?: string;
+    when?: ExprNode;
+}
+
+/**
+ * Exponent-vector dimension model for the composed calculations layer.
+ *
+ * Dimensions are 5-element exponent vectors over base physical quantities:
+ *   [L, M, T, C, E]  =  [length, mass, time, count(reps), energy(cal)]
+ *
+ * Algebra (docs/composed-calculations-spec.md §5.1):
+ *   Dim(a * b) = Dim(a) + Dim(b)
+ *   Dim(a / b) = Dim(a) − Dim(b)
+ *   Dim(a ± b) requires Dim(a) = Dim(b)   (static registration failure otherwise)
+ */
+type DimVector = readonly [number, number, number, number, number];
+declare const DIM_ZERO: DimVector;
+declare const DIM_LENGTH: DimVector;
+declare const DIM_MASS: DimVector;
+declare const DIM_TIME: DimVector;
+declare const DIM_COUNT: DimVector;
+declare const DIM_ENERGY: DimVector;
+declare function addDim(a: DimVector, b: DimVector): DimVector;
+declare function subDim(a: DimVector, b: DimVector): DimVector;
+declare function dimEquals(a: DimVector, b: DimVector): boolean;
+declare function isDimensionless(d: DimVector): boolean;
+/** Human-readable vector, e.g. "T·L⁻¹" for pace. */
+declare function formatDim(d: DimVector): string;
+/**
+ * Named compound dimension registry (spec §5.2). Used for diagnostics and
+ * dimension-filtered unit suggestions — not required for evaluation.
+ */
+declare const NAMED_COMPOUNDS: Record<string, {
+    dim: DimVector;
+    preferredUnits: string[];
+}>;
+/** Reverse lookup: find the compound name for a vector, if one exists. */
+declare function compoundName(d: DimVector): string | undefined;
+
+/**
+ * Canonical Node DAG records (spec §2.2) — the storage/registration form for
+ * calculations. Seeds are TS object literals (#849); the line-form parser
+ * (#863) must round-trip these losslessly.
+ */
+
+type CalcOrigin = 'analyzed' | 'analyzed-estimated' | 'user';
+type CalcScope = 'segment' | 'workout' | 'store';
+interface CalcNode {
+    id: string;
+    kind: 'metric' | 'lookup' | 'builtin' | 'wql' | 'expr';
+    expression?: string;
+    ast?: ExprNode;
+    /**
+     * Declared node unit. Named zero-vector casts (AU, pts, MET-min, ratio)
+     * override the computed vector (§5.3 applied to intermediate nodes —
+     * required by TIS-shaped formulas that fold time into a score); any other
+     * unit must match the computed vector.
+     */
+    unit?: string;
+}
+interface CalcVariant {
+    id: string;
+    priority: number;
+    when?: string;
+    whenAst?: ExprNode;
+    origin: CalcOrigin;
+    nodes: Record<string, CalcNode>;
+    /** Node dimensions computed at registration (static check output). */
+    nodeDims?: Record<string, DimVector>;
+}
+interface CalculationDefinition {
+    id: string;
+    kind: 'output' | 'library';
+    scope: CalcScope;
+    fences?: string[];
+    when?: string;
+    whenAst?: ExprNode;
+    variants: CalcVariant[];
+    output?: {
+        nodeId: string | string[];
+        key?: string;
+        emitType?: string;
+        unit?: string;
+        isGrouped?: boolean;
+        /** Group dimensions for grouped emission (e.g. ['effort']). */
+        groupBy?: string[];
+        publishMetadataNodes?: string[];
+        /** Display label for published facts (store-scope rollups). */
+        label?: string;
+    };
+}
+
 /**
  * Factory function type for wrapping blocks in debug mode.
  * Receives the original block and returns a wrapped version.
@@ -673,6 +927,35 @@ interface RuntimeStackOptions extends IRuntimeOptions {
         userProfile?: {
             vo2max?: number;
         };
+        /**
+         * The functions available to the run — user-authored calculations,
+         * registered after the built-ins.
+         */
+        calcs?: CalculationDefinition[];
+        /**
+         * The tag catalogue: the tags a script can reference with `#slug`
+         * and the functions they carry.
+         */
+        tags?: TagIndex;
+        /**
+         * Tags active for the whole run, whatever the segments say — the
+         * bundle a profile applies.
+         */
+        activeTags?: readonly string[];
+    };
+    /**
+     * Sound configuration for this run.
+     *
+     * `profiles` are the user's sound profiles, available for selection.
+     * `noteProfileId` is the profile selected for the note as a whole — the
+     * note-level `sound-{profile}` tag, resolved by the host before the
+     * runtime starts. A block that names its own profile overrides it.
+     *
+     * With neither, blocks fall back to the default profile.
+     */
+    soundOptions?: {
+        profiles?: readonly SoundProfile[];
+        noteProfileId?: string;
     };
 }
 
@@ -1687,6 +1970,15 @@ interface CompletionDecision {
  * - Memory usage should be minimized during execution
  */
 interface IRuntimeBlock extends IBlockRef {
+    /**
+     * The tag composition of this block — the tags its statements referenced,
+     * and what each carried (the functions it activates, the sound profile it
+     * names).
+     *
+     * Resolved at compile time, so the runtime and the surfaces that show a
+     * block know which tags shaped it without re-reading the catalogue.
+     */
+    readonly tagComposition?: readonly TagReferenceMetadata[];
     /**
      * Execution timing metadata propagated by the runtime (start/completion timestamps).
      * Implementations can rely on RuntimeStack/PushBlockAction to set this.
@@ -2521,4 +2813,4 @@ declare function getRuntimeNowMs(): number;
 /** Creates an INowProvider that reads the browser sender-clock when available. */
 declare function createBrowserRuntimeNow(): INowProvider;
 
-export { type HandlerScope as $, type AnalyticsContext as A, type BehaviorEventType as B, type IBlockContext as C, type MetricVisibility as D, type EffortResolverOptions as E, type BlockLifecycleOptions as F, type CompletionDecision as G, type IRuntimeMemory as H, type IEquipment as I, TypedMemoryReference as J, type MemorySearchCriteria as K, type IMemoryReference as L, type MemoryTag as M, type RuntimeStackLogger as N, type OutputListener as O, type StackObserver as P, type StackSnapshot as Q, type ReferenceIndex as R, type SubscribeOptions as S, TimeSpan as T, type Unsubscribe as U, type StackListener as V, WhiteboardScript as W, MemoryTypeEnum as X, type IAnchorValue as Y, type ButtonConfig as Z, type IEventHandler as _, type ReferenceResolutionDefaults as a, resolveSourceRank as a$, type IScriptRuntime as a0, type TestableBlockConfig as a1, type IRuntimeOptions as a2, ScriptRuntime as a3, type EventHandlerOptions as a4, type EventCallback as a5, type TimerState as a6, type IRealtimeProcessor as a7, type ISummaryProcessor as a8, type ProjectionResult as a9, type InterceptMode as aA, MemoryLocation as aB, type MemoryType as aC, type MemoryTypeMap as aD, type MemoryValueOf as aE, type ReferenceCatalog as aF, type ResolvedReferences as aG, type RoundState as aH, type RuntimeState as aI, type ScriptRuntimeDependencies as aJ, type StackEvent as aK, type TimerDirection as aL, VISIBILITY_ICONS as aM, VISIBILITY_LABELS as aN, createBrowserRuntimeNow as aO, createReferenceIndex as aP, dedupeEntitiesByPrecedence as aQ, disciplineFactorFor as aR, extractStatementRefs as aS, filterTagsByVisibility as aT, frozenNow as aU, getMetricVisibility as aV, getRuntimeNowMs as aW, isEffortDiscipline as aX, isFragmentTag as aY, resolveEntityRank as aZ, resolveEntityTier as a_, type ButtonVariant as aa, type ButtonsState as ab, CATALOG_PRECEDENCE_RANK as ac, type CatalogPrecedenceTier as ad, type ChildrenStatusState as ae, type CompletionState as af, DEFAULT_RESOLVER_OPTIONS as ag, DEFAULT_RUNTIME_OPTIONS as ah, DISCIPLINE_FACTORS as ai, type DisplayState as aj, EFFORT_DISCIPLINES as ak, EFFORT_REGISTRY_ORIGINS as al, type EffortBaseAttributes as am, type EffortDerivation as an, type EffortDiscipline as ao, type EffortMaterializer as ap, type EffortResolvedFrom as aq, type EquipmentStorageAdapter as ar, type FenceDialect as as, type FragmentDisplayState as at, type FragmentState as au, type IAnalyticsProcessorDescriptor as av, type IEquipmentRegistry as aw, INTENSITY_TIERS as ax, type IScript as ay, type IntensityTier as az, type IEffort as b, resolveSourceTier as b0, slugifyRefLabel as b1, wallClockNow as b2, type IEffortResolver as c, type IEffortRegistry as d, type EffortResolutionOptions as e, type ResolvedEffort as f, type EffortRegistrySource as g, type EffortStorageAdapter as h, type IRuntimeActionable as i, type IEventBus as j, type IRuntimeStack as k, type IRuntimeClock as l, type IJitCompiler as m, type INowProvider as n, type RuntimeStackOptions as o, type RuntimeError as p, type IEvent as q, type IRuntimeAction as r, type IAnalyticsEngine as s, type IRuntimeBlock as t, type IBehaviorContext as u, type BehaviorEventListener as v, type Unsubscribe$1 as w, type OutputOptions as x, type IMemoryLocation as y, type IRuntimeBehavior as z };
+export { type IEventHandler as $, type AnalyticsContext as A, type BehaviorEventType as B, type IBlockContext as C, type MetricVisibility as D, type EffortResolverOptions as E, type BlockLifecycleOptions as F, type CompletionDecision as G, type IRuntimeMemory as H, type IEquipment as I, TypedMemoryReference as J, type MemorySearchCriteria as K, type IMemoryReference as L, type MemoryTag as M, type RuntimeStackLogger as N, type OutputListener as O, type StackObserver as P, type StackSnapshot as Q, type ReferenceIndex as R, type SubscribeOptions as S, TimeSpan as T, type Unsubscribe as U, type StackListener as V, WhiteboardScript as W, MemoryTypeEnum as X, type IAnchorValue as Y, type SoundProfile as Z, type ButtonConfig as _, type ReferenceResolutionDefaults as a, type ScriptRuntimeDependencies as a$, type HandlerScope as a0, type IScriptRuntime as a1, type TestableBlockConfig as a2, type IRuntimeOptions as a3, ScriptRuntime as a4, type EventHandlerOptions as a5, type EventCallback as a6, type TimerState as a7, type CalculationDefinition as a8, type IRealtimeProcessor as a9, type DisplayState as aA, EFFORT_DISCIPLINES as aB, EFFORT_REGISTRY_ORIGINS as aC, type EffortBaseAttributes as aD, type EffortDerivation as aE, type EffortDiscipline as aF, type EffortMaterializer as aG, type EffortResolvedFrom as aH, type EquipmentStorageAdapter as aI, type FenceDialect as aJ, type FragmentDisplayState as aK, type FragmentState as aL, type IAnalyticsProcessorDescriptor as aM, type IEquipmentRegistry as aN, INTENSITY_TIERS as aO, type IScript as aP, type IntensityTier as aQ, type InterceptMode as aR, MemoryLocation as aS, type MemoryType as aT, type MemoryTypeMap as aU, type MemoryValueOf as aV, NAMED_COMPOUNDS as aW, type ReferenceCatalog as aX, type ResolvedReferences as aY, type RoundState as aZ, type RuntimeState as a_, type ISummaryProcessor as aa, type ProjectionResult as ab, type DimVector as ac, type CalcLine as ad, type ExprNode as ae, type CalcScope as af, type BinaryOp as ag, type ButtonVariant as ah, type ButtonsState as ai, CATALOG_PRECEDENCE_RANK as aj, type CalcNode as ak, type CalcOrigin as al, type CalcVariant as am, type CatalogPrecedenceTier as an, type ChildrenStatusState as ao, type CompletionState as ap, DEFAULT_RESOLVER_OPTIONS as aq, DEFAULT_RUNTIME_OPTIONS as ar, DEFAULT_SOUND_PROFILE as as, DIM_COUNT as at, DIM_ENERGY as au, DIM_LENGTH as av, DIM_MASS as aw, DIM_TIME as ax, DIM_ZERO as ay, DISCIPLINE_FACTORS as az, type IEffort as b, type SoundRule as b0, type SoundTriggerAnchor as b1, type SoundTriggerPoint as b2, type StackEvent as b3, type TimerDirection as b4, VISIBILITY_ICONS as b5, VISIBILITY_LABELS as b6, addDim as b7, compoundName as b8, createBrowserRuntimeNow as b9, createReferenceIndex as ba, dedupeEntitiesByPrecedence as bb, dimEquals as bc, disciplineFactorFor as bd, extractStatementRefs as be, filterTagsByVisibility as bf, formatDim as bg, formatSoundTrigger as bh, frozenNow as bi, getMetricVisibility as bj, getRuntimeNowMs as bk, isDimensionless as bl, isEffortDiscipline as bm, isFragmentTag as bn, parseSoundTrigger as bo, resolveEntityRank as bp, resolveEntityTier as bq, resolveProfileRules as br, resolveSourceRank as bs, resolveSourceTier as bt, slugifyRefLabel as bu, subDim as bv, wallClockNow as bw, type IEffortResolver as c, type IEffortRegistry as d, type EffortResolutionOptions as e, type ResolvedEffort as f, type EffortRegistrySource as g, type EffortStorageAdapter as h, type IRuntimeActionable as i, type IEventBus as j, type IRuntimeStack as k, type IRuntimeClock as l, type IJitCompiler as m, type INowProvider as n, type RuntimeStackOptions as o, type RuntimeError as p, type IEvent as q, type IRuntimeAction as r, type IAnalyticsEngine as s, type IRuntimeBlock as t, type IBehaviorContext as u, type BehaviorEventListener as v, type Unsubscribe$1 as w, type OutputOptions as x, type IMemoryLocation as y, type IRuntimeBehavior as z };

package/dist/{browserRuntimeNow-M4hQ_DTl.d.ts → browserRuntimeNow-_zhhbzoE.d.ts}

@@ -1,4 +1,4 @@
-import { ReferenceMatchKind, ReferenceRef, ReferenceDiagnostic, ICodeStatement, ParseError, MetricContainer, IMetric, BlockKey, TimeSpan as TimeSpan$1, OutputStatementType, MetricType, IOutputStatement, MetricOrigin } from '@bitcobblers/wod-wiki-core';
+import { ReferenceMatchKind, ReferenceRef, ReferenceDiagnostic, ICodeStatement, ParseError, TagIndex, MetricContainer, IMetric, BlockKey, TimeSpan as TimeSpan$1, OutputStatementType, TagReferenceMetadata, MetricType, IOutputStatement, MetricOrigin } from '@bitcobblers/wod-wiki-core';
 
 /**
  * Canonical discipline vocabulary — the single source of truth for effort
@@ -587,6 +587,260 @@ interface TestableBlockConfig {
     disposeOverride?: (runtime: IRuntimeActionable) => void;
 }
 
+/**
+ * Sound profiles — user-defined rule sets that drive workout audio.
+ *
+ * A profile is a list of rules. Each rule names a **trigger point** (an offset
+ * relative to the block's own duration) and the **sound** to play there. The
+ * profile therefore decides both *when* a sound fires and *what* it is.
+ *
+ * ## Trigger notation
+ *
+ * A trigger is a duration offset written in the whiteboard duration notation,
+ * with a leading anchor that says which end of the block it counts from:
+ *
+ * - `:00` — the **start** of the block (elapsed = 0).
+ * - `-:00` — the **end** of the block (remaining = 0).
+ * - `-:03` — three seconds before the end (remaining).
+ * - `:05:00` — five minutes after the start (elapsed).
+ *
+ * The magnitude accepts every duration spelling the language already
+ * understands — `05:00`, `5:00`, `00:05:00` and `5` all mean the same
+ * duration. The anchor is what distinguishes the two families:
+ *
+ * | Anchor | Counts from | Fires when |
+ * |--------|-------------|------------|
+ * | `:`    | block start | elapsed reaches the offset |
+ * | `-:`   | block end   | remaining falls to the offset |
+ *
+ * Because the offset is relative to the block's own duration, one profile
+ * works for any block length: the same `-:03` rule beeps three seconds
+ * before the end of a 5:00 run and three seconds before the end of a 1:00
+ * rest.
+ */
+/** Which end of the block a trigger counts from. */
+type SoundTriggerAnchor = 'start' | 'end';
+/** A trigger point: an anchor plus an offset from that anchor. */
+interface SoundTriggerPoint {
+    /** Counts from the block's start (`start`) or its end (`end`). */
+    readonly anchor: SoundTriggerAnchor;
+    /** Offset from the anchor, in milliseconds. Never negative. */
+    readonly offsetMs: number;
+}
+/** One rule in a profile: a trigger point plus the sound to play there. */
+interface SoundRule {
+    /** When the sound fires. */
+    readonly trigger: SoundTriggerPoint;
+    /** Name of the sound to play. Resolved against the app's sound table. */
+    readonly sound: string;
+}
+/** A named, user-defined set of sound rules. */
+interface SoundProfile {
+    /** Stable identifier (slug). Unique across profiles. */
+    readonly id: string;
+    /** Human-readable name shown in Settings. */
+    readonly name: string;
+    /** The rules, in declaration order. */
+    readonly rules: readonly SoundRule[];
+}
+/**
+ * Parse a trigger notation into a {@link SoundTriggerPoint}.
+ *
+ * The anchor says which end of the block the offset counts from:
+ *
+ * - `:` — from the block's start (elapsed). This is the default, so the
+ *   magnitude may be written with or without it: `:05:00`, `05:00`,
+ *   `00:05:00` and `5:00` all mean five minutes from the start.
+ * - `-` — from the block's end (remaining). The colon is optional here
+ *   too: `-:03` and `-03` both mean three seconds remaining.
+ *
+ * The magnitude accepts every duration spelling the language already
+ * understands: `5` (seconds), `5:00` (minutes), `00:05:00` (hours).
+ *
+ * @returns the parsed trigger, or `undefined` when the notation is malformed.
+ */
+declare function parseSoundTrigger(notation: string): SoundTriggerPoint | undefined;
+/**
+ * Format a trigger back into its canonical notation.
+ *
+ * `:00` for the start, `-:00` for the end, `-:03` for three seconds before
+ * the end, `:05:00` for five minutes after the start.
+ */
+declare function formatSoundTrigger(trigger: SoundTriggerPoint): string;
+/**
+ * Resolve a profile's rules against a block's duration, dropping any rule
+ * whose trigger point can never be reached.
+ *
+ * - A rule anchored to the **start** measures elapsed time, so it always
+ *   applies — no duration needed.
+ * - A rule anchored to the **end** with no offset means "when the block
+ *   ends", so it always applies too.
+ * - A rule anchored to the **end** with an offset needs a duration to count
+ *   down from. It applies only when the block's duration is known and long
+ *   enough to reach it.
+ *
+ * A rule that cannot be reached is dropped silently — an unreachable trigger
+ * is not an authoring error, it is simply a rule that does not apply to this
+ * block.
+ *
+ * @param profile the profile whose rules to resolve
+ * @param durationMs the block's duration in milliseconds, when known
+ */
+declare function resolveProfileRules(profile: SoundProfile, durationMs: number | undefined): SoundRule[];
+/**
+ * The profile applied when nothing selects one.
+ *
+ * A three-two-one countdown into a completion cue — the behaviour the app
+ * has always implied but never actually played.
+ */
+declare const DEFAULT_SOUND_PROFILE: SoundProfile;
+
+/**
+ * AST for the composed-calculation expression language (spec §2).
+ *
+ * One expression language across all three scopes; scope only changes how
+ * atoms resolve. `wql` atoms are legal in store scope only (executed by
+ * QueryService); stream aggregates (`sum(reps)`) are builtin calls resolved
+ * by the engine, not by this core.
+ */
+type BinaryOp = '+' | '-' | '*' | '/' | '==' | '!=' | '<' | '<=' | '>' | '>=' | 'and' | 'or';
+type ExprNode = {
+    kind: 'literal';
+    value: number;
+} | {
+    kind: 'period';
+    days: number;
+} | {
+    kind: 'string';
+    value: string;
+}
+/** Metric ref, context node (`session.duration`), or library node ref. */
+ | {
+    kind: 'ref';
+    name: string;
+} | {
+    kind: 'call';
+    name: string;
+    args: ExprNode[];
+}
+/** Effort-exclusion filter argument: `without: rest|pause|rest-*`. */
+ | {
+    kind: 'filter';
+    value: string;
+} | {
+    kind: 'unary';
+    op: '-' | 'not';
+    arg: ExprNode;
+} | {
+    kind: 'binary';
+    op: BinaryOp;
+    left: ExprNode;
+    right: ExprNode;
+}
+/** Store-scope WQL selection, e.g. `sum:sessionLoad{} by {day}`. */
+ | {
+    kind: 'wql';
+    aggregator: string;
+    metric: string;
+    filters?: string;
+    groupBy?: string[];
+};
+/** A parsed calc line: `name = expr -> unit when predicate`. */
+interface CalcLine {
+    name: string;
+    expr: ExprNode;
+    unit?: string;
+    when?: ExprNode;
+}
+
+/**
+ * Exponent-vector dimension model for the composed calculations layer.
+ *
+ * Dimensions are 5-element exponent vectors over base physical quantities:
+ *   [L, M, T, C, E]  =  [length, mass, time, count(reps), energy(cal)]
+ *
+ * Algebra (docs/composed-calculations-spec.md §5.1):
+ *   Dim(a * b) = Dim(a) + Dim(b)
+ *   Dim(a / b) = Dim(a) − Dim(b)
+ *   Dim(a ± b) requires Dim(a) = Dim(b)   (static registration failure otherwise)
+ */
+type DimVector = readonly [number, number, number, number, number];
+declare const DIM_ZERO: DimVector;
+declare const DIM_LENGTH: DimVector;
+declare const DIM_MASS: DimVector;
+declare const DIM_TIME: DimVector;
+declare const DIM_COUNT: DimVector;
+declare const DIM_ENERGY: DimVector;
+declare function addDim(a: DimVector, b: DimVector): DimVector;
+declare function subDim(a: DimVector, b: DimVector): DimVector;
+declare function dimEquals(a: DimVector, b: DimVector): boolean;
+declare function isDimensionless(d: DimVector): boolean;
+/** Human-readable vector, e.g. "T·L⁻¹" for pace. */
+declare function formatDim(d: DimVector): string;
+/**
+ * Named compound dimension registry (spec §5.2). Used for diagnostics and
+ * dimension-filtered unit suggestions — not required for evaluation.
+ */
+declare const NAMED_COMPOUNDS: Record<string, {
+    dim: DimVector;
+    preferredUnits: string[];
+}>;
+/** Reverse lookup: find the compound name for a vector, if one exists. */
+declare function compoundName(d: DimVector): string | undefined;
+
+/**
+ * Canonical Node DAG records (spec §2.2) — the storage/registration form for
+ * calculations. Seeds are TS object literals (#849); the line-form parser
+ * (#863) must round-trip these losslessly.
+ */
+
+type CalcOrigin = 'analyzed' | 'analyzed-estimated' | 'user';
+type CalcScope = 'segment' | 'workout' | 'store';
+interface CalcNode {
+    id: string;
+    kind: 'metric' | 'lookup' | 'builtin' | 'wql' | 'expr';
+    expression?: string;
+    ast?: ExprNode;
+    /**
+     * Declared node unit. Named zero-vector casts (AU, pts, MET-min, ratio)
+     * override the computed vector (§5.3 applied to intermediate nodes —
+     * required by TIS-shaped formulas that fold time into a score); any other
+     * unit must match the computed vector.
+     */
+    unit?: string;
+}
+interface CalcVariant {
+    id: string;
+    priority: number;
+    when?: string;
+    whenAst?: ExprNode;
+    origin: CalcOrigin;
+    nodes: Record<string, CalcNode>;
+    /** Node dimensions computed at registration (static check output). */
+    nodeDims?: Record<string, DimVector>;
+}
+interface CalculationDefinition {
+    id: string;
+    kind: 'output' | 'library';
+    scope: CalcScope;
+    fences?: string[];
+    when?: string;
+    whenAst?: ExprNode;
+    variants: CalcVariant[];
+    output?: {
+        nodeId: string | string[];
+        key?: string;
+        emitType?: string;
+        unit?: string;
+        isGrouped?: boolean;
+        /** Group dimensions for grouped emission (e.g. ['effort']). */
+        groupBy?: string[];
+        publishMetadataNodes?: string[];
+        /** Display label for published facts (store-scope rollups). */
+        label?: string;
+    };
+}
+
 /**
  * Factory function type for wrapping blocks in debug mode.
  * Receives the original block and returns a wrapped version.
@@ -673,6 +927,35 @@ interface RuntimeStackOptions extends IRuntimeOptions {
         userProfile?: {
             vo2max?: number;
         };
+        /**
+         * The functions available to the run — user-authored calculations,
+         * registered after the built-ins.
+         */
+        calcs?: CalculationDefinition[];
+        /**
+         * The tag catalogue: the tags a script can reference with `#slug`
+         * and the functions they carry.
+         */
+        tags?: TagIndex;
+        /**
+         * Tags active for the whole run, whatever the segments say — the
+         * bundle a profile applies.
+         */
+        activeTags?: readonly string[];
+    };
+    /**
+     * Sound configuration for this run.
+     *
+     * `profiles` are the user's sound profiles, available for selection.
+     * `noteProfileId` is the profile selected for the note as a whole — the
+     * note-level `sound-{profile}` tag, resolved by the host before the
+     * runtime starts. A block that names its own profile overrides it.
+     *
+     * With neither, blocks fall back to the default profile.
+     */
+    soundOptions?: {
+        profiles?: readonly SoundProfile[];
+        noteProfileId?: string;
     };
 }
 
@@ -1687,6 +1970,15 @@ interface CompletionDecision {
  * - Memory usage should be minimized during execution
  */
 interface IRuntimeBlock extends IBlockRef {
+    /**
+     * The tag composition of this block — the tags its statements referenced,
+     * and what each carried (the functions it activates, the sound profile it
+     * names).
+     *
+     * Resolved at compile time, so the runtime and the surfaces that show a
+     * block know which tags shaped it without re-reading the catalogue.
+     */
+    readonly tagComposition?: readonly TagReferenceMetadata[];
     /**
      * Execution timing metadata propagated by the runtime (start/completion timestamps).
      * Implementations can rely on RuntimeStack/PushBlockAction to set this.
@@ -2521,4 +2813,4 @@ declare function getRuntimeNowMs(): number;
 /** Creates an INowProvider that reads the browser sender-clock when available. */
 declare function createBrowserRuntimeNow(): INowProvider;
 
-export { type HandlerScope as $, type AnalyticsContext as A, type BehaviorEventType as B, type IBlockContext as C, type MetricVisibility as D, type EffortResolverOptions as E, type BlockLifecycleOptions as F, type CompletionDecision as G, type IRuntimeMemory as H, type IEquipment as I, TypedMemoryReference as J, type MemorySearchCriteria as K, type IMemoryReference as L, type MemoryTag as M, type RuntimeStackLogger as N, type OutputListener as O, type StackObserver as P, type StackSnapshot as Q, type ReferenceIndex as R, type SubscribeOptions as S, TimeSpan as T, type Unsubscribe as U, type StackListener as V, WhiteboardScript as W, MemoryTypeEnum as X, type IAnchorValue as Y, type ButtonConfig as Z, type IEventHandler as _, type ReferenceResolutionDefaults as a, resolveSourceRank as a$, type IScriptRuntime as a0, type TestableBlockConfig as a1, type IRuntimeOptions as a2, ScriptRuntime as a3, type EventHandlerOptions as a4, type EventCallback as a5, type TimerState as a6, type IRealtimeProcessor as a7, type ISummaryProcessor as a8, type ProjectionResult as a9, type InterceptMode as aA, MemoryLocation as aB, type MemoryType as aC, type MemoryTypeMap as aD, type MemoryValueOf as aE, type ReferenceCatalog as aF, type ResolvedReferences as aG, type RoundState as aH, type RuntimeState as aI, type ScriptRuntimeDependencies as aJ, type StackEvent as aK, type TimerDirection as aL, VISIBILITY_ICONS as aM, VISIBILITY_LABELS as aN, createBrowserRuntimeNow as aO, createReferenceIndex as aP, dedupeEntitiesByPrecedence as aQ, disciplineFactorFor as aR, extractStatementRefs as aS, filterTagsByVisibility as aT, frozenNow as aU, getMetricVisibility as aV, getRuntimeNowMs as aW, isEffortDiscipline as aX, isFragmentTag as aY, resolveEntityRank as aZ, resolveEntityTier as a_, type ButtonVariant as aa, type ButtonsState as ab, CATALOG_PRECEDENCE_RANK as ac, type CatalogPrecedenceTier as ad, type ChildrenStatusState as ae, type CompletionState as af, DEFAULT_RESOLVER_OPTIONS as ag, DEFAULT_RUNTIME_OPTIONS as ah, DISCIPLINE_FACTORS as ai, type DisplayState as aj, EFFORT_DISCIPLINES as ak, EFFORT_REGISTRY_ORIGINS as al, type EffortBaseAttributes as am, type EffortDerivation as an, type EffortDiscipline as ao, type EffortMaterializer as ap, type EffortResolvedFrom as aq, type EquipmentStorageAdapter as ar, type FenceDialect as as, type FragmentDisplayState as at, type FragmentState as au, type IAnalyticsProcessorDescriptor as av, type IEquipmentRegistry as aw, INTENSITY_TIERS as ax, type IScript as ay, type IntensityTier as az, type IEffort as b, resolveSourceTier as b0, slugifyRefLabel as b1, wallClockNow as b2, type IEffortResolver as c, type IEffortRegistry as d, type EffortResolutionOptions as e, type ResolvedEffort as f, type EffortRegistrySource as g, type EffortStorageAdapter as h, type IRuntimeActionable as i, type IEventBus as j, type IRuntimeStack as k, type IRuntimeClock as l, type IJitCompiler as m, type INowProvider as n, type RuntimeStackOptions as o, type RuntimeError as p, type IEvent as q, type IRuntimeAction as r, type IAnalyticsEngine as s, type IRuntimeBlock as t, type IBehaviorContext as u, type BehaviorEventListener as v, type Unsubscribe$1 as w, type OutputOptions as x, type IMemoryLocation as y, type IRuntimeBehavior as z };
+export { type IEventHandler as $, type AnalyticsContext as A, type BehaviorEventType as B, type IBlockContext as C, type MetricVisibility as D, type EffortResolverOptions as E, type BlockLifecycleOptions as F, type CompletionDecision as G, type IRuntimeMemory as H, type IEquipment as I, TypedMemoryReference as J, type MemorySearchCriteria as K, type IMemoryReference as L, type MemoryTag as M, type RuntimeStackLogger as N, type OutputListener as O, type StackObserver as P, type StackSnapshot as Q, type ReferenceIndex as R, type SubscribeOptions as S, TimeSpan as T, type Unsubscribe as U, type StackListener as V, WhiteboardScript as W, MemoryTypeEnum as X, type IAnchorValue as Y, type SoundProfile as Z, type ButtonConfig as _, type ReferenceResolutionDefaults as a, type ScriptRuntimeDependencies as a$, type HandlerScope as a0, type IScriptRuntime as a1, type TestableBlockConfig as a2, type IRuntimeOptions as a3, ScriptRuntime as a4, type EventHandlerOptions as a5, type EventCallback as a6, type TimerState as a7, type CalculationDefinition as a8, type IRealtimeProcessor as a9, type DisplayState as aA, EFFORT_DISCIPLINES as aB, EFFORT_REGISTRY_ORIGINS as aC, type EffortBaseAttributes as aD, type EffortDerivation as aE, type EffortDiscipline as aF, type EffortMaterializer as aG, type EffortResolvedFrom as aH, type EquipmentStorageAdapter as aI, type FenceDialect as aJ, type FragmentDisplayState as aK, type FragmentState as aL, type IAnalyticsProcessorDescriptor as aM, type IEquipmentRegistry as aN, INTENSITY_TIERS as aO, type IScript as aP, type IntensityTier as aQ, type InterceptMode as aR, MemoryLocation as aS, type MemoryType as aT, type MemoryTypeMap as aU, type MemoryValueOf as aV, NAMED_COMPOUNDS as aW, type ReferenceCatalog as aX, type ResolvedReferences as aY, type RoundState as aZ, type RuntimeState as a_, type ISummaryProcessor as aa, type ProjectionResult as ab, type DimVector as ac, type CalcLine as ad, type ExprNode as ae, type CalcScope as af, type BinaryOp as ag, type ButtonVariant as ah, type ButtonsState as ai, CATALOG_PRECEDENCE_RANK as aj, type CalcNode as ak, type CalcOrigin as al, type CalcVariant as am, type CatalogPrecedenceTier as an, type ChildrenStatusState as ao, type CompletionState as ap, DEFAULT_RESOLVER_OPTIONS as aq, DEFAULT_RUNTIME_OPTIONS as ar, DEFAULT_SOUND_PROFILE as as, DIM_COUNT as at, DIM_ENERGY as au, DIM_LENGTH as av, DIM_MASS as aw, DIM_TIME as ax, DIM_ZERO as ay, DISCIPLINE_FACTORS as az, type IEffort as b, type SoundRule as b0, type SoundTriggerAnchor as b1, type SoundTriggerPoint as b2, type StackEvent as b3, type TimerDirection as b4, VISIBILITY_ICONS as b5, VISIBILITY_LABELS as b6, addDim as b7, compoundName as b8, createBrowserRuntimeNow as b9, createReferenceIndex as ba, dedupeEntitiesByPrecedence as bb, dimEquals as bc, disciplineFactorFor as bd, extractStatementRefs as be, filterTagsByVisibility as bf, formatDim as bg, formatSoundTrigger as bh, frozenNow as bi, getMetricVisibility as bj, getRuntimeNowMs as bk, isDimensionless as bl, isEffortDiscipline as bm, isFragmentTag as bn, parseSoundTrigger as bo, resolveEntityRank as bp, resolveEntityTier as bq, resolveProfileRules as br, resolveSourceRank as bs, resolveSourceTier as bt, slugifyRefLabel as bu, subDim as bv, wallClockNow as bw, type IEffortResolver as c, type IEffortRegistry as d, type EffortResolutionOptions as e, type ResolvedEffort as f, type EffortRegistrySource as g, type EffortStorageAdapter as h, type IRuntimeActionable as i, type IEventBus as j, type IRuntimeStack as k, type IRuntimeClock as l, type IJitCompiler as m, type INowProvider as n, type RuntimeStackOptions as o, type RuntimeError as p, type IEvent as q, type IRuntimeAction as r, type IAnalyticsEngine as s, type IRuntimeBlock as t, type IBehaviorContext as u, type BehaviorEventListener as v, type Unsubscribe$1 as w, type OutputOptions as x, type IMemoryLocation as y, type IRuntimeBehavior as z };