react-semaphor 0.1.536 → 0.1.538

package/dist/types/shared/assistant-protocol/context.d.ts

@@ -0,0 +1,952 @@
+import { z } from 'zod';
+import { SemaphorSourceRef } from '../analytics-protocol/contracts.js';
+/**
+ * What the user is looking at, sent with each turn (analytics agent Plan 1,
+ * spec 2.2, module M3). The dashboard, the sheet, its inputs and cards, and
+ * the card the user asked about, described from its compiled execution
+ * snapshot (ledger D3a-1 to D3a-9). In the editor, the card in focus is the
+ * draft being edited, saved or not (Phase 5, D5-2).
+ */
+export declare const ASSISTANT_CONTEXT_VERSION: 1;
+export type AssistantSurface = 'dashboard' | 'editor' | 'none';
+/** What the user is looking at. Built from live state in the browser, or from a saved dashboard in the regression set. */
+export type AssistantContext = {
+    version: typeof ASSISTANT_CONTEXT_VERSION;
+    surface: AssistantSurface;
+    dashboard?: {
+        id: string;
+        title: string;
+        /** The dashboard has edits the user has not saved. */
+        unsavedEdits: boolean;
+    };
+    sheet?: {
+        id: string;
+        title: string;
+    };
+    otherSheets: Array<{
+        id: string;
+        title: string;
+    }>;
+    /** Dashboard inputs (filters, date ranges, controls) on this sheet that currently have a value. */
+    activeInputs: AssistantActiveInput[];
+    /** Cards on the current sheet, by identity; at most ASSISTANT_LIMITS.summaryCards. */
+    cards: AssistantCardSummary[];
+    /** The card in focus: the one the user asked about (Ask), or in the editor the draft being edited. */
+    selectedCard?: AssistantSelectedCard;
+    /** Editor surface only: the visual being edited, in which mode. */
+    editing?: {
+        mode: 'visual' | 'sql';
+    };
+    /** Entries left out past a list cap, counted. */
+    omitted?: {
+        otherSheets?: number;
+        activeInputs?: number;
+        cards?: number;
+    };
+    /** IANA time zone of the viewer. */
+    timeZone: string;
+};
+/**
+ * A sheet-level input (D3a-3): what is set, never which cards use it. Which
+ * inputs a card applies is decided by its compiled query and read only from
+ * its description (P3-66).
+ */
+export type AssistantActiveInput = {
+    /** The input's stable id on the dashboard. */
+    inputId: string;
+    label: string;
+    value: AssistantActiveInputValue;
+    /** The dashboard date: it applies to each card's own date field, on cards that have one. */
+    globalDate?: true;
+};
+export type AssistantActiveInputValue = {
+    kind: 'set';
+    /**
+     * The condition in full detail, from the renderer a card's filters use:
+     * the operator in words, every value up to the cap, dates as written,
+     * whole days with their zone, a relative window's definition.
+     */
+    text: string;
+    /** Values the text leaves out past ASSISTANT_LIMITS.inputValues. */
+    omittedValues?: number;
+    /**
+     * Set on screen but applied by no card in this view: the view was opened
+     * from another dashboard without this dashboard's own filters.
+     */
+    notApplied?: 'opened_from_another_dashboard';
+    /**
+     * Digest of the resolved value and whether the view applies it. Change
+     * detection reads only this, so a change the text cannot show (past a
+     * cap, past the text limit) counts.
+     */
+    fingerprint: string;
+}
+/** The value differs by card (or document section); none is listed. */
+ | {
+    kind: 'varies';
+};
+/** A card on the sheet, by identity only (D3a-2). */
+export type AssistantCardSummary = {
+    id: string;
+    title: string;
+    /** The card's visual type as stored (for example "bar", "table"). */
+    visualType: string;
+    /** When the card's source index names exactly one source. */
+    source?: SemaphorSourceRef;
+};
+/** The asked-about card (D3a-4, D3a-5, D3a-8). */
+export type AssistantSelectedCard = AssistantCardSummary & {
+    /** Digest of every compiled fact; changes when anything the card runs changes, listed or not. */
+    fingerprint: string;
+    description: AssistantCardDescription;
+};
+export type AssistantCardFieldRole = 'row' | 'column' | 'measure' | 'detail';
+export type AssistantCardField = {
+    role: AssistantCardFieldRole;
+    /** As the card stores it. */
+    label: string;
+    name: string;
+    aggregate?: string;
+    granularity?: string;
+};
+/** A dashboard input, the card's own input (an inline filter on the card), its saved filter, its drill, a selection on another card. */
+export type AssistantCardFilterOrigin = 'dashboard_input' | 'card_input' | 'card' | 'drill' | 'selection';
+export type AssistantCardFilter = {
+    origin: AssistantCardFilterOrigin;
+    /** Full detail: every value up to the cap, literals, exact instants, relative definitions. */
+    text: string;
+    omittedValues?: number;
+};
+export type AssistantCardNotDescribedReason = 'matrix' | 'custom_visual' | 'python' | 'snapshot_blocked' | 'snapshot_pending';
+export type AssistantCardDescription = {
+    status: 'described';
+    /** At the level the card runs (a drilled card at its drilled level). */
+    fields: AssistantCardField[];
+    filters: AssistantCardFilter[];
+    controls: Array<{
+        label: string;
+        valueText: string;
+    }>;
+    /** One entry per drill step, outermost first. */
+    drillPath: string[];
+    /** SQL cards: the statement and its parameters with their current values. */
+    sql?: {
+        text: string;
+        parameters: Array<{
+            name: string;
+            valueText: string;
+        }>;
+    };
+    /**
+     * Each measure's requested comparison, in words, with where it comes from
+     * (Phase 3b, D3b-6). Windows are not here: only a result carries them.
+     */
+    comparisons?: string[];
+    /** Entries left out past a list cap, counted. */
+    omitted?: {
+        fields?: number;
+        filters?: number;
+        controls?: number;
+        drillSteps?: number;
+        sqlParameters?: number;
+        comparisons?: number;
+    };
+} | {
+    status: 'not_described';
+    reason: AssistantCardNotDescribedReason;
+    message?: string;
+};
+export type AssistantContextChange = {
+    kind: 'surface_changed';
+    from: AssistantSurface;
+    to: AssistantSurface;
+} | {
+    kind: 'sheet_changed';
+    fromSheetId: string;
+    toSheetId: string;
+} | {
+    kind: 'selection_changed';
+    fromCardId?: string;
+    toCardId?: string;
+}
+/** The same card, compiled differently (fingerprint). */
+ | {
+    kind: 'card_changed';
+    cardId: string;
+} | {
+    kind: 'inputs_changed';
+    inputIds: string[];
+};
+/** The strict schema the server parses a turn's context with. */
+export declare const assistantContextSchema: z.ZodEffects<z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    surface: z.ZodEnum<["dashboard", "editor", "none"]>;
+    dashboard: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        unsavedEdits: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        title: string;
+        unsavedEdits: boolean;
+    }, {
+        id: string;
+        title: string;
+        unsavedEdits: boolean;
+    }>>;
+    sheet: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        title: string;
+    }, {
+        id: string;
+        title: string;
+    }>>;
+    otherSheets: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        title: string;
+    }, {
+        id: string;
+        title: string;
+    }>, "many">;
+    activeInputs: z.ZodArray<z.ZodObject<{
+        inputId: z.ZodString;
+        label: z.ZodString;
+        value: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+            kind: z.ZodLiteral<"set">;
+            text: z.ZodString;
+            omittedValues: z.ZodOptional<z.ZodNumber>;
+            notApplied: z.ZodOptional<z.ZodLiteral<"opened_from_another_dashboard">>;
+            fingerprint: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            kind: "set";
+            text: string;
+            fingerprint: string;
+            omittedValues?: number | undefined;
+            notApplied?: "opened_from_another_dashboard" | undefined;
+        }, {
+            kind: "set";
+            text: string;
+            fingerprint: string;
+            omittedValues?: number | undefined;
+            notApplied?: "opened_from_another_dashboard" | undefined;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"varies">;
+        }, "strict", z.ZodTypeAny, {
+            kind: "varies";
+        }, {
+            kind: "varies";
+        }>]>;
+        globalDate: z.ZodOptional<z.ZodLiteral<true>>;
+    }, "strict", z.ZodTypeAny, {
+        value: {
+            kind: "set";
+            text: string;
+            fingerprint: string;
+            omittedValues?: number | undefined;
+            notApplied?: "opened_from_another_dashboard" | undefined;
+        } | {
+            kind: "varies";
+        };
+        label: string;
+        inputId: string;
+        globalDate?: true | undefined;
+    }, {
+        value: {
+            kind: "set";
+            text: string;
+            fingerprint: string;
+            omittedValues?: number | undefined;
+            notApplied?: "opened_from_another_dashboard" | undefined;
+        } | {
+            kind: "varies";
+        };
+        label: string;
+        inputId: string;
+        globalDate?: true | undefined;
+    }>, "many">;
+    cards: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        visualType: z.ZodString;
+        source: z.ZodOptional<z.ZodType<SemaphorSourceRef, z.ZodTypeDef, SemaphorSourceRef>>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        title: string;
+        visualType: string;
+        source?: SemaphorSourceRef | undefined;
+    }, {
+        id: string;
+        title: string;
+        visualType: string;
+        source?: SemaphorSourceRef | undefined;
+    }>, "many">;
+    selectedCard: z.ZodOptional<z.ZodObject<{
+        fingerprint: z.ZodString;
+        description: z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
+            status: z.ZodLiteral<"described">;
+            fields: z.ZodArray<z.ZodObject<{
+                role: z.ZodEnum<["row", "column", "measure", "detail"]>;
+                label: z.ZodString;
+                name: z.ZodString;
+                aggregate: z.ZodOptional<z.ZodString>;
+                granularity: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }, {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }>, "many">;
+            filters: z.ZodArray<z.ZodObject<{
+                origin: z.ZodEnum<["dashboard_input", "card_input", "card", "drill", "selection"]>;
+                text: z.ZodString;
+                omittedValues: z.ZodOptional<z.ZodNumber>;
+            }, "strict", z.ZodTypeAny, {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }, {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }>, "many">;
+            controls: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                valueText: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                label: string;
+                valueText: string;
+            }, {
+                label: string;
+                valueText: string;
+            }>, "many">;
+            drillPath: z.ZodArray<z.ZodString, "many">;
+            sql: z.ZodOptional<z.ZodObject<{
+                text: z.ZodString;
+                parameters: z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    valueText: z.ZodString;
+                }, "strict", z.ZodTypeAny, {
+                    name: string;
+                    valueText: string;
+                }, {
+                    name: string;
+                    valueText: string;
+                }>, "many">;
+            }, "strict", z.ZodTypeAny, {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            }, {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            }>>;
+            comparisons: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            omitted: z.ZodOptional<z.ZodObject<Record<"filters" | "controls" | "fields" | "drillSteps" | "comparisons" | "sqlParameters", z.ZodOptional<z.ZodNumber>>, "strict", z.ZodTypeAny, {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            }, {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            status: "described";
+            filters: {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }[];
+            controls: {
+                label: string;
+                valueText: string;
+            }[];
+            fields: {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }[];
+            drillPath: string[];
+            sql?: {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            } | undefined;
+            comparisons?: string[] | undefined;
+            omitted?: {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            } | undefined;
+        }, {
+            status: "described";
+            filters: {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }[];
+            controls: {
+                label: string;
+                valueText: string;
+            }[];
+            fields: {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }[];
+            drillPath: string[];
+            sql?: {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            } | undefined;
+            comparisons?: string[] | undefined;
+            omitted?: {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            } | undefined;
+        }>, z.ZodObject<{
+            status: z.ZodLiteral<"not_described">;
+            reason: z.ZodEnum<["matrix", "custom_visual", "python", "snapshot_blocked", "snapshot_pending"]>;
+            message: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            status: "not_described";
+            reason: "matrix" | "python" | "custom_visual" | "snapshot_blocked" | "snapshot_pending";
+            message?: string | undefined;
+        }, {
+            status: "not_described";
+            reason: "matrix" | "python" | "custom_visual" | "snapshot_blocked" | "snapshot_pending";
+            message?: string | undefined;
+        }>]>;
+        id: z.ZodString;
+        title: z.ZodString;
+        visualType: z.ZodString;
+        source: z.ZodOptional<z.ZodType<SemaphorSourceRef, z.ZodTypeDef, SemaphorSourceRef>>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        description: {
+            status: "described";
+            filters: {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }[];
+            controls: {
+                label: string;
+                valueText: string;
+            }[];
+            fields: {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }[];
+            drillPath: string[];
+            sql?: {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            } | undefined;
+            comparisons?: string[] | undefined;
+            omitted?: {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            } | undefined;
+        } | {
+            status: "not_described";
+            reason: "matrix" | "python" | "custom_visual" | "snapshot_blocked" | "snapshot_pending";
+            message?: string | undefined;
+        };
+        title: string;
+        visualType: string;
+        fingerprint: string;
+        source?: SemaphorSourceRef | undefined;
+    }, {
+        id: string;
+        description: {
+            status: "described";
+            filters: {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }[];
+            controls: {
+                label: string;
+                valueText: string;
+            }[];
+            fields: {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }[];
+            drillPath: string[];
+            sql?: {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            } | undefined;
+            comparisons?: string[] | undefined;
+            omitted?: {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            } | undefined;
+        } | {
+            status: "not_described";
+            reason: "matrix" | "python" | "custom_visual" | "snapshot_blocked" | "snapshot_pending";
+            message?: string | undefined;
+        };
+        title: string;
+        visualType: string;
+        fingerprint: string;
+        source?: SemaphorSourceRef | undefined;
+    }>>;
+    editing: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<["visual", "sql"]>;
+    }, "strict", z.ZodTypeAny, {
+        mode: "sql" | "visual";
+    }, {
+        mode: "sql" | "visual";
+    }>>;
+    omitted: z.ZodOptional<z.ZodObject<Record<"cards" | "activeInputs" | "otherSheets", z.ZodOptional<z.ZodNumber>>, "strict", z.ZodTypeAny, {
+        cards?: number | undefined;
+        activeInputs?: number | undefined;
+        otherSheets?: number | undefined;
+    }, {
+        cards?: number | undefined;
+        activeInputs?: number | undefined;
+        otherSheets?: number | undefined;
+    }>>;
+    timeZone: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    timeZone: string;
+    version: 1;
+    cards: {
+        id: string;
+        title: string;
+        visualType: string;
+        source?: SemaphorSourceRef | undefined;
+    }[];
+    surface: "none" | "dashboard" | "editor";
+    activeInputs: {
+        value: {
+            kind: "set";
+            text: string;
+            fingerprint: string;
+            omittedValues?: number | undefined;
+            notApplied?: "opened_from_another_dashboard" | undefined;
+        } | {
+            kind: "varies";
+        };
+        label: string;
+        inputId: string;
+        globalDate?: true | undefined;
+    }[];
+    otherSheets: {
+        id: string;
+        title: string;
+    }[];
+    sheet?: {
+        id: string;
+        title: string;
+    } | undefined;
+    dashboard?: {
+        id: string;
+        title: string;
+        unsavedEdits: boolean;
+    } | undefined;
+    selectedCard?: {
+        id: string;
+        description: {
+            status: "described";
+            filters: {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }[];
+            controls: {
+                label: string;
+                valueText: string;
+            }[];
+            fields: {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }[];
+            drillPath: string[];
+            sql?: {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            } | undefined;
+            comparisons?: string[] | undefined;
+            omitted?: {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            } | undefined;
+        } | {
+            status: "not_described";
+            reason: "matrix" | "python" | "custom_visual" | "snapshot_blocked" | "snapshot_pending";
+            message?: string | undefined;
+        };
+        title: string;
+        visualType: string;
+        fingerprint: string;
+        source?: SemaphorSourceRef | undefined;
+    } | undefined;
+    omitted?: {
+        cards?: number | undefined;
+        activeInputs?: number | undefined;
+        otherSheets?: number | undefined;
+    } | undefined;
+    editing?: {
+        mode: "sql" | "visual";
+    } | undefined;
+}, {
+    timeZone: string;
+    version: 1;
+    cards: {
+        id: string;
+        title: string;
+        visualType: string;
+        source?: SemaphorSourceRef | undefined;
+    }[];
+    surface: "none" | "dashboard" | "editor";
+    activeInputs: {
+        value: {
+            kind: "set";
+            text: string;
+            fingerprint: string;
+            omittedValues?: number | undefined;
+            notApplied?: "opened_from_another_dashboard" | undefined;
+        } | {
+            kind: "varies";
+        };
+        label: string;
+        inputId: string;
+        globalDate?: true | undefined;
+    }[];
+    otherSheets: {
+        id: string;
+        title: string;
+    }[];
+    sheet?: {
+        id: string;
+        title: string;
+    } | undefined;
+    dashboard?: {
+        id: string;
+        title: string;
+        unsavedEdits: boolean;
+    } | undefined;
+    selectedCard?: {
+        id: string;
+        description: {
+            status: "described";
+            filters: {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }[];
+            controls: {
+                label: string;
+                valueText: string;
+            }[];
+            fields: {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }[];
+            drillPath: string[];
+            sql?: {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            } | undefined;
+            comparisons?: string[] | undefined;
+            omitted?: {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            } | undefined;
+        } | {
+            status: "not_described";
+            reason: "matrix" | "python" | "custom_visual" | "snapshot_blocked" | "snapshot_pending";
+            message?: string | undefined;
+        };
+        title: string;
+        visualType: string;
+        fingerprint: string;
+        source?: SemaphorSourceRef | undefined;
+    } | undefined;
+    omitted?: {
+        cards?: number | undefined;
+        activeInputs?: number | undefined;
+        otherSheets?: number | undefined;
+    } | undefined;
+    editing?: {
+        mode: "sql" | "visual";
+    } | undefined;
+}>, {
+    timeZone: string;
+    version: 1;
+    cards: {
+        id: string;
+        title: string;
+        visualType: string;
+        source?: SemaphorSourceRef | undefined;
+    }[];
+    surface: "none" | "dashboard" | "editor";
+    activeInputs: {
+        value: {
+            kind: "set";
+            text: string;
+            fingerprint: string;
+            omittedValues?: number | undefined;
+            notApplied?: "opened_from_another_dashboard" | undefined;
+        } | {
+            kind: "varies";
+        };
+        label: string;
+        inputId: string;
+        globalDate?: true | undefined;
+    }[];
+    otherSheets: {
+        id: string;
+        title: string;
+    }[];
+    sheet?: {
+        id: string;
+        title: string;
+    } | undefined;
+    dashboard?: {
+        id: string;
+        title: string;
+        unsavedEdits: boolean;
+    } | undefined;
+    selectedCard?: {
+        id: string;
+        description: {
+            status: "described";
+            filters: {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }[];
+            controls: {
+                label: string;
+                valueText: string;
+            }[];
+            fields: {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }[];
+            drillPath: string[];
+            sql?: {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            } | undefined;
+            comparisons?: string[] | undefined;
+            omitted?: {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            } | undefined;
+        } | {
+            status: "not_described";
+            reason: "matrix" | "python" | "custom_visual" | "snapshot_blocked" | "snapshot_pending";
+            message?: string | undefined;
+        };
+        title: string;
+        visualType: string;
+        fingerprint: string;
+        source?: SemaphorSourceRef | undefined;
+    } | undefined;
+    omitted?: {
+        cards?: number | undefined;
+        activeInputs?: number | undefined;
+        otherSheets?: number | undefined;
+    } | undefined;
+    editing?: {
+        mode: "sql" | "visual";
+    } | undefined;
+}, {
+    timeZone: string;
+    version: 1;
+    cards: {
+        id: string;
+        title: string;
+        visualType: string;
+        source?: SemaphorSourceRef | undefined;
+    }[];
+    surface: "none" | "dashboard" | "editor";
+    activeInputs: {
+        value: {
+            kind: "set";
+            text: string;
+            fingerprint: string;
+            omittedValues?: number | undefined;
+            notApplied?: "opened_from_another_dashboard" | undefined;
+        } | {
+            kind: "varies";
+        };
+        label: string;
+        inputId: string;
+        globalDate?: true | undefined;
+    }[];
+    otherSheets: {
+        id: string;
+        title: string;
+    }[];
+    sheet?: {
+        id: string;
+        title: string;
+    } | undefined;
+    dashboard?: {
+        id: string;
+        title: string;
+        unsavedEdits: boolean;
+    } | undefined;
+    selectedCard?: {
+        id: string;
+        description: {
+            status: "described";
+            filters: {
+                text: string;
+                origin: "card" | "selection" | "drill" | "dashboard_input" | "card_input";
+                omittedValues?: number | undefined;
+            }[];
+            controls: {
+                label: string;
+                valueText: string;
+            }[];
+            fields: {
+                label: string;
+                name: string;
+                role: "measure" | "row" | "detail" | "column";
+                granularity?: string | undefined;
+                aggregate?: string | undefined;
+            }[];
+            drillPath: string[];
+            sql?: {
+                parameters: {
+                    name: string;
+                    valueText: string;
+                }[];
+                text: string;
+            } | undefined;
+            comparisons?: string[] | undefined;
+            omitted?: {
+                filters?: number | undefined;
+                controls?: number | undefined;
+                fields?: number | undefined;
+                drillSteps?: number | undefined;
+                comparisons?: number | undefined;
+                sqlParameters?: number | undefined;
+            } | undefined;
+        } | {
+            status: "not_described";
+            reason: "matrix" | "python" | "custom_visual" | "snapshot_blocked" | "snapshot_pending";
+            message?: string | undefined;
+        };
+        title: string;
+        visualType: string;
+        fingerprint: string;
+        source?: SemaphorSourceRef | undefined;
+    } | undefined;
+    omitted?: {
+        cards?: number | undefined;
+        activeInputs?: number | undefined;
+        otherSheets?: number | undefined;
+    } | undefined;
+    editing?: {
+        mode: "sql" | "visual";
+    } | undefined;
+}>;
+/** Pure. Compares the last finished turn's context with this turn's. */
+export declare function compareAssistantContexts(previous: AssistantContext | undefined, next: AssistantContext): AssistantContextChange[];
+/**
+ * Pure. The text block the model reads at the start of a turn: where the user
+ * is, the asked-about card as compiled, the sources in scope, the changes
+ * since the last turn. Never a card config or rows.
+ */
+export declare function renderContextForModel(context: AssistantContext, changes: AssistantContextChange[], addedSources: SemaphorSourceRef[]): string;
+/** A source in words, with the identifiers the tools take. */
+export declare function describeSource(source: SemaphorSourceRef): string;