@bitcobblers/wod-wiki-wql 0.8.39 → 0.10.41

package/dist/index.d.cts

@@ -58,9 +58,9 @@ 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];
+/** Canonical source filter values (C2): scope folded into the source: filter key. */
+declare const WQL_SOURCE_VALUES: readonly ["journal", "collections", "feeds", "all"];
+type WqlSourceValue = (typeof WQL_SOURCE_VALUES)[number];
 /** Result planes — `rows:<plane>` narrows raw output-statement rows by the
  *  unified store's promoted `outputType` column. The STORE vocabulary is
  *  open (core KNOWN_OUTPUT_TYPES, ticket 002: unknowns are stored and
@@ -152,22 +152,31 @@ declare namespace wql_parser_terms {
  * 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>`
+ *   - Display unit: `in <unit>` (analytics queries only — C2 de-overloaded `in`)
  *   - Rollup period: `.rollup(<size><unit>)`
  *   - Group-by: `by {<dims>}`
- *   - Time window: `last <n><unit>`
- *   - Scope: `in <scope>`
+ *   - Time window: `last <n><unit>` or `from <YYYY-MM-DD> [to <YYYY-MM-DD>]`
+ *     (C1 — one window per query, every family)
  */
 interface ParsedWqlRollupSuffix {
     size: number;
     unit: string;
     raw: string;
 }
