@malloydata/malloy 0.0.391 → 0.0.392

package/dist/model/malloy_types.d.ts

@@ -36,7 +36,7 @@ export type AnyExpr = ExprE | ExprOptionalE | ExprWithKids | ExprLeaf;
 export declare function exprHasKids(e: AnyExpr): e is ExprWithKids;
 export declare function exprHasE(e: AnyExpr): e is ExprE;
 export declare function exprIsLeaf(e: AnyExpr): boolean;
-export type Expr = BinaryExpr | UnaryExpr | FunctionCallNode | OutputFieldNode | FilterCondition | FilteredExpr | AggregateExpr | EmptyExpr | UngroupNode | FunctionParameterNode | SpreadExpr | AggregateOrderByNode | AggregateLimitNode | FieldnameNode | SourceReferenceNode | ParameterNode | NowNode | MeasureTimeExpr | TimeExtractExpr | TimeDeltaExpr | TimeTruncExpr | DateLiteralNode | TimestampLiteralNode | TimestamptzLiteralNode | TypecastExpr | RegexMatchExpr | RegexLiteralNode | FilterMatchExpr | FilterLiteralExpr | StringLiteralNode | NumberLiteralNode | BooleanLiteralNode | RecordLiteralNode | ArrayLiteralNode | FunctionOrderBy | GenericSQLExpr | NullNode | CaseExpr | InCompareExpr | CompositeFieldExpr | ErrorNode;
+export type Expr = BinaryExpr | UnaryExpr | FunctionCallNode | OutputFieldNode | FilterCondition | FilteredExpr | AggregateExpr | EmptyExpr | UngroupNode | FunctionParameterNode | SpreadExpr | AggregateOrderByNode | AggregateLimitNode | FieldnameNode | SourceReferenceNode | ParameterNode | GivenRefNode | NowNode | MeasureTimeExpr | TimeExtractExpr | TimeDeltaExpr | TimeTruncExpr | DateLiteralNode | TimestampLiteralNode | TimestamptzLiteralNode | TypecastExpr | RegexMatchExpr | RegexLiteralNode | FilterMatchExpr | FilterLiteralExpr | StringLiteralNode | NumberLiteralNode | BooleanLiteralNode | RecordLiteralNode | ArrayLiteralNode | FunctionOrderBy | GenericSQLExpr | NullNode | CaseExpr | InCompareExpr | CompositeFieldExpr | ErrorNode;
 export type BinaryOperator = '+' | '-' | '*' | '%' | '/' | 'and' | 'or' | '=' | '!=' | '>' | '<' | '>=' | '<=' | 'coalesce' | 'like' | '!like';
 export interface BinaryExpr extends ExprWithKids {
     node: BinaryOperator;
@@ -71,7 +71,7 @@ export interface FilterCondition extends ExprE {
     node: 'filterCondition';
     code: string;
     expressionType: ExpressionType;
-    fieldUsage?: FieldUsage[];
+    refSummary?: RefSummary;
     filterView?: string;
     stableFilter?: Malloy.Filter;
     isSourceFilter?: boolean;
@@ -128,6 +128,11 @@ export interface ParameterNode extends ExprLeaf {
     node: 'parameter';
     path: string[];
 }
+export interface GivenRefNode extends ExprLeaf {
+    node: 'given';
+    id: GivenID;
+    refName: string;
+}
 export interface NowNode extends ExprLeaf {
     node: 'now';
     typeDef: {
@@ -287,12 +292,12 @@ export interface InCompareExpr extends ExprWithKids {
 export type ExpressionType = 'scalar' | 'aggregate' | 'scalar_analytic' | 'aggregate_analytic' | 'ungrouped_aggregate';
 export interface Expression {
     e?: Expr;
-    fieldUsage?: FieldUsage[];
+    refSummary?: RefSummary;
     expressionType?: ExpressionType;
     code?: string;
     drillExpression?: Malloy.Expression;
 }
-type ConstantExpr = Expr;
+export type ConstantExpr = Expr;
 interface ParameterInfo {
     name: string;
     value: ConstantExpr | null;
@@ -306,6 +311,42 @@ export declare function isParameterType(t: string): t is ParameterType;
 export type ParameterTypeDef = StringTypeDef | NumberTypeDef | BooleanTypeDef | TemporalTypeDef | FilterExpressionParamTypeDef | ErrorTypeDef;
 export type Parameter = ParameterTypeDef & ParameterInfo;
 export type Argument = Parameter;
+/**
+ * Type of a given declaration. The grammar's `malloyType` already excludes
+ * `json` and `sql native`, so any value of this union is a legal given type.
+ *
+ * The fully-narrowed recursive form described in `~/ctx/mp/implementation.md`
+ * (a fresh union over a smaller atomic base) lands with the IR work; the
+ * shape here is the conservative "not yet narrowed" version.
+ */
+export type GivenTypeDef = AtomicTypeDef | FilterExpressionParamTypeDef;
+export interface Given extends HasLocation, HasAnnotation {
+    /** The name as written at the declaration site. Used by diagnostics
+     *  that need a readable surface name out of an opaque GivenID. */
+    name: string;
+    type: GivenTypeDef;
+    /** Non-optional so the no-default case is explicit at every read site. */
+    default: ConstantExpr | undefined;
+    /** Pre-rendered source text of the default expression, captured at
+     *  declaration time so hover (`DocumentGivenReference`) can show it
+     *  without re-rendering an Expr back to source. Absent when there's
+     *  no default. */
+    defaultText?: string;
+    /** Transitive closure of givens this declaration references — only
+     *  reachable through the default's expression chain (a Given has no
+     *  other given-referencing surface). Precomputed at declaration time.
+     *  For `A is $B + 1` where `B is $C`: A's `givenUsage` is `[B, C]`.
+     *  The satisfiability check expands each Query.givenUsage entry
+     *  through this closure and verifies each id is in-namespace or has
+     *  its own default. Empty/undefined when the default is a closed
+     *  literal. */
+    givenUsage?: GivenUsage;
+}
+export interface GivenEntry {
+    type: 'given';
+    name: string;
+    id: GivenID;
+}
 export declare function paramHasValue(p: Parameter): boolean;
 export interface DocumentRange {
     start: DocumentPosition;
@@ -335,10 +376,8 @@ export interface DocumentLocation {
  * the references, and in that case, this should include something like an
  * index or pointer to the full definition elsewhere in the model.
  */
-export interface LightweightDefinition {
+export interface LightweightDefinition extends HasLocation, HasAnnotation {
     type: string;
-    annotation?: Annotation;
-    location?: DocumentLocation;
 }
 interface DocumentReferenceBase {
     text: string;
@@ -360,11 +399,26 @@ export interface DocumentQueryReference extends DocumentReferenceBase {
 export interface DocumentFieldReference extends DocumentReferenceBase {
     type: 'fieldReference';
 }
-export type DocumentReference = DocumentExploreReference | DocumentQueryReference | DocumentSQLBlockReference | DocumentFieldReference | DocumentJoinReference;
+/**
+ * Definition info attached to a `DocumentGivenReference`. Extends the
+ * base with `defaultText` — the pre-rendered source of the given's
+ * default expression, if one was declared.
+ */
+export interface GivenLightweightDefinition extends LightweightDefinition {
+    defaultText?: string;
+}
+export interface DocumentGivenReference extends DocumentReferenceBase {
+    type: 'givenReference';
+    definition: GivenLightweightDefinition;
+}
+export type DocumentReference = DocumentExploreReference | DocumentQueryReference | DocumentSQLBlockReference | DocumentFieldReference | DocumentJoinReference | DocumentGivenReference;
 /** put location into the parse tree. */
 export interface HasLocation {
     location?: DocumentLocation;
 }
+export interface HasAnnotation {
+    annotation?: Annotation;
+}
 /** All names have their source names and how they will appear in the symbol table that owns them */
 export interface AliasedName {
     name: string;
@@ -423,8 +477,7 @@ export declare function canOrderBy(s: string): boolean;
  * value could be an expression, and this is one of the objects
  * which might have an annotation.
  */
-export interface FieldBase extends NamedObject, Expression, ResultMetadata {
-    annotation?: Annotation;
+export interface FieldBase extends NamedObject, Expression, ResultMetadata, HasAnnotation {
     accessModifier?: NonDefaultAccessModifierLabel | undefined;
     requiresGroupBy?: RequiredGroupBy[];
     ungroupings?: AggregateUngrouping[];
@@ -514,7 +567,7 @@ export interface JoinBase {
     join: JoinType;
     matrixOperation?: MatrixOperation;
     onExpression?: Expr;
-    fieldUsage?: FieldUsage[];
+    refSummary?: RefSummary;
     accessModifier?: NonDefaultAccessModifierLabel | undefined;
 }
 export type Joinable = CompositeSourceDef | TableSourceDef | SQLSourceDef | QuerySourceDef | VirtualSourceDef | RepeatedRecordDef | RecordDef | ArrayDef;
@@ -586,14 +639,14 @@ export interface TurtleSegment extends Filtered {
 export interface Pipeline {
     pipeline: PipeSegment[];
 }
-export interface Query extends Pipeline, Filtered, HasLocation {
+export interface Query extends Pipeline, Filtered, HasLocation, HasAnnotation {
     type?: 'query';
     name?: string;
     structRef: StructRef;
     sourceArguments?: SafeRecord<Argument>;
-    annotation?: Annotation;
     modelAnnotation?: Annotation;
     compositeResolvedSourceDef?: SourceDef;
+    givenUsage?: GivenUsage;
 }
 export type NamedQueryDef = Query & NamedObject;
 export type PipeSegment = QuerySegment | IndexSegment | RawSegment;
@@ -647,8 +700,9 @@ export type SegmentFieldDef = IndexFieldDef | QueryFieldDef;
  *   4) Each join path ending in an analytic funtion
  */
 export interface SegmentUsageSummary {
-    activeJoins?: FieldUsage[];
-    expandedFieldUsage?: FieldUsage[];
+    activeJoins?: FieldUsage;
+    expandedFieldUsage?: FieldUsage;
+    expandedGivenUsage?: GivenUsage;
     expandedUngroupings?: AggregateUngrouping[];
 }
 export interface IndexSegment extends Filtered, SegmentUsageSummary {
@@ -658,18 +712,82 @@ export interface IndexSegment extends Filtered, SegmentUsageSummary {
     weightMeasure?: string;
     sample?: Sampling;
     alwaysJoins?: string[];
-    fieldUsage?: FieldUsage[];
+    refSummary?: RefSummary;
     referencedAt?: DocumentLocation;
     outputStruct: SourceDef;
 }
 export declare function isIndexSegment(pe: PipeSegment): pe is IndexSegment;
-export interface FieldUsage {
+export interface FieldUsageEntry {
     path: string[];
     at?: DocumentLocation;
     uniqueKeyRequirement?: UniqueKeyRequirement;
     analyticFunctionUse?: boolean;
 }
-export declare function bareFieldUsage(fu: FieldUsage): boolean;
+/** Plural alias — most "field usage" data is a collection of entries. */
+export type FieldUsage = FieldUsageEntry[];
+export declare function bareFieldUsage(fu: FieldUsageEntry): boolean;
+/**
+ * What a `givenRef` IR node references, accumulated while walking IR.
+ * `id` is the global GivenID; `at` carries the reference site for diagnostics.
+ */
+export interface GivenUsageEntry {
+    id: GivenID;
+    at?: DocumentLocation;
+}
+/** Plural alias — most "given usage" data is a collection of entries. */
+export type GivenUsage = GivenUsageEntry[];
+/**
+ * `refSummary` is the IR-level reference-tracking field — what fields and
+ * givens does this IR fragment reference. `fieldUsage` carries source-rooted
+ * field paths (paths-rooted-in-source invariant unchanged); `givenUsage`
+ * carries GivenIDs reachable from this fragment, populated by the same
+ * walker that populates `fieldUsage`.
+ *
+ * Read sites use `fieldUsageFrom` / `givenUsageFrom` accessors so callers
+ * don't have to handle the optional-`refSummary` case.
+ */
+export interface RefSummary {
+    fieldUsage: FieldUsage;
+    givenUsage?: GivenUsage;
+}
+export declare function fieldUsageFrom(rs: RefSummary | undefined): FieldUsage;
+export declare function givenUsageFrom(rs: RefSummary | undefined): GivenUsage;
+/**
+ * Construct a `RefSummary` from optionally-supplied component arrays. Returns
+ * undefined when no component is supplied (matching the IR convention that an
+ * absent `refSummary` means "I never set this"). An explicitly-empty array
+ * is preserved (e.g. `{fieldUsage: []}` mirrors the pre-rename "I checked,
+ * found nothing" state distinct from "I never set the field").
+ *
+ * Object-arg shape is the forward-compatible seam for `givenUsage` and any
+ * future RefSummary slots — they get added as additional optional keys on
+ * the destructured param without touching call sites that don't supply them.
+ */
+export declare function mkRefSummary({ fieldUsage, givenUsage, }: {
+    fieldUsage?: FieldUsage;
+    givenUsage?: GivenUsage;
+}): RefSummary | undefined;
+/**
+ * Apply `fn` to each `FieldUsageEntry` in a `RefSummary`, preserving all other
+ * RefSummary fields. Returns undefined when `rs` is undefined. The site that
+ * needs to rewrite usage paths (e.g. rename, location-rebrand) goes through
+ * here so future RefSummary fields like `givenUsage` are carried along
+ * untouched without each call site having to know about them.
+ */
+export declare function mapFieldUsage(rs: RefSummary | undefined, fn: (u: FieldUsageEntry) => FieldUsageEntry): RefSummary | undefined;
+/**
+ * Mutating setter for a node's `fieldUsage`. When the node already has a
+ * `refSummary`, replaces just the `fieldUsage` slice (preserving `givenUsage`
+ * and any future RefSummary fields). When it doesn't, creates a fresh
+ * `refSummary` with the supplied usages.
+ *
+ * Use at sites that mutate an already-constructed IR node; for sites that
+ * build a node from a literal, write `{fieldUsage: [...]}` directly or use
+ * `mkRefSummary` for possibly-undefined inputs.
+ */
+export declare function setFieldUsage(target: {
+    refSummary?: RefSummary;
+}, usages: FieldUsage): void;
 export interface QuerySegment extends Filtered, Ordered, SegmentUsageSummary {
     type: 'reduce' | 'project' | 'partial';
     queryFields: QueryFieldDef[];
@@ -677,25 +795,23 @@ export interface QuerySegment extends Filtered, Ordered, SegmentUsageSummary {
     limit?: number;
     queryTimezone?: string;
     alwaysJoins?: string[];
-    fieldUsage?: FieldUsage[];
+    refSummary?: RefSummary;
     referencedAt?: DocumentLocation;
     outputStruct: SourceDef;
     isRepeated: boolean;
 }
 export type NonDefaultAccessModifierLabel = 'private' | 'internal';
 export type AccessModifierLabel = NonDefaultAccessModifierLabel | 'public';
-export interface TurtleDef extends NamedObject, Pipeline {
+export interface TurtleDef extends NamedObject, Pipeline, HasAnnotation {
     type: 'turtle';
-    annotation?: Annotation;
     accessModifier?: NonDefaultAccessModifierLabel | undefined;
-    fieldUsage?: FieldUsage[];
+    refSummary?: RefSummary;
     requiredGroupBys?: string[][];
 }
 export interface TurtleDefPlusFilters extends TurtleDef, Filtered {
 }
-interface StructDefBase extends HasLocation, NamedObject {
+interface StructDefBase extends HasLocation, NamedObject, HasAnnotation {
     type: string;
-    annotation?: Annotation;
     modelAnnotation?: ModelAnnotation;
     fields: FieldDef[];
     /** Marker for error placeholder structs created by ErrorFactory */
@@ -739,6 +855,8 @@ export declare function isSegmentSQL(f: SQLPhraseSegment): f is SQLStringSegment
 export declare function isSegmentSource(f: SQLPhraseSegment): f is PersistableSourceDef;
 /** Format: "name@modelUrl" - uniquely identifies a source for persistence */
 export type SourceID = string;
+/** Created with `mkGivenID`. */
+export type GivenID = string;
 /** Hash of (connectionDigest, sql) - uniquely identifies a built artifact */
 export type BuildID = string;
 /**
@@ -832,13 +950,13 @@ export type ExpressionValueType = AtomicFieldType | NonAtomicType | TurtleType;
 export type ExpressionValueTypeDef = AtomicTypeDef | NonAtomicTypeDef | TurtleTypeDef;
 export type BasicExpressionType = Exclude<ExpressionValueType, JoinElementType | 'turtle'>;
 export interface RequiredGroupBy {
-    fieldUsage?: FieldUsage;
+    fieldUsage?: FieldUsageEntry;
     at?: DocumentLocation;
     path: string[];
 }
 export interface AggregateUngrouping {
     ungroupedFields: string[][] | '*';
-    fieldUsage: FieldUsage[];
+    fieldUsage: FieldUsage;
     requiresGroupBy?: RequiredGroupBy[];
     exclude: boolean;
     path: string[];
@@ -847,7 +965,7 @@ export interface AggregateUngrouping {
 export type TypeInfo = {
     expressionType: ExpressionType;
     evalSpace: EvalSpace;
-    fieldUsage: FieldUsage[];
+    refSummary?: RefSummary;
     requiresGroupBy?: RequiredGroupBy[];
     ungroupings?: AggregateUngrouping[];
 };
@@ -946,10 +1064,9 @@ export type AtomicFieldDef = BasicAtomicDef | BasicArrayDef | RecordDef | Repeat
 export declare function isBasicAtomic(fd: FieldDef | QueryFieldDef | AtomicTypeDef): fd is BasicAtomicDef;
 export type FieldDef = BasicAtomicDef | JoinFieldDef | TurtleDef;
 export type FieldDefType = AtomicFieldType | 'turtle' | JoinElementType;
-export interface RefToField {
+export interface RefToField extends HasAnnotation {
     type: 'fieldref';
     path: string[];
-    annotation?: Annotation;
     at?: DocumentLocation;
     drillExpression?: Malloy.Expression | undefined;
 }
@@ -957,18 +1074,16 @@ export type QueryFieldDef = AtomicFieldDef | TurtleDef | RefToField;
 export type TypedDef = AtomicTypeDef | JoinFieldDef | TurtleDef | RefToField | StructDef;
 /** Get the output name for a NamedObject */
 export declare function getIdentifier(n: AliasedName): string;
-export interface UserTypeFieldDef {
+export interface UserTypeFieldDef extends HasAnnotation {
     name: string;
     typeDef: AtomicTypeDef;
-    annotation?: Annotation;
 }
-export interface UserTypeDef extends NamedObject {
+export interface UserTypeDef extends NamedObject, HasAnnotation {
     type: 'userType';
     fields: UserTypeFieldDef[];
-    annotation?: Annotation;
 }
 export declare function isUserTypeDef(sd: NamedModelObject): sd is UserTypeDef;
-export type NamedModelObject = SourceDef | NamedQueryDef | FunctionDef | ConnectionDef | UserTypeDef;
+export type NamedModelObject = SourceDef | NamedQueryDef | FunctionDef | ConnectionDef | UserTypeDef | GivenEntry;
 export interface DependencyTree {
     [url: string]: DependencyTree;
 }
@@ -984,6 +1099,7 @@ export interface ModelDef {
      * Each entry includes a lazily-computed persist flag.
      */
     sourceRegistry: Record<SourceID, SourceRegistryValue>;
+    givens?: Record<GivenID, Given>;
     annotation?: ModelAnnotation;
     queryList: Query[];
     dependencies: DependencyTree;
@@ -1034,7 +1150,7 @@ export interface DrillSource {
     sourceFilters?: FilterCondition[];
     sourceArguments?: SafeRecord<Argument>;
 }
-export interface CompiledQuery extends DrillSource {
+export interface CompiledQuery extends DrillSource, HasAnnotation {
     structs: SourceDef[];
     sql: string;
     lastStageName: string;
@@ -1042,7 +1158,6 @@ export interface CompiledQuery extends DrillSource {
     queryName?: string | undefined;
     connectionName: string;
     queryTimezone?: string;
-    annotation?: Annotation;
     defaultRowLimitAdded?: number;
 }
 /** Result type for running a Malloy query. */
@@ -1089,6 +1204,10 @@ export interface SearchValueMapResult {
  * Uses Map instead of Record because both keys are user-provided strings.
  */
 export type VirtualMap = Map<string, Map<string, string>>;
+/** JS-side accepted shapes for caller-supplied given values. */
+export type GivenValue = string | number | bigint | boolean | Date | null | GivenValue[] | {
+    [key: string]: GivenValue;
+};
 export interface PrepareResultOptions {
     defaultRowLimit?: number;
     isPartialQuery?: boolean;
@@ -1099,6 +1218,7 @@ export interface PrepareResultOptions {
     connectionDigests?: SafeRecord<string>;
     /** Map from connectionName → virtualName → tablePath for virtual source resolution */
     virtualMap?: VirtualMap;
+    resolvedGivens?: Map<GivenID, Expr>;
 }
 type UTD = AtomicTypeDef | TypedDef | FunctionParameterTypeDef | FunctionReturnTypeDef | undefined;
 /**
@@ -1119,6 +1239,13 @@ export declare const TD: {
     isAnyTimestamp(td: UTD): td is ATimestampTypeDef;
     isTemporal(td: UTD): td is TemporalTypeDef;
     isError: (td: UTD) => td is ErrorTypeDef;
+    /**
+     * Strip non-type metadata (name, joins, expressionType, evalSpace, ...)
+     * off a typed def, leaving a clean AtomicTypeDef. Used when copying a
+     * field's type onto an Expr's typeDef, where the field metadata would
+     * pollute the IR. Returns `{type: 'error'}` for non-atomic inputs.
+     */
+    atomicDef(td: UTD): AtomicTypeDef;
     eq(x: UTD, y: UTD): boolean;
 };
 /**

package/dist/model/malloy_types.js

@@ -78,6 +78,11 @@ exports.isSamplingEnable = isSamplingEnable;
 exports.isRawSegment = isRawSegment;
 exports.isIndexSegment = isIndexSegment;
 exports.bareFieldUsage = bareFieldUsage;
+exports.fieldUsageFrom = fieldUsageFrom;
+exports.givenUsageFrom = givenUsageFrom;
+exports.mkRefSummary = mkRefSummary;
+exports.mapFieldUsage = mapFieldUsage;
+exports.setFieldUsage = setFieldUsage;
 exports.isSegmentSQL = isSegmentSQL;
 exports.isSegmentSource = isSegmentSource;
 exports.isSourceRegistryReference = isSourceRegistryReference;
@@ -458,6 +463,61 @@ function bareFieldUsage(fu) {
     return (fu.uniqueKeyRequirement === undefined &&
         fu.analyticFunctionUse === undefined);
 }
+function fieldUsageFrom(rs) {
+    var _a;
+    return (_a = rs === null || rs === void 0 ? void 0 : rs.fieldUsage) !== null && _a !== void 0 ? _a : [];
+}
+function givenUsageFrom(rs) {
+    var _a;
+    return (_a = rs === null || rs === void 0 ? void 0 : rs.givenUsage) !== null && _a !== void 0 ? _a : [];
+}
+/**
+ * Construct a `RefSummary` from optionally-supplied component arrays. Returns
+ * undefined when no component is supplied (matching the IR convention that an
+ * absent `refSummary` means "I never set this"). An explicitly-empty array
+ * is preserved (e.g. `{fieldUsage: []}` mirrors the pre-rename "I checked,
+ * found nothing" state distinct from "I never set the field").
+ *
+ * Object-arg shape is the forward-compatible seam for `givenUsage` and any
+ * future RefSummary slots — they get added as additional optional keys on
+ * the destructured param without touching call sites that don't supply them.
+ */
+function mkRefSummary({ fieldUsage, givenUsage, }) {
+    if (fieldUsage === undefined && givenUsage === undefined)
+        return undefined;
+    return {
+        fieldUsage: fieldUsage !== null && fieldUsage !== void 0 ? fieldUsage : [],
+        ...(givenUsage && { givenUsage }),
+    };
+}
+/**
+ * Apply `fn` to each `FieldUsageEntry` in a `RefSummary`, preserving all other
+ * RefSummary fields. Returns undefined when `rs` is undefined. The site that
+ * needs to rewrite usage paths (e.g. rename, location-rebrand) goes through
+ * here so future RefSummary fields like `givenUsage` are carried along
+ * untouched without each call site having to know about them.
+ */
+function mapFieldUsage(rs, fn) {
+    return rs && { ...rs, fieldUsage: rs.fieldUsage.map(fn) };
+}
+/**
+ * Mutating setter for a node's `fieldUsage`. When the node already has a
+ * `refSummary`, replaces just the `fieldUsage` slice (preserving `givenUsage`
+ * and any future RefSummary fields). When it doesn't, creates a fresh
+ * `refSummary` with the supplied usages.
+ *
+ * Use at sites that mutate an already-constructed IR node; for sites that
+ * build a node from a literal, write `{fieldUsage: [...]}` directly or use
+ * `mkRefSummary` for possibly-undefined inputs.
+ */
+function setFieldUsage(target, usages) {
+    if (target.refSummary) {
+        target.refSummary.fieldUsage = usages;
+    }
+    else {
+        target.refSummary = { fieldUsage: usages };
+    }
+}
 function isSegmentSQL(f) {
     return 'sql' in f;
 }
@@ -585,6 +645,43 @@ exports.TD = {
         return isTemporalType(typ);
     },
     isError: (td) => (td === null || td === void 0 ? void 0 : td.type) === 'error',
+    /**
+     * Strip non-type metadata (name, joins, expressionType, evalSpace, ...)
+     * off a typed def, leaving a clean AtomicTypeDef. Used when copying a
+     * field's type onto an Expr's typeDef, where the field metadata would
+     * pollute the IR. Returns `{type: 'error'}` for non-atomic inputs.
+     */
+    atomicDef(td) {
+        if (!exports.TD.isAtomic(td))
+            return { type: 'error' };
+        switch (td.type) {
+            case 'array':
+                return isRepeatedRecord(td)
+                    ? {
+                        type: 'array',
+                        elementTypeDef: td.elementTypeDef,
+                        fields: td.fields,
+                    }
+                    : { type: 'array', elementTypeDef: td.elementTypeDef };
+            case 'record':
+                return { type: 'record', fields: td.fields };
+            case 'number':
+                return td.numberType
+                    ? { type: 'number', numberType: td.numberType }
+                    : { type: 'number' };
+            case 'sql native':
+                return td.rawType
+                    ? { type: 'sql native', rawType: td.rawType }
+                    : { type: 'sql native' };
+            case 'timestamp':
+            case 'timestamptz':
+                return td.timeframe
+                    ? { type: td.type, timeframe: td.timeframe }
+                    : { type: td.type };
+            default:
+                return { type: td.type };
+        }
+    },
     eq(x, y) {
         if (x === undefined || y === undefined) {
             return false;

package/dist/model/query_model_contract.d.ts

@@ -1,7 +1,7 @@
 import type { Connection } from '../connection/types';
 import type { Dialect } from '../dialect';
 import type { EventStream } from '../runtime_types';
-import type { SourceDef, ModelDef, StructRef, Argument, PrepareResultOptions, CompiledQuery, SearchIndexResult, Query } from './malloy_types';
+import type { SourceDef, ModelDef, StructRef, Argument, Given, PrepareResultOptions, CompiledQuery, SearchIndexResult, Query } from './malloy_types';
 import type { QueryStruct } from './query_node';
 import type { StageWriter } from './stage_writer';
 export interface ParentQueryModel {
@@ -18,6 +18,7 @@ export interface QueryModel {
     dialect: Dialect;
     modelDef: ModelDef | undefined;
     structs: Map<string, QueryStruct>;
+    givens: Record<string, Given>;
     eventStream?: EventStream;
     loadModelFromDef(modelDef: ModelDef): void;
     getStructByName(name: string): QueryStruct;

package/dist/model/query_model_impl.d.ts

@@ -1,4 +1,4 @@
-import type { ModelDef, StructRef, Argument, PrepareResultOptions, Query, SourceDef, SearchIndexResult, CompiledQuery, TurtleDef } from './malloy_types';
+import type { ModelDef, StructRef, Argument, Given, PrepareResultOptions, Query, SourceDef, SearchIndexResult, CompiledQuery, TurtleDef } from './malloy_types';
 import { StageWriter } from './stage_writer';
 import { type Dialect } from '../dialect';
 import type { Connection } from '../connection/types';
@@ -10,6 +10,7 @@ export declare class QueryModelImpl implements QueryModel, ModelRootInterface {
     dialect: Dialect;
     modelDef: ModelDef | undefined;
     structs: Map<string, QueryStruct>;
+    get givens(): Record<string, Given>;
     constructor(modelDef: ModelDef | undefined);
     getFinalOutputStruct(query: Query, options: PrepareResultOptions | undefined): SourceDef | undefined;
     loadModelFromDef(modelDef: ModelDef): void;

package/dist/model/query_model_impl.js

@@ -18,6 +18,10 @@ function makeQueryModel(modelDef) {
     return new QueryModelImpl(modelDef);
 }
 class QueryModelImpl {
+    get givens() {
+        var _a, _b;
+        return (_b = (_a = this.modelDef) === null || _a === void 0 ? void 0 : _a.givens) !== null && _b !== void 0 ? _b : {};
+    }
     constructor(modelDef) {
         this.dialect = new dialect_1.StandardSQLDialect();
         // dialect: Dialect = new PostgresDialect();
@@ -49,6 +53,9 @@ class QueryModelImpl {
             else if (s.type === 'userType') {
                 // User type definitions are metadata only, not queryable
             }
+            else if (s.type === 'given') {
+                // Givens are metadata in the namespace, not queryable structures.
+            }
             else {
                 throw new Error('Internal Error: Unknown structure type');
             }

package/dist/model/query_node.d.ts

@@ -1,4 +1,4 @@
-import type { FieldDef, BooleanFieldDef, DateFieldDef, StringFieldDef, JSONFieldDef, NumberFieldDef, ATimestampFieldDef, NativeUnsupportedFieldDef, JoinFieldDef, Argument, PrepareResultOptions, AtomicFieldDef, BasicAtomicDef, FilterCondition, RefToField, StructDef, TurtleDef, TurtleDefPlusFilters, SourceDef, Query } from './malloy_types';
+import type { FieldDef, BooleanFieldDef, DateFieldDef, StringFieldDef, JSONFieldDef, NumberFieldDef, ATimestampFieldDef, NativeUnsupportedFieldDef, JoinFieldDef, Argument, Given, GivenID, PrepareResultOptions, AtomicFieldDef, BasicAtomicDef, FilterCondition, RefToField, StructDef, TurtleDef, TurtleDefPlusFilters, SourceDef, Query } from './malloy_types';
 import type { EventStream } from '../runtime_types';
 import type { Tag } from '@malloydata/malloy-tag';
 import type { Dialect } from '../dialect';
@@ -62,6 +62,7 @@ export interface ParentQueryStruct {
 }
 export interface ModelRootInterface {
     structs: Map<string, QueryStruct>;
+    givens: Record<GivenID, Given>;
 }
 export interface ParentQueryModel {
     model: ModelRootInterface;

package/dist/model/source_def_utils.d.ts

@@ -7,8 +7,9 @@
  *
  * The `extends` property is set by callers when processing extend blocks.
  */
-import type { BuildID, FieldDef, ModelDef, PersistableSourceDef, Query, QuerySourceDef, SourceDef, SourceID, SourceRegistryEntry, SourceRegistryValue, SQLPhraseSegment, SQLSourceDef, TableSourceDef } from './malloy_types';
+import type { BuildID, FieldDef, GivenID, ModelDef, PersistableSourceDef, Query, QuerySourceDef, SourceDef, SourceID, SourceRegistryEntry, SourceRegistryValue, SQLPhraseSegment, SQLSourceDef, TableSourceDef } from './malloy_types';
 export declare function mkSourceID(name: string, url: string | undefined): SourceID;
+export declare function mkGivenID(name: string, url: string | undefined): GivenID;
 /**
  * Create a BuildID from connection digest and SQL.
  * BuildID is a hash that uniquely identifies a build artifact.

package/dist/model/source_def_utils.js

@@ -5,6 +5,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mkSourceID = mkSourceID;
+exports.mkGivenID = mkGivenID;
 exports.mkBuildID = mkBuildID;
 exports.mkQuerySourceDef = mkQuerySourceDef;
 exports.mkSQLSourceDef = mkSQLSourceDef;
@@ -17,6 +18,9 @@ const malloy_types_1 = require("./malloy_types");
 function mkSourceID(name, url) {
     return `${name}@${url !== null && url !== void 0 ? url : 'unknown'}`;
 }
+function mkGivenID(name, url) {
+    return (0, utils_1.pathToKey)('given', [name, url !== null && url !== void 0 ? url : 'unknown']);
+}
 /**
  * Create a BuildID from connection digest and SQL.
  * BuildID is a hash that uniquely identifies a build artifact.

package/dist/model/utils.d.ts

@@ -1,5 +1,18 @@
-import type { Expr, GenericSQLExpr, ModelDef, StructDef } from './malloy_types';
+import type { AtomicTypeDef, Expr, FieldDef, GenericSQLExpr, GivenTypeDef, ModelDef, StructDef } from './malloy_types';
 import type { DialectFieldList } from '../dialect';
+/**
+ * Format a typeDef as user-readable Malloy type syntax. Used in error
+ * messages where we want to echo a compound type back to the user in the
+ * same form they wrote it.
+ *
+ *   `string`               → `string`
+ *   `string[]`             → `string[]`
+ *   `{a::string, b::number}` → `{a :: string, b :: number}`
+ *   `{a::string}[]`        → `{a :: string}[]`
+ *   `filter<string>`       → `filter<string>`
+ *   sql-native rawType     → `sql native: jsonb`
+ */
+export declare function typeDefToString(td: AtomicTypeDef | GivenTypeDef | FieldDef): string;
 /** simple indent function */
 export declare function indent(s: string): string;
 /**