@malloydata/malloy 0.0.391 → 0.0.393

package/dist/api/foundation/runtime.js

@@ -46,7 +46,8 @@ class FluentState {
  * An environment for compiling and running Malloy queries.
  */
 class Runtime {
-    constructor({ urlReader, connections, connection, config, buildManifest, eventStream, cacheManager, }) {
+    constructor({ urlReader, connections, connection, config, buildManifest, eventStream, cacheManager, givens, }) {
+        var _a, _b;
         this.isTestRuntime = false;
         if (config !== undefined) {
             this._config = config;
@@ -68,6 +69,19 @@ class Runtime {
         this._buildManifest = buildManifest;
         this._eventStream = eventStream;
         this._cacheManager = cacheManager;
+        if (givens) {
+            for (const [name, value] of Object.entries(givens)) {
+                if (value === undefined) {
+                    throw new Error(`Runtime givens.${name}: explicit undefined is not a valid value. ` +
+                        'Omit the key to defer to declaration default or the file layer; ' +
+                        'use null for an explicit null value.');
+                }
+            }
+        }
+        this._constructorGivensMap = givens
+            ? new Map(Object.entries(givens))
+            : new Map();
+        this._finalizedGivensSet = new Set((_b = (_a = this._config) === null || _a === void 0 ? void 0 : _a.finalizeGivens) !== null && _b !== void 0 ? _b : []);
     }
     /**
      * @return The `CacheManager` for this runtime instance.
@@ -93,6 +107,49 @@ class Runtime {
     get eventStream() {
         return this._eventStream;
     }
+    /**
+     * Constructor-supplied givens, exposed for the materializer's per-query
+     * merge. Underscore-prefixed because it's the constructor layer only —
+     * use `getGivens()` for the full file+constructor view a caller usually
+     * wants.
+     *
+     * @internal Accessed from QueryMaterializer.
+     */
+    get _constructorGivens() {
+        return this._constructorGivensMap;
+    }
+    /**
+     * The runtime's effective givens — file (from `config.givensPath`,
+     * lazily loaded) merged with the constructor `givens:` option, with
+     * the constructor winning per-key. Per-query supply via
+     * `.run({ givens: ... })` is *not* included; that's a per-call
+     * argument, not runtime state.
+     *
+     * Async because the file may not yet be loaded; subsequent calls share
+     * the cached promise.
+     */
+    async getGivens() {
+        const file = await this._resolveGivens();
+        const merged = new Map();
+        if (file) {
+            for (const [k, v] of Object.entries(file))
+                merged.set(k, v);
+        }
+        for (const [k, v] of this._constructorGivensMap)
+            merged.set(k, v);
+        return merged;
+    }
+    /**
+     * Surface names of givens locked at the runtime layer (the resolved set
+     * the `config.finalizeGivens` directive produced). Per-query supply for
+     * these names throws; `Model.givens` and `PreparedQuery.givens` filter
+     * them out so introspection-driven UIs don't render editors for them.
+     *
+     * @internal Accessed from QueryMaterializer and Model construction.
+     */
+    get _finalizedGivens() {
+        return this._finalizedGivensSet;
+    }
     /**
      * Setter — install an explicit build manifest for persist source
      * substitution. From this point on, compiled queries resolve persist
@@ -142,14 +199,14 @@ class Runtime {
         if (this._buildManifest) {
             return Promise.resolve(this._buildManifest);
         }
-        const url = (_a = this._config) === null || _a === void 0 ? void 0 : _a.manifestURL;
-        if (!url)
+        const urlStr = (_a = this._config) === null || _a === void 0 ? void 0 : _a.manifestURL;
+        if (!urlStr)
             return Promise.resolve(undefined);
         if (!this._resolvedBuildManifestPromise) {
             this._resolvedBuildManifestPromise = (async () => {
                 let text;
                 try {
-                    const result = await this._urlReader.readURL(url);
+                    const result = await this._urlReader.readURL(new URL(urlStr));
                     text = typeof result === 'string' ? result : result.contents;
                 }
                 catch {
@@ -173,13 +230,68 @@ class Runtime {
                     const msg = e instanceof Error ? e.message : String(e);
                     return {
                         entries: {},
-                        loadError: `Manifest file at ${url.toString()} could not be parsed: ${msg}`,
+                        loadError: `Manifest file at ${urlStr} could not be parsed: ${msg}`,
                     };
                 }
             })();
         }
         return this._resolvedBuildManifestPromise;
     }
+    /**
+     * Resolve the per-runtime givens map from `config.givensURL` (the file
+     * `givensPath` points at). Lazy and cached as a Promise — first compile
+     * triggers the read, subsequent compiles share the result.
+     *
+     * Stricter error policy than `_resolveBuildManifest`: a missing file or
+     * malformed JSON throws. Per design, the per-runtime givens layer is a
+     * configured contract, not an opportunistic read; a misconfigured path
+     * should fail loudly at the first compile, not silently degrade.
+     *
+     * Returns `undefined` only when no `givensURL` is configured.
+     *
+     * @internal Accessed from QueryMaterializer.
+     */
+    _resolveGivens() {
+        var _a;
+        const urlStr = (_a = this._config) === null || _a === void 0 ? void 0 : _a.givensURL;
+        if (!urlStr)
+            return Promise.resolve(undefined);
+        if (!this._resolvedGivensPromise) {
+            this._resolvedGivensPromise = (async () => {
+                let text;
+                try {
+                    const result = await this._urlReader.readURL(new URL(urlStr));
+                    text = typeof result === 'string' ? result : result.contents;
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    throw new Error(`givens: failed to read givens file at ${urlStr}: ${msg}`);
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    throw new Error(`givens: failed to parse JSON at ${urlStr}: ${msg}`);
+                }
+                if (!isGivensObject(parsed)) {
+                    const got = Array.isArray(parsed)
+                        ? 'array'
+                        : parsed === null
+                            ? 'null'
+                            : typeof parsed;
+                    throw new Error(`givens: file at ${urlStr} must be a JSON object of name → value pairs, got ${got}`);
+                }
+                return parsed;
+            })();
+        }
+        return this._resolvedGivensPromise;
+    }
+    /** @internal */
+    _invalidateGivensCache() {
+        this._resolvedGivensPromise = undefined;
+    }
     /**
      * The virtual map for virtual source resolution.
      * When set, compiled queries automatically resolve virtual sources
@@ -244,7 +356,7 @@ class Runtime {
         }
         const compilable = source instanceof URL ? { url: source } : { source };
         return new ModelMaterializer(this, async () => {
-            return compile_1.Malloy.compile({
+            const m = await compile_1.Malloy.compile({
                 ...compilable,
                 urlReader: this.urlReader,
                 connections: this.connections,
@@ -255,15 +367,34 @@ class Runtime {
                 testEnvironment: options === null || options === void 0 ? void 0 : options.testEnvironment,
                 cacheManager: this.cacheManager,
             });
+            return this._withRuntimeContext(m);
         }, options);
     }
+    /**
+     * Re-wrap a `Model` produced by `Malloy.compile` with this runtime's
+     * `RuntimeContext` so context-sensitive Model methods (currently
+     * `Model.givens` filtering finalized names; future runtime-aware
+     * concerns) work correctly. No-op when there's nothing in the context.
+     *
+     * @internal Accessed from `ModelMaterializer.extendModel` and Runtime
+     * loadModel paths.
+     */
+    _withRuntimeContext(m) {
+        if (this._finalizedGivensSet.size === 0)
+            return m;
+        return new core_1.Model(m._modelDef, m.problems, m.fromSources, m.getExistingQueryModel(), {
+            finalizedGivens: this._finalizedGivensSet,
+        });
+    }
     // TODO Consider formalizing this. Perhaps as a `withModel` method,
     //      as well as a `Model.fromModelDefinition` if we choose to expose
     //      `ModelDef` to the world formally. For now, this should only
     //      be used in tests.
     _loadModelFromModelDef(modelDef, options) {
         return new ModelMaterializer(this, async () => {
-            return new core_1.Model(modelDef, [], []);
+            return new core_1.Model(modelDef, [], [], undefined, this._finalizedGivensSet.size > 0
+                ? { finalizedGivens: this._finalizedGivensSet }
+                : undefined);
         }, options);
     }
     /**
@@ -507,7 +638,7 @@ class ModelMaterializer extends FluentState {
                 testEnvironment: options === null || options === void 0 ? void 0 : options.testEnvironment,
                 ...this.compileQueryOptions,
             });
-            return queryModel;
+            return this.runtime._withRuntimeContext(queryModel);
         }, options);
     }
     async search(sourceName, searchTerm, limit = 1000, searchField = undefined) {
@@ -691,7 +822,7 @@ class QueryMaterializer extends FluentState {
      */
     loadPreparedResult(options) {
         return this.makePreparedResultMaterializer(async () => {
-            var _a, _b;
+            var _a, _b, _c;
             const preparedQuery = await this.materialize();
             const mergedOptions = {
                 eventStream: this.eventStream,
@@ -735,7 +866,58 @@ class QueryMaterializer extends FluentState {
             }
             // Use virtualMap from options if provided, otherwise fall back to Runtime's.
             const virtualMap = (_b = mergedOptions.virtualMap) !== null && _b !== void 0 ? _b : this.runtime.virtualMap;
-            // Build PrepareResultOptions from CompileQueryOptions + connectionDigests
+            // Per-query supply for a finalized given is rejected at API entry
+            // — the finalized-givens set is the runtime's "this can't be
+            // overridden by the caller" guarantee. Fail before any IO so misuse
+            // is loud.
+            const finalizedSet = this.runtime._finalizedGivens;
+            if (finalizedSet.size > 0 && mergedOptions.givens) {
+                for (const name of Object.keys(mergedOptions.givens)) {
+                    if (finalizedSet.has(name)) {
+                        throw new Error(`Cannot supply '${name}' per-query: it is finalized at the runtime layer (config.finalizeGivens).`);
+                    }
+                }
+            }
+            // Three layers of givens, merged per-key in precedence order:
+            //   1. config.givensURL file (lazy + cached)
+            //   2. Runtime constructor `givens:` option
+            //   3. Per-query supply via `.run({givens: ...})`
+            // Higher-numbered layers win on collision. Each layer is optional;
+            // the merge collapses to undefined when all three are absent.
+            const fileGivens = await this.runtime._resolveGivens();
+            const constructorGivens = mapToRecord(this.runtime._constructorGivens);
+            const haveAny = fileGivens || constructorGivens || mergedOptions.givens;
+            const mergedGivens = haveAny
+                ? { ...fileGivens, ...constructorGivens, ...mergedOptions.givens }
+                : undefined;
+            // Query-scoped validation: of the givens THIS query references,
+            // any that are finalized must have a value somewhere (file or
+            // constructor). One config covers a project; individual files
+            // declare overlapping but distinct given sets; an unrelated query
+            // shouldn't fail because some other file's given is in the
+            // finalize list without a value. The per-query rejection above is
+            // the actual security primitive; this check is the sanity net for
+            // "you locked it but forgot to supply it."
+            const queryGivenUsage = (_c = preparedQuery._query.givenUsage) !== null && _c !== void 0 ? _c : [];
+            if (finalizedSet.size > 0 && queryGivenUsage.length > 0) {
+                const referencedIds = new Set(queryGivenUsage.map(g => g.id));
+                const missing = [];
+                for (const [surfaceName, entry] of Object.entries(preparedQuery._modelDef.contents)) {
+                    if (entry.type !== 'given')
+                        continue;
+                    if (!referencedIds.has(entry.id))
+                        continue;
+                    if (!finalizedSet.has(surfaceName))
+                        continue;
+                    if (mergedGivens && surfaceName in mergedGivens)
+                        continue;
+                    missing.push(surfaceName);
+                }
+                if (missing.length > 0) {
+                    throw new Error(`Query references finalized given(s) with no resolved value: ${missing.join(', ')}. Each finalized given the query needs must have a value in givensPath or in the Runtime constructor's \`givens\`.`);
+                }
+            }
+            // Build PrepareResultOptions from CompileQueryOptions + connectionDigests.
             const prepareResultOptions = {
                 defaultRowLimit: mergedOptions.defaultRowLimit,
                 buildManifest,
@@ -745,6 +927,7 @@ class QueryMaterializer extends FluentState {
             return preparedQuery.getPreparedResult({
                 ...mergedOptions,
                 ...prepareResultOptions,
+                givens: mergedGivens,
             });
         });
     }
@@ -901,4 +1084,23 @@ function isBuildManifestShape(value) {
     const entries = value.entries;
     return typeof entries === 'object' && entries !== null;
 }
+/**
+ * Shallow shape-check for the givens-values file: must be a non-array
+ * non-null object. Per-value type checking happens later when each
+ * declared given is bound via `resolveSuppliedGivens` — at this layer we
+ * only ensure the top-level shape is a name → value map.
+ */
+function isGivensObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Convert a non-empty `ReadonlyMap` into a plain object for spread-merging
+ * with other given layers. Returns `undefined` for an empty map so the
+ * merge can short-circuit when all layers are absent.
+ */
+function mapToRecord(m) {
+    if (m.size === 0)
+        return undefined;
+    return Object.fromEntries(m);
+}
 //# sourceMappingURL=runtime.js.map

package/dist/api/foundation/types.d.ts

@@ -1,5 +1,5 @@
 import type { EventStream } from '../../runtime_types';
-import type { BuildManifest, VirtualMap } from '../../model';
+import type { BuildManifest, GivenValue, VirtualMap } from '../../model';
 /**
  * An empty BuildManifest with no entries and strict mode off.
  * Use this to explicitly suppress manifest substitution in a query:
@@ -35,6 +35,7 @@ export interface CompileQueryOptions {
     connectionDigests?: Record<string, string>;
     /** Map from connectionName → virtualName → tablePath for virtual source resolution */
     virtualMap?: VirtualMap;
+    givens?: Record<string, GivenValue>;
 }
 /**
  * A node in the build graph (recursive DAG structure).

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 export { DuckDBDialect, StandardSQLDialect, TrinoDialect, PostgresDialect, SnowflakeDialect, MySQLDialect, DatabricksDialect, registerDialect, arg, qtz, overload, minScalar, anyExprType, minAggregate, maxScalar, sql, makeParam, param, variadicParam, literal, spread, Dialect, } from './dialect';
 export type { DialectFieldList, DialectFunctionOverloadDef, QueryInfo, MalloyStandardFunctionImplementations, DefinitionBlueprint, DefinitionBlueprintMap, OverloadedDefinitionBlueprint, } from './dialect';
-export type { QueryRecord, StructDef, TableSourceDef, SQLSourceDef, SourceDef, JoinFieldDef, NamedSourceDefs, MalloyQueryData, DateUnit, ExtractUnit, TimestampUnit, TemporalFieldType, QueryData, QueryValue, Expr, FilterCondition, Argument, Parameter, FieldDef, PipeSegment, QueryFieldDef, IndexFieldDef, TurtleDef, SearchValueMapResult, SearchIndexResult, ModelDef, Query, QueryResult, QueryResultDef, QueryRunStats, QueryScalar, NamedQueryDef, NamedModelObject, ExpressionType, FunctionDef, FunctionOverloadDef, FunctionParameterDef, ExpressionValueType, TypeDesc, FunctionParamTypeDesc, DocumentLocation, DocumentRange, DocumentPosition, Sampling, Annotation, BasicAtomicTypeDef, BasicAtomicDef, AtomicTypeDef, AtomicFieldDef, ArrayDef, ArrayTypeDef, RecordTypeDef, RepeatedRecordTypeDef, RecordDef, RepeatedRecordDef, RecordLiteralNode, StringLiteralNode, ArrayLiteralNode, SourceComponentInfo, DateLiteralNode, TimestampLiteralNode, TimestamptzLiteralNode, TimeLiteralExpr, TypecastExpr, BuildID, BuildManifest, BuildManifestEntry, VirtualMap, } from './model';
+export type { QueryRecord, StructDef, TableSourceDef, SQLSourceDef, SourceDef, JoinFieldDef, NamedSourceDefs, MalloyQueryData, DateUnit, ExtractUnit, TimestampUnit, TemporalFieldType, QueryData, QueryValue, Expr, FilterCondition, Argument, Parameter, FieldDef, PipeSegment, QueryFieldDef, IndexFieldDef, TurtleDef, SearchValueMapResult, SearchIndexResult, ModelDef, Query, QueryResult, QueryResultDef, QueryRunStats, QueryScalar, NamedQueryDef, NamedModelObject, ExpressionType, FunctionDef, FunctionOverloadDef, FunctionParameterDef, ExpressionValueType, TypeDesc, FunctionParamTypeDesc, DocumentLocation, DocumentRange, DocumentPosition, Sampling, Annotation, BasicAtomicTypeDef, BasicAtomicDef, AtomicTypeDef, AtomicFieldDef, ArrayDef, ArrayTypeDef, RecordTypeDef, RepeatedRecordTypeDef, RecordDef, RepeatedRecordDef, RecordLiteralNode, StringLiteralNode, ArrayLiteralNode, SourceComponentInfo, DateLiteralNode, TimestampLiteralNode, TimestamptzLiteralNode, TimeLiteralExpr, TypecastExpr, BuildID, BuildManifest, BuildManifestEntry, GivenValue, VirtualMap, } from './model';
 export { isSourceDef, isAtomic, isBasicAtomic, isCompoundArrayData, isJoined, isJoinedSource, isSamplingEnable, isSamplingPercent, isSamplingRows, isRepeatedRecord, isBasicArray, mkArrayDef, mkFieldDef, expressionIsAggregate, expressionIsAnalytic, expressionIsCalculation, expressionIsScalar, expressionIsUngroupedAggregate, indent, composeSQLExpr, isTimestampUnit, isDateUnit, constantExprToSQL, } from './model';
 export { malloyToQuery, MalloyTranslator, } from './lang';
 export type { LogMessage, TranslateResponse } from './lang';
 export { Model, Malloy, Runtime, AtomicFieldType, ConnectionRuntime, SingleConnectionRuntime, EmptyURLReader, InMemoryURLReader, FixedConnectionMap, MalloyError, JoinRelationship, SourceRelationship, DateTimeframe, TimestampTimeframe, PreparedResult, Result, QueryMaterializer, CSVWriter, JSONWriter, Parse, DataWriter, Explore, InMemoryModelCache, CacheManager, Manifest, MalloyConfig, envOverlay, contextOverlay, defaultConfigOverlays, discoverConfig, } from './api/foundation';
 export type { PreparedQuery, Field, AtomicField, ExploreField, QueryField, SortableField, DataArray, DataRecord, DataColumn, DataArrayOrRecord, Loggable, ModelMaterializer, DocumentTablePath, DocumentSymbol, ResultJSON, PreparedResultJSON, PreparedResultMaterializer, ExploreMaterializer, WriteStream, SerializedExplore, ModelCache, CachedModel, DateField, TimestampField, } from './api/foundation';
 export type { Overlay, ConfigOverlays } from './api/foundation';
+export type { FilesystemContext, MalloyConfigOptions } from './api/foundation';
+export type { RuntimeContext } from './api/foundation';
 export type { QueryOptionsReader, RunSQLOptions } from './run_sql_options';
 export type { EventStream, ModelString, ModelURL, QueryString, QueryURL, URLReader, InvalidationKey, } from './runtime_types';
 export type { Connection, ConnectionConfig, ConnectionParameterValue, FetchSchemaOptions, InfoConnection, LookupConnection, PersistSQLResults, PooledConnection, TestableConnection, StreamingConnection, } from './connection/types';

package/dist/lang/ast/ast-utils.js

@@ -37,7 +37,6 @@ function errorFor(reason) {
         expressionType: 'scalar',
         value: { node: 'error', message: reason },
         evalSpace: 'constant',
-        fieldUsage: [],
     };
 }
 //# sourceMappingURL=ast-utils.js.map

package/dist/lang/ast/expressions/expr-aggregate-function.d.ts

@@ -10,7 +10,7 @@ export declare abstract class ExprAggregateFunction extends ExpressionDef {
     source?: FieldReference;
     expr?: ExpressionDef;
     explicitSource?: boolean;
-    legalChildTypes: import("../../../model/malloy_types").TypeDesc[];
+    legalChildTypes: import("../../..").TypeDesc[];
     constructor(func: AggregateFunctionType, expr?: ExpressionDef, explicitSource?: boolean);
     abstract returns(fromExpr: ExprValue): ExprValue;
     getExpression(fs: FieldSpace): ExprValue;

package/dist/lang/ast/expressions/expr-aggregate-function.js

@@ -106,7 +106,11 @@ class ExprAggregateFunction extends expression_def_1.ExpressionDef {
                                     at: this.source.location,
                                 },
                             evalSpace: footType.evalSpace,
-                            fieldUsage: [{ path: this.source.path, at: this.source.location }],
+                            refSummary: {
+                                fieldUsage: [
+                                    { path: this.source.path, at: this.source.location },
+                                ],
+                            },
                         };
                         structPath = this.source.path.slice(0, -1);
                         // Here we handle a special case where you write `foo.agg()` and `foo` is a
@@ -178,13 +182,10 @@ class ExprAggregateFunction extends expression_def_1.ExpressionDef {
             }
             const returnExpr = this.returns(exprVal);
             if (!this.isSymmetricFunction()) {
-                if (returnExpr.fieldUsage === undefined) {
-                    returnExpr.fieldUsage = [];
-                }
-                returnExpr.fieldUsage.push({
-                    path: structPath || [],
-                    uniqueKeyRequirement: { isCount: false },
-                });
+                (0, malloy_types_1.setFieldUsage)(returnExpr, [
+                    ...(0, malloy_types_1.fieldUsageFrom)(returnExpr.refSummary),
+                    { path: structPath || [], uniqueKeyRequirement: { isCount: false } },
+                ]);
             }
             return {
                 ...returnExpr,

package/dist/lang/ast/expressions/expr-coalesce.d.ts

@@ -5,7 +5,7 @@ export declare class ExprCoalesce extends ExpressionDef {
     readonly expr: ExpressionDef;
     readonly altExpr: ExpressionDef;
     elementType: string;
-    legalChildTypes: import("../../../model").TypeDesc[];
+    legalChildTypes: import("../../..").TypeDesc[];
     constructor(expr: ExpressionDef, altExpr: ExpressionDef);
     getExpression(fs: FieldSpace): ExprValue;
 }

package/dist/lang/ast/expressions/expr-coalesce.js

@@ -57,9 +57,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExprCoalesce = void 0;
 const model_1 = require("../../../model");
+const composite_source_utils_1 = require("../../composite-source-utils");
 const TDU = __importStar(require("../typedesc-utils"));
 const expression_def_1 = require("../types/expression-def");
-const composite_source_utils_1 = require("../../composite-source-utils");
 class ExprCoalesce extends expression_def_1.ExpressionDef {
     constructor(expr, altExpr) {
         super({ expr, altExpr });
@@ -69,7 +69,6 @@ class ExprCoalesce extends expression_def_1.ExpressionDef {
         this.legalChildTypes = TDU.anyAtomicT;
     }
     getExpression(fs) {
-        var _a;
         const maybeNull = this.expr.getExpression(fs);
         const whenNull = this.altExpr.getExpression(fs);
         if (maybeNull.type === 'null') {
@@ -101,7 +100,7 @@ class ExprCoalesce extends expression_def_1.ExpressionDef {
                 kids: { left: maybeNull.value, right: whenNull.value },
             },
             evalSpace: (0, model_1.mergeEvalSpaces)(maybeNull.evalSpace, whenNull.evalSpace),
-            fieldUsage: (_a = (0, composite_source_utils_1.mergeFieldUsage)(maybeNull.fieldUsage, whenNull.fieldUsage)) !== null && _a !== void 0 ? _a : [],
+            refSummary: (0, composite_source_utils_1.mergeRefSummaries)(maybeNull.refSummary, whenNull.refSummary),
         };
     }
 }

package/dist/lang/ast/expressions/expr-count-distinct.js

@@ -76,7 +76,7 @@ class ExprCountDistinct extends expr_aggregate_function_1.ExprAggregateFunction
             evalSpace: ev.evalSpace,
             expressionType: 'aggregate',
             value: ev.value,
-            fieldUsage: ev.fieldUsage,
+            refSummary: ev.refSummary,
         };
     }
 }

package/dist/lang/ast/expressions/expr-count.js

@@ -44,7 +44,7 @@ class ExprCount extends expr_aggregate_function_1.ExprAggregateFunction {
             evalSpace: ev.evalSpace,
             expressionType: 'aggregate',
             value: ev.value,
-            fieldUsage: ev.fieldUsage,
+            refSummary: ev.refSummary,
         };
     }
     getExpression(_fs) {
@@ -63,9 +63,11 @@ class ExprCount extends expr_aggregate_function_1.ExprAggregateFunction {
             expressionType: 'aggregate',
             value: ret,
             evalSpace: 'output',
-            fieldUsage: [
-                { path: ret.structPath || [], uniqueKeyRequirement: { isCount: true } },
-            ],
+            refSummary: {
+                fieldUsage: [
+                    { path: ret.structPath || [], uniqueKeyRequirement: { isCount: true } },
+                ],
+            },
         };
     }
 }

package/dist/lang/ast/expressions/expr-filter-expr.js

@@ -20,7 +20,6 @@ class ExprFilterExpression extends expression_def_1.ExpressionDef {
             value: { node: 'filterLiteral', filterSrc: this.filterText },
             expressionType: 'scalar',
             evalSpace: 'constant',
-            fieldUsage: [],
         };
     }
 }

package/dist/lang/ast/expressions/expr-func.js

@@ -154,7 +154,9 @@ class ExprFunc extends expression_def_1.ExpressionDef {
                             at: this.source.location,
                         },
                         evalSpace: footType.evalSpace,
-                        fieldUsage: [{ path: this.source.path, at: this.source.location }],
+                        refSummary: {
+                            fieldUsage: [{ path: this.source.path, at: this.source.location }],
+                        },
                     };
                     structPath = this.source.path.slice(0, -1);
                 }
@@ -357,14 +359,17 @@ class ExprFunc extends expression_def_1.ExpressionDef {
                 : 'output';
         const aggregateFunctionUsage = [];
         if (isAsymmetric || isAnalytic) {
-            const funcUsage = { path: structPath || [], at: this.location };
+            const funcUsage = {
+                path: structPath || [],
+                at: this.location,
+            };
             if (isAsymmetric)
                 funcUsage.uniqueKeyRequirement = { isCount: false };
             if (isAnalytic)
                 funcUsage.analyticFunctionUse = true;
             aggregateFunctionUsage.push(funcUsage);
         }
-        const fieldUsage = (0, composite_source_utils_1.mergeFieldUsage)(...argExprs.map(ae => ae.fieldUsage), orderByUsage, sqlFunctionFieldUsage, aggregateFunctionUsage);
+        const refSummary = (0, composite_source_utils_1.mergeRefSummaries)(...argExprs.map(ae => ae.refSummary), (0, malloy_types_1.mkRefSummary)({ fieldUsage: orderByUsage }), (0, malloy_types_1.mkRefSummary)({ fieldUsage: sqlFunctionFieldUsage }), (0, malloy_types_1.mkRefSummary)({ fieldUsage: aggregateFunctionUsage }));
         const ungroupings = argExprs.reduce((ug, a) => { var _a; return (_a = a.ungroupings) !== null && _a !== void 0 ? _a : ug; }, []);
         // TODO consider if I can use `computedExprValue` here...
         // seems like the rules for the evalSpace is a bit different from normal though
@@ -374,7 +379,7 @@ class ExprFunc extends expression_def_1.ExpressionDef {
             expressionType,
             value: funcCall,
             evalSpace,
-            fieldUsage,
+            refSummary,
             ungroupings,
         };
     }

package/dist/lang/ast/expressions/expr-given.d.ts

@@ -0,0 +1,18 @@
+import { ExpressionDef } from '../types/expression-def';
+import type { ExprValue } from '../types/expr-value';
+import type { FieldSpace } from '../types/field-space';
+/**
+ * Reference to a given inside an expression: `$NAME`.
+ *
+ * Resolution bypasses `fs.lookup` (which is source-scoped) and goes
+ * straight to the document's given namespace — that lets `$NAME` work
+ * even inside a `ConstantFieldSpace`, which is how default values
+ * (`given: B :: number is $A + 1`) refuse field references but accept
+ * other givens.
+ */
+export declare class GivenReference extends ExpressionDef {
+    readonly name: string;
+    elementType: string;
+    constructor(name: string);
+    getExpression(_fs: FieldSpace): ExprValue;
+}

package/dist/lang/ast/expressions/expr-given.js

@@ -0,0 +1,69 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GivenReference = void 0;
+const utils_1 = require("../../../model/utils");
+const expression_def_1 = require("../types/expression-def");
+const expr_value_1 = require("../types/expr-value");
+/**
+ * Reference to a given inside an expression: `$NAME`.
+ *
+ * Resolution bypasses `fs.lookup` (which is source-scoped) and goes
+ * straight to the document's given namespace — that lets `$NAME` work
+ * even inside a `ConstantFieldSpace`, which is how default values
+ * (`given: B :: number is $A + 1`) refuse field references but accept
+ * other givens.
+ */
+class GivenReference extends expression_def_1.ExpressionDef {
+    constructor(name) {
+        super();
+        this.name = name;
+        this.elementType = 'givenReference';
+    }
+    getExpression(_fs) {
+        var _a;
+        const doc = this.document();
+        const entry = (_a = doc === null || doc === void 0 ? void 0 : doc.getEntry(this.name)) === null || _a === void 0 ? void 0 : _a.entry;
+        if (entry === undefined) {
+            return this.loggedErrorExpr('given-not-found', `\`$${this.name}\` references a given named \`${this.name}\`, which is not declared in this model`);
+        }
+        if (entry.type !== 'given') {
+            return this.loggedErrorExpr('given-not-found', `\`$${this.name}\` expects a given named \`${this.name}\`, but \`${this.name}\` is a ${entry.type}`);
+        }
+        const given = doc === null || doc === void 0 ? void 0 : doc.documentGivens.get(entry.id);
+        if (given === undefined) {
+            return this.loggedErrorExpr('given-not-found', `Internal error: given \`${this.name}\` is in the namespace but has no declaration. Likely a compiler bug.`);
+        }
+        // Use-site reference. `location` covers `$NAME` at the use site;
+        // `definition.location` points at the canonical `given:`
+        // declaration (in the same file or in an imported file).
+        this.addReference({
+            type: 'givenReference',
+            text: this.name,
+            location: this.location,
+            definition: {
+                type: (0, utils_1.typeDefToString)(given.type),
+                annotation: given.annotation,
+                location: given.location,
+                defaultText: given.defaultText,
+            },
+        });
+        const refNode = {
+            node: 'given',
+            id: entry.id,
+            refName: this.name,
+        };
+        return {
+            ...(0, expr_value_1.literalExprValue)({ value: refNode, dataType: given.type }),
+            refSummary: {
+                fieldUsage: [],
+                givenUsage: [{ id: entry.id, at: this.location }],
+            },
+        };
+    }
+}
+exports.GivenReference = GivenReference;
+//# sourceMappingURL=expr-given.js.map

package/dist/lang/ast/expressions/expr-granular-time.d.ts

@@ -16,7 +16,7 @@ export declare class ExprGranularTime extends ExpressionDef {
     readonly units: TimestampUnit;
     readonly truncate: boolean;
     elementType: string;
-    legalChildTypes: import("../../../model/malloy_types").TypeDesc[];
+    legalChildTypes: import("../../..").TypeDesc[];
     constructor(expr: ExpressionDef, units: TimestampUnit, truncate: boolean);
     granular(): boolean;
     drillExpression(): Malloy.Expression | undefined;

package/dist/lang/ast/expressions/expr-id-reference.js

@@ -57,13 +57,14 @@ class ExprIdReference extends expression_def_1.ExpressionDef {
                 ]
                 : [];
             const td = def.found.typeDesc();
+            const refSummary = (0, malloy_types_1.mkRefSummary)({ fieldUsage: fieldUsage });
             if (def.isOutputField) {
                 return {
                     ...td,
                     // TODO what about literal??
                     evalSpace: td.evalSpace === 'constant' ? 'constant' : 'output',
                     value: { node: 'outputField', name: this.refString },
-                    fieldUsage,
+                    refSummary,
                 };
             }
             const value = {
@@ -79,7 +80,7 @@ class ExprIdReference extends expression_def_1.ExpressionDef {
                 ...td,
                 value,
                 evalSpace,
-                fieldUsage,
+                refSummary,
                 requiresGroupBy: undefined,
             };
         }