react-semaphor 0.1.504 → 0.1.505

package/dist/types/shared/analytics-protocol/matrix-window-contract.d.ts

@@ -0,0 +1,404 @@
+import { z } from 'zod';
+import { SemaphorScalarValue } from './scalar-value.js';
+import { SemaphorResultColumn, SemaphorValueFormat } from './contracts.js';
+import { MatrixAggregate, MatrixAxis, MatrixCoordinate, MatrixPath, MatrixSpec } from './matrix-definition-contract.js';
+export type MatrixPageRequest = {
+    id: string;
+    axis: MatrixAxis;
+    parent: MatrixPath;
+    position: {
+        kind: 'first';
+    } | {
+        kind: 'after' | 'before';
+        cursor: string;
+    };
+    size: number;
+};
+export type MatrixPathSelection = {
+    paths: readonly MatrixPath[];
+    pageIds: readonly string[];
+};
+export type MatrixBlockRequest = {
+    id: string;
+    rows: MatrixPathSelection;
+    columns: MatrixPathSelection;
+    measureIds: readonly string[];
+};
+export type MatrixWindowRequest = {
+    pages: readonly MatrixPageRequest[];
+    blocks: readonly MatrixBlockRequest[];
+};
+export type MatrixAxisPage = {
+    requestId: string;
+    axis: MatrixAxis;
+    parent: MatrixPath;
+    members: readonly {
+        path: MatrixPath;
+    }[];
+    before: string | null;
+    after: string | null;
+    exactCount?: number;
+};
+export type MatrixCellBlock = {
+    requestId: string;
+    coverage: {
+        rowPaths: readonly MatrixPath[];
+        columnPaths: readonly MatrixPath[];
+        measureIds: readonly string[];
+    };
+    cells: readonly (MatrixCoordinate & {
+        value: SemaphorScalarValue;
+    })[];
+};
+export type MatrixDescriptor = {
+    id: string;
+    column: SemaphorResultColumn;
+    nativeDataType: string;
+    semanticFormat?: SemaphorValueFormat;
+};
+export type MatrixFailure = {
+    code: 'invalid_request' | 'unsupported_capability' | 'stale_cursor' | 'forbidden' | 'budget_exceeded' | 'source_truncated' | 'execution_failed' | 'cancelled';
+    message: string;
+    detail?: string;
+    retryable: boolean;
+    scope: {
+        kind: 'operation';
+    } | {
+        kind: 'page' | 'block';
+        requestId: string;
+    };
+};
+export type MatrixCapabilities = {
+    dialect: 'postgres' | 'clickhouse' | 'duckdb';
+    aggregates: readonly MatrixAggregate[];
+};
+export type MatrixWindow = {
+    queryIdentity: string;
+    descriptors: {
+        levels: readonly MatrixDescriptor[];
+        measures: readonly MatrixDescriptor[];
+    };
+    capabilities: MatrixCapabilities;
+    pages: readonly MatrixAxisPage[];
+    blocks: readonly MatrixCellBlock[];
+    failures: readonly MatrixFailure[];
+};
+export type MatrixWindowOutcome = {
+    status: 'success' | 'partial';
+    window: MatrixWindow;
+} | {
+    status: 'failed';
+    failure: MatrixFailure;
+};
+type MatrixWindowInput = {
+    spec: MatrixSpec;
+    request: MatrixWindowRequest;
+};
+type MatrixResult = {
+    kind: 'matrix';
+    window: MatrixWindow;
+};
+/** Shared request ceiling used by client tile sizing and server enforcement. */
+export declare const MATRIX_WINDOW_LIMITS: Readonly<{
+    coordinates: 20000;
+}>;
+export declare const matrixPageRequestSchema: z.ZodType<MatrixPageRequest>;
+export declare const matrixPathSelectionSchema: z.ZodType<MatrixPathSelection>;
+export declare const matrixBlockRequestSchema: z.ZodType<MatrixBlockRequest>;
+export declare const matrixWindowRequestSchema: z.ZodType<MatrixWindowRequest>;
+export declare const matrixWindowInputSchema: z.ZodType<MatrixWindowInput>;
+export declare const matrixAxisPageSchema: z.ZodType<MatrixAxisPage>;
+export declare const matrixCellBlockSchema: z.ZodType<MatrixCellBlock>;
+export declare const matrixDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    column: z.ZodType<SemaphorResultColumn, z.ZodTypeDef, SemaphorResultColumn>;
+    nativeDataType: z.ZodString;
+    semanticFormat: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodEffects<z.ZodObject<Omit<{
+        type: z.ZodEnum<["number", "currency", "percent", "percentage", "scientific"]>;
+        locale: z.ZodOptional<z.ZodString>;
+        minimumFractionDigits: z.ZodOptional<z.ZodNumber>;
+        maximumFractionDigits: z.ZodOptional<z.ZodNumber>;
+        useGrouping: z.ZodOptional<z.ZodBoolean>;
+        prefix: z.ZodOptional<z.ZodString>;
+        suffix: z.ZodOptional<z.ZodString>;
+        negativeStyle: z.ZodOptional<z.ZodEnum<["minus", "parentheses"]>>;
+        compact: z.ZodOptional<z.ZodBoolean>;
+        scale: z.ZodOptional<z.ZodNumber>;
+        currency: z.ZodOptional<z.ZodString>;
+        percentValueMode: z.ZodOptional<z.ZodEnum<["fraction", "whole"]>>;
+    }, "locale">, "strict", z.ZodTypeAny, {
+        type: "number" | "currency" | "percent" | "percentage" | "scientific";
+        currency?: string | undefined;
+        minimumFractionDigits?: number | undefined;
+        maximumFractionDigits?: number | undefined;
+        useGrouping?: boolean | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        compact?: boolean | undefined;
+        scale?: number | undefined;
+        percentValueMode?: "fraction" | "whole" | undefined;
+    }, {
+        type: "number" | "currency" | "percent" | "percentage" | "scientific";
+        currency?: string | undefined;
+        minimumFractionDigits?: number | undefined;
+        maximumFractionDigits?: number | undefined;
+        useGrouping?: boolean | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        compact?: boolean | undefined;
+        scale?: number | undefined;
+        percentValueMode?: "fraction" | "whole" | undefined;
+    }>, {
+        type: "number" | "currency" | "percent" | "percentage" | "scientific";
+        currency?: string | undefined;
+        minimumFractionDigits?: number | undefined;
+        maximumFractionDigits?: number | undefined;
+        useGrouping?: boolean | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        compact?: boolean | undefined;
+        scale?: number | undefined;
+        percentValueMode?: "fraction" | "whole" | undefined;
+    }, {
+        type: "number" | "currency" | "percent" | "percentage" | "scientific";
+        currency?: string | undefined;
+        minimumFractionDigits?: number | undefined;
+        maximumFractionDigits?: number | undefined;
+        useGrouping?: boolean | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        compact?: boolean | undefined;
+        scale?: number | undefined;
+        percentValueMode?: "fraction" | "whole" | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodEnum<["date", "datetime"]>;
+        locale: z.ZodOptional<z.ZodString>;
+        pattern: z.ZodOptional<z.ZodString>;
+        relative: z.ZodOptional<z.ZodBoolean>;
+        timezone: z.ZodOptional<z.ZodString>;
+        sourceTimezone: z.ZodOptional<z.ZodString>;
+        prefix: z.ZodOptional<z.ZodString>;
+        suffix: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        type: "date" | "datetime";
+        pattern?: string | undefined;
+        locale?: string | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        relative?: boolean | undefined;
+        timezone?: string | undefined;
+        sourceTimezone?: string | undefined;
+    }, {
+        type: "date" | "datetime";
+        pattern?: string | undefined;
+        locale?: string | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        relative?: boolean | undefined;
+        timezone?: string | undefined;
+        sourceTimezone?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"duration">;
+        inputUnit: z.ZodOptional<z.ZodEnum<["millisecond", "second", "minute", "hour", "day"]>>;
+        outputStyle: z.ZodOptional<z.ZodEnum<["compact", "digital", "long"]>>;
+        largestUnit: z.ZodOptional<z.ZodEnum<["millisecond", "second", "minute", "hour", "day"]>>;
+        smallestUnit: z.ZodOptional<z.ZodEnum<["millisecond", "second", "minute", "hour", "day"]>>;
+        maxUnits: z.ZodOptional<z.ZodNumber>;
+        prefix: z.ZodOptional<z.ZodString>;
+        suffix: z.ZodOptional<z.ZodString>;
+        negativeStyle: z.ZodOptional<z.ZodEnum<["minus", "parentheses"]>>;
+    }, "strict", z.ZodTypeAny, {
+        type: "duration";
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        inputUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        outputStyle?: "compact" | "digital" | "long" | undefined;
+        largestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        smallestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        maxUnits?: number | undefined;
+    }, {
+        type: "duration";
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        inputUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        outputStyle?: "compact" | "digital" | "long" | undefined;
+        largestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        smallestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        maxUnits?: number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"string">;
+        prefix: z.ZodOptional<z.ZodString>;
+        suffix: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        type: "string";
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+    }, {
+        type: "string";
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+    }>]>, z.ZodType<import('./contracts.js').TemporalBucketFormat, z.ZodTypeDef, import('./contracts.js').TemporalBucketFormat>]>>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    nativeDataType: string;
+    column: SemaphorResultColumn;
+    semanticFormat?: import('./contracts.js').TemporalBucketFormat | {
+        type: "date" | "datetime";
+        pattern?: string | undefined;
+        locale?: string | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        relative?: boolean | undefined;
+        timezone?: string | undefined;
+        sourceTimezone?: string | undefined;
+    } | {
+        type: "duration";
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        inputUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        outputStyle?: "compact" | "digital" | "long" | undefined;
+        largestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        smallestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        maxUnits?: number | undefined;
+    } | {
+        type: "string";
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+    } | {
+        type: "number" | "currency" | "percent" | "percentage" | "scientific";
+        currency?: string | undefined;
+        minimumFractionDigits?: number | undefined;
+        maximumFractionDigits?: number | undefined;
+        useGrouping?: boolean | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        compact?: boolean | undefined;
+        scale?: number | undefined;
+        percentValueMode?: "fraction" | "whole" | undefined;
+    } | undefined;
+}, {
+    id: string;
+    nativeDataType: string;
+    column: SemaphorResultColumn;
+    semanticFormat?: import('./contracts.js').TemporalBucketFormat | {
+        type: "date" | "datetime";
+        pattern?: string | undefined;
+        locale?: string | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        relative?: boolean | undefined;
+        timezone?: string | undefined;
+        sourceTimezone?: string | undefined;
+    } | {
+        type: "duration";
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        inputUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        outputStyle?: "compact" | "digital" | "long" | undefined;
+        largestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        smallestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+        maxUnits?: number | undefined;
+    } | {
+        type: "string";
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+    } | {
+        type: "number" | "currency" | "percent" | "percentage" | "scientific";
+        currency?: string | undefined;
+        minimumFractionDigits?: number | undefined;
+        maximumFractionDigits?: number | undefined;
+        useGrouping?: boolean | undefined;
+        prefix?: string | undefined;
+        suffix?: string | undefined;
+        negativeStyle?: "minus" | "parentheses" | undefined;
+        compact?: boolean | undefined;
+        scale?: number | undefined;
+        percentValueMode?: "fraction" | "whole" | undefined;
+    } | undefined;
+}>;
+export declare const matrixFailureSchema: z.ZodType<MatrixFailure>;
+export declare const matrixCapabilitiesSchema: z.ZodType<MatrixCapabilities>;
+export declare const matrixWindowSchema: z.ZodType<MatrixWindow>;
+export declare const matrixWindowOutcomeSchema: z.ZodType<MatrixWindowOutcome>;
+export declare const matrixResultSchema: z.ZodType<MatrixResult>;
+export type MatrixExportColumn = {
+    kind: 'hierarchy';
+    label: string;
+} | {
+    kind: 'level';
+    levelId: string;
+    label: string;
+} | {
+    kind: 'measure';
+    measureId: string;
+    columnPath: MatrixPath;
+    role: 'member' | 'subtotal' | 'grand_total';
+    label: string;
+};
+export type MatrixExportLayout = {
+    columns: readonly MatrixExportColumn[];
+    descriptors: MatrixWindow['descriptors'];
+};
+export type MatrixExportValue = {
+    kind: 'value';
+    value: Exclude<SemaphorScalarValue, null>;
+} | {
+    kind: 'null' | 'empty';
+};
+type MatrixExportValueInput = {
+    kind: 'value';
+    value: SemaphorScalarValue;
+} | {
+    kind: 'null' | 'empty';
+};
+export type MatrixExportRow = {
+    kind: 'layout';
+    rowPath: MatrixPath;
+    role: 'member' | 'subtotal' | 'grand_total';
+    values: readonly MatrixExportValue[];
+} | {
+    kind: 'flat';
+    rowPath: MatrixPath;
+    columnPath: MatrixPath;
+    values: readonly MatrixExportValue[];
+};
+type MatrixExportRowInput = Omit<Extract<MatrixExportRow, {
+    kind: 'layout';
+}>, 'values'> & {
+    values: readonly MatrixExportValueInput[];
+} | Omit<Extract<MatrixExportRow, {
+    kind: 'flat';
+}>, 'values'> & {
+    values: readonly MatrixExportValueInput[];
+};
+export type MatrixExportBatch = {
+    kind: 'layout';
+    layout: MatrixExportLayout;
+    next: string;
+} | {
+    kind: 'rows';
+    rows: readonly MatrixExportRow[];
+    next: string | null;
+};
+type MatrixExportBatchInput = Extract<MatrixExportBatch, {
+    kind: 'layout';
+}> | {
+    kind: 'rows';
+    rows: readonly MatrixExportRowInput[];
+    next: string | null;
+};
+export declare const matrixExportColumnSchema: z.ZodType<MatrixExportColumn>;
+export declare const matrixExportLayoutSchema: z.ZodType<MatrixExportLayout>;
+export declare const matrixExportValueSchema: z.ZodType<MatrixExportValue, z.ZodTypeDef, MatrixExportValueInput>;
+export declare const matrixExportRowSchema: z.ZodType<MatrixExportRow, z.ZodTypeDef, MatrixExportRowInput>;
+export declare const matrixExportBatchSchema: z.ZodType<MatrixExportBatch, z.ZodTypeDef, MatrixExportBatchInput>;
+export {};

