@bitcobblers/wod-wiki-core 0.11.43 → 0.35.2116

package/dist/index.d.ts

@@ -1,58 +1,8 @@
 /**
  * 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.
  *
@@ -115,6 +65,12 @@ interface IMetric {
     readonly ownershipLayer?: MetricOwnershipLayer;
     /** Optional human-readable name or label */
     readonly name?: string;
+    /**
+     * Optional icon (emoji/glyph) for hint metrics. Hints without an icon are
+     * data-only — they never render in display surfaces; a hint WITH an icon
+     * renders as the icon alone, with the hint text on hover.
+     */
+    readonly icon?: string;
 }
 /**
  * Metric type enumeration.
@@ -184,6 +140,9 @@ declare enum MetricType {
     Custom = "custom",
     Volume = "volume",
     Intensity = "intensity",
+    /** Climb grade label carried by an observation (e.g. `V8`, `5.12a`) —
+     *  user-authored grade metrics promote to the analytics `grade` dim. */
+    Grade = "grade",
     Load = "load",
     Work = "work",
     /** Per-set Reps in Reserve (real-time, strength) */
@@ -295,6 +254,233 @@ interface IMetricSource {
     readonly rawMetrics: IMetric[];
 }
 
+/**
+ * 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;
+}
+
+/**
+ * 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;
+
+declare function resolveLayer(metric: IMetric): MetricOwnershipLayer;
+declare function ownershipRank(metric: IMetric): number;
+declare function createMetricOwnershipLedger(metrics: readonly IMetric[]): MetricOwnershipLedger;
+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[];
+}
+
+/**
+ * Field identity — the pure normalization/identity layer for typed metric
+ * fields (wayfinder datadog-analytics ticket 11, per the field discovery
+ * contract §Identity and discovery).
+ *
+ * A metric variant is identified by **normalized full property path + value
+ * kind + physical dimension where applicable**. Source, display label,
+ * original spelling, and convertible unit spelling are provenance, not
+ * identity. Built-in and custom metrics use the same rules.
+ *
+ * This module is pure data + functions with zero dependencies: `lang` and
+ * `wql` (and the app adapter) both consume it through their existing core
+ * dependency. Dimension resolution from units lives with the unit catalog —
+ * callers attach a resolved `dimension` when one is known.
+ */
+/** The observed value kinds of a field variant (field discovery contract). */
+type FieldValueKind = 'number' | 'string' | 'boolean' | 'array';
+/** Presence/clearing marker — null records presence, never a value. */
+type NullValueKind = 'null';
+/**
+ * Typed field reference — the identity of one metric variant.
+ * `dimension` is the physical dimension for numeric kinds (resolved through
+ * the unit registry); undefined means dimensionless or unknown.
+ */
+interface FieldRef {
+    /** Normalized full property path — lower camelCase components, dots delimit. */
+    readonly path: string;
+    /** Observed value kind of the variant. */
+    readonly kind: FieldValueKind | NullValueKind;
+    /** Physical dimension for numeric kinds, when known. */
+    readonly dimension?: string;
+}
+/** Lower camelCase one path component: `heart rate`, `heart_rate`,
+ *  `HeartRate`, and `heartRate` all normalize to `heartRate`; `HRV`
+ *  normalizes to `hrv`. No synonym inference: `heartrate` stays `heartrate`. */
+declare function normalizeFieldComponent(component: string): string;
+/**
+ * Normalize a full property path. Dots are reserved path separators, so
+ * `sleep_quality.score_value` → `sleepQuality.scoreValue` and nested/flat
+ * forms share one identity. Empty components collapse: `sleep..score` →
+ * `sleep.score`.
+ */
+declare function normalizeFieldPath(path: string): string;
+/** Classify an observed value into a field value kind. Objects and null are
+ *  deliberately outside the value kinds: objects contribute nested leaves and
+ *  null records presence/clearing — neither is a value. */
+declare function valueKindOf(value: unknown): FieldValueKind | 'object' | 'null' | 'undefined';
+/** One flattened leaf observation: identity path + kind, the raw value, and
+ *  the original spelling/shape it was authored with (provenance). */
+interface FieldLeaf {
+    /** Normalized full path. */
+    readonly path: string;
+    /** Value kind — 'null' leaves record presence/clearing, never a value. */
+    readonly kind: FieldValueKind | NullValueKind;
+    readonly value: unknown;
+    /** Original path spelling/shape as authored (flat dotted or nested). */
+    readonly originalPath: string;
+}
+/**
+ * Flatten an authored property object into typed leaves.
+ *
+ * - Dots in keys delimit paths: flat `{"sleep.score": 85}` ≡ nested
+ *   `{sleep:{score:85}}` — one identity.
+ * - Objects contribute nested leaves; empty objects contribute nothing.
+ * - Arrays are collections: one collection-valued leaf, never per-element
+ *   observations.
+ * - Null records presence under its path without a value.
+ */
+declare function flattenFieldLeaves(input: Record<string, unknown>, prefix?: string): FieldLeaf[];
+/**
+ * Collision-free canonical string for a typed variant identity. JSON array
+ * encoding keeps a separator character inside a path from masquerading as a
+ * structural boundary (`a|number` as path cannot collide with `a` + a
+ * `number` dimension).
+ */
+declare function fieldRefKey(ref: FieldRef): string;
+/** Parse a {@link fieldRefKey} back into a FieldRef (round-trip helper). */
+declare function fieldRefFromKey(key: string): FieldRef;
+
+/**
+ * Unit catalog — the shared home for unit recognition, conversion evidence,
+ * and the system default output table (wayfinder decision ticket 21;
+ * consumed by wql's arithmetic rewrite, ticket 13).
+ *
+ * Recognition spellings are case-insensitive through canonical spellings and
+ * aliases. Every entry carries its conversion evidence: the physical
+ * dimension it measures and the fixed factor converting it to that
+ * dimension's base unit. Compound units (speed, pace) convert through their
+ * own scale factors to the compound base.
+ *
+ * `bw` (body-weight-relative load) is deliberately NOT a fixed-factor entry:
+ * it requires genuine measurement-time context persisted with the value
+ * (ticket 14's conversion evidence) — never a constant kg conversion, never
+ * today's body mass reinterpreting history (missing-context limitation).
+ */
+/** Named result dimensions — the keys of the system default table. */
+type DimensionKey = 'mass' | 'distance' | 'duration' | 'count' | 'count-rate' | 'energy' | 'speed' | 'pace' | 'ratio';
+/** Error taxonomy (decision ticket 21). */
+type UnitErrorCode = 'unknown-unit' | 'dimension-mismatch' | 'scale-mismatch' | 'missing-context' | 'non-finite' | 'non-convertible';
+declare class UnitConversionError extends Error {
+    readonly code: UnitErrorCode;
+    constructor(code: UnitErrorCode, message: string);
+}
+interface UnitDefinition {
+    /** Canonical spelling (e.g. `kg`, `mi`, `min/km`). */
+    readonly canonical: string;
+    /** Named result dimension. */
+    readonly dimension: DimensionKey;
+    /** Fixed factor converting a value of this unit to the dimension's base
+     *  unit (conversion evidence). */
+    readonly factor: number;
+    /** Registered alternate spellings (case-insensitive at lookup). */
+    readonly aliases?: readonly string[];
+}
+/**
+ * Base units per dimension: mass `kg`, distance `m`, duration `s`,
+ * count `count`, energy `cal`, speed `m/s`, pace `min/km`; ratio is
+ * unitless (factor 1).
+ */
+declare const UNIT_CATALOG: readonly UnitDefinition[];
+/** Look up a unit by canonical spelling or alias (case-insensitive). */
+declare function lookupUnit(spelling: string): UnitDefinition | undefined;
+/** The named result dimension of a unit spelling, or undefined when the
+ *  spelling is not in the catalog. */
+declare function dimensionKeyOf(spelling: string): DimensionKey | undefined;
+/** System default output unit per result dimension (arithmetic contract §5;
+ *  values agreed in ticket 13, home resolved in ticket 21). Ratio defaults
+ *  to unitless — `undefined`, never a fabricated unit label. */
+declare const SYSTEM_DEFAULT_OUTPUT_UNIT: Readonly<Record<DimensionKey, string | undefined>>;
+/** Default output unit for a result dimension — undefined means unitless. */
+declare function systemDefaultUnit(dimension: DimensionKey): string | undefined;
+/**
+ * Strict conversion through the catalog's conversion evidence.
+ *
+ * Errors (`UnitConversionError`) on unknown units (`unknown-unit`) and
+ * cross-dimension conversions (`dimension-mismatch`) — an explicit unknown
+ * unit is never passed through and never replaced by a default.
+ */
+declare function convertViaCatalog(value: number, from: string, to: string): number;
+
 interface ICodeMetadata {
     line: number;
     startOffset: number;
@@ -526,6 +712,10 @@ interface OutputStatementOptions {
     stackLevel?: number;
     /** The source statement ID (optional) */
     sourceStatementId?: number;
+    /** Original source line/text/dialect (when rebuilding from stored records) */
+    line?: number;
+    text?: string;
+    dialect?: string;
     /** Runtime-collected metrics */
     metrics?: MetricContainer | IMetric[];
     /** Map of metrics to metadata */
@@ -540,7 +730,7 @@ interface OutputStatementOptions {
 /**
  * Concrete implementation of IOutputStatement.
  */
-declare class OutputStatement implements IOutputStatement, IMetricSource {
+declare class OutputStatement extends CodeStatement implements IOutputStatement {
     private static nextId;
     readonly id: number;
     readonly outputType: OutputStatementType;
@@ -558,105 +748,12 @@ declare class OutputStatement implements IOutputStatement, IMetricSource {
     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;
@@ -766,6 +863,15 @@ interface Segment {
     metrics?: MetricContainer;
 }
 
+/**
+ * Content-stable identity for a workout block.
+ *
+ * A 32-bit FNV-1a hash of the trimmed fenced content, formatted as `bc-<8 hex>`.
+ * Survives clone / reorder / edit-above so results and facts keyed by it stay
+ * linked across runs.
+ */
+declare function blockContentId(content: string): string;
+
 /**
  * Plain-data snapshot of a runtime OutputStatement safe for JSON / IndexedDB
  * round-trips. Class methods and non-serialisable fields (Set, Map,
@@ -831,17 +937,20 @@ interface WorkoutResults {
 }
 
 type SegmentDataType = 'script' | 'youtube' | 'markdown' | 'header' | 'frontmatter' | 'wod' | 'title' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
-type NoteKind = 'note' | 'template' | 'playground' | 'journal';
+type NoteKind = 'journal' | 'template' | 'playground' | 'feed' | 'dashboard' | 'page' | (string & {});
 interface Note {
     id: string;
     title: string;
-    slug?: string;
-    pageId?: string;
+    date?: number;
     createdAt: number;
     type?: NoteKind;
     sourceId?: string;
     catalog?: string;
     tags?: string[];
+    /** Original seed file path (e.g. `markdown/collections/girls/fran.md`) — the
+     *  deterministic UUID is derived from this path; retained for seed content
+     *  reconstruction (canvas routes, collection READMEs, block-index lookup). */
+    sourcePath?: string;
 }
 interface Page {
     id: string;
@@ -850,7 +959,21 @@ interface Page {
     title?: string;
     createdAt: number;
 }
-type TagType = 'template' | 'playground' | 'qualification' | 'notebook' | 'general';
+interface PageNote {
+    id: string;
+    pageId: string;
+    noteId: string;
+    position?: number;
+    createdAt: number;
+}
+type TagType = 'template' | 'playground' | 'qualification' | 'notebook' | 'general' | (string & {});
+interface TagTypeRecord {
+    id: string;
+    name: string;
+    label: string;
+    color?: string;
+    createdAt: number;
+}
 interface Tag {
     id: string;
     label: string;
@@ -891,7 +1014,7 @@ interface BlockIndexRow {
     sourceId?: string;
 }
 type ResultOrigin = 'journal' | 'playground' | 'user';
-interface WorkoutResult {
+interface Session {
     id: string;
     segmentId?: string;
     segmentVersion?: number;
@@ -905,7 +1028,20 @@ interface WorkoutResult {
      *  start, flipped to 'completed' at finalize. Absent = 'completed'
      *  (legacy rows predate streaming). */
     status?: 'in-progress' | 'completed';
-    data: 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;
+    /** Whether workout was completed or stopped early */
+    completed: boolean;
     createdAt: number;
 }
 interface Attachment {
@@ -933,6 +1069,10 @@ interface AnalyticsDataPoint {
     discipline?: string;
     intensityTier?: string;
     grade?: string;
+    /** User-authored categorical dims (custom property metrics and grouped
+     *  partitions) — normalized key → value, resolved by factTagValue after
+     *  the structural switch so `by {coach}` / `{coach:greg}` work. */
+    dimensions?: Record<string, string>;
     segmentId: string;
     segmentVersion: number;
     resultId: string;
@@ -943,6 +1083,22 @@ interface AnalyticsDataPoint {
     metricKey?: string;
     metricLabel?: string;
     metricUnit?: string;
+    /** Typed field reference provenance (ticket 11) — normalized path + kind
+     *  of the variant this observation belongs to. */
+    fieldRef?: {
+        path: string;
+        kind: string;
+        dimension?: string;
+    };
+    /** The observation's own civil date (YYYY-MM-DD) when it is date-only
+     *  (ticket 12) — grouping uses this instead of a fabricated instant. */
+    metricDate?: string;
+    /** Temporal kind of the observation's anchor (ticket 12). */
+    temporalKind?: 'instant' | 'civil-date';
+    /** Ticket 14 provenance carried onto the fact (ticket 16 selection). */
+    representationKind?: 'direct' | 'calculated' | 'substitute_summary';
+    summaryCoverage?: SummaryCoverage;
+    reducerStats?: ReducerStats;
     timestamp: number;
     createdAt: number;
 }
@@ -954,7 +1110,7 @@ type EventGrain = 'event' | 'summary';
  *  open string + known-values module; unknowns are stored and returned,
  *  matched only by kind-agnostic logic). */
 declare const KNOWN_OUTPUT_TYPES: readonly ["segment", "system", "load", "event", "compiler", "completion", "analytics", "wellness"];
-interface UnifiedEventRecord {
+interface EventRecord {
     /**
      * Event rows:    `${resultId}:${seq}` — immutable, append-only.
      * Summary rows:  `${resultId}:summary:${metricKey}[:k=v…]` — deterministic
@@ -971,9 +1127,9 @@ interface UnifiedEventRecord {
     /** Canonical time — when the workout happened, never when derived. */
     timestamp: number;
     grain: EventGrain;
+    effortSlug?: string;
     /** Open vocabulary — see KNOWN_OUTPUT_TYPES. */
     outputType: string;
-    effortSlug?: string;
     /** Typed metric array; EXACTLY ONE entry when grain:'summary'. Summary
      *  fold identity (canonicalKey, groupTags, effort metadata) lives in
      *  metrics[0].metadata — shape-uniform with events. */
@@ -983,10 +1139,119 @@ interface UnifiedEventRecord {
         ended?: number;
     };
     sourceBlockKey?: string;
+    sourceStatementId?: number;
+    line?: number;
+    text?: string;
+    dialect?: string;
     stackLevel?: number;
     completionReason?: string;
     segmentId?: string;
     segmentVersion?: number;
+    /** Per-metric temporal anchors (ticket 12) — parallel to `metrics` when
+     *  the producing statement carries its own instants/dates:
+     *  'instant' = recorded occurrence instant; 'civil-date' = recorded civil
+     *  date (date-only wellness), never a fabricated midnight. The row
+     *  timestamp remains the V16 fetch anchor until the by-metricDate index
+     *  (ticket 14); it must not relocate a metric whose own date differs. */
+    metricTemporal?: MetricTemporal[];
+    /** Ticket 14: civil-date keys (d:YYYY-MM-DD) of every metricTemporal with
+     *  temporalKind 'civil-date' — the multiEntry `by-metric-date` index
+     *  source. Kept distinct from the instant index on purpose: a date-only
+     *  observation is never a midnight instant. */
+    metricDateKeys?: string[];
+    /** Ticket 14 provenance: how this row represents the underlying
+     *  observations — directly recorded, calculated, or a substitute summary. */
+    representationKind?: 'direct' | 'calculated' | 'substitute_summary';
+    /** Ticket 14: the temporal/production scope a substitute summary covers. */
+    summaryCoverage?: SummaryCoverage;
+    /** Ticket 14: retained reducer statistics for substitution proofs. */
+    reducerStats?: ReducerStats;
+}
+/** Scope descriptor of a substitute summary's coverage (ticket 14). */
+interface SummaryCoverage {
+    scope: 'workout' | 'effort' | 'partition';
+    effortSlug?: string;
+    /** Partition identity (group-tag pairs, key-sorted). */
+    groupTags?: Record<string, string>;
+}
+/** Retained statistics for substitution proofs (ticket 16 consumes).
+ *  `observedCount` is the true represented observation count — never
+ *  invented for legacy rows that lack it (undefined = insufficient
+ *  evidence, not 1). */
+interface ReducerStats {
+    observedCount?: number;
+    sum?: number;
+    min?: number;
+    max?: number;
+}
+interface MetricTemporal {
+    temporalKind: 'instant' | 'civil-date';
+    /** Occurrence instant (ms epoch) when temporalKind === 'instant'. */
+    instant?: number;
+    /** Civil YYYY-MM-DD when temporalKind === 'civil-date'. */
+    civilDate?: string;
+}
+/** One typed field identity in the catalog. `id` is the collision-free
+ *  typed key (see fieldRefKey in fields/fieldIdentity). */
+interface FieldCatalogEntry {
+    id: string;
+    /** Normalized full path — the ordered prefix-lookup key for typeahead. */
+    path: string;
+    kind: string;
+    /** Physical/named dimension of a numeric variant, when known. */
+    dimension?: string;
+    /** Observed original spellings → supporting-source counts (provenance,
+     *  not identity); a spelling disappears when its final support does. */
+    spellings: Record<string, number>;
+    /** Observed effective units → supporting-source counts. */
+    units: Record<string, number>;
+    /** Number of source records currently supporting this identity. */
+    sourceCount: number;
+    firstSeen: number;
+    lastSeen: number;
+}
+/** One field identity a source record supports, with everything needed to
+ *  reverse the contribution (per-source unit/spelling/value evidence). */
+interface FieldContribution {
+    fieldId: string;
+    path: string;
+    kind: string;
+    unit?: string;
+    /** Original spelling this source used. */
+    spelling?: string;
+    /** Categorical value (string/boolean fields only) — original spelling. */
+    value?: string;
+}
+/** The contribution set of one stable source record — the reversal record
+ *  that makes re-saves idempotent and deletions reversible. Contributions
+ *  are attributed to their owning row id, so streaming appends, finalize
+ *  replacement, and cascade deletes reverse exactly the affected rows. */
+interface FieldSourceRecord {
+    /** `${entityKind}:${recordId}` — e.g. `result:r1`, `note:n1`. */
+    id: string;
+    contributions: Array<FieldContribution & {
+        rowId: string;
+    }>;
+}
+/** One observed categorical value of a field (string/boolean only). */
+interface FieldValueRecord {
+    key: [string, string];
+    fieldId: string;
+    value: string;
+    sourceCount: number;
+}
+/** Backfill progress/completion marker (field_catalog_meta store). */
+interface CatalogBackfillState {
+    id: 'backfill';
+    status: 'initializing' | 'complete';
+    /** Last processed source key per source store (resume cursor). */
+    cursor?: {
+        results?: string;
+        notes?: string;
+        events?: string;
+    };
+    revision: number;
+    updatedAt: number;
 }
 
 /**
@@ -1014,7 +1279,7 @@ declare const VALID_FENCE_DIALECTS: FenceDialect[];
  */
 declare function runAffordance(baseTag: string): 'run' | 'log' | null;
 /** Section types the editor can parse and render */
-type SectionType = 'title' | 'markdown' | 'time' | 'log' | 'frontmatter' | 'embed';
+type SectionType = 'title' | 'markdown' | 'time' | 'log' | 'frontmatter' | 'embed' | 'code' | 'widget' | 'query';
 /** Workout section types — the runnable/recorded fence tags */
 type WorkoutSectionType = Extract<SectionType, FenceDialect>;
 /** Type guard for workout sections */
@@ -1059,6 +1324,7 @@ interface Section {
     id: string;
     contentId?: string;
     type: SectionType;
+    subtype?: string;
     rawContent: string;
     displayContent: string;
     startLine: number;
@@ -1066,6 +1332,9 @@ interface Section {
     lineCount: number;
     level?: number;
     sport?: string;
+    widgetName?: string;
+    queryType?: string;
+    queryError?: string;
     scriptBlock?: ScriptBlock;
     properties?: Record<string, string>;
     frontmatterType?: FrontMatterSubtype;
@@ -1118,17 +1387,67 @@ interface IScript {
     getAt(index: number): ICodeStatement | undefined;
 }
 
+/**
+ * Try to match a line against known workout fence patterns.
+ * Returns the base tag and optional :sport suffix, or null otherwise.
+ */
+declare function matchDialectFence(trimmedLine: string): {
+    dialect: FenceDialect;
+    sport?: string;
+} | null;
+/**
+ * Detects all WOD blocks in markdown content.
+ * Recognises ```time and ```log as valid workout fences (optional :sport suffix).
+ *
+ * @param content - Markdown content to parse
+ * @returns Array of detected WOD blocks (with dialect set)
+ */
+declare function detectScriptBlocks(content: string): ScriptBlock[];
+/**
+ * Find which block contains a given line number.
+ *
+ * @param blocks - Array of WOD blocks
+ * @param lineNumber - Line number to search for (0-indexed)
+ * @returns The block containing the line, or null if not found
+ */
+declare function findBlockAtLine(blocks: ScriptBlock[], lineNumber: number): ScriptBlock | null;
+/**
+ * Extract WOD block content from markdown (without backticks).
+ *
+ * @param content - Full markdown content
+ * @param startLine - Start line of block (0-indexed)
+ * @param endLine - End line of block (0-indexed)
+ * @returns Extracted block content
+ */
+declare function extractBlockContent(content: string, startLine: number, endLine: number): string;
+
+interface SectionMetadata {
+    id: string;
+    version: number;
+    createdAt: number;
+}
+/**
+ * Generate a deterministic section ID from type, startLine (0-indexed), and a content hash.
+ * Stable across re-parses when structure doesn't change.
+ */
+declare function generateSectionId(type: SectionType | string, startLine: number, content: string): string;
+
+declare function parseDocumentSections(content: string, scriptBlocks?: ScriptBlock[]): Section[];
+declare function buildRawContent(sections: Section[]): string;
+declare function calculateTotalLines(sections: Section[]): number;
+declare function matchSectionIds(oldSections: Section[], newSections: Section[]): Section[];
+
 /**
  * Auto-generated build version metadata.
  * Do not edit directly; updated by scripts/stamp-version.ts
  */
-declare const VERSION = "0.11.43";
-declare const GIT_SHA = "ed28149";
-declare const BUILD_TIME = "2026-08-26T16:34:15.927Z";
+declare const VERSION = "0.35.2116";
+declare const GIT_SHA = "a4d411f";
+declare const BUILD_TIME = "2026-10-12T00:14:24.795Z";
 declare const SEMVER: {
-    readonly version: "0.11.43";
-    readonly gitSha: "ed28149";
-    readonly buildTime: "2026-08-26T16:34:15.927Z";
+    readonly version: "0.35.2116";
+    readonly gitSha: "a4d411f";
+    readonly buildTime: "2026-10-12T00:14:24.795Z";
 };
 
-export { type AnalyticsDataPoint, type AnalyticsGraphConfig, type AnalyticsGroup, type Attachment, BUILD_TIME, type BlockIndexRow, BlockKey, CodeMetadata, CodeStatement, type DialectAnalysis, type DisplayStatus, Duration, type EventGrain, type FenceDialect, type FrontMatterSubtype, GIT_SHA, 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, KNOWN_OUTPUT_TYPES, 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, SEMVER, 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, type UnifiedEventRecord, VALID_FENCE_DIALECTS, VERSION, type VisualizerFilter, type VisualizerSize, type WorkoutResult, type WorkoutResults, type WorkoutSectionType, createMetricOwnershipLedger, fromNotebookTag, getMetricOwnershipLayer, isNotebookTag, isWorkoutSectionType, ownershipRank, runAffordance, toNotebookTag };
+export { type AnalyticsDataPoint, type AnalyticsGraphConfig, type AnalyticsGroup, type Attachment, BUILD_TIME, type BlockIndexRow, BlockKey, type CatalogBackfillState, CodeMetadata, CodeStatement, type DialectAnalysis, type DimensionKey, type DisplayStatus, type EventGrain, type EventRecord, type FenceDialect, type FieldCatalogEntry, type FieldContribution, type FieldLeaf, type FieldRef, type FieldSourceRecord, type FieldValueKind, type FieldValueRecord, type FrontMatterSubtype, GIT_SHA, type IBlockKey, type ICodeMetadata, type ICodeStatement, type IDialect, type IDialectTagDescriptor, type IMetric, type IMetricOwnershipResolver, type IMetricSource, type IOutputStatement, type IScript, KNOWN_OUTPUT_TYPES, 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, type MetricTemporal, MetricType, type MetricWithOptionalOwnershipLayer, NOTEBOOK_TAG_PREFIX, type Note, type NoteKind, type NoteSegment, type NoteTag, type Notebook, type NullValueKind, type Origin, OutputStatement, type OutputStatementOptions, type OutputStatementType, OwnershipResolver, type Page, type PageNote, type ParseError, ParsedCodeStatement, type ReducerStats, type ResultOrigin, SEMVER, SYSTEM_DEFAULT_OUTPUT_UNIT, type ScriptBlock, type ScriptBlockState, type Section, type SectionDocument, type SectionMetadata, type SectionType, type Segment, type SegmentDataType, type Session, type StoredOutputStatement, type SummaryCoverage, type Tag, type TagType, type TagTypeRecord, type TimeSpan, UNIT_CATALOG, UnitConversionError, type UnitDefinition, type UnitErrorCode, VALID_FENCE_DIALECTS, VERSION, type VisualizerFilter, type VisualizerSize, type WorkoutResults, type WorkoutSectionType, blockContentId, buildRawContent, calculateTotalLines, convertViaCatalog, createMetricOwnershipLedger, detectScriptBlocks, dimensionKeyOf, extractBlockContent, fieldRefFromKey, fieldRefKey, findBlockAtLine, flattenFieldLeaves, fromNotebookTag, generateSectionId, getMetricOwnershipLayer, isNotebookTag, isWorkoutSectionType, lookupUnit, matchDialectFence, matchSectionIds, normalizeFieldComponent, normalizeFieldPath, ownershipRank, parseDocumentSections, resolveLayer, runAffordance, systemDefaultUnit, toNotebookTag, valueKindOf };