@malloydata/malloy 0.0.334 → 0.0.336

package/dist/lang/test/test-translator.js

@@ -23,7 +23,7 @@
  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BetaExpression = exports.TestTranslator = exports.TestChildTranslator = exports.aTableDef = void 0;
+exports.BetaExpression = exports.TestTranslator = exports.TestChildTranslator = exports.mockSchema = exports.bqTableDef = exports.aTableDef = exports.TEST_DIALECT = void 0;
 exports.pretty = pretty;
 exports.humanify = humanify;
 exports.getExplore = getExplore;
@@ -134,65 +134,85 @@ function humanify(value) {
 }
 const intType = { type: 'number', numberType: 'integer' };
 const bigintType = { type: 'number', numberType: 'bigint' };
-const mockSchema = {
-    'aTable': {
-        type: 'table',
-        name: 'aTable',
-        dialect: 'standardsql',
-        tablePath: 'aTable',
-        connection: 'test',
+// Base fields shared by both duckdb and BigQuery table definitions
+const baseFields = [
+    { type: 'string', name: 'astr' },
+    { type: 'number', name: 'af', numberType: 'float' },
+    { ...intType, name: 'ai' },
+    { ...bigintType, name: 'abig' },
+    { type: 'date', name: 'ad' },
+    { type: 'boolean', name: 'abool' },
+    { type: 'timestamp', name: 'ats' },
+    { type: 'sql native', name: 'aun' },
+    { type: 'sql native', name: 'aweird', rawType: 'weird' },
+    {
+        type: 'array',
+        name: 'astruct',
+        elementTypeDef: { type: 'record_element' },
+        join: 'many',
         fields: [
-            { type: 'string', name: 'astr' },
-            { type: 'number', name: 'af', numberType: 'float' },
-            { ...intType, name: 'ai' },
-            { ...bigintType, name: 'abig' },
-            { type: 'date', name: 'ad' },
-            { type: 'boolean', name: 'abool' },
-            { type: 'timestamp', name: 'ats' },
-            { type: 'sql native', name: 'aun' },
-            { type: 'sql native', name: 'aweird', rawType: 'weird' },
-            {
-                type: 'array',
-                name: 'astruct',
-                elementTypeDef: { type: 'record_element' },
-                join: 'many',
-                fields: [
-                    {
-                        name: 'column',
-                        type: 'number',
-                        numberType: 'integer',
-                    },
-                ],
-            },
             {
-                type: 'record',
-                name: 'aninline',
-                fields: [{ ...intType, name: 'column' }],
-                join: 'one',
-                matrixOperation: 'left',
+                name: 'column',
+                type: 'number',
+                numberType: 'integer',
             },
-            (0, malloy_types_1.mkArrayDef)(intType, 'ais'),
         ],
     },
-    'malloytest.carriers': {
+    {
+        type: 'record',
+        name: 'aninline',
+        fields: [{ ...intType, name: 'column' }],
+        join: 'one',
+        matrixOperation: 'left',
+    },
+    (0, malloy_types_1.mkArrayDef)(intType, 'ais'),
+];
+exports.TEST_DIALECT = 'duckdb';
+exports.aTableDef = {
+    type: 'table',
+    name: 'aTable',
+    dialect: exports.TEST_DIALECT,
+    tablePath: 'aTable',
+    connection: '_db_',
+    fields: [
+        ...baseFields,
+        { type: 'timestamptz', name: 'atstz' }, // duckdb supports timestamptz
+    ],
+};
+// BigQuery-compatible table definition (no timestamptz support)
+exports.bqTableDef = {
+    type: 'table',
+    name: 'aTable',
+    dialect: 'standardsql',
+    tablePath: 'aTable',
+    connection: '_bq_',
+    fields: baseFields,
+};
+/**
+ * A TestTranlator never actually talks to connection, instead uses
+ * some mocked schema definitions.
+ */
+exports.mockSchema = [
+    exports.aTableDef,
+    exports.bqTableDef,
+    {
         type: 'table',
-        name: 'malloytest.carriers',
-        dialect: 'standardsql',
+        name: 'carriers',
+        dialect: exports.TEST_DIALECT,
         tablePath: 'malloytest.carriers',
-        connection: 'bigquery',
+        connection: '_db_',
         fields: [
             { name: 'code', type: 'string' },
             { name: 'name', type: 'string' },
             { name: 'nickname', type: 'string' },
         ],
-        as: 'carriers',
     },
-    'malloytest.flights': {
+    {
         type: 'table',
-        name: 'malloytest.flights',
-        dialect: 'standardsql',
+        name: 'flights',
+        dialect: exports.TEST_DIALECT,
         tablePath: 'malloytest.flights',
-        connection: 'bigquery',
+        connection: '_db_',
         fields: [
             { name: 'carrier', type: 'string' },
             { name: 'origin', type: 'string' },
@@ -211,14 +231,13 @@ const mockSchema = {
             { name: 'diverted', type: 'string' },
             { name: 'id2', type: 'number', numberType: 'integer' },
         ],
-        as: 'flights',
     },
-    'malloytest.airports': {
+    {
         type: 'table',
-        name: 'malloytest.airports',
-        dialect: 'standardsql',
+        name: 'airports',
+        dialect: exports.TEST_DIALECT,
         tablePath: 'malloytest.airports',
-        connection: 'bigquery',
+        connection: '_db_',
         fields: [
             { name: 'id', type: 'number', numberType: 'integer' },
             { name: 'code', type: 'string' },
@@ -248,17 +267,11 @@ const mockSchema = {
             { name: 'cntl_twr', type: 'string' },
             { name: 'major', type: 'string' },
         ],
-        as: 'airports',
     },
-};
-exports.aTableDef = mockSchema['aTable'];
+];
 const bJoinedIntoA = {
-    type: 'table',
-    name: 'aTable',
-    dialect: 'standardsql',
-    tablePath: 'aTable',
-    connection: 'test',
-    as: 'b',
+    ...exports.aTableDef,
+    name: 'b',
     join: 'one',
     matrixOperation: 'left',
     onExpression: {
@@ -268,7 +281,6 @@ const bJoinedIntoA = {
             right: { node: 'field', path: ['b', 'astr'] },
         },
     },
-    fields: exports.aTableDef.fields,
 };
 /**
  * When translating partial trees, there will not be a document node
@@ -323,29 +335,44 @@ class TestTranslator extends parse_malloy_1.MalloyTranslator {
         this.testSrc = testSrc;
         this.allDialectsEnabled = true;
         /*
+         * There are two connections:
+         *   _db_  - duckdb dialect, with the following tables ...
+         *      aTable, malloytest.carriers, malloytest.flights, malloytest.airports
+         *   _bq_  - bigquery/standardsql dialect, with one table
+         *      aTable
+         *
+         * The "aTable" table is a mocked table with one column of each type.
+         * The _bq_ version does not have the timestamptz column, and when
+         * DATETIME support is added, the _db_ version will not have that.
+         *
          * All test source files can assume that an import of this
-      
          *
-         * Also the following tables will be available on _db_
-         *   aTable, malloytest.carriers, malloytest.flights, malloytest.airports
+         *   source:
+         *     bq_a is _bq_.table('aTable') extend { primary_key: astr }
+         *     carriers is _db_.table('malloytest.carriers')
+         *     flights is _db_.table('malloytest.flights')
+         *     airports is _db_.table('malloytest.airports')
+         *     a is _db_.table('aTable') extend { primary_key: astr }
+         *     b is a
+         *     ab is a extend {
+         *       join_one: b with astr
+         *       measure: acount is count()
+         *       view: aturtle is { group_by: astr; aggregate: acount }
+         *     }
          *
-         *   source: a is _db_.table('aTable') extend { primary_key: astr }
-         *   source: b is a
-         *   source: ab is a extend {
-         *     join_one: b with astr
-         *     measure: acount is count()
-         *     query: aturtle is { group_by: astr; aggregate: acount }
-         *   }
          */
         this.internalModel = {
             name: testURI,
             exports: [],
             queryList: [],
+            sourceRegistry: {},
             dependencies: {},
             contents: {
                 _db_: { type: 'connection', name: '_db_' },
-                a: { ...exports.aTableDef, primaryKey: 'astr', as: 'a' },
-                b: { ...exports.aTableDef, primaryKey: 'astr', as: 'b' },
+                _bq_: { type: 'connection', name: '_bq_' },
+                a: { ...exports.aTableDef, primaryKey: 'astr', name: 'a' },
+                b: { ...exports.aTableDef, primaryKey: 'astr', name: 'b' },
+                bq_a: { ...exports.bqTableDef, primaryKey: 'astr', name: 'bq_a' },
                 ab: {
                     ...exports.aTableDef,
                     primaryKey: 'astr',
@@ -378,7 +405,7 @@ class TestTranslator extends parse_malloy_1.MalloyTranslator {
                                             { type: 'string', name: 'acount' },
                                         ],
                                         connection: 'test',
-                                        dialect: 'standardsql',
+                                        dialect: exports.TEST_DIALECT,
                                     },
                                     isRepeated: true,
                                 },
@@ -393,9 +420,8 @@ class TestTranslator extends parse_malloy_1.MalloyTranslator {
         if (internalModel !== undefined) {
             this.internalModel = internalModel;
         }
-        for (const tableName in mockSchema) {
-            this.schemaZone.define(tableName, mockSchema[tableName]);
-            this.schemaZone.define(`_db_:${tableName}`, mockSchema[tableName]);
+        for (const actualSchema of exports.mockSchema) {
+            this.schemaZone.define(`${actualSchema.connection}:${actualSchema.tablePath}`, actualSchema);
         }
     }
     translate() {
@@ -645,7 +671,7 @@ function getSelectOneStruct(sqlBlock) {
         [key]: {
             type: 'sql_select',
             name: key,
-            dialect: 'standardsql',
+            dialect: exports.TEST_DIALECT,
             connection: '_db_',
             selectStr: sqlBlock.selectStr,
             fields: [{ type: 'number', name: 'one' }],

package/dist/lang/translate-response.d.ts

@@ -64,6 +64,7 @@ export type HelpContextResponse = Partial<HelpContext>;
 interface TranslatedResponseData extends ResponseBase, NeededData, ProblemResponse, FinalResponse {
     modelDef: ModelDef;
     fromSources: string[];
+    modelWasModified: boolean;
 }
 interface TablePath extends ResponseBase, NeededData, ProblemResponse, FinalResponse {
     pathInfo: PathInfo[];

package/dist/model/constant_expression_compiler.js

@@ -84,18 +84,17 @@ class ConstantQueryStruct extends query_node_1.QueryStruct {
             connection: dialect.name,
             dialect: dialect.name,
         };
-        // Create a minimal model interface that only provides eventStream
-        const minimalModel = { eventStream };
-        // Create minimal prepare result options
-        const minimalPrepareOptions = {};
+        // Create minimal model with empty structs map
+        const minimalModel = {
+            structs: new Map(),
+        };
+        // Create minimal prepare result options with eventStream
+        const minimalPrepareOptions = { eventStream };
         // Call parent constructor with minimal requirements
         super(minimalStructDef, undefined, // no source arguments initially
         { model: minimalModel }, minimalPrepareOptions);
         this.dialect = dialect;
         this._constantArguments = parameters;
-        if (eventStream) {
-            this.model.eventStream = eventStream;
-        }
     }
     /**
      * Override arguments() to return our parameters

package/dist/model/index.d.ts

@@ -4,5 +4,7 @@ import { QueryQuery } from './query_query';
 import { QueryModelImpl } from './query_model_impl';
 export { QueryField, QueryStruct, QueryQuery, QueryModelImpl as QueryModel };
 export { getResultStructDefForQuery, getResultStructDefForView, } from './query_model_impl';
-export { indent, composeSQLExpr } from './utils';
+export { indent, composeSQLExpr, makeDigest, mkModelDef } from './utils';
 export { constantExprToSQL } from './constant_expression_compiler';
+export { getCompiledSQL } from './sql_compiled';
+export { mkSourceID, mkBuildID, mkQuerySourceDef, mkSQLSourceDef, mkTableSourceDef, resolveSourceID, registerSource, hasSourceRegistryEntry, } from './source_def_utils';

package/dist/model/index.js

@@ -36,7 +36,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.constantExprToSQL = exports.composeSQLExpr = exports.indent = exports.getResultStructDefForView = exports.getResultStructDefForQuery = exports.QueryModel = exports.QueryQuery = exports.QueryStruct = exports.QueryField = void 0;
+exports.hasSourceRegistryEntry = exports.registerSource = exports.resolveSourceID = exports.mkTableSourceDef = exports.mkSQLSourceDef = exports.mkQuerySourceDef = exports.mkBuildID = exports.mkSourceID = exports.getCompiledSQL = exports.constantExprToSQL = exports.mkModelDef = exports.makeDigest = exports.composeSQLExpr = exports.indent = exports.getResultStructDefForView = exports.getResultStructDefForQuery = exports.QueryModel = exports.QueryQuery = exports.QueryStruct = exports.QueryField = void 0;
 __exportStar(require("./malloy_types"), exports);
 const query_node_1 = require("./query_node");
 Object.defineProperty(exports, "QueryField", { enumerable: true, get: function () { return query_node_1.QueryField; } });
@@ -47,15 +47,8 @@ Object.defineProperty(exports, "QueryQuery", { enumerable: true, get: function (
 const field_instance_1 = require("./field_instance");
 const query_model_impl_1 = require("./query_model_impl");
 Object.defineProperty(exports, "QueryModel", { enumerable: true, get: function () { return query_model_impl_1.QueryModelImpl; } });
-// We have a circular dependency issue, and this is the minimal
-// dependency injection needed to get around it. Ideally, we would
-// like to avoid this, and I think a thoughtful pass through
-// FieldInstance and QueryField might eliminate the need for this.
 function getLookupFun(mri) {
-    if (mri instanceof query_model_impl_1.QueryModelImpl) {
-        return (name) => mri.structs.get(name);
-    }
-    return () => undefined;
+    return (name) => mri.structs.get(name);
 }
 field_instance_1.FieldInstanceField.registerExpressionCompiler(expression_compiler_1.exprToSQL);
 query_node_1.QueryStruct.registerTurtleFieldMaker((field, parent) => query_query_1.QueryQuery.makeQuery(field, parent, undefined, false, getLookupFun(parent.getModel())));
@@ -65,6 +58,19 @@ Object.defineProperty(exports, "getResultStructDefForView", { enumerable: true,
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "indent", { enumerable: true, get: function () { return utils_1.indent; } });
 Object.defineProperty(exports, "composeSQLExpr", { enumerable: true, get: function () { return utils_1.composeSQLExpr; } });
+Object.defineProperty(exports, "makeDigest", { enumerable: true, get: function () { return utils_1.makeDigest; } });
+Object.defineProperty(exports, "mkModelDef", { enumerable: true, get: function () { return utils_1.mkModelDef; } });
 var constant_expression_compiler_1 = require("./constant_expression_compiler");
 Object.defineProperty(exports, "constantExprToSQL", { enumerable: true, get: function () { return constant_expression_compiler_1.constantExprToSQL; } });
+var sql_compiled_1 = require("./sql_compiled");
+Object.defineProperty(exports, "getCompiledSQL", { enumerable: true, get: function () { return sql_compiled_1.getCompiledSQL; } });
+var source_def_utils_1 = require("./source_def_utils");
+Object.defineProperty(exports, "mkSourceID", { enumerable: true, get: function () { return source_def_utils_1.mkSourceID; } });
+Object.defineProperty(exports, "mkBuildID", { enumerable: true, get: function () { return source_def_utils_1.mkBuildID; } });
+Object.defineProperty(exports, "mkQuerySourceDef", { enumerable: true, get: function () { return source_def_utils_1.mkQuerySourceDef; } });
+Object.defineProperty(exports, "mkSQLSourceDef", { enumerable: true, get: function () { return source_def_utils_1.mkSQLSourceDef; } });
+Object.defineProperty(exports, "mkTableSourceDef", { enumerable: true, get: function () { return source_def_utils_1.mkTableSourceDef; } });
+Object.defineProperty(exports, "resolveSourceID", { enumerable: true, get: function () { return source_def_utils_1.resolveSourceID; } });
+Object.defineProperty(exports, "registerSource", { enumerable: true, get: function () { return source_def_utils_1.registerSource; } });
+Object.defineProperty(exports, "hasSourceRegistryEntry", { enumerable: true, get: function () { return source_def_utils_1.hasSourceRegistryEntry; } });
 //# sourceMappingURL=index.js.map

package/dist/model/malloy_types.d.ts

@@ -1,4 +1,5 @@
 import type * as Malloy from '@malloydata/malloy-interfaces';
+import type { EventStream } from '../runtime_types';
 /**
  * Field computations are compiled into an expression tree of "Expr"
  * type nodes. Each node is one of these three interfaces. The
@@ -582,7 +583,7 @@ export interface Query extends Pipeline, Filtered, HasLocation {
     modelAnnotation?: Annotation;
     compositeResolvedSourceDef?: SourceDef;
 }
-export type NamedQuery = Query & NamedObject;
+export type NamedQueryDef = Query & NamedObject;
 export type PipeSegment = QuerySegment | IndexSegment | RawSegment;
 export declare function segmentHasErrors(segment: PipeSegment): boolean;
 export declare function structHasErrors(struct: StructDef): boolean;
@@ -685,6 +686,8 @@ interface StructDefBase extends HasLocation, NamedObject {
     annotation?: Annotation;
     modelAnnotation?: ModelAnnotation;
     fields: FieldDef[];
+    /** Marker for error placeholder structs created by ErrorFactory */
+    errorFactory?: boolean;
 }
 export interface PartitionCompositeDesc {
     partitionField: string;
@@ -716,13 +719,46 @@ export interface CompositeSourceDef extends SourceDefBase {
 export interface SQLStringSegment {
     sql: string;
 }
-export type SQLPhraseSegment = Query | SQLStringSegment;
+export type SQLPhraseSegment = Query | PersistableSourceDef | SQLStringSegment;
 export declare function isSegmentSQL(f: SQLPhraseSegment): f is SQLStringSegment;
-export interface SQLSourceDef extends SourceDefBase {
+export declare function isSegmentSource(f: SQLPhraseSegment): f is PersistableSourceDef;
+/** Format: "name@modelUrl" - uniquely identifies a source for persistence */
+export type SourceID = string;
+/** Hash of (connectionDigest, sql) - uniquely identifies a built artifact */
+export type BuildID = string;
+/**
+ * Reference to a source in modelDef.contents by name.
+ * Used in sourceRegistry to avoid duplicating SourceDefs that are in the namespace.
+ */
+export interface SourceRegistryReference {
+    type: 'source_registry_reference';
+    name: string;
+}
+/**
+ * Inner entry type: either a reference to contents or an actual PersistableSourceDef.
+ * - SourceRegistryReference: source is in namespace (contents), look it up by name
+ * - PersistableSourceDef: source is not in namespace (hidden dependency), stored directly
+ */
+export type SourceRegistryEntry = SourceRegistryReference | PersistableSourceDef;
+/**
+ * Value in the sourceRegistry, wrapping the entry with persistence info.
+ * persist is lazily computed: undefined = not checked, true/false = checked
+ */
+export interface SourceRegistryValue {
+    entry: SourceRegistryEntry;
+    persist?: boolean;
+}
+export declare function isSourceRegistryReference(entry: SourceRegistryEntry): entry is SourceRegistryReference;
+export interface PersistableSourceProperties {
+    sourceID?: SourceID;
+    extends?: SourceID;
+}
+export interface SQLSourceDef extends SourceDefBase, PersistableSourceProperties {
     type: 'sql_select';
     selectStr: string;
+    selectSegments?: SQLPhraseSegment[];
 }
-export interface QuerySourceDef extends SourceDefBase {
+export interface QuerySourceDef extends SourceDefBase, PersistableSourceProperties {
     type: 'query_source';
     query: Query;
 }
@@ -738,7 +774,21 @@ export interface FinalizeSourceDef extends SourceDefBase {
 }
 export declare function sourceBase(sd: SourceDefBase): SourceDefBase;
 export declare function isSourceDef(sd: NamedModelObject | FieldDef): sd is SourceDef;
+/**
+ * Union of all source definition types.
+ *
+ * IMPORTANT: Never use object spread to copy a SourceDef. Use the factory
+ * methods in source_def_utils.ts to merge changes into a source def:
+ * - mkSQLSourceDef(base, ...) - create SQLSourceDef from base
+ * - mkQuerySourceDef(base, ...) - create QuerySourceDef from base
+ *
+ * These factories explicitly copy only safe fields, preventing accidental
+ * propagation of sourceID/extends which must only be set in DefineSource.
+ */
 export type SourceDef = TableSourceDef | SQLSourceDef | QuerySourceDef | QueryResultDef | FinalizeSourceDef | NestSourceDef | CompositeSourceDef;
+/** Sources that can be persisted (materialized to tables) */
+export type PersistableSourceDef = SQLSourceDef | QuerySourceDef;
+export declare function isPersistableSourceDef(sd: SourceDef): sd is PersistableSourceDef;
 /** Is this the "FROM" table of a query tree */
 export declare function isBaseTable(def: StructDef): def is SourceDef;
 export type StructDef = SourceDef | RecordDef | ArrayDef;
@@ -891,7 +941,7 @@ 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 type NamedModelObject = SourceDef | NamedQuery | FunctionDef | ConnectionDef;
+export type NamedModelObject = SourceDef | NamedQueryDef | FunctionDef | ConnectionDef;
 export interface DependencyTree {
     [url: string]: DependencyTree;
 }
@@ -900,6 +950,13 @@ export interface ModelDef {
     name: string;
     exports: string[];
     contents: Record<string, NamedModelObject>;
+    /**
+     * Registry mapping sourceID to source definitions for build graph construction.
+     * For sources in namespace: maps to SourceRegistryReference (look up in contents)
+     * For hidden dependencies: maps to actual PersistableSourceDef (not in namespace)
+     * Each entry includes a lazily-computed persist flag.
+     */
+    sourceRegistry: Record<SourceID, SourceRegistryValue>;
     annotation?: ModelAnnotation;
     queryList: Query[];
     dependencies: DependencyTree;
@@ -948,12 +1005,6 @@ export interface DrillSource {
     sourceFilters?: FilterCondition[];
     sourceArguments?: Record<string, Argument>;
 }
-export type QueryToMaterialize = {
-    id: string;
-    path: string;
-    source: string | undefined;
-    queryName: string;
-};
 export interface CompiledQuery extends DrillSource {
     structs: SourceDef[];
     sql: string;
@@ -963,8 +1014,6 @@ export interface CompiledQuery extends DrillSource {
     connectionName: string;
     queryTimezone?: string;
     annotation?: Annotation;
-    dependenciesToMaterialize?: Record<string, QueryToMaterialize>;
-    materialization?: QueryToMaterialize;
     defaultRowLimitAdded?: number;
 }
 /** Result type for running a Malloy query. */
@@ -1007,10 +1056,15 @@ export interface SearchValueMapResult {
     }[];
 }
 export interface PrepareResultOptions {
-    replaceMaterializedReferences?: boolean;
-    materializedTablePrefix?: string;
     defaultRowLimit?: number;
     isPartialQuery?: boolean;
+    eventStream?: EventStream;
+    /** Manifest of built tables (BuildID → entry), the build cache */
+    buildManifest?: BuildManifest;
+    /** Map from connectionName to connectionDigest (from Connection.getDigest()) */
+    connectionDigests?: Record<string, string>;
+    /** If true, throw when a persist query's digest is not in the manifest */
+    strictPersist?: boolean;
 }
 type UTD = AtomicTypeDef | TypedDef | FunctionParameterTypeDef | FunctionReturnTypeDef | undefined;
 /**
@@ -1048,4 +1102,24 @@ export type UniqueKeyRequirement = undefined | {
     isCount: boolean;
 };
 export declare function mergeUniqueKeyRequirement(existing: UniqueKeyRequirement, newInfo: UniqueKeyRequirement): UniqueKeyRequirement;
+/**
+ * Entry in a BuildManifest for a persisted table.
+ */
+export interface BuildManifestEntry {
+    /** Hash of (connectionDigest, sql) - also the key in buildEntries */
+    buildId: BuildID;
+    tableName: string;
+    buildStartedAt: string;
+    buildFinishedAt: string;
+}
+/**
+ * Manifest of persisted query results (the build cache).
+ * Used by compileQuery to substitute persist queries with table references.
+ */
+export interface BuildManifest {
+    modelUrl: string;
+    buildStartedAt: string;
+    buildFinishedAt: string;
+    buildEntries: Record<BuildID, BuildManifestEntry>;
+}
 export {};

package/dist/model/malloy_types.js

@@ -76,8 +76,11 @@ exports.isRawSegment = isRawSegment;
 exports.isIndexSegment = isIndexSegment;
 exports.bareFieldUsage = bareFieldUsage;
 exports.isSegmentSQL = isSegmentSQL;
+exports.isSegmentSource = isSegmentSource;
+exports.isSourceRegistryReference = isSourceRegistryReference;
 exports.sourceBase = sourceBase;
 exports.isSourceDef = isSourceDef;
+exports.isPersistableSourceDef = isPersistableSourceDef;
 exports.isBaseTable = isBaseTable;
 exports.isLiteral = isLiteral;
 exports.mergeEvalSpaces = mergeEvalSpaces;
@@ -443,6 +446,12 @@ function bareFieldUsage(fu) {
 function isSegmentSQL(f) {
     return 'sql' in f;
 }
+function isSegmentSource(f) {
+    return 'type' in f && (f.type === 'sql_select' || f.type === 'query_source');
+}
+function isSourceRegistryReference(entry) {
+    return entry.type === 'source_registry_reference';
+}
 // The gesture {...sourceStruct moreProperties}  happens everywhere, now that
 // structs aren't all identical, we need a way to make one from any of the
 // exisitng structs
@@ -458,6 +467,9 @@ function isSourceDef(sd) {
         sd.type === 'nest_source' ||
         sd.type === 'composite');
 }
+function isPersistableSourceDef(sd) {
+    return sd.type === 'sql_select' || sd.type === 'query_source';
+}
 /** Is this the "FROM" table of a query tree */
 function isBaseTable(def) {
     if (isJoinedSource(def)) {

package/dist/model/persist_utils.d.ts

@@ -0,0 +1,47 @@
+import type { ModelDef, SourceDef, Query } from './malloy_types';
+import type { BuildNode } from '../api/foundation/types';
+/**
+ * Find persistent dependencies for a source or query, returning a nested DAG.
+ *
+ * Walks the full dependency tree but only includes persistent sources in the
+ * result. Non-persistent sources are "flattened out" - their persistent
+ * dependencies bubble up to become direct dependencies of the caller.
+ *
+ * Example: source_c (persist) -> source_b (NOT persist) -> source_a (persist)
+ * Returns: [{sourceID: source_a, dependsOn: []}]
+ * (source_b is flattened out, source_a becomes direct dependency)
+ *
+ * ## The 6 Dependency Paths in the IR
+ *
+ * Starting from a Query or SourceDef, these are ALL the ways a SourceDef
+ * can be referenced (and thus must be walked for dependency tracking):
+ *
+ * 1. **Query.structRef** → SourceDef (the FROM clause)
+ * 2. **Query.pipeline[].extendSource[]** → JoinFieldDef (joins in extend blocks)
+ * 3. **SourceDef.fields[]** → JoinFieldDef (joins defined on a source)
+ * 4. **PersistableSourceDef.extends** → SourceID (extend chain reference)
+ * 5. **SQLSourceDef.selectSegments[]** → Query | PersistableSourceDef (SQL interpolation)
+ * 6. **QuerySourceDef.query** → Query (nested query in query_source)
+ *
+ * Note: CompositeSourceDef.sources[] is ignored - composite sources and
+ * persistence may be incompatible features.
+ *
+ * @param root The source or query to find dependencies for
+ * @param modelDef The model definition containing the source registry
+ * @returns Array of BuildNode representing the persistent dependency DAG
+ */
+export declare function findPersistentDependencies(root: SourceDef | Query, modelDef: ModelDef): BuildNode[];
+/**
+ * Find the minimal set of root build graphs from a forest of BuildNodes.
+ *
+ * Uses flattening for ANALYSIS ONLY to identify unique nodes and find roots.
+ * Returns original graph structures (NOT flattened) - preserves branching
+ * for parallel builds.
+ *
+ * Roots are sourceIDs that exist but nothing depends on them - these are
+ * the entry points for building.
+ *
+ * @param deps Array of BuildNode trees (potentially overlapping)
+ * @returns Array of root BuildNode trees (deduplicated)
+ */
+export declare function minimalBuildGraph(deps: BuildNode[]): BuildNode[];