package/dist/types/shared/analytics-protocol/metric-comparison.d.ts

@@ -0,0 +1,183 @@
+import { SemaphorFieldRef, SemaphorTimeGrain, SemaphorValidationResult } from './contracts.js';
+export type MetricComparisonSpec = {
+    kind: 'previous_period';
+    offsetPeriods?: number;
+    alignment?: 'calendar' | 'weekday';
+    toDate?: boolean;
+} | {
+    kind: 'previous_year';
+    offsetYears?: number;
+    alignment?: 'calendar' | 'weekday';
+    toDate?: boolean;
+} | {
+    kind: 'target';
+    targetValue: number;
+};
+export type MetricComparisonConfig = {
+    mode: 'off';
+} | {
+    mode: 'explicit';
+    spec: MetricComparisonSpec;
+};
+export type MetricComparisonPolarity = 'higher_is_better' | 'lower_is_better' | 'neutral';
+export declare const DEFAULT_METRIC_COMPARISON_POLARITY: "higher_is_better";
+export type ComparisonPresentationSpec = {
+    /** Defaults to difference. */
+    displayMode?: 'difference' | 'percent_change' | 'both' | 'ratio';
+    /** Defaults to true. This controls display, not baseline selection. */
+    showComparison?: boolean;
+    /** Percent/ratio precision. Defaults to the surface formatter; valid range is 0..6. */
+    precision?: number;
+    /** Defaults to arrow_badge. */
+    indicatorStyle?: 'arrow_badge' | 'arrow' | 'badge' | 'none';
+    /** Defaults to true. */
+    showColor?: boolean;
+    position?: 'left' | 'right' | 'top';
+    /** Defaults to false. */
+    conditionalLabel?: boolean;
+    labelName?: string;
+    conditionalLabels?: {
+        increase?: string;
+        decrease?: string;
+        neutral?: string;
+    };
+    colors?: {
+        increase?: string;
+        decrease?: string;
+        neutral?: string;
+    };
+};
+export declare const COMPARISON_PRESENTATION_DEFAULTS: {
+    readonly displayMode: "difference";
+    readonly showComparison: true;
+    readonly indicatorStyle: "arrow_badge";
+    readonly showColor: true;
+    readonly conditionalLabel: false;
+};
+export type ViewerPeriodComparisonSpec = Extract<MetricComparisonSpec, {
+    kind: 'previous_period' | 'previous_year';
+}>;
+export type GlobalDateComparisonSelection = {
+    mode: 'off';
+} | {
+    mode: 'period';
+    spec: ViewerPeriodComparisonSpec;
+};
+export type DashboardDateComparisonOwner = {
+    kind: 'global_date';
+} | {
+    kind: 'field_date';
+    filterId: string;
+    label: string;
+};
+export type GlobalDateComparisonContext = {
+    selection: GlobalDateComparisonSelection;
+    inheritGlobalComparison?: false;
+    owner?: DashboardDateComparisonOwner;
+    /** Fixed execution clock carried by authoritative dashboard replay snapshots. */
+    referenceTime?: string;
+};
+export type ResolvedMetricComparisonRequest = {
+    source: 'explicit';
+    spec: MetricComparisonSpec;
+} | {
+    source: 'inherited';
+    spec: ViewerPeriodComparisonSpec;
+    owner?: DashboardDateComparisonOwner;
+};
+export declare function resolveMetricComparisonRequest(input: {
+    metricComparison?: MetricComparisonConfig;
+    inheritGlobalComparison?: false;
+    globalDateComparison?: GlobalDateComparisonContext;
+}): ResolvedMetricComparisonRequest | undefined;
+export type ResolvedDateWindow = {
+    startInclusive: string;
+    endExclusive: string;
+    timezone: string;
+};
+export type ComparisonUnavailableReason = 'finite_current_window_required' | 'current_window_not_started' | 'temporal_binding_missing' | 'temporal_binding_ambiguous' | 'temporal_binding_invalid' | 'unsupported_output_shape' | 'unsupported_raw_sql' | 'insufficient_history' | 'invalid_comparison_spec' | 'comparison_execution_failed';
+export type ComparisonAvailability = {
+    status: 'available';
+} | {
+    status: 'unavailable';
+    reason: ComparisonUnavailableReason;
+    traceId?: string;
+};
+export type MetricComparisonOutputBase = {
+    outputId: string;
+    metricId: string;
+    metricAlias: string;
+    currentColumnKey: string;
+    windowGrain?: MetricComparisonWindowGrain;
+    currentWindow?: ResolvedDateWindow;
+    comparisonWindow?: ResolvedDateWindow;
+    referenceTime?: string;
+    temporalField?: SemaphorFieldRef;
+};
+export type MetricComparisonWindowGrain = SemaphorTimeGrain;
+export type MetricResultAliasInput = {
+    alias?: string;
+    name: string;
+    entityName?: string;
+    role?: string;
+    aggregate?: string;
+    expression?: string;
+};
+/** Stable result-instance identity shared by query producers and consumers. */
+export declare function resolveMetricResultAlias(metric: MetricResultAliasInput): string;
+export type MetricComparisonOutput = MetricComparisonOutputBase & ({
+    request: ResolvedMetricComparisonRequest;
+    availability: {
+        status: 'available';
+    };
+    comparisonColumnKey: string;
+    deltaColumnKey: string;
+    percentChangeColumnKey: string;
+    ratioColumnKey: string;
+    rowStatusColumnKey?: string;
+    currentBucketColumnKey?: string;
+    comparisonSourceBucketColumnKey?: string;
+} | {
+    request?: ResolvedMetricComparisonRequest;
+    availability: Extract<ComparisonAvailability, {
+        status: 'unavailable';
+    }>;
+    comparisonColumnKey?: never;
+    deltaColumnKey?: never;
+    percentChangeColumnKey?: never;
+    ratioColumnKey?: never;
+    rowStatusColumnKey?: never;
+    currentBucketColumnKey?: never;
+    comparisonSourceBucketColumnKey?: never;
+});
+export type MetricComparisonMetadataEntry = {
+    type: MetricComparisonSpec['kind'];
+    displayName?: string;
+    displayLabel?: string;
+    output: MetricComparisonOutput;
+};
+/** Keyed by MetricComparisonOutput.outputId, never by source id or label. */
+export type MetricComparisonMetadataMap = Record<MetricComparisonOutput['outputId'], MetricComparisonMetadataEntry>;
+export type MetricComparisonDirection = 'increase' | 'decrease' | 'no_change' | 'unknown';
+export type MetricComparisonSentiment = 'favorable' | 'unfavorable' | 'neutral';
+export type MetricComparisonEvaluation = {
+    status: 'available' | 'insufficient_history';
+    currentValue: number | null;
+    comparisonValue: number | null;
+    delta: number | null;
+    percentChange: number | null;
+    ratio: number | null;
+    direction: MetricComparisonDirection;
+    sentiment: MetricComparisonSentiment;
+};
+export declare function validateMetricComparisonSpec(value: unknown, path?: string): SemaphorValidationResult;
+export declare function validateMetricComparisonConfig(value: unknown, path?: string): SemaphorValidationResult;
+export declare function validateGlobalDateComparisonSelection(value: unknown, path?: string): SemaphorValidationResult;
+export declare function validateGlobalDateComparisonContext(value: unknown, path?: string): SemaphorValidationResult;
+export declare function validateMetricComparisonPolarity(value: unknown, path?: string): SemaphorValidationResult;
+export declare function validateComparisonPresentationSpec(value: unknown, path?: string): SemaphorValidationResult;
+export declare function evaluateMetricComparison(input: {
+    currentValue: number | null;
+    comparisonValue: number | null;
+    polarity?: MetricComparisonPolarity;
+}): MetricComparisonEvaluation;

