react-semaphor 0.1.526 → 0.1.528

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

@@ -56,10 +56,19 @@ export type MatrixDescriptor = {
     nativeDataType: string;
     semanticFormat?: SemaphorValueFormat;
 };
+/**
+ * Matrix failure codes: the shared refusal codes (Plan 2b, owner C) plus the
+ * two only a windowed Matrix has.
+ */
+export declare const MATRIX_FAILURE_CODES: readonly ["invalid_request", "missing_relationship", "ambiguous_relationship", "unsafe_join", "unsupported_capability", "capability_required", "forbidden", "not_found", "execution_failed", "timeout", "budget_exceeded", "cancelled", "stale_cursor", "source_truncated"];
+export type MatrixFailureCode = (typeof MATRIX_FAILURE_CODES)[number];
 export type MatrixFailure = {
-    code: 'invalid_request' | 'unsupported_capability' | 'stale_cursor' | 'forbidden' | 'budget_exceeded' | 'source_truncated' | 'execution_failed' | 'cancelled';
+    code: MatrixFailureCode;
     message: string;
     detail?: string;
+    details?: Record<string, unknown>;
+    nextStep?: string;
+    status?: number;
     retryable: boolean;
     scope: {
         kind: 'operation';
@@ -90,6 +99,33 @@ export type MatrixWindowOutcome = {
     status: 'failed';
     failure: MatrixFailure;
 };
+/**
+ * One present intersection of an indexed block: positions into the block's
+ * own coverage lists, then the value. Absent means no data at that
+ * intersection; `null` is a present aggregate null.
+ */
+export type MatrixIndexedCell = readonly [
+    row: number,
+    column: number,
+    measure: number,
+    value: SemaphorScalarValue
+];
+/** The dashboard's wire form of a cell block: each path is sent once, in coverage. */
+export type MatrixIndexedCellBlock = {
+    requestId: string;
+    coverage: MatrixCellBlock['coverage'];
+    values: readonly MatrixIndexedCell[];
+};
+export type MatrixIndexedWindow = Omit<MatrixWindow, 'blocks'> & {
+    blocks: readonly MatrixIndexedCellBlock[];
+};
+export type MatrixIndexedWindowOutcome = {
+    status: 'success' | 'partial';
+    window: MatrixIndexedWindow;
+} | {
+    status: 'failed';
+    failure: MatrixFailure;
+};
 type MatrixWindowInput = {
     spec: MatrixSpec;
     request: MatrixWindowRequest;
@@ -98,9 +134,14 @@ type MatrixResult = {
     kind: 'matrix';
     window: MatrixWindow;
 };
-/** Shared request ceiling used by client tile sizing and server enforcement. */
+/**
+ * Shared ceilings: request coordinates (client tile sizing and server
+ * enforcement), and the serialized size of one acquired window at its
+ * indexed size, which is what the dashboard receives.
+ */
 export declare const MATRIX_WINDOW_LIMITS: Readonly<{
     coordinates: 20000;
+    responseBytes: number;
 }>;
 export declare const matrixPageRequestSchema: z.ZodType<MatrixPageRequest>;
 export declare const matrixPathSelectionSchema: z.ZodType<MatrixPathSelection>;
@@ -109,6 +150,8 @@ 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>;
+/** Positions are checked against coverage; no per-cell path keys are built. */
+export declare const matrixIndexedCellBlockSchema: z.ZodType<MatrixIndexedCellBlock>;
 export declare const matrixDescriptorSchema: z.ZodObject<{
     id: z.ZodString;
     column: z.ZodType<SemaphorResultColumn, z.ZodTypeDef, SemaphorResultColumn>;
@@ -327,8 +370,20 @@ export declare const matrixDescriptorSchema: z.ZodObject<{
 }>;
 export declare const matrixFailureSchema: z.ZodType<MatrixFailure>;
 export declare const matrixCapabilitiesSchema: z.ZodType<MatrixCapabilities>;
-export declare const matrixWindowSchema: z.ZodType<MatrixWindow>;
+export declare const matrixWindowSchema: z.ZodType<MatrixWindow, z.ZodTypeDef, MatrixWindow>;
+export declare const matrixIndexedWindowSchema: z.ZodType<MatrixIndexedWindow, z.ZodTypeDef, MatrixIndexedWindow>;
 export declare const matrixWindowOutcomeSchema: z.ZodType<MatrixWindowOutcome>;
+export declare const matrixIndexedWindowOutcomeSchema: z.ZodType<MatrixIndexedWindowOutcome>;
+/**
+ * The indexed wire form of a block. Every cell must be inside coverage (the
+ * block schema guarantees it for parsed blocks).
+ */
+export declare function encodeMatrixCellBlock(block: MatrixCellBlock): MatrixIndexedCellBlock;
+/** Cells again; their paths are the coverage path objects, not copies. */
+export declare function decodeMatrixCellBlock(block: MatrixIndexedCellBlock): MatrixCellBlock;
+export declare function encodeMatrixWindow(window: MatrixWindow): MatrixIndexedWindow;
+export declare function decodeMatrixWindow(window: MatrixIndexedWindow): MatrixWindow;
+export declare function encodeMatrixWindowOutcome(outcome: MatrixWindowOutcome): MatrixIndexedWindowOutcome;
 export declare const matrixResultSchema: z.ZodType<MatrixResult>;
 export type MatrixExportColumn = {
     kind: 'hierarchy';
@@ -371,15 +426,15 @@ export type MatrixExportRow = {
     columnPath: MatrixPath;
     values: readonly MatrixExportValue[];
 };
-type MatrixExportRowInput = Omit<Extract<MatrixExportRow, {
+type MatrixExportRowInput = (Omit<Extract<MatrixExportRow, {
     kind: 'layout';
 }>, 'values'> & {
     values: readonly MatrixExportValueInput[];
-} | Omit<Extract<MatrixExportRow, {
+}) | (Omit<Extract<MatrixExportRow, {
     kind: 'flat';
 }>, 'values'> & {
     values: readonly MatrixExportValueInput[];
-};
+});
 export type MatrixExportBatch = {
     kind: 'layout';
     layout: MatrixExportLayout;

package/dist/types/shared/analytics-protocol/measure-aggregation-profile.d.ts

@@ -0,0 +1,63 @@
+import { AggregationFunctionKind } from './aggregate-expression.js';
+/** The structural fields of a measure the profile reads. */
+export type MeasureProfileField = {
+    name?: string;
+    role?: string;
+    aggregate?: string;
+    expression?: string;
+    isPreAggregated?: boolean;
+    calculatedFormula?: {
+        computeStage?: 'row' | 'aggregate';
+        inputFields?: ReadonlyArray<MeasureProfileField>;
+    };
+    derivedField?: {
+        computeStage?: 'row' | 'aggregate';
+        aggregationBehavior?: string;
+    };
+};
+/** How partial results of a measure combine into a larger group. */
+export type MeasureReaggregation = 
+/** Sum the partials (SUM, COUNT, and sums of them). */
+{
+    kind: 'additive';
+}
+/** Rebuild from summed parts: AVG from SUM and COUNT partials. */
+ | {
+    kind: 'decomposable_avg';
+}
+/** Take the MIN or MAX of the partials. */
+ | {
+    kind: 'idempotent';
+    fn: 'min' | 'max';
+}
+/** Partials can't be combined; recompute at the larger grain. */
+ | {
+    kind: 'none';
+    reason: 'distinct' | 'median' | 'ratio' | 'window' | 'declared' | 'unresolved' | 'other';
+};
+export type MeasureAggregationProfile = {
+    /** `aggregate`: the measure aggregates itself; `row`: it needs `outer`. */
+    stage: 'row' | 'aggregate';
+    /** The aggregate wrapping a row-stage measure. */
+    outer?: AggregationFunctionKind;
+    /** Every aggregate the measure computes, nested inputs expanded. */
+    calls: Array<{
+        kind: AggregationFunctionKind;
+        distinct: boolean;
+    }>;
+    windowed: boolean;
+    /** The value is unchanged when input rows repeat (as through a to-many join). */
+    repeatSafe: boolean;
+    reaggregation: MeasureReaggregation;
+    /** MIN and MAX keep their input's type; everything else is a number. */
+    outputType: 'numeric' | 'input';
+    /** A stable name for labels and result identity. */
+    identity: AggregationFunctionKind | 'ratio' | 'linear' | 'expression' | 'unresolved';
+    /** The profile could not be determined exactly; every answer is the cautious one. */
+    unresolved: boolean;
+};
+/**
+ * The aggregation profile of a compiled measure field. Pure; reads only the
+ * field and its nested `calculatedFormula.inputFields`.
+ */
+export declare function resolveMeasureAggregationProfile(field: MeasureProfileField): MeasureAggregationProfile;

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

@@ -74,8 +74,6 @@ 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';
@@ -95,7 +93,9 @@ export type ResolvedDateWindow = {
     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 ComparisonUnavailableReason = 'finite_current_window_required' | 'current_window_not_started'
+/** The date ranges the run applies to the field have no instant in common. */
+ | 'current_window_empty' | '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';
 } | {
@@ -174,6 +174,12 @@ export declare function validateMetricComparisonSpec(value: unknown, path?: stri
 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;
+/**
+ * A validated comparison context without the legacy `referenceTime`, so no
+ * request replays the clock a stored rule or an old client stamped: every
+ * operation pins its own instant (analytics kernel K5).
+ */
+export declare function withoutLegacyComparisonClock(context: GlobalDateComparisonContext): GlobalDateComparisonContext;
 export declare function validateMetricComparisonPolarity(value: unknown, path?: string): SemaphorValidationResult;
 export declare function validateComparisonPresentationSpec(value: unknown, path?: string): SemaphorValidationResult;
 export declare function evaluateMetricComparison(input: {

package/dist/types/shared/analytics-protocol/operation-temporal-state.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+/**
+ * The latest value of a field within a lookup scope, as the database wrote it
+ * (never a value passed through a JavaScript `Date`), or `null` when the scope
+ * has no rows. It carries no type: the server takes the native type from the
+ * field's governed metadata.
+ */
+export type DataAnchor = {
+    key: string;
+    nativeText: string | null;
+};
+/**
+ * What one operation fixed: the instant every relative date resolves on, and
+ * the data anchors it read. Governed responses report it; requests that
+ * continue the operation (a Matrix page or expansion) send it back.
+ */
+export type OperationTemporalState = {
+    executionInstant: string;
+    dataAnchors: DataAnchor[];
+};
+/**
+ * Strict. A request may send only `{ executionInstant }`; `dataAnchors`
+ * defaults to none. The instant must be a full ISO instant, and anchor keys
+ * are unique.
+ */
+export declare const operationTemporalStateSchema: z.ZodEffects<z.ZodObject<{
+    executionInstant: z.ZodEffects<z.ZodString, string, string>;
+    dataAnchors: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        nativeText: z.ZodNullable<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        key: string;
+        nativeText: string | null;
+    }, {
+        key: string;
+        nativeText: string | null;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    executionInstant: string;
+    dataAnchors: {
+        key: string;
+        nativeText: string | null;
+    }[];
+}, {
+    executionInstant: string;
+    dataAnchors?: {
+        key: string;
+        nativeText: string | null;
+    }[] | undefined;
+}>, {
+    executionInstant: string;
+    dataAnchors: {
+        key: string;
+        nativeText: string | null;
+    }[];
+}, {
+    executionInstant: string;
+    dataAnchors?: {
+        key: string;
+        nativeText: string | null;
+    }[] | undefined;
+}>;
+/** The state as parsed, or `undefined` when absent or invalid. */
+export declare function readOperationTemporalState(value: unknown): OperationTemporalState | undefined;

package/dist/types/shared/analytics-protocol/relative-date-filter.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/** Calendar units a relative date can count in. */
+export type DateUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
+/** Sub-day units, used only by rolling `last` windows. */
+export type SubDayDateUnit = 'minute' | 'hour';
+export type RelativeDateUnit = DateUnit | SubDayDateUnit;
+/**
+ * A date window stated relative to an anchor ("now" or a pinned instant).
+ * Dashboard filters carry it as `TFilterValue.relativeMeta` and card filters as
+ * `FilterCondition.relativeMeta`; the server resolves it on every run in the
+ * governed calendar.
+ */
+export type RelativeDateFilter = {
+    mode: 'last';
+    n: number;
+    unit: SubDayDateUnit;
+    complete?: false;
+    relativeTo?: RelativeDateAnchor;
+} | {
+    mode: 'last';
+    n: number;
+    unit: DateUnit;
+    complete?: boolean;
+    relativeTo?: RelativeDateAnchor;
+} | {
+    mode: 'this';
+    unit: DateUnit;
+    toDate?: boolean;
+    /** Only used with unit=month for single-day month-boundary presets. */
+    boundary?: 'first_day' | 'last_day';
+} | {
+    mode: 'previous';
+    unit: DateUnit;
+} | {
+    mode: 'between';
+    unit: DateUnit;
+    from: number;
+    to: number;
+};
+/**
+ * What a `last` window counts back from. Omitted means now (or a pinned
+ * instant); `'latest_data'` means the latest value of the window's own field
+ * in its lookup scope (analytics kernel K11). Only agents author it.
+ */
+export type RelativeDateAnchor = 'latest_data';
+/** A `last` window that counts back from the latest data (K11). */
+export type DataRelativeDateFilter = Extract<RelativeDateFilter, {
+    mode: 'last';
+}> & {
+    relativeTo: 'latest_data';
+};
+/**
+ * A window that counts back from the latest data instead of from now (K11):
+ * the one test every reader uses. It reads any value, so callers can pass a
+ * field they have not validated.
+ */
+export declare function isDataRelativeDateFilter(meta: unknown): meta is DataRelativeDateFilter;
+/** A relative date belongs only on a range condition (plan D3). */
+export declare function allowsRelativeDate(operator: string): boolean;
+/** Strict schema for a persisted `RelativeDateFilter`. */
+export declare const relativeDateFilterSchema: z.ZodType<RelativeDateFilter>;

package/dist/types/shared/analytics-protocol/relative-date-label.d.ts

@@ -0,0 +1,20 @@
+import { RelativeDateFilter } from './relative-date-filter.js';
+/** The preset a relative date is, or null when it isn't one. */
+export declare function findPresetLabel(meta: RelativeDateFilter | undefined): string | null;
+/** One offset as an option label: "Today", "Last month", "6 days ago". */
+export declare function getRelativeOffsetLabel(offset: number, unit: RelativeDateFilter['unit']): string;
+/**
+ * Format a `RelativeDateFilter` meta into a human-readable label.
+ *
+ * 1. First tries to reverse-match against `presetMetadata` so canonical
+ *    presets (Today, Last 7 days, This week, …) round-trip back to the
+ *    same wording the user originally clicked.
+ * 2. Falls back to a generated label for ad-hoc relative ranges that
+ *    aren't in the preset list (e.g., from the Relative tab's custom
+ *    From/To dropdowns).
+ *
+ * Returns null if the meta can't be sensibly labelled.
+ */
+export declare function getRelativeDateLabel(meta: RelativeDateFilter | undefined): string | null;
+export declare function relativeMetaEquals(a: RelativeDateFilter, b: RelativeDateFilter): boolean;
+export declare const presetMetadata: Record<string, RelativeDateFilter>;

package/dist/types/shared/analytics-protocol/runtime-schemas.d.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import { SemaphorAnalyzeResult } from './analyze-result-types.js';
 import { SemaphorAnalyticsDiagnosticFeedback, SemaphorAnalyticsExecutionResult, SemaphorAnalyticsPopulation, SemaphorAnalyticsResult, SemaphorRelationshipDiagnostics } from './contracts.js';
-import { SemaphorDataAppCodegenSummary } from './data-app-codegen-summary.js';
 export * from './analytics-base-schemas.js';
 export { matrixResultSchema as semaphorMatrixResultSchema } from './matrix-window-contract.js';
 export declare const semaphorAnalyticsResultSchema: z.ZodType<SemaphorAnalyticsResult>;
@@ -3370,4 +3369,3 @@ export declare const analyticsExecutionEnvelopeSchema: z.ZodObject<{
 export declare const semaphorAnalyticsExecutionResultSchema: z.ZodType<SemaphorAnalyticsExecutionResult>;
 export declare const semaphorAnalyzeResultShape: z.ZodRawShape;
 export declare const semaphorAnalyzeResultSchema: z.ZodType<SemaphorAnalyzeResult>;
-export declare const semaphorDataAppCodegenSummarySchema: z.ZodType<SemaphorDataAppCodegenSummary>;