-interface ParsedWqlLastSuffix {
+/** A window clause (C1): relative (`last 8w`) or civil-date range
+ *  (`from 2026-01-01 [to 2026-03-31]`). One window per query — `last` and
+ *  `from` are mutually exclusive (validated as a C3-style conflict). */
+type ParsedWqlWindowSuffix = {
+    kind: 'relative';
     size: number;
     unit: 'd' | 'w';
     raw: string;
-}
+} | {
+    kind: 'range';
+    start: string;
+    end?: string;
+    raw: string;
+};
 interface ParsedWqlSuffixes {
     /** Outer cross-store join clause text (`where ...`). */
     where?: string;
@@ -177,10 +186,10 @@ interface ParsedWqlSuffixes {
     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;
+    /** Time window — relative or civil-date range, legal on every family (C1). */
+    window?: ParsedWqlWindowSuffix;
+    /** Legacy scope clause (`in journal` / `in all`) stripped for the C2 compatibility normalizer. */
+    legacyScope?: string;
     /** Duplicate-clause diagnostics (C3) — each names both conflicting spans. */
     conflicts?: string[];
     /** Primary query text with suffixes removed. */
@@ -197,7 +206,8 @@ declare function splitAtWhere(text: 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`).
+ * group-by (`by {week}`), time window (`last 8w` / `from … [to …]`), and
+ * legacy scope (`in journal`).
  */
 declare function parseWqlSuffixes(raw: string): ParsedWqlSuffixes;
 
@@ -249,7 +259,6 @@ interface MetricPredicate {
 interface FindPredicate {
     target: string;
     filters: TagFilter[];
-    scope?: string;
     last?: {
         size: number;
         unit: 'd' | 'w';
@@ -272,10 +281,14 @@ interface ParsedAggregateQuery {
         size: number;
         unit: 'd' | 'w';
     };
+    /** Time-selection window (C1): `last 6w` or `from … [to …]`. */
+    window?: QueryWindow;
     /** Optional display unit directive — `in kg` / `in lb`. */
     displayUnit?: string;
     /** Cross-store content join (`where find:note{...}`); restricts to raw logs. */
     join?: FindPredicate;
+    /** Deprecation advisories (C2 normalizer). */
+    advisories?: string[];
     error?: string;
 }
 /** Result of parsing a content-discovery query (`find:target{filters} in scope`). */
@@ -285,17 +298,29 @@ interface ParsedFindQuery {
     /** Content target — a WQL_FIND_TARGETS value (C7 closed enum). */
     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';
-    };
+    /** Time-selection window (C1): `last 8w` or `from … [to …]`. */
+    window?: QueryWindow;
     /** Cross-store metric join (`where sum:totalVolume{} > 5000`). */
     join?: MetricPredicate;
+    /** Deprecation advisories (C2 normalizer). */
+    advisories?: string[];
     error?: string;
 }
+/**
+ * Time-selection window (C1) — legal on every query family. `last <n><d|w>`
+ * is relative; `from <YYYY-MM-DD> [to <YYYY-MM-DD>]` is a civil-date range
+ * (local-midnight semantics, inclusive end day). One window per query;
+ * `last` and `from` are mutually exclusive (C3-style conflict).
+ */
+type QueryWindow = {
+    kind: 'relative';
+    size: number;
+    unit: 'd' | 'w';
+} | {
+    kind: 'range';
+    start: string;
+    end?: string;
+};
 type AnyParsedQuery = ParsedAggregateQuery | ParsedFindQuery | ParsedRowsQuery;
 /** Type guard: true for content-discovery queries. */
 declare function isFindQuery(parsed: AnyParsedQuery): parsed is ParsedFindQuery;
@@ -320,11 +345,11 @@ interface ParsedRowsQuery {
     /** 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';
-    };
+    /** Time-selection window (C1): `last 4w` or `from … [to …]` over the
+     *  workout end time. */
+    window?: QueryWindow;
+    /** Deprecation advisories (C2 normalizer). */
+    advisories?: string[];
     error?: string;
 }
 interface Series {
@@ -340,6 +365,46 @@ interface Series {
  * `rows` to the rows path, everything else to analytics.
  */
 declare function parseQuery(raw: string): AnyParsedQuery;
+/**
+ * C2 Compatibility normalizer: rewrites legacy query syntax into modern WQL.
+ *   - Bare `rows:{…}` heads rewrite to `rows:all{…}`
+ *   - Legacy trailing `in <scope>` rewrites into `{source:<scope>}`
+ * Returns the normalized query string and any deprecation advisories.
+ */
+declare function normalizeWql(raw: string): {
+    query: string;
+    advisories: string[];
+};
+
+/**
+ * WQL serializer (C6 — one structured interface for code).
+ *
+ * The total serializer over the C5 discriminated query union: code holds the
+ * AST; strings live only at document edges (URL `?q=`, ```query``` fences,
+ * dashboard bodies). Properties (proven by tests/serialize.test.ts):
+ *
+ *   1. `serialize(parse(x)) === x` for canonical inputs (fixed-point text), and
+ *   2. `parse(serialize(a))` is structurally equal to `a` for every AST —
+ *      equal on all query-structure fields; `raw` (provenance text) and
+ *      `advisories` (parse-time deprecation notices) are intentionally not
+ *      reproduced, since serialization emits modern canonical syntax.
+ *
+ * Errored ASTs serialize to their original `raw` text — a query that failed
+ * to parse has no well-defined structure to re-emit, and echoing the input
+ * keeps the function total.
+ *
+ * Round-trip equality holds for text-surface-representable ASTs. Three value
+ * shapes the grammar cannot express (or parses away) sit outside that
+ * contract — documented here rather than silently corrupted:
+ *   - a `"` inside a filter value: the quoted token has no escape form;
+ *   - a quoted value with `wildcard: true`: the parser forces wildcard=false
+ *     on quoted atoms (extractFilters), so the flag cannot survive;
+ *   - thresholds whose String() is exponential (>= 1e21): outside the join
+ *     comparison regex's plain-decimal domain.
+ */
+
+/** Serialize any parsed query to canonical WQL text. Total: never throws. */
+declare function serialize(parsed: AnyParsedQuery): string;
 
 /**
  * Canonical discipline vocabulary — the single source of truth for effort
@@ -974,13 +1039,13 @@ declare function parseFrontmatterProps(lines: string[]): Record<string, string>;
  * Auto-generated build version metadata.
  * Do not edit directly; updated by scripts/stamp-version.ts
  */
-declare const VERSION = "0.8.39";
-declare const GIT_SHA = "3c19185";
-declare const BUILD_TIME = "2026-08-26T00:07:31.934Z";
+declare const VERSION = "0.10.41";
+declare const GIT_SHA = "1b9b771";
+declare const BUILD_TIME = "2026-08-26T04:16:38.418Z";
 declare const SEMVER: {
-    readonly version: "0.8.39";
-    readonly gitSha: "3c19185";
-    readonly buildTime: "2026-08-26T00:07:31.934Z";
+    readonly version: "0.10.41";
+    readonly gitSha: "1b9b771";
+    readonly buildTime: "2026-08-26T04:16:38.418Z";
 };
 
-export { type Aggregator, type AnyParsedQuery, BUILD_TIME, 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 EventRowIdentity, type FindOptions, type FindPredicate, type FindQueryResult, GIT_SHA, type IEffort, KG_PER_LB, type LinkWidget, type MetricPredicate, type NoteQueryStore, PLANNED_WIDGET_TYPES, type ParsedAggregateQuery, type ParsedFindQuery, type ParsedFrontmatter, type ParsedRowsQuery, type ParsedWqlLastSuffix, type ParsedWqlRollupSuffix, type ParsedWqlSuffixes, type QueryOptions, type QueryResult, QueryService, type QueryServiceStores, type QueryWidgetSuffix, type RowsQueryResult, type RowsRun, SEMVER, type Series, type SeriesPoint, type SummaryFactIdentity, type SummaryFactSourceOutput, type TagFilter, type TagValue, UNIT_FAMILIES, type UnifiedEventStore, type UnitFamily, type UnitFamilyDef, VERSION, 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_RESULT_PLANES, WQL_ROLLUP_PERIODS, WQL_ROWS_SCOPE_KEYS, WQL_ROWS_TARGETS, 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 WqlResultPlane, type WqlRollupPeriod, type WqlRowsTarget, type WqlScope, type WqlSource, type WqlTagKey, type WqlVirtualDim, buildDashboardDocument, buildDashboardScaffold, convert, dashboardSlug, defaultTokenValues, disciplineFactorFor, extractDashboardTokens, extractFrontmatterTags, getList, getScalar, getUnitFamily, isAggregateQuery, isDashboardMeta, isDashboardWidgetType, isEffortDiscipline, isFindQuery, isProposedMetric, isRowsQuery, normalizeSummaryFacts, parseDashboardNote, parseFlatProperties, parseFrontmatter, parseFrontmatterBody, parseFrontmatterCategories, parseFrontmatterProps, parseQuery, parseQueryWidgetSuffix, parseWqlSuffixes, projectEventToFacts, referencedTokens, resolveCanonicalMetricKey, resolveDisplayUnit, resolveWidgetType, serializeFrontmatter, setDashboardTokenValue, splitAtWhere, splitWidgetBody, staticNotesFromBlocks, staticTagIndexFromBlocks, stripFrontmatter, substituteTokens, toEventRows, toSummaryEventRows, unknownTokensMessage, unknownWidgetTypeMessage, wql, wqlCompletion, wqlCompletionSource, wqlHighlightStyle, wqlLanguage, parser as wqlParser, wql_parser_terms as wqlTerms };
+export { type Aggregator, type AnyParsedQuery, BUILD_TIME, 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 EventRowIdentity, type FindOptions, type FindPredicate, type FindQueryResult, GIT_SHA, type IEffort, KG_PER_LB, type LinkWidget, type MetricPredicate, type NoteQueryStore, PLANNED_WIDGET_TYPES, type ParsedAggregateQuery, type ParsedFindQuery, type ParsedFrontmatter, type ParsedRowsQuery, type ParsedWqlRollupSuffix, type ParsedWqlSuffixes, type ParsedWqlWindowSuffix, type QueryOptions, type QueryResult, QueryService, type QueryServiceStores, type QueryWidgetSuffix, type QueryWindow, type RowsQueryResult, type RowsRun, SEMVER, type Series, type SeriesPoint, type SummaryFactIdentity, type SummaryFactSourceOutput, type TagFilter, type TagValue, UNIT_FAMILIES, type UnifiedEventStore, type UnitFamily, type UnitFamilyDef, VERSION, 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_RESULT_PLANES, WQL_ROLLUP_PERIODS, WQL_ROWS_SCOPE_KEYS, WQL_ROWS_TARGETS, WQL_SOURCES, WQL_SOURCE_VALUES, 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 WqlResultPlane, type WqlRollupPeriod, type WqlRowsTarget, type WqlSource, type WqlSourceValue, type WqlTagKey, type WqlVirtualDim, buildDashboardDocument, buildDashboardScaffold, convert, dashboardSlug, defaultTokenValues, disciplineFactorFor, extractDashboardTokens, extractFrontmatterTags, getList, getScalar, getUnitFamily, isAggregateQuery, isDashboardMeta, isDashboardWidgetType, isEffortDiscipline, isFindQuery, isProposedMetric, isRowsQuery, normalizeSummaryFacts, normalizeWql, parseDashboardNote, parseFlatProperties, parseFrontmatter, parseFrontmatterBody, parseFrontmatterCategories, parseFrontmatterProps, parseQuery, parseQueryWidgetSuffix, parseWqlSuffixes, projectEventToFacts, referencedTokens, resolveCanonicalMetricKey, resolveDisplayUnit, resolveWidgetType, serialize, serializeFrontmatter, setDashboardTokenValue, splitAtWhere, splitWidgetBody, staticNotesFromBlocks, staticTagIndexFromBlocks, stripFrontmatter, substituteTokens, toEventRows, toSummaryEventRows, unknownTokensMessage, unknownWidgetTypeMessage, wql, wqlCompletion, wqlCompletionSource, wqlHighlightStyle, wqlLanguage, parser as wqlParser, wql_parser_terms as wqlTerms };

package/dist/index.d.ts

@@ -58,9 +58,9 @@ 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];
+/** Canonical source filter values (C2): scope folded into the source: filter key. */
+declare const WQL_SOURCE_VALUES: readonly ["journal", "collections", "feeds", "all"];
+type WqlSourceValue = (typeof WQL_SOURCE_VALUES)[number];
 /** Result planes — `rows:<plane>` narrows raw output-statement rows by the
  *  unified store's promoted `outputType` column. The STORE vocabulary is
  *  open (core KNOWN_OUTPUT_TYPES, ticket 002: unknowns are stored and
@@ -152,22 +152,31 @@ declare namespace wql_parser_terms {
  * 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>`
+ *   - Display unit: `in <unit>` (analytics queries only — C2 de-overloaded `in`)
  *   - Rollup period: `.rollup(<size><unit>)`
  *   - Group-by: `by {<dims>}`
- *   - Time window: `last <n><unit>`
- *   - Scope: `in <scope>`
+ *   - Time window: `last <n><unit>` or `from <YYYY-MM-DD> [to <YYYY-MM-DD>]`
+ *     (C1 — one window per query, every family)
  */
 interface ParsedWqlRollupSuffix {
     size: number;
     unit: string;
     raw: string;
 }
-interface ParsedWqlLastSuffix {
+/** A window clause (C1): relative (`last 8w`) or civil-date range
+ *  (`from 2026-01-01 [to 2026-03-31]`). One window per query — `last` and
+ *  `from` are mutually exclusive (validated as a C3-style conflict). */
+type ParsedWqlWindowSuffix = {
+    kind: 'relative';
     size: number;
     unit: 'd' | 'w';
     raw: string;
-}
+} | {
+    kind: 'range';
+    start: string;
+    end?: string;
+    raw: string;
+};
 interface ParsedWqlSuffixes {
     /** Outer cross-store join clause text (`where ...`). */
     where?: string;
@@ -177,10 +186,10 @@ interface ParsedWqlSuffixes {
     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;
+    /** Time window — relative or civil-date range, legal on every family (C1). */
+    window?: ParsedWqlWindowSuffix;
+    /** Legacy scope clause (`in journal` / `in all`) stripped for the C2 compatibility normalizer. */
+    legacyScope?: string;
     /** Duplicate-clause diagnostics (C3) — each names both conflicting spans. */
     conflicts?: string[];
     /** Primary query text with suffixes removed. */
@@ -197,7 +206,8 @@ declare function splitAtWhere(text: 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`).
+ * group-by (`by {week}`), time window (`last 8w` / `from … [to …]`), and
+ * legacy scope (`in journal`).
  */
 declare function parseWqlSuffixes(raw: string): ParsedWqlSuffixes;
 
@@ -249,7 +259,6 @@ interface MetricPredicate {
 interface FindPredicate {
     target: string;
     filters: TagFilter[];
-    scope?: string;
     last?: {
         size: number;
         unit: 'd' | 'w';
@@ -272,10 +281,14 @@ interface ParsedAggregateQuery {
         size: number;
         unit: 'd' | 'w';
     };
+    /** Time-selection window (C1): `last 6w` or `from … [to …]`. */
+    window?: QueryWindow;
     /** Optional display unit directive — `in kg` / `in lb`. */
     displayUnit?: string;
     /** Cross-store content join (`where find:note{...}`); restricts to raw logs. */
     join?: FindPredicate;
+    /** Deprecation advisories (C2 normalizer). */
+    advisories?: string[];
     error?: string;
 }
 /** Result of parsing a content-discovery query (`find:target{filters} in scope`). */
@@ -285,17 +298,29 @@ interface ParsedFindQuery {
     /** Content target — a WQL_FIND_TARGETS value (C7 closed enum). */
     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';
-    };
+    /** Time-selection window (C1): `last 8w` or `from … [to …]`. */
+    window?: QueryWindow;
     /** Cross-store metric join (`where sum:totalVolume{} > 5000`). */
     join?: MetricPredicate;
+    /** Deprecation advisories (C2 normalizer). */
+    advisories?: string[];
     error?: string;
 }
+/**
+ * Time-selection window (C1) — legal on every query family. `last <n><d|w>`
+ * is relative; `from <YYYY-MM-DD> [to <YYYY-MM-DD>]` is a civil-date range
+ * (local-midnight semantics, inclusive end day). One window per query;
+ * `last` and `from` are mutually exclusive (C3-style conflict).
+ */
+type QueryWindow = {
+    kind: 'relative';
+    size: number;
+    unit: 'd' | 'w';
+} | {
+    kind: 'range';
+    start: string;
+    end?: string;
+};
 type AnyParsedQuery = ParsedAggregateQuery | ParsedFindQuery | ParsedRowsQuery;
 /** Type guard: true for content-discovery queries. */
 declare function isFindQuery(parsed: AnyParsedQuery): parsed is ParsedFindQuery;
@@ -320,11 +345,11 @@ interface ParsedRowsQuery {
     /** 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';
-    };
+    /** Time-selection window (C1): `last 4w` or `from … [to …]` over the
+     *  workout end time. */
+    window?: QueryWindow;
+    /** Deprecation advisories (C2 normalizer). */
+    advisories?: string[];
     error?: string;
 }
 interface Series {
@@ -340,6 +365,46 @@ interface Series {
  * `rows` to the rows path, everything else to analytics.
  */
 declare function parseQuery(raw: string): AnyParsedQuery;
+/**
+ * C2 Compatibility normalizer: rewrites legacy query syntax into modern WQL.
+ *   - Bare `rows:{…}` heads rewrite to `rows:all{…}`
+ *   - Legacy trailing `in <scope>` rewrites into `{source:<scope>}`
+ * Returns the normalized query string and any deprecation advisories.
+ */
+declare function normalizeWql(raw: string): {
+    query: string;
+    advisories: string[];
+};
+
+/**
+ * WQL serializer (C6 — one structured interface for code).
+ *
+ * The total serializer over the C5 discriminated query union: code holds the
+ * AST; strings live only at document edges (URL `?q=`, ```query``` fences,
+ * dashboard bodies). Properties (proven by tests/serialize.test.ts):
+ *
+ *   1. `serialize(parse(x)) === x` for canonical inputs (fixed-point text), and
+ *   2. `parse(serialize(a))` is structurally equal to `a` for every AST —
+ *      equal on all query-structure fields; `raw` (provenance text) and
+ *      `advisories` (parse-time deprecation notices) are intentionally not
+ *      reproduced, since serialization emits modern canonical syntax.
+ *
+ * Errored ASTs serialize to their original `raw` text — a query that failed
+ * to parse has no well-defined structure to re-emit, and echoing the input
+ * keeps the function total.
+ *
+ * Round-trip equality holds for text-surface-representable ASTs. Three value
+ * shapes the grammar cannot express (or parses away) sit outside that
+ * contract — documented here rather than silently corrupted:
+ *   - a `"` inside a filter value: the quoted token has no escape form;
+ *   - a quoted value with `wildcard: true`: the parser forces wildcard=false
+ *     on quoted atoms (extractFilters), so the flag cannot survive;
+ *   - thresholds whose String() is exponential (>= 1e21): outside the join
+ *     comparison regex's plain-decimal domain.
+ */
+
+/** Serialize any parsed query to canonical WQL text. Total: never throws. */
+declare function serialize(parsed: AnyParsedQuery): string;
 
 /**
  * Canonical discipline vocabulary — the single source of truth for effort
@@ -974,13 +1039,13 @@ declare function parseFrontmatterProps(lines: string[]): Record<string, string>;
  * Auto-generated build version metadata.
  * Do not edit directly; updated by scripts/stamp-version.ts
  */
-declare const VERSION = "0.8.39";
-declare const GIT_SHA = "3c19185";
-declare const BUILD_TIME = "2026-08-26T00:07:31.934Z";
+declare const VERSION = "0.10.41";
+declare const GIT_SHA = "1b9b771";
+declare const BUILD_TIME = "2026-08-26T04:16:38.418Z";
 declare const SEMVER: {
-    readonly version: "0.8.39";
-    readonly gitSha: "3c19185";
-    readonly buildTime: "2026-08-26T00:07:31.934Z";
+    readonly version: "0.10.41";
+    readonly gitSha: "1b9b771";
+    readonly buildTime: "2026-08-26T04:16:38.418Z";
 };
 
-export { type Aggregator, type AnyParsedQuery, BUILD_TIME, 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 EventRowIdentity, type FindOptions, type FindPredicate, type FindQueryResult, GIT_SHA, type IEffort, KG_PER_LB, type LinkWidget, type MetricPredicate, type NoteQueryStore, PLANNED_WIDGET_TYPES, type ParsedAggregateQuery, type ParsedFindQuery, type ParsedFrontmatter, type ParsedRowsQuery, type ParsedWqlLastSuffix, type ParsedWqlRollupSuffix, type ParsedWqlSuffixes, type QueryOptions, type QueryResult, QueryService, type QueryServiceStores, type QueryWidgetSuffix, type RowsQueryResult, type RowsRun, SEMVER, type Series, type SeriesPoint, type SummaryFactIdentity, type SummaryFactSourceOutput, type TagFilter, type TagValue, UNIT_FAMILIES, type UnifiedEventStore, type UnitFamily, type UnitFamilyDef, VERSION, 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_RESULT_PLANES, WQL_ROLLUP_PERIODS, WQL_ROWS_SCOPE_KEYS, WQL_ROWS_TARGETS, 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 WqlResultPlane, type WqlRollupPeriod, type WqlRowsTarget, type WqlScope, type WqlSource, type WqlTagKey, type WqlVirtualDim, buildDashboardDocument, buildDashboardScaffold, convert, dashboardSlug, defaultTokenValues, disciplineFactorFor, extractDashboardTokens, extractFrontmatterTags, getList, getScalar, getUnitFamily, isAggregateQuery, isDashboardMeta, isDashboardWidgetType, isEffortDiscipline, isFindQuery, isProposedMetric, isRowsQuery, normalizeSummaryFacts, parseDashboardNote, parseFlatProperties, parseFrontmatter, parseFrontmatterBody, parseFrontmatterCategories, parseFrontmatterProps, parseQuery, parseQueryWidgetSuffix, parseWqlSuffixes, projectEventToFacts, referencedTokens, resolveCanonicalMetricKey, resolveDisplayUnit, resolveWidgetType, serializeFrontmatter, setDashboardTokenValue, splitAtWhere, splitWidgetBody, staticNotesFromBlocks, staticTagIndexFromBlocks, stripFrontmatter, substituteTokens, toEventRows, toSummaryEventRows, unknownTokensMessage, unknownWidgetTypeMessage, wql, wqlCompletion, wqlCompletionSource, wqlHighlightStyle, wqlLanguage, parser as wqlParser, wql_parser_terms as wqlTerms };
+export { type Aggregator, type AnyParsedQuery, BUILD_TIME, 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 EventRowIdentity, type FindOptions, type FindPredicate, type FindQueryResult, GIT_SHA, type IEffort, KG_PER_LB, type LinkWidget, type MetricPredicate, type NoteQueryStore, PLANNED_WIDGET_TYPES, type ParsedAggregateQuery, type ParsedFindQuery, type ParsedFrontmatter, type ParsedRowsQuery, type ParsedWqlRollupSuffix, type ParsedWqlSuffixes, type ParsedWqlWindowSuffix, type QueryOptions, type QueryResult, QueryService, type QueryServiceStores, type QueryWidgetSuffix, type QueryWindow, type RowsQueryResult, type RowsRun, SEMVER, type Series, type SeriesPoint, type SummaryFactIdentity, type SummaryFactSourceOutput, type TagFilter, type TagValue, UNIT_FAMILIES, type UnifiedEventStore, type UnitFamily, type UnitFamilyDef, VERSION, 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_RESULT_PLANES, WQL_ROLLUP_PERIODS, WQL_ROWS_SCOPE_KEYS, WQL_ROWS_TARGETS, WQL_SOURCES, WQL_SOURCE_VALUES, 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 WqlResultPlane, type WqlRollupPeriod, type WqlRowsTarget, type WqlSource, type WqlSourceValue, type WqlTagKey, type WqlVirtualDim, buildDashboardDocument, buildDashboardScaffold, convert, dashboardSlug, defaultTokenValues, disciplineFactorFor, extractDashboardTokens, extractFrontmatterTags, getList, getScalar, getUnitFamily, isAggregateQuery, isDashboardMeta, isDashboardWidgetType, isEffortDiscipline, isFindQuery, isProposedMetric, isRowsQuery, normalizeSummaryFacts, normalizeWql, parseDashboardNote, parseFlatProperties, parseFrontmatter, parseFrontmatterBody, parseFrontmatterCategories, parseFrontmatterProps, parseQuery, parseQueryWidgetSuffix, parseWqlSuffixes, projectEventToFacts, referencedTokens, resolveCanonicalMetricKey, resolveDisplayUnit, resolveWidgetType, serialize, serializeFrontmatter, setDashboardTokenValue, splitAtWhere, splitWidgetBody, staticNotesFromBlocks, staticTagIndexFromBlocks, stripFrontmatter, substituteTokens, toEventRows, toSummaryEventRows, unknownTokensMessage, unknownWidgetTypeMessage, wql, wqlCompletion, wqlCompletionSource, wqlHighlightStyle, wqlLanguage, parser as wqlParser, wql_parser_terms as wqlTerms };