package/dist/types/shared/analytics-protocol/operators.d.ts

@@ -0,0 +1,10 @@
+import { SemaphorAnalyticsFilterOperator, SemaphorInputOperator } from './contracts.js';
+export declare function normalizeSemaphorInputOperator(value: SemaphorInputOperator | string | null | undefined): SemaphorInputOperator | undefined;
+export declare function normalizeSemaphorAnalyticsFilterOperator(value: SemaphorAnalyticsFilterOperator | string | null | undefined): SemaphorAnalyticsFilterOperator | undefined;
+/**
+ * Maps a dashboard filter operation (the `TFilterValue.operation` vocabulary)
+ * to the shared input operator. Null checks have no input operator; callers
+ * that carry the native predicate keep the original operation and only use
+ * this mapping to describe the binding.
+ */
+export declare function toSemaphorInputOperatorFromFilterOperation(operation: string | null | undefined): SemaphorInputOperator | undefined;

package/dist/types/shared/analytics-protocol/option-predicate.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Predicate semantics a dashboard transport wants executed verbatim. This is
+ * a closed contract: only the keys below survive, so a native filter value
+ * crossing a JSON boundary can never carry identity (field name, qualified
+ * name, owning entity, datatype, source context, calculated expression). The
+ * server rebuilds identity from grounding and re-applies the same contract.
+ */
+export type NativePredicateSemantics = {
+    operation: NativePredicateOperation;
+    values: unknown[];
+    valueType?: 'string' | 'number' | 'date' | 'boolean';
+    temporalBucket?: unknown;
+    relativeMeta?: unknown;
+    temporalPrecision?: unknown;
+};
+export declare const NATIVE_PREDICATE_OPERATIONS: readonly ["=", "!=", ">", "<", ">=", "<=", "like", "not like", "between", "not between", "in", "not in", "is null", "is not null"];
+export type NativePredicateOperation = (typeof NATIVE_PREDICATE_OPERATIONS)[number];
+/**
+ * The allowlisted keys of a native filter value, unvalidated. This is what a
+ * client transport sends: it never decides whether a predicate is executable,
+ * so nothing is dropped on the way to the server, and it never carries a key
+ * outside the contract. Returns undefined only for a non-object value.
+ */
+export type NativePredicateSemanticsCandidate = Partial<Record<keyof NativePredicateSemantics, unknown>>;
+export declare function projectNativePredicateSemantics(value: unknown): NativePredicateSemanticsCandidate | undefined;
+/**
+ * Builds validated predicate semantics from a native filter value or a
+ * transported candidate. Returns undefined when the operation or cardinality
+ * is not executable; the server reports that as a typed outcome rather than
+ * dropping the candidate.
+ */
+export declare function parseNativePredicateSemantics(value: unknown): NativePredicateSemantics | undefined;
+/**
+ * Semantics of a native filter value the caller already trusts structurally.
+ * Throws only for programming errors (an unknown operation on a typed filter
+ * value); JSON callers must use `parseNativePredicateSemantics`.
+ */
+export declare function toNativePredicateSemantics(filter: {
+    operation: string;
+    values: unknown[];
+} & Record<string, unknown>): NativePredicateSemantics;
+/** Null checks carry no values but still constrain the option list. */
+export declare function isNullCheckPredicate(predicate: Pick<NativePredicateSemantics, 'operation'>): boolean;

package/dist/types/shared/analytics-protocol/option-relevance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A raw value a relevance check may submit. NULL is deliberately excluded:
+ * an `in` predicate cannot express "is null", so a null selection can never
+ * be proven present or absent by this check and stays unknown on the client.
+ */
+export type SemaphorOptionMatchValue = string | number | boolean;
+export declare function isSemaphorOptionMatchValue(value: unknown): value is SemaphorOptionMatchValue;
+/**
+ * The one structural rule for `matchValues` on every transport: a non-empty
+ * list of scalar values within the bound. Both the intent validator and the
+ * standard body parser use it, so the two transports cannot drift.
+ */
+export declare function parseOptionMatchValues(raw: unknown): {
+    ok: true;
+    values: SemaphorOptionMatchValue[];
+} | {
+    ok: false;
+    error: string;
+};