react-semaphor 0.1.545 → 0.1.547

package/dist/types/lib/types/semantic-types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Joinability types: the response of GET /api/v1/domains/[domainId]/joinability,
+ * used by field draggability states in the query builder.
+ *
+ * The domain template contract (datasets, fields, metrics, relationships) has one
+ * owner, semaphor-app (`src/lib/semantic/template/contract.ts`); it is not copied
+ * here. If a react-semaphor consumer ever needs template types, move the contract
+ * into react-semaphor's shared contracts and have the app import it, rather than
+ * copy it (domain template 2.1, ledger P2-20).
+ */
+/**
+ * Joinability map for a semantic domain
+ *
+ * Maps each dataset to the datasets it can join with, including both direct (1-hop)
+ * and indirect (2-hop) joins. This is a lightweight topology representation used by
+ * the frontend for UX feedback (field draggability states).
+ *
+ * The backend generates this from the full relationship definitions and serves it
+ * via GET /api/v1/domains/[domainId]/joinability
+ */
+export interface JoinabilityMap {
+    [datasetName: string]: {
+        /**
+         * Datasets that can be joined directly (1-hop)
+         * Example: orders.canJoinTo = ['customers', 'products']
+         */
+        canJoinTo: string[];
+        /**
+         * Datasets that require multi-hop joins (2-hop)
+         * Key: target dataset name
+         * Value: array of intermediate datasets to traverse
+         *
+         * Example: orders.indirectJoins = { countries: ['stores'] }
+         * Means: orders → stores → countries
+         */
+        indirectJoins: {
+            [targetDataset: string]: string[];
+        };
+        /**
+         * Datasets related by an ACTIVE relationship that is not set to join
+         * automatically. The query engine will not auto-join these; the user
+         * has to enable automatic join on the relationship or configure the
+         * join on the chart. Drives the "Requires setup" field state.
+         * Optional: older servers omit it.
+         */
+        manualJoins?: string[];
+        /**
+         * Direct neighbours connected by MORE THAN ONE active auto-join
+         * relationship, with the count. The engine picks by join priority,
+         * so this is informational ("Multiple relationships; highest
+         * priority is used"), never blocking. Optional.
+         */
+        ambiguousJoins?: {
+            [targetDataset: string]: number;
+        };
+        /**
+         * Cardinality of the direct auto-join, from THIS dataset's side.
+         * `one_to_many` means one row here matches many rows there, so an
+         * aggregate over this dataset's values joined to that dataset may
+         * repeat. `unknown` when the relationship has no authored cardinality
+         * (the planner refuses repeat-sensitive measures across it).
+         * Informational; drives a warning, never a block. Optional.
+         */
+        cardinality?: {
+            [targetDataset: string]: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many' | 'unknown';
+        };
+    };
+}
+/**
+ * Response from the joinability map API
+ */
+export interface JoinabilityMapResponse {
+    /** Lightweight joinability map for field state calculation */
+    joinabilityMap: JoinabilityMap;
+    /** Minimal dataset information */
+    datasets: Array<{
+        name: string;
+        label: string;
+        type: string;
+        table?: string | null;
+        catalog?: string | null;
+        schema?: string | null;
+    }>;
+}

package/dist/types/lib/utils/build-saved-editor-card.d.ts

@@ -0,0 +1,20 @@
+import { TCard } from '../types/common-types.js';
+type BuildSavedEditorCardOptions = {
+    isDevMode: boolean;
+    cardSql?: string;
+    selectedSchemaName?: string;
+    selectedDatabaseName?: string;
+    selectedTableName?: string;
+    selectedConnectionId?: string;
+    remoteChartSettings?: unknown;
+    stripConfig: (config: TCard['config']) => TCard['config'];
+};
+/**
+ * The card the editor saves. The editor's picker selection (database,
+ * schema, table, data model) is not written onto the card: a card's source is
+ * its `dataSource`, so Done with no change leaves the card as it was
+ * (MCP dashboard editing ledger V-50, V-58). A stored card's older copies of
+ * the picker stay as they are, read by nothing at run time.
+ */
+export declare function buildSavedEditorCard(card: TCard, { isDevMode, cardSql, selectedSchemaName, selectedDatabaseName, selectedTableName, selectedConnectionId, remoteChartSettings, stripConfig, }: BuildSavedEditorCardOptions): TCard;
+export {};

