@bitcobblers/wod-wiki-wql 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,896 @@
+import { LRParser } from '@lezer/lr';
+import { LanguageSupport, HighlightStyle, LRLanguage } from '@codemirror/language';
+import { CompletionContext, CompletionResult } from '@codemirror/autocomplete';
+import { Extension } from '@codemirror/state';
+import { ResultOrigin, AnalyticsDataPoint, BlockIndexRow, Note, WorkoutResult, StoredOutputStatement } from '@bitcobblers/wod-wiki-core';
+
+/**
+ * WQL vocabulary — the single owner of the WQL dictionary: aggregators,
+ * comparison operators, metric families/aggregates, calc.* targets, tag
+ * keys, dimensions, rollup periods, grains, sources, scopes, display units,
+ * and structural keywords. Every surface that needs these words imports from
+ * here (or from language.ts, which re-exports this module for editor
+ * consumers) rather than hand-writing its own copy — issue #871.
+ *
+ * The calc registry's built-in calcs (@bitcobblers/wod-wiki-lang's calc seeds)
+ * publish exactly the `calc.*` targets listed in WQL_CALC_TARGETS; keep the
+ * two in sync. User-authored calcs extend this set at runtime.
+ */
+/** Canonical Metric Key families (CONTEXT.md §Analytics). */
+declare const WQL_METRIC_FAMILIES: readonly ["reps", "distance", "resistance", "elapsed", "power", "pace"];
+type WqlMetricFamily = (typeof WQL_METRIC_FAMILIES)[number];
+/** Tier-2 aggregate keys written to the Analytics Store. */
+declare const WQL_METRIC_AGGREGATES: readonly ["totalVolume", "totalDistance", "tis", "sessionLoad"];
+type WqlMetricAggregate = (typeof WQL_METRIC_AGGREGATES)[number];
+/** Aggregate head operators for the analytics grammar (agg:metric{filters}). */
+declare const WQL_AGGREGATORS: readonly ["sum", "avg", "min", "max", "count", "last", "delta"];
+type WqlAggregator = (typeof WQL_AGGREGATORS)[number];
+/** Comparison operators for cross-store `where` joins (#800). */
+declare const WQL_COMPARISON_OPS: readonly [">", ">=", "<", "<=", "==", "!="];
+type WqlComparisonOp = (typeof WQL_COMPARISON_OPS)[number];
+/** Tag keys the Query Service reads off a fact row (QueryService.factTagValue). */
+declare const WQL_TAG_KEYS: readonly ["effort", "discipline", "intensity", "note", "page", "origin", "grain", "metric", "block", "result", "tags"];
+type WqlTagKey = (typeof WQL_TAG_KEYS)[number];
+/** Virtual dimensions — time buckets and stream positions, not fact fields. */
+declare const WQL_VIRTUAL_DIMS: readonly ["day", "week", "session", "round"];
+type WqlVirtualDim = (typeof WQL_VIRTUAL_DIMS)[number];
+/**
+ * Canonical `calc.*` targets. The single source of truth for the set of
+ * calculation metric keys: source for the composer/CM6 typeahead (#871) and
+ * the dashboard's known-vs-proposed gate (model.ts). Must
+ * match the keys the calc engine registers in
+ * @bitcobblers/wod-wiki-lang seeds (`calc.e1rm`, `calc.metMinutes`,
+ * `calc.acwr`, `calc.monotony`, `calc.strain`, `calc.ctl`, `calc.atl`,
+ * `calc.tsb`, etc.). NOTE: `calc.pmc` (composite {ctl, atl, tsb} series) is
+ * deliberately absent — the store calc model publishes one scalar key per
+ * definition, so PMC ships as the three loads (#905); a composite stays
+ * 'proposed' until a dedicated series widget lands.
+ */
+declare const WQL_CALC_TARGETS: readonly ["calc.metMinutes", "calc.acwr", "calc.monotony", "calc.strain", "calc.e1rm", "calc.ctl", "calc.atl", "calc.tsb", "calc.soreness", "calc.sleep", "calc.hrv", "calc.readiness", "calc.mvcBw", "calc.ef", "calc.adherence", "calc.pct1rm", "calc.sends"];
+type WqlCalcTarget = (typeof WQL_CALC_TARGETS)[number];
+declare const WQL_INTENSITY_TIERS: readonly ["low", "moderate", "high"];
+type WqlIntensityTier = (typeof WQL_INTENSITY_TIERS)[number];
+declare const WQL_GRAINS: readonly ["segment", "summary", "rollup"];
+type WqlGrain = (typeof WQL_GRAINS)[number];
+/** Content-discovery query targets (find:<target>). */
+declare const WQL_FIND_TARGETS: readonly ["note", "block", "effort"];
+type WqlFindTarget = (typeof WQL_FIND_TARGETS)[number];
+/** Content query scopes (in <scope>). */
+declare const WQL_SCOPES: readonly ["journal", "collections", "feeds", "all"];
+type WqlScope = (typeof WQL_SCOPES)[number];
+/** Content-specific filter keys (beyond the analytics tag keys). */
+declare const WQL_CONTENT_FILTER_KEYS: readonly ["type", "text", "has", "source", "catalog", "effort", "discipline", "intensity", "note", "page", "origin", "grain", "metric", "block", "result", "tags"];
+type WqlContentFilterKey = (typeof WQL_CONTENT_FILTER_KEYS)[number];
+/**
+ * Composer source planes (issue #838, decision #836): the single `source`
+ * head slot that pivots the query kind. Content sources compile the `find:`
+ * skeleton; `metrics` compiles the aggregate skeleton. `efforts` compiles
+ * `find:effort` against the effort registry (origin/intensity/discipline
+ * vocab from types.ts). The `results` plane is
+ * deliberately absent — it needs new grammar/engine semantics and is
+ * deferred to its own ticket.
+ */
+declare const WQL_SOURCES: readonly ["journal", "collections", "feeds", "notes", "blocks", "efforts", "metrics"];
+type WqlSource = (typeof WQL_SOURCES)[number];
+/** Rollup periods the aggregate grammar accepts (wql.ts: unit d|w only). */
+declare const WQL_ROLLUP_PERIODS: readonly ["1d", "1w"];
+type WqlRollupPeriod = (typeof WQL_ROLLUP_PERIODS)[number];
+/** Display units the app can render (analytics unit preference, kg/lb). The
+ *  `in <unit>` directive accepts any word; these are the canonical options. */
+declare const WQL_DISPLAY_UNITS: readonly ["kg", "lb"];
+type WqlDisplayUnit = (typeof WQL_DISPLAY_UNITS)[number];
+/** All WQL keywords */
+declare const WQL_KEYWORDS: readonly ["find", "rows", "where", "group", "by", "order", "limit", "sum", "avg", "min", "max", "count", "last", "delta"];
+type WqlKeyword = (typeof WQL_KEYWORDS)[number];
+
+declare const parser: LRParser;
+
+declare const Query = 1;
+declare const Head = 2;
+declare const Aggregator$1 = 3;
+declare const Word = 4;
+declare const Metric = 5;
+declare const Filters = 6;
+declare const Filter = 7;
+declare const Negate = 8;
+declare const TagKey = 9;
+declare const TagValue$1 = 10;
+declare const Value = 11;
+declare const Star = 12;
+declare const Quoted = 13;
+declare const GroupBy = 14;
+declare const By = 15;
+declare const Dimension = 16;
+declare const Rollup = 17;
+declare const RollupDot = 18;
+declare const Int = 19;
+
+declare const wql_parser_terms_By: typeof By;
+declare const wql_parser_terms_Dimension: typeof Dimension;
+declare const wql_parser_terms_Filter: typeof Filter;
+declare const wql_parser_terms_Filters: typeof Filters;
+declare const wql_parser_terms_GroupBy: typeof GroupBy;
+declare const wql_parser_terms_Head: typeof Head;
+declare const wql_parser_terms_Int: typeof Int;
+declare const wql_parser_terms_Metric: typeof Metric;
+declare const wql_parser_terms_Negate: typeof Negate;
+declare const wql_parser_terms_Query: typeof Query;
+declare const wql_parser_terms_Quoted: typeof Quoted;
+declare const wql_parser_terms_Rollup: typeof Rollup;
+declare const wql_parser_terms_RollupDot: typeof RollupDot;
+declare const wql_parser_terms_Star: typeof Star;
+declare const wql_parser_terms_TagKey: typeof TagKey;
+declare const wql_parser_terms_Value: typeof Value;
+declare const wql_parser_terms_Word: typeof Word;
+declare namespace wql_parser_terms {
+  export { Aggregator$1 as Aggregator, wql_parser_terms_By as By, wql_parser_terms_Dimension as Dimension, wql_parser_terms_Filter as Filter, wql_parser_terms_Filters as Filters, wql_parser_terms_GroupBy as GroupBy, wql_parser_terms_Head as Head, wql_parser_terms_Int as Int, wql_parser_terms_Metric as Metric, wql_parser_terms_Negate as Negate, wql_parser_terms_Query as Query, wql_parser_terms_Quoted as Quoted, wql_parser_terms_Rollup as Rollup, wql_parser_terms_RollupDot as RollupDot, wql_parser_terms_Star as Star, wql_parser_terms_TagKey as TagKey, TagValue$1 as TagValue, wql_parser_terms_Value as Value, wql_parser_terms_Word as Word };
+}
+
+/**
+ * WqlSuffix — Unified WQL suffix parser and adapter (issue #870).
+ *
+ * Encapsulates suffix parsing order, regexes, depth-0 brace-aware splitting,
+ * and AST extraction for all WQL suffix clauses:
+ *   - Outer join: `where <joinClause>`
+ *   - Display unit: `in <unit>`
+ *   - Rollup period: `.rollup(<size><unit>)`
+ *   - Group-by: `by {<dims>}`
+ *   - Time window: `last <n><unit>`
+ *   - Scope: `in <scope>`
+ */
+interface ParsedWqlRollupSuffix {
+    size: number;
+    unit: string;
+    raw: string;
+}
+interface ParsedWqlLastSuffix {
+    size: number;
+    unit: 'd' | 'w';
+    raw: string;
+}
+interface ParsedWqlSuffixes {
+    /** Outer cross-store join clause text (`where ...`). */
+    where?: string;
+    /** Display unit directive (`in kg`). */
+    displayUnit?: string;
+    /** Rollup period (`.rollup(1w)`). */
+    rollup?: ParsedWqlRollupSuffix;
+    /** Group-by dimensions (`by {week, effort}`). */
+    groupBy?: string[];
+    /** Content time window (`last 8w`). */
+    last?: ParsedWqlLastSuffix;
+    /** Content scope (`in journal` / `in all`). */
+    scope?: string;
+    /** Primary query text with suffixes removed. */
+    primaryText: string;
+}
+/**
+ * Split a query at the first top-level `where` keyword (depth-0, word-bounded).
+ * Returns the primary half and, when present, the join clause text.
+ */
+declare function splitAtWhere(text: string): {
+    primary: string;
+    where?: string;
+};
+/**
+ * Extract suffixes from a raw WQL query string.
+ * Strips outer join (`where`), display unit (`in kg`), rollup (`.rollup(1w)`),
+ * group-by (`by {week}`), time window (`last 8w`), and scope (`in journal`).
+ */
+declare function parseWqlSuffixes(raw: string): ParsedWqlSuffixes;
+
+/**
+ * WQL — Wod Query Language (Datadog-flavored). See CONTEXT.md glossary.
+ *
+ *   <aggregator>:<metric.namespace>{<tag filters>} by {<dimensions>} .rollup(<period>)
+ *
+ *   sum:totalVolume{discipline:strength} by {week}.rollup(1w)
+ *   avg:tis{effort:thruster,!discipline:recovery} by {session}
+ *
+ * This module holds the AST contract the Query Service executes and the
+ * Lezer-backed `parseQuery` front-end over grammar/wql.grammar (house
+ * pattern). The grammar accepts the full WQL surface with error recovery;
+ * this mapper validates the recovered tree and produces the AST below.
+ */
+
+type Aggregator = WqlAggregator;
+interface TagValue {
+    value: string;
+    wildcard: boolean;
+}
+interface TagFilter {
+    key: string;
+    negate: boolean;
+    values: TagValue[];
+}
+/** Comparison operator in a cross-store metric predicate (`> 5000`). */
+type ComparisonOp = WqlComparisonOp;
+/**
+ * Analytics half of a cross-store join — the metric predicate attached to a
+ * find query via `where`. Example: `sum:totalVolume{discipline:strength} > 5000`.
+ * Aggregates are evaluated against RAW WorkoutResult logs (not derived facts),
+ * joined at the blockContentId level ("logs win", issue #800).
+ */
+interface MetricPredicate {
+    agg: Aggregator;
+    metric: string;
+    filters: TagFilter[];
+    operator: ComparisonOp;
+    threshold: number;
+}
+/**
+ * Content half of a cross-store join — the find predicate attached to an
+ * analytics query via `where`. Example: `find:note{tags:competition} in journal`.
+ * Restricts the metric computation to the blockContentIds owned by matching
+ * content; the metric is recomputed from raw logs for those blocks only.
+ */
+interface FindPredicate {
+    target: string;
+    filters: TagFilter[];
+    scope?: string;
+    last?: {
+        size: number;
+        unit: 'd' | 'w';
+    };
+}
+interface ParsedQuery {
+    raw: string;
+    agg: Aggregator;
+    /** Canonical Metric Key (fact row `metricKey`). */
+    metric: string;
+    filters: TagFilter[];
+    /** Tag keys, or virtual dims: day | week | session | round. */
+    groupBy: string[];
+    rollup?: {
+        size: number;
+        unit: 'd' | 'w';
+    };
+    /** Optional display unit directive — `in kg` / `in lb`. */
+    displayUnit?: string;
+    /** Cross-store content join (`where find:note{...}`); restricts to raw logs. */
+    join?: FindPredicate;
+    error?: string;
+}
+/** Result of parsing a content-discovery query (`find:target{filters} in scope`). */
+interface ParsedFindQuery {
+    raw: string;
+    /** Content target: 'note' or 'block'. */
+    target: string;
+    filters: TagFilter[];
+    /** Where to look: journal | collections | feeds | all. */
+    scope?: string;
+    /** Time window: last 8w, last 4d. */
+    last?: {
+        size: number;
+        unit: 'd' | 'w';
+    };
+    /** Cross-store metric join (`where sum:totalVolume{} > 5000`). */
+    join?: MetricPredicate;
+    error?: string;
+}
+type AnyParsedQuery = ParsedQuery | ParsedFindQuery | ParsedRowsQuery;
+/** Type guard: true for content-discovery queries. */
+declare function isFindQuery(parsed: AnyParsedQuery): parsed is ParsedFindQuery;
+/** Type guard: true for rows queries. */
+declare function isRowsQuery(parsed: AnyParsedQuery): parsed is ParsedRowsQuery;
+interface SeriesPoint {
+    ts: number;
+    value: number;
+}
+/**
+ * Result of parsing a rows query (`rows:{filters}` / `rows:segment{filters}`) —
+ * the third WQL family (ADR docs/adr/rows-query-plane.md, #949): raw
+ * output-statement rows re-derived from WorkoutResult logs, scoped by
+ * `result:` / `block:` / `note:`. Never aggregates — no by/rollup/where.
+ */
+interface ParsedRowsQuery {
+    raw: string;
+    /** Family discriminator (the other families are told apart by 'target'/'agg'). */
+    family: 'rows';
+    /** Output-statement type narrowing from the optional target (`rows:segment{…}`); undefined = all types. */
+    outputType?: string;
+    filters: TagFilter[];
+    /** Time window over the workout end time: last 8w, last 4d. */
+    last?: {
+        size: number;
+        unit: 'd' | 'w';
+    };
+    error?: string;
+}
+interface Series {
+    key: string;
+    label: string;
+    points: SeriesPoint[];
+    unit?: string;
+}
+/**
+ * Parse a WQL query string into either an analytics ParsedQuery or a content
+ * ParsedFindQuery. Dispatch is textual: a leading `find:` routes to the
+ * content path, everything else to analytics.
+ */
+declare function parseQuery(raw: string): AnyParsedQuery;
+
+/**
+ * Canonical discipline vocabulary — the single source of truth for effort
+ * disciplines across the resolver, the TIS factor table, fact-row tags, the
+ * WQL tag dictionary, and UI filters.
+ */
+declare const EFFORT_DISCIPLINES: readonly ["bodyweight", "cycling", "gymnastics", "kettlebell", "recovery", "rowing", "running", "strength", "swimming", "walking"];
+type EffortDiscipline = (typeof EFFORT_DISCIPLINES)[number];
+declare function isEffortDiscipline(value: unknown): value is EffortDiscipline;
+/**
+ * TIS discipline multiplier per canonical discipline. Loaded modalities
+ * (strength + the loaded-skill pair kettlebell/gymnastics) score 1.2;
+ * recovery absorbs the retired 'yoga' case at 0.9; the monostructural five
+ * and bodyweight take the 1.0 default. Unknown/absent disciplines fall back
+ * to 1.0.
+ */
+declare const DISCIPLINE_FACTORS: Record<EffortDiscipline, number>;
+/** Factor for an arbitrary discipline string; 1.0 when absent or unknown. */
+declare function disciplineFactorFor(discipline: string | undefined): number;
+
+/**
+ * WQL language support — CodeMirror highlighting + autocomplete over the
+ * Lezer grammar (grammar/wql.grammar).
+ *
+ * The completion vocabulary is the analytics dictionary:
+ *   - aggregators from the AST contract (WQL_AGGREGATORS)
+ *   - Canonical Metric Keys (CONTEXT.md §Analytics): base families, Tier-2
+ *     aggregates, and `<effortSlug>.<family>` for every known effort
+ *   - Tag keys read off fact rows by the Query Service, with value
+ *     vocabularies for discipline (canonical EFFORT_DISCIPLINES), intensity,
+ *     and grain; effort values come from the EffortResolver
+ *   - virtual dimensions day | week | session | round
+ */
+
+declare const wqlLanguage: LRLanguage;
+interface WqlCompletionOptions {
+    /**
+     * Effort slugs for `{effort:…}` values and `<effortSlug>.<family>` metric
+     * keys — feed from the EffortResolver:
+     * `() => resolver.list().map(e => e.slug)`.
+     */
+    effortNames?: () => readonly string[];
+}
+declare function wqlCompletionSource(options_?: WqlCompletionOptions): (context: CompletionContext) => CompletionResult | null;
+declare function wqlCompletion(options?: WqlCompletionOptions): Extension;
+/**
+ * Query-field colors, mapped onto the app's theme tokens so
+ * the field follows light/dark mode: aggregator + structural keywords take
+ * the primary hue, the metric takes accent, tag keys secondary, values
+ * success-green, dimensions warning-ochre.
+ */
+declare const wqlHighlightStyle: HighlightStyle;
+declare function wql(completionOptions?: WqlCompletionOptions): LanguageSupport;
+
+/**
+ * Analytics unit conversion seam — narrow, fake-free, pure.
+ *
+ * Supports exactly the unit families analytics currently needs:
+ *   - mass: kg ↔ lb (exact 0.45359237 kg per lb)
+ *   - distance: m ↔ km
+ *
+ * Any unknown or incompatible units pass through unchanged.
+ */
+declare const KG_PER_LB = 0.45359237;
+type UnitFamily = 'mass' | 'distance';
+interface UnitFamilyDef {
+    /** Base unit for the family (used for documentation, not conversion). */
+    base: string;
+    /** Factor to convert FROM this unit TO the base unit. */
+    units: Record<string, number>;
+}
+declare const UNIT_FAMILIES: Record<UnitFamily, UnitFamilyDef>;
+declare function getUnitFamily(unit: string | undefined): UnitFamily | undefined;
+/**
+ * Convert a value between known units.
+ *
+ * Returns the input unchanged when:
+ *   - from === to
+ *   - either unit is unknown
+ *   - the units belong to different families
+ */
+declare function convert(value: number, from: string | undefined, to: string | undefined): number;
+/**
+ * Determine the target display unit for a set of matched facts and query
+ * options. Returns the unit to render and whether values should be converted.
+ */
+declare function resolveDisplayUnit(facts: ReadonlyArray<{
+    unit?: string;
+    metricUnit?: string;
+}>, { directive, preferred, }: {
+    directive?: string;
+    preferred?: string;
+}): {
+    unit?: string;
+    convert: boolean;
+};
+
+/**
+ * Workout derivation helpers for WQL QueryService and cross-store joins.
+ */
+
+/**
+ * Map a summary projection name to its Canonical Metric Key — the one key two
+ * workouts must share for an aggregate to be compared across them. Same key
+ * in fact rows and display. 'Total Volume' → 'totalVolume', 'TIS' → 'tis'.
+ */
+declare function resolveCanonicalMetricKey(projectionName: string): string;
+/**
+ * Identity of the block a result belongs to, stamped on every fact row.
+ */
+interface SummaryFactIdentity {
+    noteId: string;
+    resultId: string;
+    /** FK to NoteSegment.id (positional section id of the block run). */
+    segmentId?: string;
+    /** NoteSegment.version at record time. */
+    segmentVersion?: number;
+    /** Content-stable cross-note join key. */
+    blockContentId?: string;
+    /** Which surface produced the result; trend queries exclude 'playground' by default. */
+    origin?: ResultOrigin;
+    /** FK to the `page` store (copied from the parent note). */
+    pageId?: string;
+    /**
+     * Canonical workout time — WorkoutResult.createdAt (true workout end).
+     * Every fact row carries it as `timestamp` so time-range queries mean
+     * "when the workout happened", never "when the metric was derived".
+     */
+    workoutTimestamp?: number;
+}
+/** Logs shape read by normalizeSummaryFacts (StoredOutputStatement-compatible). */
+interface SummaryFactSourceOutput {
+    outputType?: string;
+    metrics: readonly {
+        type?: string;
+        value?: unknown;
+        image?: string;
+        unit?: string;
+        /** Summary-processor payload (effortSlug / effortDiscipline / effortIntensityTier / …). */
+        metadata?: Record<string, unknown>;
+    }[];
+    timeSpan?: {
+        started?: number;
+        ended?: number;
+    };
+}
+/**
+ * Convert Tier-2 summary outputs (outputType 'analytics') in a result's logs
+ * into persisted fact rows — one row per result × Canonical Metric Key.
+ */
+declare function normalizeSummaryFacts(logs: readonly SummaryFactSourceOutput[], identity: SummaryFactIdentity): AnalyticsDataPoint[];
+
+/**
+ * Pure projection of a block_index into static Notes — one Note per distinct
+ * noteId, with a `catalog` field set to `noteId.split('/')[0]`. The catalog is
+ * the directory the file lives under (e.g. `crossfit-girls` for collections,
+ * `crossfit-programming` for feeds) and is what the Library's panel uses to
+ * target the `+ Filter → Catalog` menu.
+ */
+declare function staticNotesFromBlocks(blocks: BlockIndexRow[]): Note[];
+/**
+ * Tag → noteIds index over a block index's frontmatter rows. Static-corpus
+ * notes declare tags only in frontmatter `tags:`; this recovers the mapping
+ * the note store needs to answer `tags:` clauses (issue #853 — the store
+ * previously returned an empty set for every tag).
+ */
+declare function staticTagIndexFromBlocks(blocks: BlockIndexRow[]): Map<string, Set<string>>;
+
+/**
+ * Injected store interfaces for WQL QueryService.
+ * Zero database/storage dependencies — 100% pure abstractions.
+ */
+
+/** Store surface the Query Service needs for fact rows. */
+interface FactQueryStore {
+    getFactsByMetric(metricKey: string): Promise<AnalyticsDataPoint[]>;
+    getFactsByTimeRange(start: number, end: number): Promise<AnalyticsDataPoint[]>;
+    getNoteTagLabels(noteId: string): Promise<string[]>;
+}
+/** Store surface for content queries (`find:note`). */
+interface NoteQueryStore {
+    getAllNotes(): Promise<Note[]>;
+    getNoteIdsForTag(label: string): Promise<Set<string>>;
+}
+/** Store surface for block-index queries (`find:block`). */
+interface BlockQueryStore {
+    getAllBlocks(): Promise<BlockIndexRow[]>;
+}
+/** Pure effort model interface for `find:effort` queries. */
+interface IEffort {
+    id: string;
+    slug: string;
+    label: string;
+    aliases: string[];
+    baseAttributes: {
+        met?: number;
+        discipline?: string;
+        intensityTier?: string;
+        [key: string]: unknown;
+    };
+    registrySource?: 'bundled' | 'user' | string;
+    [key: string]: unknown;
+}
+/** Store surface for effort queries (`find:effort`). */
+interface EffortQueryStore {
+    getAllEfforts(): Promise<IEffort[]>;
+}
+/** Store surface for raw WorkoutResult logs — the cross-store join & rows source. */
+interface ResultLogStore {
+    getResultsByContentId(blockContentId: string): Promise<WorkoutResult[]>;
+    /** Rows plane (#949): single-result scope (`rows:{result:…}`). */
+    getResultById(resultId: string): Promise<WorkoutResult | undefined>;
+    /** Rows plane (#949): whole-note scope (`rows:{note:…}`). */
+    getResultsForNote(noteId: string): Promise<WorkoutResult[]>;
+}
+/** Optional bundle of stores for QueryService initialization. */
+interface QueryServiceStores {
+    factStore?: FactQueryStore;
+    noteStore?: NoteQueryStore;
+    blockStore?: BlockQueryStore;
+    resultStore?: ResultLogStore;
+    effortStore?: EffortQueryStore;
+    staticNoteStore?: NoteQueryStore;
+    staticBlockStore?: BlockQueryStore;
+}
+
+/**
+ * Query Service — the executor of WQL against the Analytics Store
+ * (CONTEXT.md glossary). Four-stage physical plan:
+ *
+ *   SELECT (index-first: by-metric + by-timestamp IDBKeyRange fetches,
+ *           intersected in memory)
+ *   BUCKET (time dim or rollup period)
+ *   AGGREGATE (per bucket)
+ *   GROUP (tag-dimension fan-out)
+ *
+ * Inputs are uncapped — personal-journal scale; widgets and tables are dumb
+ * consumers of QueryResult. Fact rows are summary-grain AnalyticsDataPoint
+ * rows; Tags are query-time dimensions read off the row (effort, discipline,
+ * note, intensity, …) — 'tags' resolves through the note_tags store.
+ *
+ * Fully inverted dependencies: zero IndexedDB/storage module-level imports.
+ */
+
+interface FindQueryResult {
+    parsed: ParsedFindQuery;
+    notes: Note[];
+    blocks: BlockIndexRow[];
+    /** Registry rows for find:effort queries. */
+    efforts?: IEffort[];
+    stages: {
+        selected: number;
+        matched: number;
+    };
+}
+interface QueryOptions {
+    rangeStart?: number;
+    rangeEnd?: number;
+    /** App-level unit preference ('kg' | 'lb'). Used when query has no `in <unit>` directive. */
+    preferredUnit?: string;
+}
+/** Options for `runFind` / `runFindBlock` — overrides for the parsed WQL. */
+interface FindOptions {
+    /** Explicit timestamp range; overrides parsed WQL's `last` clause when set. */
+    range?: {
+        start: number;
+        end: number;
+    };
+    /** Time-window anchoring mode. 'wall-clock' anchors to Date.now();
+     *  'latest-activity' anchors to the newest row in the scope selection
+     *  (#857). Defaults to 'wall-clock'. */
+    anchor?: 'wall-clock' | 'latest-activity';
+    /** Explicit reference time for the window (useful for tests/replay).
+     *  Overrides `anchor`. */
+    anchorNow?: number;
+}
+interface QueryResult {
+    parsed: ParsedQuery;
+    series: Series[];
+    stages: {
+        selected: number;
+        buckets: number;
+        aggregated: number;
+        groups: number;
+    };
+    matched: AnalyticsDataPoint[];
+    /** Single scalar value when the result has exactly one point. */
+    scalar?: number;
+    /** Result display unit, if determined by directive, preference, or fact metadata. */
+    unit?: string;
+}
+/** One run in a rows result: the stored result plus the output statements
+ *  that survived the optional output-type narrowing (`rows:segment{…}`). */
+interface RowsRun {
+    result: WorkoutResult;
+    logs: StoredOutputStatement[];
+}
+interface RowsQueryResult {
+    parsed: ParsedRowsQuery;
+    runs: RowsRun[];
+    error?: string;
+}
+declare class QueryService {
+    private readonly store;
+    private readonly noteStore;
+    private readonly blockStore;
+    private readonly resultStore;
+    private readonly effortStore;
+    private readonly staticNoteStore?;
+    private readonly staticBlockStore?;
+    constructor(storesOrFactStore?: QueryServiceStores | FactQueryStore, noteStore?: NoteQueryStore, blockStore?: BlockQueryStore, resultStore?: ResultLogStore, effortStore?: EffortQueryStore, staticNoteStore?: NoteQueryStore, staticBlockStore?: BlockQueryStore);
+    getFactsByTimeRange(start: number, end: number): Promise<AnalyticsDataPoint[]>;
+    runQuery(raw: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Execute a rows query (rows:{…}, #949) — the session results table plane.
+     * Re-derives output statements from raw WorkoutResult logs through the
+     * ResultLogStore seam ("logs win" — facts are never read for this path).
+     */
+    runRows(parsed: ParsedRowsQuery, options?: {
+        anchorNow?: number;
+    }): Promise<RowsQueryResult>;
+    /**
+     * Execute a content-discovery query (find:note). Naive in-memory filtering
+     * per the tracer-bullet scope (#797): load all notes, then apply tag/text/
+     * time filters.
+     */
+    runFind(parsed: ParsedFindQuery, options?: FindOptions): Promise<FindQueryResult>;
+    /**
+     * Execute a find:block query against the derived block_index store.
+     */
+    runFindBlock(parsed: ParsedFindQuery, options?: FindOptions): Promise<FindQueryResult>;
+    /**
+     * Execute a find:effort query against the effort registry.
+     */
+    runFindEffort(parsed: ParsedFindQuery): Promise<FindQueryResult>;
+    run(parsed: ParsedQuery, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Stages 2–4 — BUCKET → GROUP → AGGREGATE over an already-selected +
+     * filtered `matched` set.
+     */
+    private buildResult;
+    /** Direction 2 — re-derive the metric from raw logs, restricted to the
+     *  blockContentIds owned by the find predicate's content matches. */
+    private runJoined;
+    /** Direction 1 — keep only content owning a wod block whose raw-log metric
+     *  aggregate satisfies the predicate. `notes` for find:note, `blocks` for
+     *  find:block. */
+    private applyMetricJoin;
+    /** Re-derive the metric from raw logs for each content id, aggregate per id,
+     *  and return the ids whose aggregate satisfies the join predicate. */
+    private contentIdsSatisfying;
+    /** Filter per-effort vs un-attributed overall summary rows to avoid
+     *  double-counting. */
+    private applyEffortScope;
+    /** Re-derive summary facts for one Canonical Metric Key from RAW WorkoutResult
+     *  logs across the given content ids — the cross-store join source. One fact
+     *  row per result (normalizeSummaryFacts dedupes within a result). */
+    private deriveMetricFacts;
+    /** All content blocks across the journal + static corpus. */
+    private allContentBlocks;
+    /** Map each note id to the wod blockContentIds it owns. */
+    private noteContentMap;
+    /** Collect wod blockContentIds owned by a find query's content matches. */
+    private contentIdsFromFindResult;
+    /** Load note tag labels only when the query touches 'tags'. */
+    private loadNoteTags;
+}
+
+/**
+ * Dashboard Note model (#898 map, format locked in #899).
+ *
+ * A dashboard is a markdown note: frontmatter marks it (`dashboard: true`) and
+ * declares top-level controls as `dashboard.*` dot-keys; the body composes
+ * ```query[:<type>][-<N>|-full] blocks whose title/question associate from the
+ * markdown heading/paragraph directly above each block. Queries reference
+ * tokens as `$name`, substituted as raw text at execution time. A block body
+ * is one line: WQL query + optional `/`-separated positional params.
+ *
+ * This module is pure — no React, no editor, no query service — so the editor
+ * extensions, the inline block renderer, and the dashboard route all share it.
+ */
+declare const DASHBOARD_WIDGET_TYPES: readonly ["table", "value", "timeseries", "bar", "toplist", "stacked-bar", "goal-rings", "zone-distribution"];
+type DashboardWidgetType = (typeof DASHBOARD_WIDGET_TYPES)[number];
+declare function isDashboardWidgetType(type: string): type is DashboardWidgetType;
+/** The widget type a block renders as: a bare ```query fence defaults to `table`. */
+declare function resolveWidgetType(type: string | undefined): string;
+/** Shared badge messages — the editor, inline renderer, and route all word these identically. */
+declare function unknownWidgetTypeMessage(type: string): string;
+declare function unknownTokensMessage(missing: readonly string[]): string;
+/** Types whose renderer is planned for future maps (none remaining in #901). */
+declare const PLANNED_WIDGET_TYPES: readonly string[];
+/**
+ * True when a metric is a proposed calculation not yet landed in the engine
+ * (e.g. `calc.readiness`, `calc.mvcBw`, `calc.hrv`). Renderers show a labeled
+ * placeholder badge (#901).
+ */
+declare function isProposedMetric(metricKey: string | undefined): boolean;
+declare const DASHBOARD_GRID_MAX_COLS = 4;
+interface QueryWidgetSuffix {
+    /** Raw widget type from the tag, lowercased; '' for a bare ```query fence. */
+    type: string;
+    /** Grid column span 1..4 (`-N`). */
+    spanCols?: number;
+    /** Full-row flag (`-full`). Mutually exclusive with spanCols. */
+    spanFull?: boolean;
+    /** Set when the suffix is malformed (the type is still reported raw). */
+    error?: string;
+}
+/**
+ * Parse the suffix after `query:` in a fence tag — `<type>`, `<type>-<N>` or
+ * `<type>-full`. Unknown types parse fine (renderers badge them); structural
+ * problems (empty type, bad span, `-N-full` combo) set `error`.
+ */
+declare function parseQueryWidgetSuffix(suffix: string): QueryWidgetSuffix;
+/** Frontmatter meta shape. */
+type DashboardMeta = Record<string, string | number | string[]>;
+interface DashboardToken {
+    /** Token name without the `dashboard.` prefix (referenced as `$name`). */
+    name: string;
+    /** Scalar → single entry; block list → entries in declared order. */
+    values: string[];
+    /** List tokens render as segmented controls; scalars as inputs. */
+    isList: boolean;
+}
+/** True when the note's frontmatter marks it as a dashboard (`dashboard: true`). */
+declare function isDashboardMeta(meta: DashboardMeta): boolean;
+/** Extract `dashboard.*` dot-keys as tokens, in frontmatter declaration order. */
+declare function extractDashboardTokens(meta: DashboardMeta): DashboardToken[];
+/** Default value per token: the scalar, or the first list entry (its control default). */
+declare function defaultTokenValues(tokens: readonly DashboardToken[]): Record<string, string>;
+/**
+ * Write a control change back into frontmatter meta (decision #899-6): a list
+ * token reorders so the chosen value becomes the first entry (the default);
+ * a scalar token's value is replaced. Returns a NEW meta object — serialize
+ * with `serializeFrontmatter` and patch the note's frontmatter section.
+ */
+declare function setDashboardTokenValue(meta: DashboardMeta, name: string, value: string): DashboardMeta;
+/**
+ * Substitute `$name` references with token values — raw text replacement at
+ * execution time (decision #899-6). Unknown references stay literal and are
+ * reported in `missing` (renderers badge them; never silent).
+ */
+declare function substituteTokens(query: string, values: Record<string, string>): {
+    query: string;
+    missing: string[];
+};
+/** Token names a query references, in order of first appearance. */
+declare function referencedTokens(query: string): string[];
+/**
+ * Split a block body into the WQL query and its trailing `/`-separated
+ * positional parameters (decision #899-7). Splits at the FIRST ` / ` so
+ * params stay trailing; a literal ` / ` inside a tag value is pathological
+ * and unsupported. Params are whitespace-split literals or `$token` refs.
+ */
+declare function splitWidgetBody(body: string): {
+    query: string;
+    params: string[];
+};
+/** Structural input for the builder — satisfied by EditorSection + doc text. */
+interface DashboardSectionInput {
+    /** Section type ('query', 'markdown', 'frontmatter', …). */
+    type: string;
+    /** Markdown subtype ('heading', 'paragraph', …) for markdown sections. */
+    subtype?: string;
+    /** Raw inner content of the section. */
+    content: string;
+    /** Widget type suffix parsed from the fence tag (query sections). */
+    widgetType?: string;
+    /** Grid column span parsed from the fence tag (query sections). */
+    spanCols?: number;
+    /** Full-row flag parsed from the fence tag (query sections). */
+    spanFull?: boolean;
+    /** Malformed fence-suffix reason — carried so route mode badges it too. */
+    widgetError?: string;
+}
+interface DashboardWidget {
+    /** Stable key within the document (section index). */
+    key: string;
+    /** Raw widget type ('' → default `table` in dashboard composition). */
+    type: string;
+    spanCols?: number;
+    spanFull?: boolean;
+    /** Raw block body (query + params). */
+    body: string;
+    /** Malformed fence-suffix reason — renderers badge instead of executing. */
+    widgetError?: string;
+    /** WQL query after parameter split. */
+    query: string;
+    /** Positional parameters (literals or `$token` refs). */
+    params: string[];
+    /** Title from the markdown heading directly above (or above the question). */
+    title?: string;
+    /** Coaching question from the paragraph directly above the block. */
+    question?: string;
+}
+interface DashboardDocument {
+    isDashboard: boolean;
+    /** Note title from frontmatter. */
+    title?: string;
+    tokens: DashboardToken[];
+    widgets: DashboardWidget[];
+}
+/**
+ * Build the dashboard document from ordered sections + frontmatter meta.
+ *
+ * Title/question association (decision #899-4) is strictly adjacency-based:
+ * a paragraph directly above the block is its question; a heading directly
+ * above that paragraph — or directly above the block — is its title. Anything
+ * else leaves the widget untitled (renderers fall back to the query text).
+ */
+declare function buildDashboardDocument(sections: readonly DashboardSectionInput[], meta: DashboardMeta): DashboardDocument;
+
+interface DashboardParsedSection extends DashboardSectionInput {
+    /** 0-indexed start line of the section in the raw content. */
+    startLine: number;
+    /** 0-indexed inclusive end line of the section in the raw content. */
+    endLine: number;
+}
+/**
+ * Parses a raw markdown note into sections suitable for `buildDashboardDocument`,
+ * keeping track of line numbers so edits can write back to the source text.
+ */
+declare function parseDashboardNote(rawContent: string): {
+    meta: DashboardMeta;
+    sections: DashboardParsedSection[];
+};
+
+/**
+ * buildDashboardScaffold — raw markdown for a freshly created dashboard note
+ * (#907 creation flow, format locked in #899).
+ */
+declare const DEFAULT_DASHBOARD_TITLE = "New Dashboard";
+/** Slugify a dashboard title for route addressing (/dashboard/:slug). */
+declare function dashboardSlug(title: string): string;
+declare function buildDashboardScaffold(title?: string): string;
+
+/**
+ * Shared frontmatter parser utilities for WQL dashboard models and notes.
+ */
+interface ParsedFrontmatter {
+    meta: Record<string, string | number | string[]>;
+    body: string;
+}
+interface LinkWidget {
+    kind: 'youtube' | 'amazon' | 'strava' | 'source' | 'website' | 'book';
+    url?: string;
+    label: string;
+    videoId?: string;
+}
+/**
+ * Parse the leading YAML frontmatter block of a markdown string.
+ */
+declare function parseFrontmatter(raw: string): ParsedFrontmatter;
+/**
+ * Parse frontmatter body content (the lines between the `---` delimiters).
+ */
+declare function parseFrontmatterBody(innerContent: string): ParsedFrontmatter['meta'];
+/**
+ * Serialize frontmatter metadata back to YAML body lines.
+ */
+declare function serializeFrontmatter(meta: ParsedFrontmatter['meta']): string;
+/** Body of `raw` with the leading frontmatter block removed. */
+declare function stripFrontmatter(raw: string): string;
+/** Scalar value at `key`, or `undefined` when absent or a list. */
+declare function getScalar(meta: ParsedFrontmatter['meta'], key: string): string | number | undefined;
+/** List value at `key`, or `[]` when absent or a scalar. */
+declare function getList(meta: ParsedFrontmatter['meta'], key: string): string[];
+/**
+ * Parse the `category` YAML array from a full markdown string's frontmatter.
+ */
+declare function parseFrontmatterCategories(raw: string): string[];
+/**
+ * Extract the `tags` list from a frontmatter block's raw content.
+ */
+declare function extractFrontmatterTags(raw: string): string[];
+/**
+ * Parse flat scalar key-value pairs from raw inner content (no delimiters).
+ */
+declare function parseFlatProperties(innerContent: string): Record<string, string>;
+/**
+ * Parse scalar key-value pairs from an array of lines.
+ */
+declare function parseFrontmatterProps(lines: string[]): Record<string, string>;
+
+export { type Aggregator, type AnyParsedQuery, type BlockQueryStore, type ComparisonOp, DASHBOARD_GRID_MAX_COLS, DASHBOARD_WIDGET_TYPES, DEFAULT_DASHBOARD_TITLE, DISCIPLINE_FACTORS, type DashboardDocument, type DashboardMeta, type DashboardParsedSection, type DashboardSectionInput, type DashboardToken, type DashboardWidget, type DashboardWidgetType, EFFORT_DISCIPLINES, type EffortDiscipline, type EffortQueryStore, type FactQueryStore, type FindOptions, type FindPredicate, type FindQueryResult, type IEffort, KG_PER_LB, type LinkWidget, type MetricPredicate, type NoteQueryStore, PLANNED_WIDGET_TYPES, type ParsedFindQuery, type ParsedFrontmatter, type ParsedQuery, type ParsedRowsQuery, type ParsedWqlLastSuffix, type ParsedWqlRollupSuffix, type ParsedWqlSuffixes, type QueryOptions, type QueryResult, QueryService, type QueryServiceStores, type QueryWidgetSuffix, type ResultLogStore, type RowsQueryResult, type RowsRun, type Series, type SeriesPoint, type SummaryFactIdentity, type SummaryFactSourceOutput, type TagFilter, type TagValue, UNIT_FAMILIES, type UnitFamily, type UnitFamilyDef, WQL_AGGREGATORS, WQL_CALC_TARGETS, WQL_COMPARISON_OPS, WQL_CONTENT_FILTER_KEYS, WQL_DISPLAY_UNITS, WQL_FIND_TARGETS, WQL_GRAINS, WQL_INTENSITY_TIERS, WQL_KEYWORDS, WQL_METRIC_AGGREGATES, WQL_METRIC_FAMILIES, WQL_ROLLUP_PERIODS, WQL_SCOPES, WQL_SOURCES, WQL_TAG_KEYS, WQL_VIRTUAL_DIMS, type WqlAggregator, type WqlCalcTarget, type WqlComparisonOp, type WqlCompletionOptions, type WqlContentFilterKey, type WqlDisplayUnit, type WqlFindTarget, type WqlGrain, type WqlIntensityTier, type WqlKeyword, type WqlMetricAggregate, type WqlMetricFamily, type WqlRollupPeriod, type WqlScope, type WqlSource, type WqlTagKey, type WqlVirtualDim, buildDashboardDocument, buildDashboardScaffold, convert, dashboardSlug, defaultTokenValues, disciplineFactorFor, extractDashboardTokens, extractFrontmatterTags, getList, getScalar, getUnitFamily, isDashboardMeta, isDashboardWidgetType, isEffortDiscipline, isFindQuery, isProposedMetric, isRowsQuery, normalizeSummaryFacts, parseDashboardNote, parseFlatProperties, parseFrontmatter, parseFrontmatterBody, parseFrontmatterCategories, parseFrontmatterProps, parseQuery, parseQueryWidgetSuffix, parseWqlSuffixes, referencedTokens, resolveCanonicalMetricKey, resolveDisplayUnit, resolveWidgetType, serializeFrontmatter, setDashboardTokenValue, splitAtWhere, splitWidgetBody, staticNotesFromBlocks, staticTagIndexFromBlocks, stripFrontmatter, substituteTokens, unknownTokensMessage, unknownWidgetTypeMessage, wql, wqlCompletion, wqlCompletionSource, wqlHighlightStyle, wqlLanguage, parser as wqlParser, wql_parser_terms as wqlTerms };