@malloydata/malloy 0.0.390 → 0.0.392

package/dist/lang/ast/types/space-field.js

@@ -36,25 +36,23 @@ class SpaceField extends space_entry_1.SpaceEntry {
             ...def,
             expressionType,
             evalSpace: 'input',
-            fieldUsage: 
-            // Use the composite field usage in the def if it exists, otherwise, if the
-            // field has an e whic is a composite field, then the composite field usage
-            // should be just the name of the field.
-            (_a = def.fieldUsage) !== null && _a !== void 0 ? _a : (((_b = def.e) === null || _b === void 0 ? void 0 : _b.node) === 'compositeField'
-                ? [{ path: [def.name], at: def.location }]
-                : []),
+            // Use the composite field usage in the def if it exists, otherwise, if
+            // the field has an e which is a composite field, then the composite
+            // field usage should be just the name of the field.
+            refSummary: (_a = def.refSummary) !== null && _a !== void 0 ? _a : (((_b = def.e) === null || _b === void 0 ? void 0 : _b.node) === 'compositeField'
+                ? { fieldUsage: [{ path: [def.name], at: def.location }] }
+                : undefined),
         };
         return ref;
     }
     turtleTypeFromTurtleDef(def) {
-        var _a;
         const turtleTypeDef = {
             type: 'turtle',
             pipeline: def.pipeline,
         };
         return {
             ...turtleTypeDef,
-            fieldUsage: (_a = def.fieldUsage) !== null && _a !== void 0 ? _a : [],
+            refSummary: def.refSummary,
             // TODO these are sorta weird for a turtle...
             expressionType: 'scalar',
             evalSpace: 'constant',

package/dist/lang/ast/view-elements/reference-view.js

@@ -83,9 +83,11 @@ class ReferenceView extends view_1.View {
             const newSegment = {
                 type: 'reduce',
                 queryFields: [this.reference.refToField],
-                fieldUsage: (0, composite_source_utils_1.mergeFieldUsage)(fieldDef.fieldUsage, [
-                    { path: this.reference.refToField.path, at: this.reference.location },
-                ]),
+                refSummary: (0, composite_source_utils_1.mergeRefSummaries)(fieldDef.refSummary, {
+                    fieldUsage: [
+                        { path: this.reference.refToField.path, at: this.reference.location },
+                    ],
+                }),
                 outputStruct,
                 // An atomic lens results in a array segment if it is a scalar
                 isRepeated: (0, malloy_types_1.expressionIsScalar)(fieldDef.expressionType),
@@ -136,7 +138,6 @@ class ReferenceView extends view_1.View {
         }
     }
     getRefinement(inputFS) {
-        var _a;
         const { pipeline, error } = this._pipelineComp(inputFS, {
             forRefinement: true,
         });
@@ -151,7 +152,7 @@ class ReferenceView extends view_1.View {
             return segment;
         return {
             ...segment,
-            fieldUsage: (_a = segment.fieldUsage) === null || _a === void 0 ? void 0 : _a.map(u => ({
+            refSummary: (0, malloy_types_1.mapFieldUsage)(segment.refSummary, u => ({
                 ...u,
                 at: this.reference.location,
             })),

package/dist/lang/ast/view-elements/refine-utils.js

@@ -102,7 +102,7 @@ function refine(logTo, refineTo, refineFrom) {
             if (missingOut.length > 0) {
                 logTo.logError('name-conflict-in-refinement', `missing output fields in refinement: ${missingOut.join(', ')}`);
             }
-            to.fieldUsage = (0, composite_source_utils_1.mergeFieldUsage)(to.fieldUsage, from.fieldUsage);
+            to.refSummary = (0, composite_source_utils_1.mergeRefSummaries)(to.refSummary, from.refSummary);
         }
         else if (from.type === 'index' && to.type === 'index') {
             to.indexFields = [...from.indexFields, ...to.indexFields];

package/dist/lang/composite-source-utils.d.ts

@@ -1,9 +1,9 @@
 import type { MalloyElement } from './ast';
-import type { FieldUsage, PipeSegment, SourceDef, RequiredGroupBy, Annotation, PartitionCompositeDesc, StructDef } from '../model/malloy_types';
+import type { FieldUsage, FieldUsageEntry, GivenUsage, PipeSegment, RefSummary, SourceDef, RequiredGroupBy, Annotation, PartitionCompositeDesc, StructDef } from '../model/malloy_types';
 type CompositeCouldNotFindFieldError = {
     code: 'could_not_find_field';
     data: {
-        field: FieldUsage;
+        field: FieldUsageEntry;
     };
 };
 type CompositeError = {
@@ -31,17 +31,17 @@ type CompositeError = {
     data: {
         failures: CompositeFailure[];
         path: string[];
-        usage: FieldUsage[];
+        usage: FieldUsage;
     };
 };
 type CompositeIssue = {
     type: 'join-failed';
     failures: CompositeFailure[];
     path: string[];
-    firstUsage: FieldUsage;
+    firstUsage: FieldUsageEntry;
 } | {
     type: 'missing-field';
-    field: FieldUsage;
+    field: FieldUsageEntry;
 } | {
     type: 'missing-required-group-by';
     requiredGroupBy: RequiredGroupBy;
@@ -70,18 +70,33 @@ export declare function resolveCompositeSources(source: SourceDef, segment: Pipe
     error: CompositeError;
     sourceDef: undefined;
 };
-export declare function fieldUsagePaths(fieldUsage: FieldUsage[]): string[][];
-export declare function formatFieldUsages(fieldUsage: FieldUsage[]): string;
-export declare function isEmptyFieldUsage(fieldUsage: FieldUsage[]): boolean;
-export declare function fieldUsageIsPlural(fieldUsage: FieldUsage[]): boolean;
+export declare function fieldUsagePaths(fieldUsage: FieldUsage): string[][];
+export declare function formatFieldUsages(fieldUsage: FieldUsage): string;
+export declare function isEmptyFieldUsage(fieldUsage: FieldUsage): boolean;
+export declare function fieldUsageIsPlural(fieldUsage: FieldUsage): boolean;
 export declare function formatFieldUsage(fieldUsage: string[]): string;
 export declare function unique<T>(values: T[]): T[];
-export declare function mergeFieldUsage(...usages: FieldUsage[][]): FieldUsage[];
-export declare function mergeFieldUsage(...usages: (FieldUsage[] | undefined)[]): FieldUsage[] | undefined;
-export declare function fieldUsageDifference(a: FieldUsage[], b: FieldUsage[]): FieldUsage[];
-export declare function emptyFieldUsage(): FieldUsage[];
-export declare function joinedFieldUsage(joinPath: string[], fieldUsage: FieldUsage[]): FieldUsage[];
-export declare function fieldUsageJoinPaths(fieldUsage: FieldUsage[]): string[][];
+export declare function mergeFieldUsage(...usages: FieldUsage[]): FieldUsage;
+export declare function mergeFieldUsage(...usages: (FieldUsage | undefined)[]): FieldUsage | undefined;
+/**
+ * Concat-merge of `GivenUsage` arrays. Same shape as `mergeFieldUsage`:
+ * undefined inputs are skipped, all-empty result returns undefined,
+ * duplicates by id are kept (each carries its own `at` for diagnostics).
+ */
+export declare function mergeGivenUsage(...usages: (GivenUsage | undefined)[]): GivenUsage | undefined;
+/**
+ * Combine N `RefSummary` values into one. Merges both `fieldUsage` and
+ * `givenUsage`; when more reference-tracking slots land on `RefSummary`,
+ * their merge logic lands here instead of being duplicated at every call
+ * site.
+ */
+export declare function mergeRefSummaries(...rss: (RefSummary | undefined)[]): RefSummary | undefined;
+export declare function fieldUsageDifference(a: FieldUsage, b: FieldUsage): FieldUsageEntry[];
+export declare function emptyFieldUsage(): FieldUsage;
+export declare function joinedFieldUsage(joinPath: string[], fieldUsage: FieldUsage): FieldUsage;
+export declare function fieldUsageJoinPaths(fieldUsage: FieldUsage): string[][];
+export declare function computeQueryGivenUsage(pipeline: PipeSegment[]): GivenUsage;
+export declare function givenUsageOfSource(sd: SourceDef): GivenUsage;
 export declare function checkRequiredGroupBys(compositeResolvedSourceDef: SourceDef, segment: PipeSegment): RequiredGroupBy[];
 export declare function pathEq(a: string[], b: string[]): boolean;
 export declare function pathBegins(path: string[], prefix: string[]): boolean;

package/dist/lang/composite-source-utils.js

@@ -16,10 +16,14 @@ exports.fieldUsageIsPlural = fieldUsageIsPlural;
 exports.formatFieldUsage = formatFieldUsage;
 exports.unique = unique;
 exports.mergeFieldUsage = mergeFieldUsage;
+exports.mergeGivenUsage = mergeGivenUsage;
+exports.mergeRefSummaries = mergeRefSummaries;
 exports.fieldUsageDifference = fieldUsageDifference;
 exports.emptyFieldUsage = emptyFieldUsage;
 exports.joinedFieldUsage = joinedFieldUsage;
 exports.fieldUsageJoinPaths = fieldUsageJoinPaths;
+exports.computeQueryGivenUsage = computeQueryGivenUsage;
+exports.givenUsageOfSource = givenUsageOfSource;
 exports.checkRequiredGroupBys = checkRequiredGroupBys;
 exports.pathEq = pathEq;
 exports.pathBegins = pathBegins;
@@ -39,7 +43,7 @@ sources) {
     let anyComposites = false;
     let joinsProcessed = false;
     const nonCompositeFields = getNonCompositeFields(source);
-    const expandedForError = onlyCompositeUsage(expandFieldUsage(fieldUsage, rootFields).result, source.fields);
+    const expandedForError = onlyCompositeUsage(expandRefUsage({ fieldUsage }, rootFields).fieldUsage, source.fields);
     if (source.type === 'composite') {
         let found = false;
         anyComposites = true;
@@ -66,7 +70,7 @@ sources) {
             }
             const fieldUsageWithWheres = (_b = mergeFieldUsage(getFieldUsageFromFilterList(inputSource), fieldUsage)) !== null && _b !== void 0 ? _b : [];
             const fieldsForLookup = [...nonCompositeFields, ...inputSource.fields];
-            const expanded = expandFieldUsage(fieldUsageWithWheres, fieldsForLookup);
+            const expanded = expandRefUsage({ fieldUsage: fieldUsageWithWheres }, fieldsForLookup);
             if (expanded.missingFields.length > 0) {
                 // A lookup failed while expanding, which means this source certainly won't work
                 for (const missingField of expanded.missingFields) {
@@ -81,7 +85,7 @@ sources) {
                 abort();
                 continue overSources;
             }
-            const expandedCategorized = categorizeFieldUsage(expanded.result);
+            const expandedCategorized = categorizeFieldUsage(expanded.fieldUsage);
             const compositeUsageInThisSource = onlyCompositeUsage(expandedCategorized.sourceUsage, source.fields);
             for (const usage of compositeUsageInThisSource) {
                 if (usage.path.length > 0 && !fieldNames.has(usage.path[0])) {
@@ -177,7 +181,7 @@ sources) {
     }
     else if (source.partitionComposite !== undefined) {
         anyComposites = true;
-        const expanded = expandFieldUsage(fieldUsage, rootFields).result;
+        const expanded = expandRefUsage({ fieldUsage }, rootFields).fieldUsage;
         // TODO possibly abort if expanded has missing fields...
         const expandedCategorized = categorizeFieldUsage(expanded);
         const { partitionFilter, issues } = getPartitionCompositeFilter(source.partitionComposite, expandedCategorized.sourceUsage);
@@ -199,7 +203,7 @@ sources) {
         };
     }
     if (!joinsProcessed) {
-        const expanded = expandFieldUsage(fieldUsage, getJoinFields(rootFields, path));
+        const expanded = expandRefUsage({ fieldUsage }, getJoinFields(rootFields, path));
         if (expanded.missingFields.length > 0) {
             return {
                 error: {
@@ -208,7 +212,7 @@ sources) {
                 },
             };
         }
-        const joinResult = processJoins(path, base, rootFields, nests, categorizeFieldUsage(expanded.result));
+        const joinResult = processJoins(path, base, rootFields, nests, categorizeFieldUsage(expanded.fieldUsage));
         if (joinResult.errors.length > 0) {
             return { error: joinResult.errors[0].error };
         }
@@ -230,11 +234,11 @@ function onlyCompositeUsage(fieldUsage, fields) {
     });
 }
 function getExpandedSegment(segment, inputSource) {
-    var _a;
+    var _a, _b;
     if (segment.type === 'raw')
         return segment;
     const sourceExtensions = (0, malloy_types_1.isQuerySegment)(segment)
-        ? (_a = segment.extendSource) !== null && _a !== void 0 ? _a : []
+        ? ((_a = segment.extendSource) !== null && _a !== void 0 ? _a : [])
         : [];
     const fields = mergeFields(inputSource.fields, sourceExtensions);
     const collectedUngroupings = [];
@@ -277,13 +281,30 @@ function getExpandedSegment(segment, inputSource) {
         });
         updatedSegment = { ...segment, queryFields: updatedQueryFields };
     }
-    const allFieldUsage = mergeFieldUsage(getFieldUsageFromFilterList(inputSource), segment.fieldUsage);
-    const expanded = expandFieldUsage(allFieldUsage || [], fields);
+    // Seed for the walker:
+    //   - segment.refSummary: everything the segment names directly.
+    //   - getFieldUsageFromFilterList(inputSource): field paths in the input
+    //     source's `where:` clauses, so the walker can expand them through joins.
+    //   - givenUsageOfSource(inputSource): every given the input source needs,
+    //     including any hiding inside an embedded Query / SQL segments /
+    //     composite branches.
+    // Plus segment.alwaysJoins for the walker to unconditionally activate
+    // (segment-level direct `join_one:` etc., where activation isn't driven
+    // by any field reference).
+    const seed = mergeRefSummaries(segment.refSummary, {
+        fieldUsage: getFieldUsageFromFilterList(inputSource),
+        givenUsage: givenUsageOfSource(inputSource),
+    });
+    const alwaysJoinNames = (0, malloy_types_1.isQuerySegment)(segment) || (0, malloy_types_1.isIndexSegment)(segment)
+        ? ((_b = segment.alwaysJoins) !== null && _b !== void 0 ? _b : [])
+        : [];
+    const expanded = expandRefUsage(seed, fields, alwaysJoinNames);
     // Merge ungroupings from direct collection and field expansion
     const allUngroupings = [...collectedUngroupings, ...expanded.ungroupings];
     return {
         ...updatedSegment,
-        expandedFieldUsage: expanded.result,
+        expandedFieldUsage: expanded.fieldUsage,
+        expandedGivenUsage: expanded.givenUsage,
         activeJoins: expanded.activeJoins,
         expandedUngroupings: allUngroupings,
     };
@@ -326,21 +347,37 @@ function findActiveJoins(dependencies) {
     return sorted;
 }
 /**
- * Given a list of field usage requests, expand to include all the join on and join filter expressions
- * needed to be able to reference those fields.
+ * Given a seed `RefSummary` (field usage + given usage referenced directly by
+ * the caller), expand to include everything reachable through the join graph:
+ *
+ *   - field usage: the seed fields plus any field usage on `on:` and `where:`
+ *     clauses of joins activated to reach them, recursively.
+ *   - given usage: the seed given usage plus the given usage of every
+ *     atomic-field def the walker dequeues and every join it activates.
  *
  * @returns An object containing:
- * - `result`: The expanded field usage, including usages from necessary joins
+ * - `fieldUsage`: The expanded field usage, including usages from necessary joins
+ * - `givenUsage`: The expanded given usage, seed plus every traversed def/join
  * - `missingFields`: References to fields which could not be resolved
  * - `activeJoins`: Topologically sorted list of joins needed to resolve these uses
  */
-function expandFieldUsage(fieldUsage, fields) {
-    var _a;
+function expandRefUsage(seed, fields, alwaysJoinNames = []) {
     const seen = {};
     const missingFields = [];
     const toProcess = [];
     const activeJoinGraph = {};
     const ungroupings = [];
+    const givenUsage = [];
+    const seenGivens = new Set();
+    function addGivens(items) {
+        for (const g of items) {
+            if (seenGivens.has(g.id))
+                continue;
+            seenGivens.add(g.id);
+            givenUsage.push(g);
+        }
+    }
+    addGivens((0, malloy_types_1.givenUsageFrom)(seed));
     function mergeIntoSeen(usage) {
         var _a;
         const key = (0, utils_2.pathToKey)('field', usage.path);
@@ -361,12 +398,49 @@ function expandFieldUsage(fieldUsage, fields) {
         return false;
     }
     // Initialize: mark original inputs and add them to processing queue
-    for (const usage of fieldUsage) {
+    for (const usage of (0, malloy_types_1.fieldUsageFrom)(seed)) {
         mergeIntoSeen(usage);
         toProcess.push(usage);
     }
     // Process the expanding queue
     const fieldNameSpace = buildNamespace(fields);
+    // Mark `joinDef` as activated and harvest everything it brings in: its
+    // on-clause field usage onto the queue, and its on-clause + filterList
+    // given usage into the accumulator. Used both in-loop (joins reached
+    // via reference paths) and upfront (always-on segment-level joins).
+    function activateJoin(joinDef, joinPath) {
+        const joinKey = (0, utils_2.pathToKey)('join', joinPath);
+        const thisDep = getJoin(activeJoinGraph, joinKey, joinPath);
+        if (!(0, malloy_types_1.isJoined)(joinDef) || thisDep.checked)
+            return;
+        thisDep.checked = true;
+        const joinFieldUsage = getJoinFieldUsage(joinDef, joinPath);
+        addGivens(getJoinGivenUsage(joinDef));
+        for (const usage of joinFieldUsage) {
+            const key = (0, utils_2.pathToKey)('field', usage.path);
+            if (!seen[key]) {
+                seen[key] = usage;
+                toProcess.push(usage);
+            }
+            const isInternalReference = usage.path.length === joinPath.length + 1 &&
+                pathBegins(usage.path, joinPath);
+            if (!isInternalReference && usage.path.length > 1) {
+                const dependencyPath = usage.path.slice(0, -1);
+                const dependencyKey = (0, utils_2.pathToKey)('join', dependencyPath);
+                getJoin(activeJoinGraph, dependencyKey, dependencyPath);
+                thisDep.dependsOn.add(dependencyKey);
+            }
+        }
+    }
+    // Always-on joins (segment-level direct `join_one:` etc.) are activated
+    // unconditionally — no field reference is needed. Compiler-side activation
+    // happens via `addAlwaysJoins` in query_query.ts; here we ensure their
+    // on-clause field/given usage flows into the expanded summaries.
+    for (const joinName of alwaysJoinNames) {
+        const joinDef = inNamespace([joinName], fieldNameSpace);
+        if (joinDef)
+            activateJoin(joinDef, [joinName]);
+    }
     for (let i = 0; i < toProcess.length; i++) {
         const reference = toProcess[i];
         if (reference.path.length === 0)
@@ -377,7 +451,8 @@ function expandFieldUsage(fieldUsage, fields) {
             continue;
         }
         if ((0, malloy_types_1.isAtomic)(def)) {
-            const fieldUsage = (_a = def.fieldUsage) !== null && _a !== void 0 ? _a : [];
+            const fieldUsage = (0, malloy_types_1.fieldUsageFrom)(def.refSummary);
+            addGivens((0, malloy_types_1.givenUsageFrom)(def.refSummary));
             // Add the atomic field's dependencies to the queue
             const refPath = reference.path.slice(0, -1);
             for (const usage of joinedFieldUsage(refPath, fieldUsage)) {
@@ -395,33 +470,12 @@ function expandFieldUsage(fieldUsage, fields) {
             const joinDef = inNamespace(joinPath, fieldNameSpace);
             if (!joinDef)
                 break;
-            const joinKey = (0, utils_2.pathToKey)('join', joinPath);
-            const thisDep = getJoin(activeJoinGraph, joinKey, joinPath);
-            if ((0, malloy_types_1.isJoined)(joinDef) && !thisDep.checked) {
-                thisDep.checked = true;
-                const joinFieldUsage = getJoinFieldUsage(joinDef, joinPath);
-                // Add join's field dependencies to the queue
-                for (const usage of joinFieldUsage) {
-                    const key = (0, utils_2.pathToKey)('field', usage.path);
-                    if (!seen[key]) {
-                        seen[key] = usage;
-                        toProcess.push(usage);
-                    }
-                    // Track join-to-join dependencies
-                    const isInternalReference = usage.path.length === joinPath.length + 1 &&
-                        pathBegins(usage.path, joinPath);
-                    if (!isInternalReference && usage.path.length > 1) {
-                        const dependencyPath = usage.path.slice(0, -1);
-                        const dependencyKey = (0, utils_2.pathToKey)('join', dependencyPath);
-                        getJoin(activeJoinGraph, dependencyKey, dependencyPath);
-                        thisDep.dependsOn.add(dependencyKey);
-                    }
-                }
-            }
+            activateJoin(joinDef, joinPath);
         }
     }
     return {
-        result: Object.values(seen),
+        fieldUsage: Object.values(seen),
+        givenUsage,
         missingFields,
         activeJoins: findActiveJoins(activeJoinGraph),
         ungroupings,
@@ -662,20 +716,19 @@ function processJoins(path, base, rootFields, nests, categorizedFieldUsage) {
     return { anyComposites, errors };
 }
 function segmentFieldUsage(segment) {
-    var _a;
-    return ((_a = ((0, malloy_types_1.isQuerySegment)(segment) || (0, malloy_types_1.isIndexSegment)(segment)
-        ? segment.fieldUsage
-        : undefined)) !== null && _a !== void 0 ? _a : emptyFieldUsage());
+    return (0, malloy_types_1.isQuerySegment)(segment) || (0, malloy_types_1.isIndexSegment)(segment)
+        ? (0, malloy_types_1.fieldUsageFrom)(segment.refSummary)
+        : emptyFieldUsage();
 }
 function getFieldUsageFromFilterList(source) {
     var _a;
-    return ((_a = source.filterList) !== null && _a !== void 0 ? _a : []).flatMap(filter => { var _a; return (_a = filter.fieldUsage) !== null && _a !== void 0 ? _a : []; });
+    return ((_a = source.filterList) !== null && _a !== void 0 ? _a : []).flatMap(filter => (0, malloy_types_1.fieldUsageFrom)(filter.refSummary));
 }
 function resolveCompositeSources(source, segment) {
     var _a, _b;
     const fieldUsage = segmentFieldUsage(segment);
     const sourceExtensions = (0, malloy_types_1.isQuerySegment)(segment)
-        ? (_a = segment.extendSource) !== null && _a !== void 0 ? _a : []
+        ? ((_a = segment.extendSource) !== null && _a !== void 0 ? _a : [])
         : [];
     const nestLevels = extractNestLevels(segment);
     const fields = mergeFields(source.fields, sourceExtensions);
@@ -758,6 +811,34 @@ function mergeFieldUsage(...usages) {
         return undefined;
     return usage;
 }
+/**
+ * Concat-merge of `GivenUsage` arrays. Same shape as `mergeFieldUsage`:
+ * undefined inputs are skipped, all-empty result returns undefined,
+ * duplicates by id are kept (each carries its own `at` for diagnostics).
+ */
+function mergeGivenUsage(...usages) {
+    const usage = [];
+    for (const oneUsage of usages) {
+        if (oneUsage === undefined)
+            continue;
+        usage.push(...oneUsage);
+    }
+    if (usage.length === 0)
+        return undefined;
+    return usage;
+}
+/**
+ * Combine N `RefSummary` values into one. Merges both `fieldUsage` and
+ * `givenUsage`; when more reference-tracking slots land on `RefSummary`,
+ * their merge logic lands here instead of being duplicated at every call
+ * site.
+ */
+function mergeRefSummaries(...rss) {
+    return (0, malloy_types_1.mkRefSummary)({
+        fieldUsage: mergeFieldUsage(...rss.map(rs => (0, malloy_types_1.fieldUsageFrom)(rs))),
+        givenUsage: mergeGivenUsage(...rss.map(rs => (0, malloy_types_1.givenUsageFrom)(rs))),
+    });
+}
 function fieldUsageDifference(a, b) {
     return a.filter(u1 => !b.some(u2 => pathEq(u1.path, u2.path)));
 }
@@ -839,7 +920,7 @@ function joinedUngroupings(joinPath, ungroupings) {
     }));
 }
 function extractNestLevels(segment) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     const fieldsReferencedDirectly = [];
     const fieldsReferenced = [];
     const nested = [];
@@ -864,8 +945,9 @@ function extractNestLevels(segment) {
                 // Check if the nested query has ANY unique key requirements
                 let hasNestedUniqueKeyReqs = nestedLevels.fieldsReferenced.some(usage => usage.uniqueKeyRequirement);
                 // Also check the head segment's fieldUsage directly
-                if ((0, malloy_types_1.isQuerySegment)(head) && head.fieldUsage) {
-                    const hasDirectUniqueKeyReqs = head.fieldUsage.some(usage => usage.uniqueKeyRequirement);
+                if ((0, malloy_types_1.isQuerySegment)(head)) {
+                    const headFieldUsages = (0, malloy_types_1.fieldUsageFrom)(head.refSummary);
+                    const hasDirectUniqueKeyReqs = headFieldUsages.some(usage => usage.uniqueKeyRequirement);
                     if (hasDirectUniqueKeyReqs) {
                         hasNestedUniqueKeyReqs = true;
                     }
@@ -888,13 +970,13 @@ function extractNestLevels(segment) {
                 }, head.referencedAt));
             }
             else {
-                const fieldUsage = (_a = field.fieldUsage) !== null && _a !== void 0 ? _a : [];
+                const fieldUsage = (0, malloy_types_1.fieldUsageFrom)(field.refSummary);
                 fieldsReferenced.push(...fieldUsage);
-                ungroupings.push(...((_b = field.ungroupings) !== null && _b !== void 0 ? _b : []));
-                requiredGroupBys.push(...((_c = field.requiresGroupBy) !== null && _c !== void 0 ? _c : []));
+                ungroupings.push(...((_a = field.ungroupings) !== null && _a !== void 0 ? _a : []));
+                requiredGroupBys.push(...((_b = field.requiresGroupBy) !== null && _b !== void 0 ? _b : []));
             }
         }
-        for (const filter of (_d = segment.filterList) !== null && _d !== void 0 ? _d : []) {
+        for (const filter of (_c = segment.filterList) !== null && _c !== void 0 ? _c : []) {
             if (!(0, malloy_types_1.expressionIsScalar)(filter.expressionType))
                 continue;
             const fields = getSingleValueFilterFields(filter.e);
@@ -972,7 +1054,7 @@ function isSingleValueFilterNode(e) {
     }
 }
 function expandRefs(nests, fields) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     const newNests = [];
     const requiredGroupBys = [...nests.requiredGroupBys];
     const allUngroupings = [...nests.ungroupings];
@@ -1025,7 +1107,7 @@ function expandRefs(nests, fields) {
             if (def.ungroupings) {
                 allUngroupings.push(...joinedUngroupings(joinPath, ungroupingsAt(def.ungroupings, field.at)));
             }
-            const fieldUsage = (_a = def.fieldUsage) !== null && _a !== void 0 ? _a : [];
+            const fieldUsage = (0, malloy_types_1.fieldUsageFrom)(def.refSummary);
             const moreReferences = fieldUsageAt(joinedFieldUsage(joinPath, fieldUsage), field.at).filter(u1 => !references.some(u2 => pathEq(u1.path, u2.path)));
             references.push(...moreReferences);
         }
@@ -1045,10 +1127,10 @@ function expandRefs(nests, fields) {
             fieldsReferencedDirectly: [],
             ungroupings: [],
             nested: [],
-            requiredGroupBys: (_b = ungrouping.requiresGroupBy) !== null && _b !== void 0 ? _b : [],
+            requiredGroupBys: (_a = ungrouping.requiresGroupBy) !== null && _a !== void 0 ? _a : [],
             singleValueFilters: [],
         }, fields);
-        missingFields.push(...((_c = expanded.missingFields) !== null && _c !== void 0 ? _c : []));
+        missingFields.push(...((_b = expanded.missingFields) !== null && _b !== void 0 ? _b : []));
         for (const field of expanded.result.requiredGroupBys) {
             if (isUngroupedBy(ungrouping, field.path)) {
                 unsatisfiableGroupBys.push(field);
@@ -1058,7 +1140,7 @@ function expandRefs(nests, fields) {
     const nested = [];
     for (const level of [...nests.nested, ...newNests]) {
         const expanded = expandRefs(level, fields);
-        missingFields.push(...((_d = expanded.missingFields) !== null && _d !== void 0 ? _d : []));
+        missingFields.push(...((_c = expanded.missingFields) !== null && _c !== void 0 ? _c : []));
         nested.push(expanded.result);
         unsatisfiableGroupBys.push(...expanded.result.unsatisfiableGroupBys);
         allUngroupings.push(...expanded.result.ungroupings);
@@ -1076,13 +1158,101 @@ function expandRefs(nests, fields) {
     };
 }
 function getJoinFieldUsage(join, joinPath) {
-    var _a, _b;
-    return ((_b = mergeFieldUsage(
+    var _a;
+    return ((_a = mergeFieldUsage(
     // For `fieldUsage` from join `where`s, we need the path including the join name
     joinedFieldUsage(joinPath, (0, malloy_types_1.isSourceDef)(join) ? getFieldUsageFromFilterList(join) : []), 
     // For `fieldUsage` from join `on`, we need the path excluding the join name, since it's
     // already rooted at the parent
-    joinedFieldUsage(joinPath.slice(0, -1), (_a = join.fieldUsage) !== null && _a !== void 0 ? _a : []))) !== null && _b !== void 0 ? _b : []);
+    joinedFieldUsage(joinPath.slice(0, -1), (0, malloy_types_1.fieldUsageFrom)(join.refSummary)))) !== null && _a !== void 0 ? _a : []);
+}
+// Givens have no path — `joinedFieldUsage`'s path-rerooting has no analog here.
+// The `on:` clause lives on `join.refSummary` for every join shape; everything
+// else (filterList, plus any givens hiding inside the source's embedded Query)
+// is collected by `givenUsageOfSource` for source-typed joins.
+function getJoinGivenUsage(join) {
+    const onClause = (0, malloy_types_1.givenUsageFrom)(join.refSummary);
+    if ((0, malloy_types_1.isSourceDef)(join)) {
+        return [...givenUsageOfSource(join), ...onClause];
+    }
+    return onClause;
+}
+// Dedup'd union of `expandedGivenUsage` across every segment in a Query's
+// finalized pipeline, recursing through nested turtle pipelines. This is the
+// per-Query summary that consumers (PreparedQuery.givens, satisfiability
+// check, `givenUsageOfSource` for QuerySourceDef) read instead of re-walking
+// segments. Called only from the query-arrow / query-refine construction
+// sites where every segment has been through getExpandedSegment.
+function computeQueryGivenUsage(pipeline) {
+    const seen = new Set();
+    const result = [];
+    function add(items) {
+        if (!items)
+            return;
+        for (const g of items) {
+            if (seen.has(g.id))
+                continue;
+            seen.add(g.id);
+            result.push(g);
+        }
+    }
+    function visit(segment) {
+        if ((0, malloy_types_1.isQuerySegment)(segment) || (0, malloy_types_1.isIndexSegment)(segment)) {
+            add(segment.expandedGivenUsage);
+        }
+        if ((0, malloy_types_1.isQuerySegment)(segment)) {
+            for (const field of segment.queryFields) {
+                if ((0, malloy_types_1.isTurtle)(field)) {
+                    field.pipeline.forEach(visit);
+                }
+            }
+        }
+    }
+    pipeline.forEach(visit);
+    return result;
+}
+// Returns every given a SourceDef references — its own filterList plus any
+// givens hiding inside an embedded Query. The single point of knowledge for
+// "where can a Query embed in a SourceDef" — when a future SourceDef variant
+// grows an embedded Query, teach this helper.
+//
+// Composite sources: composite-source support across the codebase is
+// partial; the givens work isn't chasing it. The `composite` arm here is
+// defensive — for the top-level `run: composite ->` path it never fires
+// because composite resolution runs first and `expandRefUsage` is seeded
+// with the resolved branch. If an unresolved `CompositeSourceDef` ever
+// reaches here (e.g. composites in join positions if/when those work),
+// the conservative union over all branches is the safe fallback. See
+// ~/ctx/mp/implementation.md "Composite sources — partial coverage".
+function givenUsageOfSource(sd) {
+    var _a, _b, _c;
+    const fromFilters = ((_a = sd.filterList) !== null && _a !== void 0 ? _a : []).flatMap(f => (0, malloy_types_1.givenUsageFrom)(f.refSummary));
+    switch (sd.type) {
+        case 'query_source':
+            return [...fromFilters, ...((_b = sd.query.givenUsage) !== null && _b !== void 0 ? _b : [])];
+        case 'sql_select': {
+            const fromSegments = ((_c = sd.selectSegments) !== null && _c !== void 0 ? _c : []).flatMap(seg => {
+                var _a;
+                if ((0, malloy_types_1.isSegmentSQL)(seg))
+                    return [];
+                if ((0, malloy_types_1.isSegmentSource)(seg))
+                    return givenUsageOfSource(seg);
+                // Remaining variant of SQLPhraseSegment is `Query`
+                return (_a = seg.givenUsage) !== null && _a !== void 0 ? _a : [];
+            });
+            return [...fromFilters, ...fromSegments];
+        }
+        case 'composite':
+            return [
+                ...fromFilters,
+                ...sd.sources.flatMap(s => givenUsageOfSource(s)),
+            ];
+        default:
+            // table, query_result, finalize, nest_source, virtual — no embedded Query.
+            // (query_result/finalize/nest_source are pipeline-internal and only seen
+            // within a Query whose segments are walked anyway. virtual is opaque.)
+            return fromFilters;
+    }
 }
 function isUngroupedBy(ungrouping, groupedBy) {
     if (ungrouping.ungroupedFields === '*')
@@ -1098,7 +1268,7 @@ function checkRequiredGroupBys(compositeResolvedSourceDef, segment) {
     var _a;
     const nests = extractNestLevels(segment);
     const sourceExtensions = (0, malloy_types_1.isQuerySegment)(segment)
-        ? (_a = segment.extendSource) !== null && _a !== void 0 ? _a : []
+        ? ((_a = segment.extendSource) !== null && _a !== void 0 ? _a : [])
         : [];
     const unsatisfied = _checkRequiredGroupBys(nests, mergeFields(compositeResolvedSourceDef.fields, sourceExtensions));
     return unsatisfied;