package/dist/types/lib/utils/card-type-change.d.ts

@@ -8,6 +8,11 @@ export type CardTypeChangeOptions = {
     catalogLoading?: boolean;
     /** A plugin visual chosen as `custom`. */
     customVisual?: TCustomCardPreferences;
+    /**
+     * Mints the ids the conversion needs (Matrix field instances), in order.
+     * Default `crypto.randomUUID`; a replayed change passes its stored ids (DE-D54).
+     */
+    createId?: () => string;
 };
 export type CardTypeChange = {
     status: 'refused';
@@ -19,6 +24,8 @@ export type CardTypeChange = {
     card: TCard;
     /** Labels of authored parts the new type could not keep. */
     leftOut: readonly string[];
+    /** Chart-scoped preference keys the new type drops (DE-D43). */
+    droppedPreferences: readonly (keyof TCardPreferences)[];
     crossedMatrixBoundary: boolean;
     forcesSqlMode: boolean;
 };
@@ -28,3 +35,12 @@ export type CardTypeChange = {
  * the editor store applies the result.
  */
 export declare function changeCardType(card: TCard, type: TCard['type'], options?: CardTypeChangeOptions): CardTypeChange;
+/**
+ * A type change as a person makes it in the editor (MCP dashboard editing
+ * DE-D51, ledger P2-01): the chart picker is `changeCardType`; between table
+ * kinds the table editor's tabs are `switchTableType`. A detail table is
+ * reached only through the tabs, so a change into or out of one goes through
+ * a table, as the editor's two steps do. The dashboard reducer's `retype`
+ * calls this; the editor keeps calling each half from its own control.
+ */
+export declare function changeCardTypeAsEditor(card: TCard, type: TCard['type'], options?: CardTypeChangeOptions): CardTypeChange;

package/dist/types/lib/utils/field-availability-context.d.ts

@@ -0,0 +1,25 @@
+import { TCard } from '../types/common-types.js';
+import { AutoJoinMetadata } from '../types/query-types.js';
+import { JoinabilityMapResponse } from '../types/semantic-types.js';
+import { FieldStateContext } from './field-state-calculator.js';
+/**
+ * Everything `calculateFieldState` needs about a visual, except the
+ * selected fields (which differ per call). Built by ONE function so the
+ * field list, the click gate, the drop gate, and the matrix editor judge
+ * the same card from the same facts: the same join plan (the authored
+ * one, which is also right for matrix cards), the same auto-resolved
+ * base, the same relationship map, aliases, labels, mode, and data-source
+ * anchor. A caller that assembles these by hand will eventually disagree
+ * with the others; do not.
+ */
+export type FieldAvailabilityContext = Omit<FieldStateContext, 'selectedFields'> & {
+    /** The semantic domain the card reads, when any. */
+    semanticDomainId?: string;
+};
+export declare function buildFieldAvailabilityContext(input: {
+    card: Pick<TCard, 'type' | 'config' | 'dataSource'> | null | undefined;
+    joinabilityData?: JoinabilityMapResponse | null;
+    autoJoinMetadata?: AutoJoinMetadata;
+    /** Labels the caller knows from elsewhere (entity groups); catalog labels win. */
+    extraDatasetLabels?: Record<string, string>;
+}): FieldAvailabilityContext;

package/dist/types/lib/utils/field-placement.d.ts

@@ -0,0 +1,96 @@
+import { TCard, TCardPreferences } from '../types/common-types.js';
+import { CardConfig, ContainerId, Field } from '../types/explorer-types.js';
+import { MatrixCardCatalog } from '../matrix-table/matrix-card-adapter.js';
+import { MatrixEditorChange } from '../matrix-table/matrix-editor.js';
+import { FieldAvailabilityContext } from './field-availability-context.js';
+import { FieldStateResult } from './field-state-calculator.js';
+/**
+ * Field placement: the one rule for putting a field on a shelf.
+ *
+ * Every entry point (drop, move, reorder, click) and the drag preview call
+ * `evaluateFieldPlacement`; only `placeField` in `useFieldManagement` commits
+ * its outcome. The rules restate today's drag behavior per placement kind; see
+ * docs/implementation-plans/shelf-drop-placement/PLAN.md, "Placement rules".
+ *
+ * Evaluation is side-effect-free during the call: no id minting, store access,
+ * notifications, clock or random reads. New ids arrive in the context.
+ */
+export type ShelfZone = Exclude<ContainerId, 'source'>;
+export declare const SHELF_ZONES: readonly ShelfZone[];
+export type FieldPlacement = {
+    /** The field-list field, or the pill being moved. */
+    field: Field;
+    /** 'source' is the field list. */
+    from: ContainerId;
+    to: ShelfZone;
+    /** Pill to insert in front of; absent means the end. */
+    beforeId?: string;
+};
+export type FieldPlacementKind = 'add' | 'move' | 'copy-to-sort' | 'reorder';
+export type FieldPlacementNotice = {
+    kind: 'join-required';
+    fieldState?: FieldStateResult;
+} | {
+    kind: 'invalid-field-type';
+    reason: string;
+} | {
+    kind: 'already-on-shelf';
+    zone: ShelfZone;
+} | {
+    kind: 'sort-needs-shelf-field';
+} | {
+    kind: 'cannot-sort-from-pivot';
+} | {
+    kind: 'matrix-refused';
+    message: string;
+};
+export type FieldPlacementCommit = {
+    cardKind: 'standard';
+    config: CardConfig;
+    /** null leaves the card's preferences untouched. */
+    preferences: TCardPreferences | null;
+} | {
+    cardKind: 'matrix';
+    change: MatrixEditorChange;
+};
+export type FieldPlacementOutcome = {
+    kind: 'placed';
+    commit: FieldPlacementCommit;
+}
+/** A standard reorder onto its own slot. */
+ | {
+    kind: 'unchanged';
+} | {
+    kind: 'refused';
+    notice: FieldPlacementNotice;
+};
+export type FieldPlacementContext = {
+    availability: FieldAvailabilityContext;
+    /** Ignored for standard cards. */
+    matrixCatalog: MatrixCardCatalog;
+    /** A string exactly when `needsNewFieldId` is true. */
+    newFieldId: string | null;
+};
+/** Reserved id for standard-card previews. Never matches a minted id and never reaches the store. */
+export declare const PLACEMENT_PREVIEW_FIELD_ID = "__placement-preview__";
+/**
+ * Reserved id for Matrix previews. The Matrix spec validates instance ids as
+ * UUIDs, so the preview needs one; minted ids are random v4 UUIDs and never
+ * equal this fixed value. Never reaches the store.
+ */
+export declare const MATRIX_PLACEMENT_PREVIEW_ID = "00000000-0000-4000-8000-000000000000";
+/** The preview id for a card type. */
+export declare function placementPreviewId(cardType: TCard['type'] | undefined): string;
+export declare function classifyFieldPlacement(placement: Pick<FieldPlacement, 'from' | 'to'>): FieldPlacementKind;
+/** Standard cards: every kind except reorder. Matrix: only from the field list. */
+export declare function needsNewFieldId(cardType: TCard['type'] | undefined, placement: Pick<FieldPlacement, 'from' | 'to'>): boolean;
+/**
+ * A standard card's shelf as the editor shows it: stored fields with their
+ * shelf identity resolved and a label defaulted from the name.
+ */
+export declare function readStandardShelf(config: CardConfig | undefined, zone: ContainerId): Field[];
+export declare function evaluateStandardPlacement(card: TCard, placement: FieldPlacement, context: FieldPlacementContext): FieldPlacementOutcome;
+/** The one evaluation. Dispatches on card type. Side-effect-free. */
+export declare function evaluateFieldPlacement(card: TCard, placement: FieldPlacement, context: FieldPlacementContext): FieldPlacementOutcome;
+/** Preview text for the shelf header while a field hovers it. */
+export declare function placementNoticeReason(notice: FieldPlacementNotice, shelfLabel: string): string;

package/dist/types/lib/utils/field-state-calculator.d.ts

@@ -0,0 +1,161 @@
+import { Field, JoinPlan } from '../types/explorer-types.js';
+import { JoinabilityMap } from '../types/semantic-types.js';
+import { AutoJoinMetadata } from '../types/query-types.js';
+import { resolveFieldDatasetDependencies, FieldDatasetDependency } from './field-dependencies.js';
+import { getQualifiedEntityName } from './qualified-entity-name.js';
+export interface DatasetIdentityAlias {
+    name: string;
+    table?: string | null;
+    catalog?: string | null;
+    schema?: string | null;
+}
+/**
+ * Field draggability states for the query builder
+ *
+ * - **base**: Field is from the base dataset (first dataset selected)
+ * - **draggable**: Field has a direct relationship to base dataset (1-hop)
+ * - **indirect**: Field requires a multi-hop join (2-hop via intermediate dataset)
+ * - **setup**: A relationship exists but the engine will not use it on its
+ *   own (not set to auto-join). The user can fix this; until then the field
+ *   is blocked exactly like `unreachable`.
+ * - **unreachable**: No relationship path exists to this field's dataset
+ *
+ * Calculated fields take the worst state among the datasets they read from.
+ */
+export type FieldDraggableState = 'base' | 'draggable' | 'indirect' | 'setup' | 'unreachable'
+/**
+ * Nothing is on the shelves and the dataset is not one of the chart's
+ * data-source datasets. Not a fault to fix: the customer chose their
+ * datasets and this field reads another one. Blocked, with the path to
+ * using it (add the dataset) offered as information.
+ */
+ | 'absent';
+/** Per-dataset availability, attached to calculated-field results. */
+export interface FieldDependencyState {
+    /** Catalog dataset name. */
+    entityName: string;
+    /** Customer-facing dataset label. */
+    label: string;
+    state: FieldDraggableState;
+    /** Customer-facing sentence when the dataset is not simply available. */
+    reason?: string;
+}
+/**
+ * Result of field state calculation
+ */
+export interface FieldStateResult {
+    /** The calculated draggability state */
+    state: FieldDraggableState;
+    /** For indirect joins: the path through intermediate datasets */
+    joinPath?: string[];
+    /** `joinPath` as readers see it: dataset labels, in path order. */
+    joinPathLabels?: string[];
+    /** Short tooltip text explaining the state (row `title`). */
+    tooltip?: string;
+    /**
+     * Customer-facing explanation when the field cannot be added as-is.
+     * Precise: names the dataset and the actual problem.
+     */
+    reason?: string;
+    /** The one thing the user can do about `reason`, when there is one. */
+    action?: string;
+    /**
+     * Dataset labels that `reason` mentions, so the UI can set them off from
+     * the surrounding sentence (a chip) without parsing the text.
+     */
+    mentions?: string[];
+    /**
+     * Non-blocking caution from governed catalog metadata, for example a
+     * one-to-many join that can repeat an aggregate. Shown in the preview.
+     */
+    warning?: string;
+    /**
+     * Datasets a calculated field reads from, each with its own state.
+     * Undefined for base fields (their dataset is their group).
+     */
+    dependencies?: FieldDependencyState[];
+    /**
+     * False when availability could not be checked (relationship map still
+     * loading, or a dependency could not be traced). UI must not present
+     * such a field as verified-ready.
+     */
+    verified?: boolean;
+    /** Indicates if this field is already selected/in the query */
+    isSelected?: boolean;
+}
+/** States that block adding the field to the query. */
+export declare function isBlockedFieldState(state: FieldDraggableState | undefined): boolean;
+export interface FieldStateContext {
+    joinabilityMap: JoinabilityMap | null;
+    selectedFields: Field[];
+    joinPlan?: JoinPlan;
+    autoJoinMetadata?: AutoJoinMetadata;
+    baseEntityName?: string;
+    datasetAliases?: DatasetIdentityAlias[];
+    /**
+     * Whether the card reads from a semantic domain. Drives the fallback when
+     * `joinabilityMap` is null:
+     *   - true  -> the map is still loading: report `verified: false`.
+     *   - false -> physical datasets: reachability comes from the join plan.
+     *   - undefined (legacy callers) -> everything draggable, as before.
+     */
+    hasSemanticDomain?: boolean;
+    /** Customer-facing dataset labels keyed by dataset name. */
+    datasetLabels?: Record<string, string>;
+    /**
+     * The datasets the chart's data source lists (`DataSource.selectedEntities`),
+     * in order. When nothing is on the shelves yet, these ARE the chart's
+     * datasets: a calculated field's dependencies are judged against them,
+     * so the card talks about the dataset the customer actually picked
+     * instead of the calculation's own first input.
+     */
+    dataSourceEntities?: DatasetAnchorRef[];
+}
+/** Minimal entity reference the calculator needs to identify a dataset. */
+export type DatasetAnchorRef = Parameters<typeof getQualifiedEntityName>[0];
+/**
+ * Customer-facing words for a state, in one place. The row tag under a
+ * dependency and the title of the refusal toast both read from here.
+ */
+export declare function getFieldStateCopy(state: FieldDraggableState | undefined): {
+    /** Short tag beside a blocking dependency; null when nothing blocks. */
+    tag: string | null;
+    /** Title of the refusal toast. */
+    toastTitle: string;
+};
+/**
+ * Calculate the draggability state for a field in the query builder
+ *
+ * This determines whether a field can be dragged based on:
+ * - Current selected fields (what's already in the query)
+ * - Joinability map (what relationships exist between datasets)
+ * - For calculated fields: the datasets their inputs read from
+ *
+ * **Fallback behavior**:
+ * - No joinability map and no `hasSemanticDomain` flag: all fields draggable
+ *   (legacy callers, no restrictions)
+ * - No fields selected yet: base fields are draggable (first selection
+ *   establishes the base dataset); calculated fields are judged against the
+ *   data source's datasets when there are any, else against their own first
+ *   dataset
+ */
+export declare function calculateFieldState(field: Field, context: FieldStateContext): FieldStateResult;
+/** One data-source dataset's connection to the visual's base, for the Datasets panel. */
+export interface DataSourceConnection {
+    /** Dataset identity (name in semantic mode, qualified table in physical). */
+    entityName: string;
+    label: string;
+    state: FieldDraggableState;
+    reason?: string;
+    action?: string;
+    mentions?: string[];
+}
+/**
+ * How each selected dataset connects to the visual's base dataset, using
+ * the same identity, base cascade, and per-dataset evaluation as the field
+ * list. The Datasets panel shows this at selection time so the customer
+ * learns about an unconnected dataset before the first drag. Order and
+ * verdicts match `calculateFieldState` for a field of that dataset.
+ */
+export declare function describeDataSourceConnections(context: FieldStateContext): DataSourceConnection[];
+export { resolveFieldDatasetDependencies, type FieldDatasetDependency };

package/dist/types/lib/utils/qualified-entity-name.d.ts

@@ -0,0 +1,2 @@
+import { DatabaseEntityReference } from '../types/explorer-types.js';
+export declare function getQualifiedEntityName(target: Pick<DatabaseEntityReference, 'type' | 'database' | 'schema' | 'name'>): string;

package/dist/types/shared/analytics-protocol/applied-constraints.d.ts

@@ -17,6 +17,33 @@ export type AppliedConstraintField = {
     label?: string;
     qualifiedName?: string;
 };
+/** To-one only with key proof (relationship filter reach RF-D12); anything else is to-many. */
+export type SemaphorRelationshipDirection = 'to_one' | 'to_many';
+/**
+ * The route a filter value took to a card through the domain's modeled
+ * relationships (relationship filter reach). Applied as "keep the card's rows
+ * that have at least one matching related row", so no row repeats.
+ */
+export type SemaphorRelationshipRoute = {
+    /** Ordered from the base dataset to the value's dataset; non-empty, no repeats. */
+    relationshipIds: string[];
+    /** The card's dataset the route starts from, for wording ("Projects with ..."). */
+    base?: {
+        name: string;
+        label?: string;
+    };
+    /** The datasets after the base, in order, for wording ("through Project"). */
+    datasets: Array<{
+        name: string;
+        label?: string;
+    }>;
+    direction: SemaphorRelationshipDirection;
+    /** For a to-many route: the dataset its first to-many step reaches (the copy's "matching {D}"). */
+    matchingDataset?: {
+        name: string;
+        label?: string;
+    };
+};
 export type AppliedFilterCondition = {
     /** The filter the condition came from: a dashboard input, a request filter, a time window. */
     filterId: string;
@@ -41,6 +68,8 @@ export type AppliedFilterCondition = {
      * Absent when it applied to the whole answer.
      */
     measures?: string[];
+    /** The condition reached the card through these relationships. */
+    through?: SemaphorRelationshipRoute;
 };
 export type SemaphorAppliedConstraint = ({
     kind: 'filter';
@@ -61,7 +90,13 @@ export type SemaphorAppliedConstraint = ({
     grain?: MetricComparisonWindowGrain;
 };
 /** Why a condition was left out of the executed query. */
-export type SemaphorSkippedConstraintReason = 'dataset_not_reachable' | 'field_not_resolvable' | 'missing_metadata' | 'unsupported_calculated_filter';
+export type SemaphorSkippedConstraintReason = 'dataset_not_reachable' | 'field_not_resolvable' | 'missing_metadata' | 'unsupported_calculated_filter'
+/** The relationships connect, but this card can't take the value through them. */
+ | 'relationship_unsupported'
+/** No active modeled relationship connects the value's dataset to the card. */
+ | 'relationship_missing'
+/** More than one equally preferred route connects them; the author chooses one. */
+ | 'relationship_ambiguous';
 export type SemaphorSkippedConstraint = {
     filterId?: string;
     field?: AppliedConstraintField;
@@ -72,3 +107,24 @@ export type SemaphorQueryConstraints = {
     applied: SemaphorAppliedConstraint[];
     skipped: SemaphorSkippedConstraint[];
 };
+/**
+ * Per filter, whether a card query applied it and why not (relationship
+ * filter reach RF-D22): built by the server from its one per-card
+ * resolution, keyed by the filter's id, never from the deduped evidence.
+ */
+export type SemaphorFilterReachEntry = {
+    filterId: string;
+    status: 'applied';
+    through?: SemaphorRelationshipRoute;
+} | {
+    filterId: string;
+    status: 'skipped';
+    reason: SemaphorSkippedConstraintReason;
+} | {
+    filterId: string;
+    status: 'blocked';
+    message: string;
+};
+export declare function readRelationshipRoute(value: unknown): SemaphorRelationshipRoute | undefined;
+/** Reads `filterReach` from a raw `/api/v1/query` response body; [] when absent or malformed. */
+export declare function readFilterReach(responseBody: unknown): SemaphorFilterReachEntry[];

package/dist/types/shared/analytics-protocol/field-provenance.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A column's aggregate and label, written with what they record about where
+ * they came from, in one place (MCP dashboard editing, ledger V-18). Every
+ * producer writes through here (the editor's aggregate menu and rename, the
+ * governed compiler, the MCP's stated labels) and every reader asks here, so
+ * the value and its provenance always tell one story. Before, the editor's
+ * aggregate menu changed `aggregate` and `aggregateOrigin` but left the
+ * compiler's record (`effectiveAggregate`, `aggregateSource`) stale, and the
+ * compiler copied a catalog `aggregateOrigin: "default"` onto an aggregate the
+ * caller chose.
+ */
+export type MetricAggregateSource = 'semantic_model' | 'caller_override' | 'default_sum';
+/** A measure's aggregate and its provenance, as a saved column carries them (structural: any field type fits). */
+export type MetricAggregateProvenance<A extends string = string> = {
+    aggregate?: A;
+    aggregateOrigin?: 'default' | 'explicit';
+    semanticAggregate?: A;
+    effectiveAggregate?: A;
+    aggregateSource?: MetricAggregateSource;
+    /** The field's type, which decides the default aggregate (`defaultMetricAggregate`). */
+    dataType?: string;
+};
+/** A column's label and its provenance. */
+export type LabelProvenance = {
+    label?: string;
+    labelOrigin?: 'semantic' | 'override';
+    derivedLabel?: string;
+};
+/**
+ * The aggregate a measure gets when nobody chooses one, the one rule the
+ * editor (a field dropped on the measures), the governed compiler and every
+ * reader share: the semantic model's, else SUM for a number (or a type not
+ * known) and COUNT for anything else.
+ */
+export declare function defaultMetricAggregate<A extends string>(semanticAggregate: A | undefined, dataType?: string): A | 'SUM' | 'COUNT';
+/**
+ * The compiler's record of a measure's aggregate: the aggregate it runs, and
+ * whether that is the default or an override. Asking for SUM on a SUM measure
+ * is not an override (Analytics MCP focus 1.4b).
+ */
+export declare function metricAggregateRecord<A extends string>(input: {
+    aggregate: A;
+    semanticAggregate?: A;
+    dataType?: string;
+}): {
+    effectiveAggregate: A;
+    aggregateSource: MetricAggregateSource;
+};
+/**
+ * What to set on a measure for a new aggregate: the aggregate, whether
+ * someone chose it (`aggregateOrigin`), and, when the column carries the
+ * compiler's record, that record refreshed. A patch, for the editor's column
+ * updates; `withMetricAggregate` applies it.
+ */
+export declare function metricAggregatePatch<A extends string>(column: Pick<MetricAggregateProvenance<A>, 'semanticAggregate' | 'effectiveAggregate' | 'aggregateSource' | 'dataType'>, aggregate: A, origin: 'default' | 'explicit'): MetricAggregateProvenance<A>;
+/** A measure with a new aggregate and its provenance (`metricAggregatePatch`). */
+export declare function withMetricAggregate<T extends MetricAggregateProvenance>(column: T, aggregate: NonNullable<T['aggregate']>, origin: 'default' | 'explicit'): T;
+/**
+ * The aggregate a measure runs: `aggregate`, which the query builder reads;
+ * the compiler's record only when it is all the column has. Readers ask here,
+ * so a column saved with a stale record is still read as it runs.
+ */
+export declare function metricColumnAggregate<A extends string>(column: Pick<MetricAggregateProvenance<A>, 'aggregate' | 'effectiveAggregate'>): A | undefined;
+/**
+ * Whether someone chose a measure's aggregate rather than it being the
+ * default: the one reading of every stored shape. A column written here says
+ * so in `aggregateOrigin`; one saved before carries either the editor's mark,
+ * the compiler's record (an override, or a default the aggregate no longer
+ * equals because an editor change left the record stale), or neither (read as
+ * chosen, so a query states it).
+ */
+export declare function isMetricAggregateChosen(column: MetricAggregateProvenance): boolean;
+/** The keys an authored label sets together. */
+export declare const AUTHORED_LABEL_KEYS: readonly string[];
+/**
+ * What to set for a label someone wrote: an override, which the editor never
+ * refreshes as a generated label, and no `derivedLabel`, so the field display
+ * rule reads it as authored even when it repeats the synthesized text. A
+ * patch for the editor's column updates (`derivedLabel: undefined` drops it
+ * when saved); `withAuthoredLabel` applies it to a column.
+ */
+export declare function authoredLabelPatch(label: string): LabelProvenance;
+/** A column with a label someone wrote (`authoredLabelPatch`). */
+export declare function withAuthoredLabel<T extends LabelProvenance>(column: T, label: string): T;
+/**
+ * What to set for a generated label (an aggregate's "Average of Sales"): the
+ * label as a refreshable semantic hint, unless someone wrote the label.
+ */
+export declare function generatedLabelPatch(column: Pick<LabelProvenance, 'labelOrigin'>, label: string): LabelProvenance;

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

@@ -28,6 +28,8 @@ export * from './relative-date-label.js';
 export * from './operation-temporal-state.js';
 export * from './aggregate-expression.js';
 export * from './measure-aggregation-profile.js';
+export * from './field-provenance.js';
+export * from './query-policies.js';
 export * from './analytics-refusal.js';
 export * from './visual-choice.js';
 /**

package/dist/types/shared/analytics-protocol/query-policies.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Small pure policies of how a query runs, shared by the governed compiler
+ * and the query builder (semaphor-app) and by whatever reads a saved card
+ * back (MCP dashboard editing, ledger V-19). Each was written once on the
+ * compiling side and again, inverted, on the reading side; a change to one
+ * copy would have broken the other silently. Grounding and SQL generation
+ * stay app-owned: these are the string and ordering rules only.
+ */
+/**
+ * The sort a query gets when it states none: the grouped date ascending;
+ * else, when something is grouped, the primary measure (the first when none
+ * is named) descending; else none.
+ */
+export declare function defaultQuerySort<T>(parts: {
+    groupedDate?: T;
+    measures: readonly T[];
+    grouped: boolean;
+    primaryMeasure?: T;
+}): {
+    target: T;
+    direction: 'asc' | 'desc';
+} | undefined;
+/** The saved condition operators that run a LIKE pattern. */
+export type SavedPatternOperator = 'contains' | 'startsWith' | 'endsWith' | 'like' | 'not like';
+export declare const SAVED_PATTERN_OPERATORS: ReadonlySet<string>;
+/** A LIKE wildcard: `%` or `_`. */
+export declare function hasLikeWildcard(value: string): boolean;
+/**
+ * The LIKE pattern a saved condition runs (the query builder's rule):
+ * `contains` matches anywhere, `startsWith` and `endsWith` at one end, and
+ * `like` and `not like` run the value as written.
+ */
+export declare function savedConditionPattern(operator: SavedPatternOperator, value: string): {
+    pattern: string;
+    negate: boolean;
+};
+/**
+ * The pattern a public `contains` filter runs (the compiler's rule): the
+ * value wrapped in `%...%`, unless it already holds a wildcard.
+ */
+export declare function containsFilterPattern(value: string): string;
+/**
+ * A saved pattern condition as the public `contains` / `not_contains` filter
+ * that runs the same pattern again, or undefined when none does (a pattern
+ * without a wildcard matches a value exactly). Checked against
+ * `containsFilterPattern` itself, so the reading can never drift from the
+ * compiler.
+ */
+export declare function statedPatternFilter(operator: SavedPatternOperator, value: string): {
+    operator: 'contains' | 'not_contains';
+    value: string;
+} | undefined;