@honua/app-platform 0.0.20-alpha.0

package/contract/widget-source.js

@@ -0,0 +1,1473 @@
+/**
+ * CARTO-style widget data models over the canonical `Source` contract.
+ *
+ * The facade keeps dashboard widgets out of protocol-specific request
+ * shapes. It prefers server aggregation when the source advertises it, uses
+ * OData `$apply` only when metadata advertises Apply support, and stamps
+ * structured degradation reasons whenever it must materialize records on the
+ * client.
+ *
+ * @module
+ */
+import { rewriteWhereToOdataFilter } from "../core/odata.js";
+import { buildAnalyticsSourceCacheKey, normalizeAnalyticsSourceDescriptor } from "./analytics-sources.js";
+export const WIDGET_SOURCE_SCHEMA_VERSION = "honua.widget-source.v1";
+const DEFAULT_MAX_CLIENT_ROWS = 10_000;
+const DEFAULT_CATEGORY_LIMIT = 25;
+const DEFAULT_TOP_VALUES_LIMIT = 10;
+const DEFAULT_HISTOGRAM_BINS = 10;
+const MAX_HISTOGRAM_BINS = 200;
+const DEFAULT_TIME_SERIES_INTERVAL = { unit: "day", step: 1, timezone: "UTC" };
+const MAX_TIME_SERIES_BUCKETS = 500;
+export function createWidgetSource(source, options = {}) {
+    return {
+        source,
+        count: (request = {}) => count(source, options, request),
+        formula: (request) => formula(source, options, request),
+        categories: (request) => categories(source, options, request, "categories"),
+        histogram: (request) => histogram(source, options, request),
+        timeSeries: (request) => timeSeries(source, options, request),
+        range: (request) => range(source, options, request),
+        topValues: (request) => topValues(source, options, request),
+    };
+}
+export const widgetSource = createWidgetSource;
+async function count(source, options, request) {
+    throwIfAborted(request.signal);
+    const field = request.field ?? "*";
+    const alias = "widget_count";
+    const resolved = resolveWidgetQuery(source, request);
+    const odata = await tryOdataApply(source, request.signal);
+    let odataFallbackDegraded = [...(odata.degraded ?? [])];
+    if (odata.supported) {
+        const attempt = await tryRunOdataApply(source, odata.adapter, `aggregate($count as ${alias})`, resolved, request.signal);
+        if (attempt.rows) {
+            const value = numeric(attempt.rows[0]?.[alias]) ?? 0;
+            return {
+                ...baseResponse(source, "count", "server", request, resolved, options, [
+                    ...(odata.degraded ?? []),
+                    ...(attempt.degraded ?? []),
+                ]),
+                value,
+                label: "Count",
+            };
+        }
+        odataFallbackDegraded = [...odataFallbackDegraded, ...(attempt.degraded ?? [])];
+    }
+    if (source.capabilities.has("queryAggregate")) {
+        const result = await source.queryAggregate({
+            ...resolved.query,
+            aggregation: { metrics: [{ fn: "count", field, alias }] },
+            signal: request.signal ?? resolved.query.signal,
+        });
+        const value = numeric(result.aggregateRows?.[0]?.[alias]) ?? 0;
+        return {
+            ...baseResponse(source, "count", "server", request, resolved, options, result.degraded),
+            value,
+            label: "Count",
+        };
+    }
+    const materialized = await materialize(source, options, request, resolved, [field === "*" ? undefined : field], odataFallbackDegraded);
+    const value = materialized.result.totalCount ?? materialized.features.length;
+    return {
+        ...baseResponse(source, "count", "client", request, resolved, options, materialized.degraded),
+        value,
+        label: "Count",
+    };
+}
+async function formula(source, options, request) {
+    throwIfAborted(request.signal);
+    const alias = metricAlias(request.metric);
+    const resolved = resolveWidgetQuery(source, request);
+    const odata = await tryOdataApply(source, request.signal);
+    let odataFallbackDegraded = [...(odata.degraded ?? [])];
+    if (odata.supported && odataMetricSupported(request.metric.fn)) {
+        const attempt = await tryRunOdataApply(source, odata.adapter, `aggregate(${odataAggregateExpression(request.metric, alias)})`, resolved, request.signal);
+        if (attempt.rows) {
+            return {
+                ...baseResponse(source, "formula", "server", request, resolved, options, [
+                    ...(odata.degraded ?? []),
+                    ...(attempt.degraded ?? []),
+                ]),
+                value: nullableNumeric(attempt.rows[0]?.[alias]),
+                metric: request.metric,
+                label: alias,
+            };
+        }
+        odataFallbackDegraded = [...odataFallbackDegraded, ...(attempt.degraded ?? [])];
+    }
+    if (source.capabilities.has("queryAggregate")) {
+        const result = await source.queryAggregate({
+            ...resolved.query,
+            aggregation: { metrics: [{ ...request.metric, alias }] },
+            signal: request.signal ?? resolved.query.signal,
+        });
+        return {
+            ...baseResponse(source, "formula", "server", request, resolved, options, result.degraded),
+            value: nullableNumeric(result.aggregateRows?.[0]?.[alias]),
+            metric: request.metric,
+            label: alias,
+        };
+    }
+    const materialized = await materialize(source, options, request, resolved, [request.metric.field], odataFallbackDegraded);
+    return {
+        ...baseResponse(source, "formula", "client", request, resolved, options, materialized.degraded),
+        value: computeMetric(materialized.features, request.metric),
+        metric: request.metric,
+        label: alias,
+    };
+}
+async function categories(source, options, request, kind) {
+    throwIfAborted(request.signal);
+    const limit = boundedLimit(request.limit, DEFAULT_CATEGORY_LIMIT);
+    const resolved = resolveWidgetQuery(source, request);
+    const metric = request.metric;
+    const metricField = metric?.field && metric.field !== "*" ? metric.field : undefined;
+    const countAlias = "count";
+    const metricValueAlias = metric ? metricAlias(metric, "metric") : undefined;
+    const odata = await tryOdataApply(source, request.signal);
+    let odataFallbackDegraded = [...(odata.degraded ?? [])];
+    if (odata.supported && (!metric || odataMetricSupported(metric.fn))) {
+        const aggregateParts = [`$count as ${countAlias}`];
+        if (metric && metricValueAlias)
+            aggregateParts.push(odataAggregateExpression(metric, metricValueAlias));
+        const attempt = await tryRunOdataApply(source, odata.adapter, `groupby((${request.field}),aggregate(${aggregateParts.join(",")}))`, resolved, request.signal);
+        if (attempt.rows) {
+            return {
+                ...baseResponse(source, kind, "server", request, resolved, options, [
+                    ...(odata.degraded ?? []),
+                    ...(attempt.degraded ?? []),
+                ]),
+                field: request.field,
+                buckets: categoryBucketsFromRows(attempt.rows, request.field, countAlias, metricValueAlias, request.orderBy, limit),
+            };
+        }
+        odataFallbackDegraded = [...odataFallbackDegraded, ...(attempt.degraded ?? [])];
+    }
+    if (source.capabilities.has("queryAggregate")) {
+        const metrics = [{ fn: "count", field: "*", alias: countAlias }];
+        if (metric && metricValueAlias)
+            metrics.push({ ...metric, alias: metricValueAlias });
+        const result = await source.queryAggregate({
+            ...resolved.query,
+            aggregation: { groupBy: [request.field], metrics },
+            signal: request.signal ?? resolved.query.signal,
+        });
+        return {
+            ...baseResponse(source, kind, "server", request, resolved, options, result.degraded),
+            field: request.field,
+            buckets: categoryBucketsFromRows(result.aggregateRows ?? [], request.field, countAlias, metricValueAlias, request.orderBy, limit),
+        };
+    }
+    const materialized = await materialize(source, options, request, resolved, [request.field, metricField], odataFallbackDegraded);
+    return {
+        ...baseResponse(source, kind, "client", request, resolved, options, materialized.degraded),
+        field: request.field,
+        buckets: categoryBucketsFromFeatures(materialized.features, request.field, metric, request.orderBy, limit),
+    };
+}
+async function topValues(source, options, request) {
+    const result = await categories(source, options, {
+        ...request,
+        limit: request.limit ?? DEFAULT_TOP_VALUES_LIMIT,
+        orderBy: request.metric ? "metric-desc" : "count-desc",
+    }, "categories");
+    return {
+        ...result,
+        kind: "top-values",
+        values: result.buckets,
+    };
+}
+async function histogram(source, options, request) {
+    throwIfAborted(request.signal);
+    const resolved = resolveWidgetQuery(source, request, histogramRangeWhere(request.field, request.min, request.max));
+    const histogramSpec = aggregationHistogramSpec(request);
+    const countAlias = "count";
+    const bucketAlias = histogramSpec.aliases?.bucket ?? "bucket";
+    const odata = await tryOdataApply(source, request.signal);
+    let fallbackDegraded = [...(odata.degraded ?? [])];
+    if (odata.supported) {
+        const range = await resolveHistogramRangeFromOdata(source, odata.adapter, request, resolved, request.signal);
+        if (range.value) {
+            const attempt = await tryRunOdataApply(source, odata.adapter, odataHistogramTransformation(request.field, range.value.min, range.value.max, histogramSpec.bins, bucketAlias), resolved, request.signal);
+            if (attempt.rows) {
+                const bins = histogramBinsFromRows(attempt.rows, {
+                    min: range.value.min,
+                    max: range.value.max,
+                    bins: histogramSpec.bins,
+                    bucketAlias,
+                    countAlias,
+                    minAlias: histogramSpec.aliases?.min,
+                    maxAlias: histogramSpec.aliases?.max,
+                    labelAlias: histogramSpec.aliases?.label,
+                });
+                return {
+                    ...baseResponse(source, "histogram", "server", request, resolved, options, [
+                        ...(odata.degraded ?? []),
+                        ...(range.degraded ?? []),
+                        ...(attempt.degraded ?? []),
+                    ]),
+                    field: request.field,
+                    min: bins.min,
+                    max: bins.max,
+                    bins: bins.bins,
+                };
+            }
+            fallbackDegraded = [...fallbackDegraded, ...(range.degraded ?? []), ...(attempt.degraded ?? [])];
+        }
+        else {
+            fallbackDegraded = [...fallbackDegraded, ...(range.degraded ?? [])];
+        }
+    }
+    const canonical = await tryCanonicalHistogramPushdown(source, request, resolved, histogramSpec, countAlias, bucketAlias);
+    if (canonical.rows) {
+        const bins = histogramBinsFromRows(canonical.rows, {
+            min: request.min ?? canonical.min,
+            max: request.max ?? canonical.max,
+            bins: histogramSpec.bins,
+            bucketAlias,
+            countAlias,
+            minAlias: histogramSpec.aliases?.min,
+            maxAlias: histogramSpec.aliases?.max,
+            labelAlias: histogramSpec.aliases?.label,
+        });
+        return {
+            ...baseResponse(source, "histogram", "server", request, resolved, options, canonical.degraded),
+            field: request.field,
+            min: bins.min,
+            max: bins.max,
+            bins: bins.bins,
+        };
+    }
+    fallbackDegraded = [...fallbackDegraded, ...(canonical.degraded ?? [])];
+    const protocol = await tryProtocolHistogramPushdown(source, request, resolved, histogramSpec, countAlias, bucketAlias);
+    if (protocol.rows) {
+        const bins = histogramBinsFromRows(protocol.rows, {
+            min: request.min ?? protocol.min,
+            max: request.max ?? protocol.max,
+            bins: histogramSpec.bins,
+            bucketAlias,
+            countAlias,
+            minAlias: histogramSpec.aliases?.min,
+            maxAlias: histogramSpec.aliases?.max,
+            labelAlias: histogramSpec.aliases?.label,
+        });
+        return {
+            ...baseResponse(source, "histogram", "server", request, resolved, options, protocol.degraded),
+            field: request.field,
+            min: bins.min,
+            max: bins.max,
+            bins: bins.bins,
+        };
+    }
+    fallbackDegraded = [...fallbackDegraded, ...(protocol.degraded ?? [])];
+    const materialized = await materialize(source, options, request, resolved, [request.field], [
+        {
+            capability: "queryAggregate",
+            reason: "No compatible histogram bucketization pushdown was advertised; values were materialized client-side.",
+            protocol: source.descriptor.protocol,
+            sourceId: source.descriptor.id,
+        },
+        ...fallbackDegraded,
+    ]);
+    const bins = histogramBins(materialized.features, request);
+    return {
+        ...baseResponse(source, "histogram", "client", request, resolved, options, materialized.degraded),
+        field: request.field,
+        min: bins.min,
+        max: bins.max,
+        bins: bins.bins,
+    };
+}
+async function timeSeries(source, options, request) {
+    throwIfAborted(request.signal);
+    const interval = normalizeTimeSeriesInterval(request.interval);
+    const rangeWhere = timeSeriesRangeWhere(request.field, request.start, request.end);
+    const resolved = resolveWidgetQuery(source, request, rangeWhere);
+    const countAlias = "count";
+    const metric = request.metric;
+    const metricAliasValue = metric ? metricAlias(metric, "metric") : undefined;
+    const timeSeriesSpec = aggregationTimeSeriesSpec(request, interval);
+    const startAlias = timeSeriesSpec.aliases?.start ?? "intervalStart";
+    const endAlias = timeSeriesSpec.aliases?.end ?? "intervalEnd";
+    const odata = await tryOdataApply(source, request.signal);
+    let fallbackDegraded = [...(odata.degraded ?? [])];
+    if (odata.supported && (!metric || odataMetricSupported(metric.fn))) {
+        const aggregateParts = [`$count as ${countAlias}`];
+        if (metric && metricAliasValue)
+            aggregateParts.push(odataAggregateExpression(metric, metricAliasValue));
+        const attempt = await tryRunOdataApply(source, odata.adapter, `${odataTimeBucketTransformation(request.field, interval, startAlias)}/groupby((${startAlias}),aggregate(${aggregateParts.join(",")}))`, resolved, request.signal);
+        if (attempt.rows) {
+            const buckets = timeSeriesBucketsFromRows(attempt.rows, {
+                interval,
+                startAlias,
+                endAlias,
+                labelAlias: timeSeriesSpec.aliases?.label,
+                countAlias,
+                metricAlias: metricAliasValue,
+                fillMissing: request.fillMissing,
+                start: request.start,
+                end: request.end,
+            });
+            return {
+                ...baseResponse(source, "time-series", "server", request, resolved, options, [
+                    ...(odata.degraded ?? []),
+                    ...(attempt.degraded ?? []),
+                ]),
+                field: request.field,
+                interval,
+                buckets: buckets.buckets,
+                totalCount: buckets.totalCount,
+                ...(metric ? { metric } : {}),
+            };
+        }
+        fallbackDegraded = [...fallbackDegraded, ...(attempt.degraded ?? [])];
+    }
+    const canonical = await tryCanonicalTimeSeriesPushdown(source, request, resolved, timeSeriesSpec, countAlias, metricAliasValue);
+    if (canonical.rows) {
+        const buckets = timeSeriesBucketsFromRows(canonical.rows, {
+            interval,
+            startAlias,
+            endAlias,
+            labelAlias: timeSeriesSpec.aliases?.label,
+            countAlias,
+            metricAlias: metricAliasValue,
+            fillMissing: request.fillMissing,
+            start: request.start,
+            end: request.end,
+        });
+        return {
+            ...baseResponse(source, "time-series", "server", request, resolved, options, canonical.degraded),
+            field: request.field,
+            interval,
+            buckets: buckets.buckets,
+            totalCount: buckets.totalCount,
+            ...(metric ? { metric } : {}),
+        };
+    }
+    fallbackDegraded = [...fallbackDegraded, ...(canonical.degraded ?? [])];
+    const protocol = await tryProtocolTimeSeriesPushdown(source, request, resolved, timeSeriesSpec, countAlias, metricAliasValue);
+    if (protocol.rows) {
+        const buckets = timeSeriesBucketsFromRows(protocol.rows, {
+            interval,
+            startAlias,
+            endAlias,
+            labelAlias: timeSeriesSpec.aliases?.label,
+            countAlias,
+            metricAlias: metricAliasValue,
+            fillMissing: request.fillMissing,
+            start: request.start,
+            end: request.end,
+        });
+        return {
+            ...baseResponse(source, "time-series", "server", request, resolved, options, protocol.degraded),
+            field: request.field,
+            interval,
+            buckets: buckets.buckets,
+            totalCount: buckets.totalCount,
+            ...(metric ? { metric } : {}),
+        };
+    }
+    fallbackDegraded = [...fallbackDegraded, ...(protocol.degraded ?? [])];
+    const metricField = metric?.field && metric.field !== "*" ? metric.field : undefined;
+    const materialized = await materialize(source, options, request, resolved, [request.field, metricField], [
+        {
+            capability: "queryAggregate",
+            reason: "No compatible time-series interval pushdown was advertised; records were materialized client-side.",
+            protocol: source.descriptor.protocol,
+            sourceId: source.descriptor.id,
+        },
+        ...fallbackDegraded,
+    ]);
+    const buckets = timeSeriesBucketsFromFeatures(materialized.features, request, interval);
+    return {
+        ...baseResponse(source, "time-series", "client", request, resolved, options, materialized.degraded),
+        field: request.field,
+        interval,
+        buckets: buckets.buckets,
+        totalCount: buckets.totalCount,
+        ...(metric ? { metric } : {}),
+    };
+}
+async function range(source, options, request) {
+    throwIfAborted(request.signal);
+    const resolved = resolveWidgetQuery(source, request);
+    const minAlias = `min_${request.field}`;
+    const maxAlias = `max_${request.field}`;
+    const countAlias = "count";
+    const odata = await tryOdataApply(source, request.signal);
+    let odataFallbackDegraded = [...(odata.degraded ?? [])];
+    if (odata.supported) {
+        const attempt = await tryRunOdataApply(source, odata.adapter, `aggregate(${request.field} with min as ${minAlias},${request.field} with max as ${maxAlias},$count as ${countAlias})`, resolved, request.signal);
+        if (attempt.rows) {
+            const row = attempt.rows[0] ?? {};
+            return {
+                ...baseResponse(source, "range", "server", request, resolved, options, [
+                    ...(odata.degraded ?? []),
+                    ...(attempt.degraded ?? []),
+                ]),
+                field: request.field,
+                min: nullableNumeric(row[minAlias]),
+                max: nullableNumeric(row[maxAlias]),
+                count: numeric(row[countAlias]) ?? 0,
+            };
+        }
+        odataFallbackDegraded = [...odataFallbackDegraded, ...(attempt.degraded ?? [])];
+    }
+    if (source.capabilities.has("queryAggregate")) {
+        const result = await source.queryAggregate({
+            ...resolved.query,
+            aggregation: {
+                metrics: [
+                    { fn: "min", field: request.field, alias: minAlias },
+                    { fn: "max", field: request.field, alias: maxAlias },
+                    { fn: "count", field: request.field, alias: countAlias },
+                ],
+            },
+            signal: request.signal ?? resolved.query.signal,
+        });
+        const row = result.aggregateRows?.[0] ?? {};
+        return {
+            ...baseResponse(source, "range", "server", request, resolved, options, result.degraded),
+            field: request.field,
+            min: nullableNumeric(row[minAlias]),
+            max: nullableNumeric(row[maxAlias]),
+            count: numeric(row[countAlias]) ?? 0,
+        };
+    }
+    const materialized = await materialize(source, options, request, resolved, [request.field], odataFallbackDegraded);
+    const values = numericValues(materialized.features, request.field);
+    return {
+        ...baseResponse(source, "range", "client", request, resolved, options, materialized.degraded),
+        field: request.field,
+        min: values.length > 0 ? Math.min(...values) : null,
+        max: values.length > 0 ? Math.max(...values) : null,
+        count: values.length,
+    };
+}
+function resolveWidgetQuery(source, request, extraWhere) {
+    const projection = request.projection;
+    const query = request.query ?? {};
+    const projectionWhere = compileProjectionWhere(projection?.filters, source.descriptor.id);
+    const where = combineWhere(combineWhere(query.where, projectionWhere), extraWhere);
+    const spatialFilter = query.spatialFilter ?? projection?.spatialFilter ?? spatialFilterFromExtent(projection?.extent);
+    const out = {
+        ...query,
+        ...(where ? { where } : {}),
+        ...(spatialFilter ? { spatialFilter } : {}),
+        ...((query.orderBy ?? projection?.orderBy) ? { orderBy: query.orderBy ?? projection?.orderBy } : {}),
+        ...((query.outFields ?? projection?.outFields) ? { outFields: query.outFields ?? projection?.outFields } : {}),
+        returnGeometry: false,
+        ...((request.signal ?? query.signal) ? { signal: request.signal ?? query.signal } : {}),
+    };
+    return { query: out, ...(where ? { where } : {}) };
+}
+function baseResponse(source, kind, execution, request, resolved, options, degraded) {
+    const cache = cacheMetadata(source, kind, request, resolved, options);
+    const normalizedDegraded = degraded && degraded.length > 0 ? dedupeDegraded(degraded) : undefined;
+    return {
+        schemaVersion: WIDGET_SOURCE_SCHEMA_VERSION,
+        kind,
+        sourceId: source.descriptor.id,
+        protocol: source.descriptor.protocol,
+        execution,
+        serverPushdown: execution === "server",
+        cache,
+        ...(normalizedDegraded ? { degraded: normalizedDegraded } : {}),
+    };
+}
+async function materialize(source, options, request, resolved, fields, extraDegraded = []) {
+    throwIfAborted(request.signal);
+    const maxRows = maxClientRows(options, request);
+    const result = await source.queryAll({
+        ...resolved.query,
+        outFields: mergeOutFields(resolved.query.outFields, fields),
+        pagination: { limit: maxRows + 1 },
+        returnGeometry: false,
+        signal: request.signal ?? resolved.query.signal,
+    });
+    throwIfAborted(request.signal);
+    const features = result.features.slice(0, maxRows);
+    const degraded = [
+        {
+            capability: "queryAggregate",
+            reason: "Widget source evaluated this model client-side because no compatible server aggregate pushdown is available.",
+            protocol: source.descriptor.protocol,
+            sourceId: source.descriptor.id,
+        },
+        ...extraDegraded,
+        ...(result.degraded ?? []),
+    ];
+    if (result.exceededTransferLimit || result.features.length > maxRows) {
+        degraded.push({
+            capability: "queryAggregate",
+            reason: `Widget source client-side scan was bounded at ${maxRows} rows; results may be partial.`,
+            protocol: source.descriptor.protocol,
+            sourceId: source.descriptor.id,
+        });
+    }
+    return { result, features, degraded: dedupeDegraded(degraded) };
+}
+async function tryOdataApply(source, signal) {
+    const adapter = source.protocol("odata");
+    if (!adapter?.apply || !adapter.metadata)
+        return { supported: false };
+    throwIfAborted(signal);
+    try {
+        const metadata = await adapter.metadata(signal ? { signal } : undefined);
+        throwIfAborted(signal);
+        if (metadata.capabilities?.[adapter.entitySetName]?.apply === true) {
+            return { supported: true, adapter };
+        }
+        return {
+            supported: false,
+            degraded: [
+                {
+                    capability: "queryAggregate",
+                    reason: "OData metadata does not advertise ApplySupported; widget source did not use $apply pushdown.",
+                    protocol: source.descriptor.protocol,
+                    sourceId: source.descriptor.id,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throwIfAborted(signal);
+        return {
+            supported: false,
+            degraded: [
+                {
+                    capability: "queryAggregate",
+                    reason: `OData Apply capability negotiation failed: ${error instanceof Error ? error.message : String(error)}`,
+                    protocol: source.descriptor.protocol,
+                    sourceId: source.descriptor.id,
+                },
+            ],
+        };
+    }
+}
+async function tryRunOdataApply(source, adapter, transformation, resolved, signal) {
+    if (resolved.query.spatialFilter) {
+        return {
+            degraded: [
+                {
+                    capability: "queryAggregate",
+                    reason: "OData $apply pushdown cannot combine with spatialFilter yet; widget source used client fallback.",
+                    protocol: source.descriptor.protocol,
+                    sourceId: source.descriptor.id,
+                },
+            ],
+        };
+    }
+    try {
+        const filter = resolved.where ? rewriteWhereToOdataFilter(resolved.where) : undefined;
+        const result = await adapter.apply(transformation, {
+            ...(filter ? { filter } : {}),
+            ...(signal ? { signal } : {}),
+        });
+        return { rows: result.rows };
+    }
+    catch (error) {
+        throwIfAborted(signal);
+        return {
+            degraded: [
+                {
+                    capability: "queryAggregate",
+                    reason: `OData $apply pushdown failed: ${error instanceof Error ? error.message : String(error)}`,
+                    protocol: source.descriptor.protocol,
+                    sourceId: source.descriptor.id,
+                },
+            ],
+        };
+    }
+}
+async function resolveHistogramRangeFromOdata(source, adapter, request, resolved, signal) {
+    if (request.min !== undefined && request.max !== undefined) {
+        return { value: { min: request.min, max: request.max } };
+    }
+    const minAlias = "histogram_min";
+    const maxAlias = "histogram_max";
+    const attempt = await tryRunOdataApply(source, adapter, `aggregate(${request.field} with min as ${minAlias},${request.field} with max as ${maxAlias})`, resolved, signal);
+    if (!attempt.rows)
+        return { degraded: attempt.degraded };
+    const row = attempt.rows[0] ?? {};
+    const min = request.min ?? numeric(row[minAlias]);
+    const max = request.max ?? numeric(row[maxAlias]);
+    if (min === undefined || max === undefined) {
+        return {
+            degraded: [
+                ...(attempt.degraded ?? []),
+                degradedReason(source, "OData $apply histogram pushdown could not determine numeric bucket boundaries; widget source used client fallback."),
+            ],
+        };
+    }
+    return { value: { min, max }, degraded: attempt.degraded };
+}
+async function tryCanonicalHistogramPushdown(source, request, resolved, histogramSpec, countAlias, bucketAlias) {
+    if (!source.capabilities.has("queryAggregate"))
+        return {};
+    if (!histogramCapabilityCompatible(source.descriptor.analytics?.histogram, request.field, histogramSpec.bins)) {
+        return {};
+    }
+    const minAlias = histogramSpec.aliases?.min ?? "bucketMin";
+    const maxAlias = histogramSpec.aliases?.max ?? "bucketMax";
+    try {
+        const result = await source.queryAggregate({
+            ...resolved.query,
+            aggregation: {
+                metrics: [
+                    { fn: "count", field: "*", alias: countAlias },
+                    { fn: "min", field: request.field, alias: minAlias },
+                    { fn: "max", field: request.field, alias: maxAlias },
+                ],
+                histogram: { ...histogramSpec, aliases: { ...histogramSpec.aliases, bucket: bucketAlias } },
+            },
+            signal: request.signal ?? resolved.query.signal,
+        });
+        const rows = result.aggregateRows ?? [];
+        return {
+            rows,
+            min: rowsMin(rows, minAlias),
+            max: rowsMax(rows, maxAlias),
+            degraded: result.degraded,
+        };
+    }
+    catch (error) {
+        throwIfAborted(request.signal);
+        return {
+            degraded: [
+                degradedReason(source, `Canonical histogram queryAggregate pushdown failed: ${error instanceof Error ? error.message : String(error)}`),
+            ],
+        };
+    }
+}
+async function tryCanonicalTimeSeriesPushdown(source, request, resolved, timeSeriesSpec, countAlias, metricAliasValue) {
+    if (!source.capabilities.has("queryAggregate"))
+        return {};
+    if (!timeSeriesCapabilityCompatible(source.descriptor.analytics?.timeSeries, request.field, timeSeriesSpec.interval.unit)) {
+        return {};
+    }
+    const metrics = [{ fn: "count", field: "*", alias: countAlias }];
+    if (request.metric && metricAliasValue)
+        metrics.push({ ...request.metric, alias: metricAliasValue });
+    try {
+        const result = await source.queryAggregate({
+            ...resolved.query,
+            aggregation: {
+                metrics,
+                timeSeries: timeSeriesSpec,
+            },
+            signal: request.signal ?? resolved.query.signal,
+        });
+        return { rows: result.aggregateRows ?? [], degraded: result.degraded };
+    }
+    catch (error) {
+        throwIfAborted(request.signal);
+        return {
+            degraded: [
+                degradedReason(source, `Canonical time-series queryAggregate pushdown failed: ${error instanceof Error ? error.message : String(error)}`),
+            ],
+        };
+    }
+}
+async function tryProtocolHistogramPushdown(source, request, resolved, histogramSpec, countAlias, bucketAlias) {
+    const adapter = widgetAnalyticsAdapter(source);
+    if (!adapter?.histogram)
+        return {};
+    const metadata = await widgetAnalyticsMetadata(source, adapter, request.signal);
+    if (metadata.degraded)
+        return { degraded: metadata.degraded };
+    if (!histogramCapabilityCompatible(metadata.analytics?.histogram, request.field, histogramSpec.bins))
+        return {};
+    const minAlias = histogramSpec.aliases?.min ?? "bucketMin";
+    const maxAlias = histogramSpec.aliases?.max ?? "bucketMax";
+    try {
+        const result = await adapter.histogram({
+            ...resolved.query,
+            aggregation: {
+                metrics: [
+                    { fn: "count", field: "*", alias: countAlias },
+                    { fn: "min", field: request.field, alias: minAlias },
+                    { fn: "max", field: request.field, alias: maxAlias },
+                ],
+                histogram: { ...histogramSpec, aliases: { ...histogramSpec.aliases, bucket: bucketAlias } },
+            },
+            signal: request.signal ?? resolved.query.signal,
+        });
+        return {
+            rows: result.rows,
+            min: rowsMin(result.rows, minAlias),
+            max: rowsMax(result.rows, maxAlias),
+            degraded: result.degraded,
+        };
+    }
+    catch (error) {
+        throwIfAborted(request.signal);
+        return {
+            degraded: [
+                degradedReason(source, `Protocol histogram pushdown failed: ${error instanceof Error ? error.message : String(error)}`),
+            ],
+        };
+    }
+}
+async function tryProtocolTimeSeriesPushdown(source, request, resolved, timeSeriesSpec, countAlias, metricAliasValue) {
+    const adapter = widgetAnalyticsAdapter(source);
+    if (!adapter?.timeSeries)
+        return {};
+    const metadata = await widgetAnalyticsMetadata(source, adapter, request.signal);
+    if (metadata.degraded)
+        return { degraded: metadata.degraded };
+    if (!timeSeriesCapabilityCompatible(metadata.analytics?.timeSeries, request.field, timeSeriesSpec.interval.unit)) {
+        return {};
+    }
+    const metrics = [{ fn: "count", field: "*", alias: countAlias }];
+    if (request.metric && metricAliasValue)
+        metrics.push({ ...request.metric, alias: metricAliasValue });
+    try {
+        const result = await adapter.timeSeries({
+            ...resolved.query,
+            aggregation: { metrics, timeSeries: timeSeriesSpec },
+            signal: request.signal ?? resolved.query.signal,
+        });
+        return { rows: result.rows, degraded: result.degraded };
+    }
+    catch (error) {
+        throwIfAborted(request.signal);
+        return {
+            degraded: [
+                degradedReason(source, `Protocol time-series pushdown failed: ${error instanceof Error ? error.message : String(error)}`),
+            ],
+        };
+    }
+}
+function aggregationHistogramSpec(request) {
+    return {
+        field: request.field,
+        bins: clampInteger(request.bins ?? DEFAULT_HISTOGRAM_BINS, 1, MAX_HISTOGRAM_BINS),
+        ...(request.min !== undefined ? { min: request.min } : {}),
+        ...(request.max !== undefined ? { max: request.max } : {}),
+        boundary: "inclusive-exclusive",
+        aliases: {
+            bucket: "bucket",
+            min: "bucketMin",
+            max: "bucketMax",
+            label: "label",
+        },
+    };
+}
+function aggregationTimeSeriesSpec(request, interval) {
+    return {
+        field: request.field,
+        interval,
+        ...(request.start !== undefined ? { start: serializeTimeValue(request.start) } : {}),
+        ...(request.end !== undefined ? { end: serializeTimeValue(request.end) } : {}),
+        aliases: {
+            start: "intervalStart",
+            end: "intervalEnd",
+            label: "label",
+        },
+    };
+}
+function odataHistogramTransformation(field, min, max, bins, bucketAlias) {
+    const width = max === min ? 1 : (max - min) / bins;
+    return `compute(floor((${field} sub ${formatOdataNumber(min)}) div ${formatOdataNumber(width)}) as ${bucketAlias})/groupby((${bucketAlias}),aggregate($count as count))`;
+}
+function odataTimeBucketTransformation(field, interval, alias) {
+    return `compute(honua.timeBucket(${field},'${interval.unit}',${interval.step},'${interval.timezone.replace(/'/g, "''")}') as ${alias})`;
+}
+function formatOdataNumber(value) {
+    return Number.isFinite(value) ? String(value) : "0";
+}
+function widgetAnalyticsAdapter(source) {
+    const protocol = source.protocol;
+    const candidate = protocol(source.descriptor.protocol);
+    if (!candidate || typeof candidate !== "object")
+        return undefined;
+    const adapter = candidate;
+    if (typeof adapter.histogram !== "function" && typeof adapter.timeSeries !== "function")
+        return undefined;
+    return adapter;
+}
+async function widgetAnalyticsMetadata(source, adapter, signal) {
+    if (!adapter.metadata) {
+        return {
+            degraded: [
+                degradedReason(source, "Protocol widget analytics adapter did not expose capability metadata; widget source used client fallback."),
+            ],
+        };
+    }
+    try {
+        const metadata = await adapter.metadata(signal ? { signal } : undefined);
+        const capabilities = metadata.capabilities;
+        const analytics = capabilities?.widgets ?? {
+            histogram: capabilities?.histogram,
+            timeSeries: capabilities?.timeSeries,
+            freshness: capabilities?.freshness,
+        };
+        return { analytics };
+    }
+    catch (error) {
+        throwIfAborted(signal);
+        return {
+            degraded: [
+                degradedReason(source, `Protocol widget analytics capability negotiation failed: ${error instanceof Error ? error.message : String(error)}`),
+            ],
+        };
+    }
+}
+function histogramCapabilityCompatible(capability, field, bins) {
+    if (capability === true)
+        return true;
+    if (capability === undefined || capability === false)
+        return false;
+    if (capability.fields && !capability.fields.includes(field))
+        return false;
+    return capability.maxBins === undefined || bins <= capability.maxBins;
+}
+function timeSeriesCapabilityCompatible(capability, field, interval) {
+    if (capability === true)
+        return true;
+    if (capability === undefined || capability === false)
+        return false;
+    if (capability.fields && !capability.fields.includes(field))
+        return false;
+    return !capability.intervals || capability.intervals.includes(interval);
+}
+function degradedReason(source, reason) {
+    return {
+        capability: "queryAggregate",
+        reason,
+        protocol: source.descriptor.protocol,
+        sourceId: source.descriptor.id,
+    };
+}
+function compileProjectionWhere(filters, sourceId) {
+    const parts = [];
+    for (const clause of Object.values(filters ?? {})) {
+        if (clause.appliesTo && clause.appliesTo.length > 0 && !clause.appliesTo.includes(sourceId))
+            continue;
+        const compiled = compileClause(clause);
+        if (compiled)
+            parts.push(compiled);
+    }
+    return parts.length > 0 ? parts.map((part) => `(${part})`).join(" AND ") : undefined;
+}
+function compileClause(clause) {
+    const field = clause.field;
+    switch (clause.operator) {
+        case "=":
+            return `${field} = ${literal(clause.value)}`;
+        case "!=":
+            return `${field} <> ${literal(clause.value)}`;
+        case "<":
+        case "<=":
+        case ">":
+        case ">=":
+            return `${field} ${clause.operator} ${literal(clause.value)}`;
+        case "in":
+        case "not-in": {
+            if (!Array.isArray(clause.value) || clause.value.length === 0)
+                return undefined;
+            const values = clause.value.map(literal).join(", ");
+            return `${field} ${clause.operator === "not-in" ? "NOT " : ""}IN (${values})`;
+        }
+        case "between": {
+            if (!Array.isArray(clause.value) || clause.value.length < 2)
+                return undefined;
+            return `${field} BETWEEN ${literal(clause.value[0])} AND ${literal(clause.value[1])}`;
+        }
+        case "like":
+            return `${field} LIKE ${literal(clause.value)}`;
+        case "is-null":
+            return `${field} IS NULL`;
+        case "is-not-null":
+            return `${field} IS NOT NULL`;
+    }
+}
+function combineWhere(left, right) {
+    if (left && right)
+        return `(${left}) AND (${right})`;
+    return left || right || undefined;
+}
+function spatialFilterFromExtent(extent) {
+    if (!extent)
+        return undefined;
+    return {
+        geometryType: "esriGeometryEnvelope",
+        geometry: {
+            xmin: extent.xmin,
+            ymin: extent.ymin,
+            xmax: extent.xmax,
+            ymax: extent.ymax,
+            ...(extent.spatialReference ? { spatialReference: extent.spatialReference } : {}),
+        },
+        spatialRel: "esriSpatialRelIntersects",
+    };
+}
+function literal(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "NULL";
+    if (typeof value === "boolean")
+        return value ? "TRUE" : "FALSE";
+    return `'${String(value).replace(/'/g, "''")}'`;
+}
+function categoryBucketsFromRows(rows, field, countAlias, metricAliasValue, orderBy, limit) {
+    const total = rows.reduce((sum, row) => sum + (numeric(row[countAlias]) ?? 0), 0);
+    return sortBuckets(rows.map((row) => {
+        const count = numeric(row[countAlias]) ?? 0;
+        const value = normalizeBucketValue(row[field]);
+        return {
+            value,
+            label: label(value),
+            count,
+            percent: total > 0 ? count / total : 0,
+            ...(metricAliasValue ? { metric: nullableNumeric(row[metricAliasValue]) } : {}),
+        };
+    }), orderBy ?? "count-desc").slice(0, limit);
+}
+function categoryBucketsFromFeatures(features, field, metric, orderBy, limit) {
+    const buckets = new Map();
+    for (const feature of features) {
+        const value = normalizeBucketValue(readField(feature.attributes, field));
+        const key = String(value);
+        const entry = buckets.get(key) ?? { value, count: 0, values: [] };
+        entry.count += 1;
+        const metricValue = metric ? numeric(readField(feature.attributes, metric.field)) : undefined;
+        if (metricValue !== undefined)
+            entry.values.push(metricValue);
+        buckets.set(key, entry);
+    }
+    const total = features.length;
+    return sortBuckets([...buckets.values()].map((entry) => ({
+        value: entry.value,
+        label: label(entry.value),
+        count: entry.count,
+        percent: total > 0 ? entry.count / total : 0,
+        ...(metric ? { metric: computeNumbersMetric(entry.values, metric.fn) } : {}),
+    })), orderBy ?? (metric ? "metric-desc" : "count-desc")).slice(0, limit);
+}
+function histogramBinsFromRows(rows, options) {
+    const min = options.min ?? (options.minAlias ? rowsMin(rows, options.minAlias) : undefined);
+    const max = options.max ?? (options.maxAlias ? rowsMax(rows, options.maxAlias) : undefined);
+    if (min === undefined || max === undefined)
+        return { min: null, max: null, bins: [] };
+    const count = clampInteger(options.bins, 1, MAX_HISTOGRAM_BINS);
+    const bins = emptyHistogramBins(min, max, count);
+    const width = max === min ? 1 : (max - min) / count;
+    for (const row of rows) {
+        const rowCount = numeric(row[options.countAlias]) ?? 0;
+        let index = numeric(row[options.bucketAlias]);
+        if (index === undefined && options.minAlias) {
+            const rowMin = numeric(row[options.minAlias]);
+            if (rowMin !== undefined)
+                index = max === min ? 0 : Math.floor((rowMin - min) / width);
+        }
+        if (index === undefined)
+            continue;
+        const bucketIndex = Math.max(0, Math.min(count - 1, Math.trunc(index)));
+        const bin = bins[bucketIndex];
+        const rowMin = options.minAlias ? numeric(row[options.minAlias]) : undefined;
+        const rowMax = options.maxAlias ? numeric(row[options.maxAlias]) : undefined;
+        const rowLabel = options.labelAlias ? row[options.labelAlias] : undefined;
+        bins[bucketIndex] = {
+            ...bin,
+            ...(rowMin !== undefined ? { min: rowMin } : {}),
+            ...(rowMax !== undefined ? { max: rowMax } : {}),
+            ...(typeof rowLabel === "string" && rowLabel !== "" ? { label: rowLabel } : {}),
+            count: bin.count + rowCount,
+        };
+    }
+    const total = bins.reduce((sum, bin) => sum + bin.count, 0);
+    return {
+        min,
+        max,
+        bins: bins.map((bin) => ({ ...bin, percent: total > 0 ? bin.count / total : 0 })),
+    };
+}
+function emptyHistogramBins(min, max, count) {
+    const width = max === min ? 1 : (max - min) / count;
+    return Array.from({ length: count }, (_, index) => {
+        const binMin = min + index * width;
+        const binMax = index === count - 1 ? max : min + (index + 1) * width;
+        return {
+            id: `${index}`,
+            min: binMin,
+            max: binMax,
+            label: `${formatNumber(binMin)} - ${formatNumber(binMax)}`,
+            count: 0,
+            percent: 0,
+        };
+    });
+}
+function histogramBins(features, request) {
+    const values = numericValues(features, request.field);
+    const min = request.min ?? (values.length > 0 ? Math.min(...values) : undefined);
+    const max = request.max ?? (values.length > 0 ? Math.max(...values) : undefined);
+    if (min === undefined || max === undefined)
+        return { min: null, max: null, bins: [] };
+    const count = clampInteger(request.bins ?? DEFAULT_HISTOGRAM_BINS, 1, MAX_HISTOGRAM_BINS);
+    const width = max === min ? 1 : (max - min) / count;
+    const bins = emptyHistogramBins(min, max, count);
+    for (const value of values) {
+        if (value < min || value > max)
+            continue;
+        const index = max === min ? 0 : Math.min(count - 1, Math.floor((value - min) / width));
+        bins[index] = { ...bins[index], count: bins[index].count + 1 };
+    }
+    const total = bins.reduce((sum, bin) => sum + bin.count, 0);
+    return {
+        min,
+        max,
+        bins: bins.map((bin) => ({ ...bin, percent: total > 0 ? bin.count / total : 0 })),
+    };
+}
+function timeSeriesBucketsFromRows(rows, options) {
+    const buckets = [];
+    for (const row of rows) {
+        const start = dateFromValue(row[options.startAlias]);
+        if (!start)
+            continue;
+        const end = dateFromValue(row[options.endAlias]) ?? addInterval(start, options.interval);
+        const count = numeric(row[options.countAlias]) ?? 0;
+        const labelValue = options.labelAlias ? row[options.labelAlias] : undefined;
+        buckets.push({
+            start,
+            end,
+            label: typeof labelValue === "string" && labelValue !== "" ? labelValue : formatTimeLabel(start, options.interval),
+            count,
+            ...(options.metricAlias ? { metric: nullableNumeric(row[options.metricAlias]) } : {}),
+        });
+    }
+    buckets.sort((a, b) => a.start.getTime() - b.start.getTime());
+    return finalizeTimeSeriesBuckets(options.fillMissing ? fillMissingTimeBuckets(buckets, options.interval, options.start, options.end) : buckets);
+}
+function timeSeriesBucketsFromFeatures(features, request, interval) {
+    const startLimit = dateFromValue(request.start);
+    const endLimit = dateFromValue(request.end);
+    const byStart = new Map();
+    for (const feature of features) {
+        const date = dateFromValue(readField(feature.attributes, request.field));
+        if (!date)
+            continue;
+        if (startLimit && date < startLimit)
+            continue;
+        if (endLimit && date >= endLimit)
+            continue;
+        const start = truncateDate(date, interval);
+        const end = addInterval(start, interval);
+        const key = start.toISOString();
+        const existing = byStart.get(key) ?? {
+            start,
+            end,
+            label: formatTimeLabel(start, interval),
+            count: 0,
+            metric: undefined,
+            values: [],
+        };
+        existing.count += 1;
+        if (request.metric && request.metric.fn !== "count") {
+            const value = numeric(readField(feature.attributes, request.metric.field));
+            if (value !== undefined)
+                existing.values.push(value);
+        }
+        byStart.set(key, existing);
+    }
+    const buckets = [...byStart.values()]
+        .map((bucket) => ({
+        start: bucket.start,
+        end: bucket.end,
+        label: bucket.label,
+        count: bucket.count,
+        metric: request.metric
+            ? request.metric.fn === "count"
+                ? bucket.count
+                : computeNumbersMetric(bucket.values, request.metric.fn)
+            : undefined,
+    }))
+        .sort((a, b) => a.start.getTime() - b.start.getTime());
+    return finalizeTimeSeriesBuckets(request.fillMissing ? fillMissingTimeBuckets(buckets, interval, request.start, request.end) : buckets);
+}
+function finalizeTimeSeriesBuckets(buckets) {
+    const totalCount = buckets.reduce((sum, bucket) => sum + bucket.count, 0);
+    return {
+        totalCount,
+        buckets: buckets.map((bucket) => ({
+            id: bucket.start.toISOString(),
+            start: bucket.start.toISOString(),
+            end: bucket.end.toISOString(),
+            label: bucket.label,
+            count: bucket.count,
+            percent: totalCount > 0 ? bucket.count / totalCount : 0,
+            ...(bucket.metric !== undefined ? { metric: bucket.metric } : {}),
+        })),
+    };
+}
+function fillMissingTimeBuckets(buckets, interval, startValue, endValue) {
+    if (buckets.length === 0 && (startValue === undefined || endValue === undefined))
+        return buckets;
+    const byStart = new Map(buckets.map((bucket) => [bucket.start.toISOString(), bucket]));
+    const first = dateFromValue(startValue) ?? buckets[0]?.start;
+    const lastEnd = dateFromValue(endValue) ?? buckets.at(-1)?.end;
+    if (!first || !lastEnd || first >= lastEnd)
+        return buckets;
+    const out = [];
+    let cursor = truncateDate(first, interval);
+    while (cursor < lastEnd && out.length < MAX_TIME_SERIES_BUCKETS) {
+        const key = cursor.toISOString();
+        const existing = byStart.get(key);
+        if (existing) {
+            out.push(existing);
+        }
+        else {
+            out.push({
+                start: new Date(cursor.getTime()),
+                end: addInterval(cursor, interval),
+                label: formatTimeLabel(cursor, interval),
+                count: 0,
+                metric: null,
+            });
+        }
+        cursor = addInterval(cursor, interval);
+    }
+    return out;
+}
+function computeMetric(features, metric) {
+    if (metric.fn === "count")
+        return features.length;
+    return computeNumbersMetric(numericValues(features, metric.field), metric.fn);
+}
+function computeNumbersMetric(values, fn) {
+    if (fn === "count")
+        return values.length;
+    if (values.length === 0)
+        return null;
+    switch (fn) {
+        case "sum":
+            return values.reduce((sum, value) => sum + value, 0);
+        case "avg":
+            return values.reduce((sum, value) => sum + value, 0) / values.length;
+        case "min":
+            return Math.min(...values);
+        case "max":
+            return Math.max(...values);
+        case "stddev": {
+            const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+            const variance = values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / values.length;
+            return Math.sqrt(variance);
+        }
+        case "var": {
+            const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+            return values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / values.length;
+        }
+    }
+}
+function numericValues(features, field) {
+    const values = [];
+    for (const feature of features) {
+        const value = numeric(readField(feature.attributes, field));
+        if (value !== undefined)
+            values.push(value);
+    }
+    return values;
+}
+function rowsMin(rows, field) {
+    const values = rows.map((row) => numeric(row[field])).filter((value) => value !== undefined);
+    return values.length > 0 ? Math.min(...values) : undefined;
+}
+function rowsMax(rows, field) {
+    const values = rows.map((row) => numeric(row[field])).filter((value) => value !== undefined);
+    return values.length > 0 ? Math.max(...values) : undefined;
+}
+function normalizeTimeSeriesInterval(interval) {
+    if (!interval)
+        return DEFAULT_TIME_SERIES_INTERVAL;
+    if (typeof interval === "string")
+        return { unit: interval, step: 1, timezone: "UTC" };
+    return {
+        unit: interval.unit,
+        step: clampInteger(interval.step ?? 1, 1, 10_000),
+        timezone: interval.timezone ?? "UTC",
+    };
+}
+function histogramRangeWhere(field, min, max) {
+    const parts = [];
+    if (min !== undefined)
+        parts.push(`${field} >= ${literal(min)}`);
+    if (max !== undefined)
+        parts.push(`${field} <= ${literal(max)}`);
+    return parts.length > 0 ? parts.join(" AND ") : undefined;
+}
+function timeSeriesRangeWhere(field, start, end) {
+    const parts = [];
+    if (start !== undefined)
+        parts.push(`${field} >= ${literal(serializeTimeValue(start))}`);
+    if (end !== undefined)
+        parts.push(`${field} < ${literal(serializeTimeValue(end))}`);
+    return parts.length > 0 ? parts.join(" AND ") : undefined;
+}
+function serializeTimeValue(value) {
+    return value instanceof Date ? value.toISOString() : value;
+}
+function dateFromValue(value) {
+    if (value instanceof Date && Number.isFinite(value.getTime()))
+        return new Date(value.getTime());
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    const date = new Date(value);
+    return Number.isFinite(date.getTime()) ? date : undefined;
+}
+function truncateDate(date, interval) {
+    const out = new Date(date.getTime());
+    const step = interval.step;
+    switch (interval.unit) {
+        case "minute":
+            out.setUTCSeconds(0, 0);
+            out.setUTCMinutes(Math.floor(out.getUTCMinutes() / step) * step);
+            return out;
+        case "hour":
+            out.setUTCMinutes(0, 0, 0);
+            out.setUTCHours(Math.floor(out.getUTCHours() / step) * step);
+            return out;
+        case "day":
+            return new Date(Math.floor(Date.UTC(out.getUTCFullYear(), out.getUTCMonth(), out.getUTCDate()) / dayMs(step)) * dayMs(step));
+        case "week": {
+            const day = out.getUTCDay();
+            const mondayOffset = day === 0 ? 6 : day - 1;
+            const monday = Date.UTC(out.getUTCFullYear(), out.getUTCMonth(), out.getUTCDate() - mondayOffset);
+            return new Date(Math.floor(monday / dayMs(step * 7)) * dayMs(step * 7));
+        }
+        case "month":
+            return new Date(Date.UTC(out.getUTCFullYear(), Math.floor(out.getUTCMonth() / step) * step, 1));
+        case "quarter": {
+            const months = step * 3;
+            return new Date(Date.UTC(out.getUTCFullYear(), Math.floor(out.getUTCMonth() / months) * months, 1));
+        }
+        case "year":
+            return new Date(Date.UTC(Math.floor(out.getUTCFullYear() / step) * step, 0, 1));
+    }
+}
+function addInterval(date, interval) {
+    const out = new Date(date.getTime());
+    switch (interval.unit) {
+        case "minute":
+            out.setUTCMinutes(out.getUTCMinutes() + interval.step);
+            return out;
+        case "hour":
+            out.setUTCHours(out.getUTCHours() + interval.step);
+            return out;
+        case "day":
+            out.setUTCDate(out.getUTCDate() + interval.step);
+            return out;
+        case "week":
+            out.setUTCDate(out.getUTCDate() + interval.step * 7);
+            return out;
+        case "month":
+            out.setUTCMonth(out.getUTCMonth() + interval.step);
+            return out;
+        case "quarter":
+            out.setUTCMonth(out.getUTCMonth() + interval.step * 3);
+            return out;
+        case "year":
+            out.setUTCFullYear(out.getUTCFullYear() + interval.step);
+            return out;
+    }
+}
+function dayMs(days) {
+    return days * 24 * 60 * 60 * 1000;
+}
+function formatTimeLabel(date, interval) {
+    const iso = date.toISOString();
+    if (interval.unit === "year")
+        return iso.slice(0, 4);
+    if (interval.unit === "quarter")
+        return `${iso.slice(0, 4)} Q${Math.floor(date.getUTCMonth() / 3) + 1}`;
+    if (interval.unit === "month")
+        return iso.slice(0, 7);
+    if (interval.unit === "day" || interval.unit === "week")
+        return iso.slice(0, 10);
+    if (interval.unit === "hour")
+        return `${iso.slice(0, 13)}:00Z`;
+    return `${iso.slice(0, 16)}Z`;
+}
+function sortBuckets(buckets, orderBy) {
+    return [...buckets].sort((a, b) => {
+        switch (orderBy) {
+            case "count-asc":
+                return a.count - b.count || compareBucketValue(a.value, b.value);
+            case "value-asc":
+                return compareBucketValue(a.value, b.value);
+            case "value-desc":
+                return compareBucketValue(b.value, a.value);
+            case "metric-asc":
+                return compareNullableNumber(a.metric, b.metric) || compareBucketValue(a.value, b.value);
+            case "metric-desc":
+                return compareNullableNumber(b.metric, a.metric) || compareBucketValue(a.value, b.value);
+            case "count-desc":
+                return b.count - a.count || compareBucketValue(a.value, b.value);
+        }
+    });
+}
+function compareBucketValue(a, b) {
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    return label(a).localeCompare(label(b));
+}
+function compareNullableNumber(a, b) {
+    const left = a ?? Number.NEGATIVE_INFINITY;
+    const right = b ?? Number.NEGATIVE_INFINITY;
+    return left - right;
+}
+function readField(attributes, field) {
+    if (!attributes || typeof attributes !== "object")
+        return undefined;
+    return attributes[field];
+}
+function normalizeBucketValue(value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) {
+        return value;
+    }
+    if (value === undefined)
+        return null;
+    return String(value);
+}
+function label(value) {
+    return value === null ? "Null" : String(value);
+}
+function numeric(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function nullableNumeric(value) {
+    return numeric(value) ?? null;
+}
+function metricAlias(metric, prefix = "widget") {
+    const field = metric.field === "*" ? "all" : metric.field.replace(/\W+/g, "_");
+    return metric.alias ?? `${prefix}_${metric.fn}_${field}`;
+}
+function odataAggregateExpression(metric, alias) {
+    if (metric.fn === "count")
+        return `$count as ${alias}`;
+    return `${metric.field} with ${odataMetricName(metric.fn)} as ${alias}`;
+}
+function odataMetricSupported(fn) {
+    return fn === "count" || fn === "sum" || fn === "avg" || fn === "min" || fn === "max";
+}
+function odataMetricName(fn) {
+    return fn === "avg" ? "average" : fn;
+}
+function mergeOutFields(existing, fields) {
+    const out = new Set(existing ?? []);
+    for (const field of fields) {
+        if (field && field !== "*")
+            out.add(field);
+    }
+    return out.size > 0 ? [...out] : existing;
+}
+function boundedLimit(value, fallback) {
+    return clampInteger(value ?? fallback, 1, 500);
+}
+function maxClientRows(options, request) {
+    return clampInteger(request.maxClientRows ?? options.maxClientRows ?? DEFAULT_MAX_CLIENT_ROWS, 1, 100_000);
+}
+function clampInteger(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+function cacheMetadata(source, kind, request, resolved, options) {
+    const hints = { ...(options.cache ?? {}), ...(request.cache ?? {}) };
+    const analyticsSource = request.analyticsSource ?? options.analyticsSource;
+    const ttlMs = hints.ttlMs ?? options.ttlMs;
+    const freshness = hints.freshness ?? options.freshness ?? source.descriptor.analytics?.freshness;
+    const normalizedAnalyticsSource = analyticsSource ? normalizeAnalyticsSourceDescriptor(analyticsSource) : undefined;
+    const keyParts = [
+        WIDGET_SOURCE_SCHEMA_VERSION,
+        source.descriptor.id,
+        source.descriptor.protocol,
+        kind,
+        ...(normalizedAnalyticsSource
+            ? [
+                buildAnalyticsSourceCacheKey(normalizedAnalyticsSource, {
+                    operation: "widget",
+                    cache: {
+                        ...(normalizedAnalyticsSource.cache?.key ?? {}),
+                        filters: resolved.query.where,
+                        projection: sanitizeQuery(resolved.query),
+                        widgetProjection: sanitizeRequest(request),
+                    },
+                }),
+            ]
+            : []),
+        stableStringify({
+            query: sanitizeQuery(resolved.query),
+            request: sanitizeRequest(request),
+        }),
+        ...(hints.keyParts ?? []),
+    ];
+    return {
+        metadataCacheable: hints.metadataCacheable ?? true,
+        resultCacheable: hints.resultCacheable ?? (!options.realtime || freshness !== undefined),
+        cacheKey: keyParts.join(":"),
+        keyParts,
+        ...(ttlMs !== undefined ? { ttlMs } : {}),
+        ...(freshness ? { freshness } : {}),
+        status: "computed",
+    };
+}
+function sanitizeQuery(query) {
+    const { signal: _signal, ...rest } = query;
+    void _signal;
+    return rest;
+}
+function sanitizeRequest(request) {
+    const { signal: _signal, query: _query, projection: _projection, analyticsSource: _analyticsSource, ...rest } = request;
+    void _signal;
+    void _query;
+    void _projection;
+    void _analyticsSource;
+    return rest;
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (value instanceof Date)
+        return JSON.stringify(value.toISOString());
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const obj = value;
+    return `{${Object.keys(obj)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`)
+        .join(",")}}`;
+}
+function dedupeDegraded(reasons) {
+    const out = [];
+    const seen = new Set();
+    for (const reason of reasons) {
+        const key = `${reason.capability}:${reason.protocol ?? ""}:${reason.sourceId ?? ""}:${reason.reason}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(reason);
+    }
+    return out;
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    const reason = signal.reason;
+    if (reason instanceof Error)
+        throw reason;
+    throw new DOMException("The operation was aborted.", "AbortError");
+}
+function formatNumber(value) {
+    return Number.isInteger(value) ? String(value) : Number(value.toFixed(6)).toString();
+}