@malloydata/malloy 0.0.427 → 0.0.429

package/dist/lang/ast/types/expression-def.js

@@ -39,7 +39,6 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExprDuration = exports.ExpressionDef = exports.ATNodeType = void 0;
 exports.getMorphicValue = getMorphicValue;
-exports.applyBinary = applyBinary;
 exports.checkFilterExpression = checkFilterExpression;
 const malloy_types_1 = require("../../../model/malloy_types");
 const TDU = __importStar(require("../typedesc-utils"));
@@ -52,6 +51,31 @@ const binary_operators_1 = require("./binary_operators");
 const malloy_filter_1 = require("@malloydata/malloy-filter");
 class TypeMismatch extends Error {
 }
+/**
+ * Mark a value as belonging to everyone. Writing into a memoized value writes
+ * into every other holder's copy and into whatever the IR already stored;
+ * freezing turns that from a silent miscompile into a TypeError naming the
+ * line which did it. Own fields only -- walking every Expr on every
+ * evaluation would cost more than the memo saves.
+ */
+function shareable(v) {
+    var _a, _b;
+    Object.freeze(v);
+    for (const share of [
+        v.value,
+        v.morphic,
+        v.refSummary,
+        (_a = v.refSummary) === null || _a === void 0 ? void 0 : _a.fieldUsage,
+        (_b = v.refSummary) === null || _b === void 0 ? void 0 : _b.givenUsage,
+        v.requiresGroupBy,
+        v.ungroupings,
+    ]) {
+        if (share !== undefined) {
+            Object.freeze(share);
+        }
+    }
+    return v;
+}
 /** Node types in an alternation tree */
 var ATNodeType;
 (function (ATNodeType) {
@@ -62,9 +86,9 @@ var ATNodeType;
 })(ATNodeType || (exports.ATNodeType = ATNodeType = {}));
 /**
  * Root node for any element in an expression. These essentially
- * create a sub-tree in the larger AST. Expression nodes know
- * how to write themselves as SQL (or rather, generate the
- * template for SQL required by the query writer)
+ * create a sub-tree in the larger AST. An ExpressionDef, when
+ * given a FieldSpace, can be evaluated to produce an ExprValue
+ * which is the IR for an Expr along with its type and other metadata.
  */
 class ExpressionDef extends malloy_element_1.MalloyElement {
     constructor() {
@@ -74,6 +98,53 @@ class ExpressionDef extends malloy_element_1.MalloyElement {
     granular() {
         return false;
     }
+    /**
+     * Returns the "translation" or Expr tree for SQL generation. When asking
+     * for a translation you may pass the types you can accept, allowing
+     * the translation code a chance to convert to match your expectations
+     * @param space Namespace for looking up field references
+     *
+     * THE RETURNED ExprValue IS SHARED -- TREAT IT AS IMMUTABLE. Asking twice
+     * yields the same object, so to derive a value from one, build a new one:
+     * `{...operand, type: 'boolean'}` or `computedExprValue({…, from: [operand]})`.
+     *
+     * DO NOT OVERRIDE THIS. Nodes implement `computeExpression`; an override
+     * here bypasses the memo, which for `+`/`-` chains is the difference
+     * between linear and exponential compile time.
+     */
+    getExpression(fs) {
+        const initialGeneration = fs.generation();
+        if (this.memoValue !== undefined &&
+            this.memoFs === fs &&
+            this.memoGen === initialGeneration) {
+            return this.memoValue;
+        }
+        // If we get here and memoFs is set and memoGen is not set, then somewhere
+        // inside this expression is a recursive call asking this node for the
+        // value it is in the middle of computing. There is nothing to return and
+        // computing one would recurse again, so throw. An abandoned computation
+        // does not look like this -- see the finally below.
+        if (this.memoFs !== undefined && this.memoGen === undefined) {
+            throw this.internalError(`ExpressionDef.getExpression memoization failure on ${this.elementType}`);
+        }
+        this.memoFs = fs;
+        this.memoGen = undefined;
+        try {
+            const value = this.computeExpression(fs);
+            if (initialGeneration === fs.generation()) {
+                this.memoGen = initialGeneration;
+                this.memoValue = shareable(value);
+            }
+            return value;
+        }
+        finally {
+            if (this.memoGen === undefined) {
+                // Threw, or a name was rebound while we ran. Leave no stamp: a caller
+                // which recovers must get a fresh computation, not our remains.
+                this.memoFs = undefined;
+            }
+        }
+    }
     /**
      * Some operators want to give the right hand value a chance to
      * rewrite itself. This requests a translation for a rewrite,
@@ -110,17 +181,38 @@ class ExpressionDef extends malloy_element_1.MalloyElement {
         return undefined;
     }
     /**
-     * This is the operation which makes partial comparison and value trees work
-     * The default implementation merely constructs LEFT OP RIGHT, but specialized
-     * nodes like alternation trees or or partial comparison can control how
-     * the appplication gets generated
+     * This is the operation which makes partial comparison and value trees work.
+     * `this` is the RIGHT operand; the left arrives here as an argument. All of
+     * the magic of malloy expressions eventually flows through here, where an
+     * operator is applied to two values -- depending on the operator and the
+     * value types that may transform the values or even the operator.
+     *
+     * Specialized nodes like alternation trees and partial comparisons override
+     * this to control how the application gets generated. They are the reason
+     * the right operand is in charge: a partial has no bound left operand, and
+     * only learns it here.
      * @param fs The symbol table
      * @param op The operator being applied
-     * @param expr The "other" (besdies 'this') value
+     * @param left The "other" (besides 'this') value
      * @return The translated expression
      */
     apply(fs, op, left, _warnOnComplexTree = false) {
-        return applyBinary(fs, left, op, this);
+        if ((0, binary_operators_1.isEquality)(op)) {
+            return equality(fs, left, op, this);
+        }
+        if ((0, binary_operators_1.isComparison)(op)) {
+            return compare(fs, left, op, this);
+        }
+        if (op === '+' || op === '-') {
+            return delta(fs, left, op, this);
+        }
+        if (op === '*') {
+            return numeric(fs, left, op, this);
+        }
+        if (op === '/' || op === '%') {
+            return divmod(fs, left, op, this);
+        }
+        return left.loggedErrorExpr('unexpected-binary-operator', `Cannot use ${op} operator here`);
     }
     canSupportPartitionBy() {
         return false;
@@ -178,7 +270,7 @@ class ExprDuration extends ExpressionDef {
         }
         return super.apply(fs, op, left);
     }
-    getExpression(fs) {
+    computeExpression(fs) {
         const num = this.n.getExpression(fs);
         return (0, expr_value_1.computedErrorExprValue)({
             dataType: { type: 'duration' },
@@ -402,6 +494,30 @@ function numeric(fs, left, op, right) {
     }
     return (0, ast_utils_1.errorFor)('numbers required');
 }
+function divmod(fs, left, op, right) {
+    const num = left.getExpression(fs);
+    const denom = right.getExpression(fs);
+    const noGo = unsupportError(left, num, right, denom);
+    if (noGo)
+        return noGo;
+    const err = errorCascade('number', num, denom);
+    if (err)
+        return err;
+    if (num.type !== 'number') {
+        left.logError('arithmetic-operation-type-mismatch', 'Numerator must be a number');
+    }
+    else if (denom.type !== 'number') {
+        right.logError('arithmetic-operation-type-mismatch', 'Denominator must be a number');
+    }
+    else {
+        return (0, expr_value_1.computedExprValue)({
+            dataType: mergeNumberTypes(num, denom, op),
+            value: { node: op, kids: { left: num.value, right: denom.value } },
+            from: [num, denom],
+        });
+    }
+    return (0, ast_utils_1.errorFor)('divide type mismatch');
+}
 function delta(fs, left, op, right) {
     const lhs = left.getExpression(fs);
     const rhs = right.getExpression(fs);
@@ -430,60 +546,6 @@ function delta(fs, left, op, right) {
     }
     return numeric(fs, left, op, right);
 }
-/**
- * All of the magic of malloy expressions eventually flows to here,
- * where an operator is applied to two values. Depending on the
- * operator and value types this may involve transformations of
- * the values or even the operator.
- * @param fs FieldSpace for the symbols
- * @param left Left value
- * @param op The operator
- * @param right Right Value
- * @return ExprValue of the expression
- */
-function applyBinary(fs, left, op, right) {
-    if ((0, binary_operators_1.isEquality)(op)) {
-        return equality(fs, left, op, right);
-    }
-    if ((0, binary_operators_1.isComparison)(op)) {
-        return compare(fs, left, op, right);
-    }
-    if (op === '+' || op === '-') {
-        return delta(fs, left, op, right);
-    }
-    if (op === '*') {
-        return numeric(fs, left, op, right);
-    }
-    if (op === '/' || op === '%') {
-        const num = left.getExpression(fs);
-        const denom = right.getExpression(fs);
-        const noGo = unsupportError(left, num, right, denom);
-        if (noGo)
-            return noGo;
-        const err = errorCascade('number', num, denom);
-        if (err)
-            return err;
-        if (num.type !== 'number') {
-            left.logError('arithmetic-operation-type-mismatch', 'Numerator must be a number');
-        }
-        else if (denom.type !== 'number') {
-            right.logError('arithmetic-operation-type-mismatch', 'Denominator must be a number');
-        }
-        else {
-            const divmod = {
-                node: op,
-                kids: { left: num.value, right: denom.value },
-            };
-            return (0, expr_value_1.computedExprValue)({
-                dataType: mergeNumberTypes(num, denom, op),
-                value: divmod,
-                from: [num, denom],
-            });
-        }
-        return (0, ast_utils_1.errorFor)('divide type mismatch');
-    }
-    return left.loggedErrorExpr('unexpected-binary-operator', `Cannot use ${op} operator here`);
-}
 function errorCascade(type, ...es) {
     if (es.some(e => e.type === 'error')) {
         return (0, expr_value_1.computedExprValue)({

package/dist/lang/ast/types/field-space.d.ts

@@ -4,6 +4,14 @@ import type { QueryOperationSpace } from '../field-space/query-spaces';
 import type { LookupResult } from './lookup-result';
 import { MalloyElement } from './malloy-element';
 import type { SpaceEntry } from './space-entry';
+export declare function currentGeneration(): number;
+/**
+ * Called by every field space operation that binds, rebinds or unbinds a
+ * name. Lazily materializing a space's entries from its StructDef is not
+ * such an operation -- the bindings were already logically present, so
+ * nothing a cache observed can have changed.
+ */
+export declare function noteRebinding(): void;
 /**
  * A FieldSpace is a hierarchy of namespaces, where the leaf nodes
  * are fields. A FieldSpace can lookup fields, and generate a StructDef
@@ -20,6 +28,12 @@ export interface FieldSpace {
     connectionName(): string;
     isQueryFieldSpace(): this is QueryFieldSpace;
     accessProtectionLevel(): AccessModifierLabel;
+    /**
+     * A value which changes whenever any name binding changes. A result
+     * computed by consulting this space may be reused only while this is
+     * unchanged. See `noteRebinding` above.
+     */
+    generation(): number;
 }
 export interface SourceFieldSpace extends FieldSpace {
     structDef(): SourceDef;

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

@@ -5,7 +5,43 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FieldName = void 0;
+exports.currentGeneration = currentGeneration;
+exports.noteRebinding = noteRebinding;
 const malloy_element_1 = require("./malloy-element");
+/**
+ * Some field spaces are static, some are dynamic. We are computing a very
+ * conservative process wide "generation" which moves forward when any
+ * dynamic field space changes. We can be very certain that if the field space
+ * generation has not changed, computations depending on the contents of
+ * field spaces are still valid.
+ *
+ * A more fine grained validity is hard to compute and possibly a fragile
+ * computation. Spaces delegate to each other -- a passthrough wraps another
+ * space, a query output space resolves names through its input space -- so a
+ * per-space generation has to forward through every one of those paths, and a
+ * path we missed is a stale cache we never notice. We think this simple
+ * approach will be good enough for a long time, possibly forever.
+ *
+ * This does not cover a computation which reads something other than a field
+ * space. `GivenReference` ignores the FieldSpace it is handed and reads the
+ * Document namespace, which never moves this counter. Nothing is known to
+ * depend on that, since document definitions happen between statements, but
+ * do not assume a cache is covered here just because it consults a field
+ * space as well.
+ */
+let bindingGeneration = 0;
+function currentGeneration() {
+    return bindingGeneration;
+}
+/**
+ * Called by every field space operation that binds, rebinds or unbinds a
+ * name. Lazily materializing a space's entries from its StructDef is not
+ * such an operation -- the bindings were already logically present, so
+ * nothing a cache observed can have changed.
+ */
+function noteRebinding() {
+    bindingGeneration += 1;
+}
 class FieldName extends malloy_element_1.MalloyElement {
     constructor(name) {
         super();

package/dist/lang/ast/types/query-element.d.ts

@@ -2,7 +2,21 @@ import type { MalloyElement } from './malloy-element';
 import type { Query } from '../../../model/malloy_types';
 import type { QueryComp } from './query-comp';
 export interface QueryElement extends MalloyElement {
-    queryComp(isRefOk: boolean): QueryComp;
+    /**
+     * Both arguments say what looseness the caller will accept.
+     *
+     * @param isRefOk `structRef` may be left as the name of a source. False
+     *   means expand it, which is what a caller writing this query into
+     *   something that must stand on its own needs.
+     * @param isPartialOk The pipeline may contain `partial` segments, whose
+     *   query class is not decided yet. Only the base of a refinement can
+     *   accept those, because the refinement is what decides the class.
+     *   False means the pipeline is finished and the compiler can read it —
+     *   any partial found is made a `reduce` and reported as
+     *   `ambiguous-view-type`, so passing false decides where that error
+     *   lands and when it is logged relative to the rest of the pipeline.
+     */
+    queryComp(isRefOk: boolean, isPartialOk: boolean): QueryComp;
     query(isRefOk?: boolean): Query;
 }
 export declare function isQueryElement(e: MalloyElement): e is QueryElement;

package/dist/lang/parse-log.d.ts

@@ -248,11 +248,13 @@ type MessageParameterTypes = {
     'unexpected-source-property': string;
     'aggregate-in-source-filter': string;
     'invalid-connection-for-sql-source': string;
+    'sql-source-connection-mismatch': string;
     'failed-to-fetch-sql-source-schema': string;
     'invalid-sql-source': string;
     'non-top-level-sql-source': string;
     'failed-to-fetch-table-schema': string;
     'invalid-connection-for-table-source': string;
+    'join-connection-mismatch': string;
     'join-on-primary-key-type-mismatch': string;
     'join-primary-key-not-found': string;
     'join-with-without-primary-key': string;

package/dist/lang/test/test-translator.d.ts

@@ -19,6 +19,13 @@ export declare function pretty(thing: unknown): string;
 export declare function humanify(value: unknown): string;
 export declare const TEST_DIALECT = "duckdb";
 export declare const aTableDef: TableSourceDef;
+/**
+ * A second connection speaking the same dialect as `_db_`. Two sources can
+ * then compile to identical SQL on different connections, which isolates the
+ * connection check from the dialect check, and is exactly the case where
+ * persistence could forget that a build target is a table on a connection.
+ */
+export declare const db2TableDef: TableSourceDef;
 export declare const bqTableDef: SourceDef;
 export declare const pgTableDef: SourceDef;
 /**
@@ -128,4 +135,14 @@ export declare function warningMessage(message: string | RegExp): {
     message: string | RegExp;
     severity: LogSeverity;
 };
+/**
+ * Drain a translation's SQL schema requests, answering each with the schema of
+ * `aTable` on the connection which asked, until it stops asking. A `sql()`
+ * source needs a schema before the translation can finish, and nothing in a
+ * TestTranslator provides one.
+ *
+ * @param selectStr What to record as the block's SELECT. Defaults to the
+ *   statement which was requested; pass a value to hand back something else.
+ */
+export declare function answerSQLSchemaRequests(translator: TestTranslator, selectStr?: string): void;
 export {};

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

@@ -5,7 +5,7 @@
  * SPDX-License-Identifier: MIT
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BetaExpression = exports.TestTranslator = exports.TestChildTranslator = exports.mockSchema = exports.pgTableDef = exports.bqTableDef = exports.aTableDef = exports.TEST_DIALECT = void 0;
+exports.BetaExpression = exports.TestTranslator = exports.TestChildTranslator = exports.mockSchema = exports.pgTableDef = exports.bqTableDef = exports.db2TableDef = exports.aTableDef = exports.TEST_DIALECT = void 0;
 exports.pretty = pretty;
 exports.humanify = humanify;
 exports.getExplore = getExplore;
@@ -24,6 +24,7 @@ exports.error = error;
 exports.warning = warning;
 exports.errorMessage = errorMessage;
 exports.warningMessage = warningMessage;
+exports.answerSQLSchemaRequests = answerSQLSchemaRequests;
 const util_1 = require("util");
 const malloy_types_1 = require("../../model/malloy_types");
 const ast_1 = require("../ast");
@@ -162,6 +163,16 @@ exports.aTableDef = {
         { type: 'timestamptz', name: 'atstz' }, // duckdb supports timestamptz
     ],
 };
+/**
+ * A second connection speaking the same dialect as `_db_`. Two sources can
+ * then compile to identical SQL on different connections, which isolates the
+ * connection check from the dialect check, and is exactly the case where
+ * persistence could forget that a build target is a table on a connection.
+ */
+exports.db2TableDef = {
+    ...exports.aTableDef,
+    connection: '_db2_',
+};
 // BigQuery-compatible table definition (no timestamptz support)
 exports.bqTableDef = {
     type: 'table',
@@ -188,6 +199,7 @@ exports.pgTableDef = {
  */
 exports.mockSchema = [
     exports.aTableDef,
+    exports.db2TableDef,
     exports.bqTableDef,
     exports.pgTableDef,
     {
@@ -331,11 +343,15 @@ class TestTranslator extends parse_malloy_1.MalloyTranslator {
         this.testSrc = testSrc;
         this.allDialectsEnabled = true;
         /*
-         * There are two connections:
+         * There are four connections:
          *   _db_  - duckdb dialect, with the following tables ...
          *      aTable, malloytest.carriers, malloytest.flights, malloytest.airports
+         *   _db2_ - duckdb dialect, with one table, aTable. A second connection
+         *      on the same dialect as _db_, for cross-connection tests.
          *   _bq_  - bigquery/standardsql dialect, with one table
          *      aTable
+         *   _pg_  - postgres 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
@@ -361,6 +377,7 @@ class TestTranslator extends parse_malloy_1.MalloyTranslator {
             ...(0, utils_1.mkModelDef)(testURI, testURI),
             contents: {
                 _db_: { type: 'connection', name: '_db_' },
+                _db2_: { type: 'connection', name: '_db2_' },
                 _bq_: { type: 'connection', name: '_bq_' },
                 _pg_: { type: 'connection', name: '_pg_' },
                 a: { ...exports.aTableDef, primaryKey: 'astr', name: 'a' },
@@ -417,6 +434,7 @@ class TestTranslator extends parse_malloy_1.MalloyTranslator {
             this.schemaZone.define(`${actualSchema.connection}:${actualSchema.tablePath}`, actualSchema);
         }
         this.connectionDialectZone.define('_db_', exports.TEST_DIALECT);
+        this.connectionDialectZone.define('_db2_', exports.TEST_DIALECT);
         this.connectionDialectZone.define('_bq_', 'standardsql');
         this.connectionDialectZone.define('_pg_', 'postgres');
         for (const flag of (_e = options.compilerFlags) !== null && _e !== void 0 ? _e : []) {
@@ -694,4 +712,30 @@ function errorMessage(message) {
 function warningMessage(message) {
     return { message, severity: 'warn' };
 }
+/**
+ * Drain a translation's SQL schema requests, answering each with the schema of
+ * `aTable` on the connection which asked, until it stops asking. A `sql()`
+ * source needs a schema before the translation can finish, and nothing in a
+ * TestTranslator provides one.
+ *
+ * @param selectStr What to record as the block's SELECT. Defaults to the
+ *   statement which was requested; pass a value to hand back something else.
+ */
+function answerSQLSchemaRequests(translator, selectStr) {
+    for (;;) {
+        const compileSQL = translator.translate().compileSQL;
+        if (compileSQL === undefined)
+            return;
+        const key = (0, sql_block_1.sqlKey)(compileSQL.connection, compileSQL.selectStr);
+        const schema = {
+            type: 'sql_select',
+            name: key,
+            dialect: exports.TEST_DIALECT,
+            connection: compileSQL.connection,
+            selectStr: selectStr !== null && selectStr !== void 0 ? selectStr : compileSQL.selectStr,
+            fields: exports.aTableDef.fields,
+        };
+        translator.update({ compileSQL: { [key]: schema } });
+    }
+}
 //# sourceMappingURL=test-translator.js.map

package/dist/model/malloy_types.d.ts

@@ -801,19 +801,6 @@ export declare function mkRefSummary({ fieldUsage, givenUsage, }: {
  * untouched without each call site having to know about them.
  */
 export declare function mapFieldUsage(rs: RefSummary | undefined, fn: (u: FieldUsageEntry) => FieldUsageEntry): RefSummary | undefined;
-/**
- * Mutating setter for a node's `fieldUsage`. When the node already has a
- * `refSummary`, replaces just the `fieldUsage` slice (preserving `givenUsage`
- * and any future RefSummary fields). When it doesn't, creates a fresh
- * `refSummary` with the supplied usages.
- *
- * Use at sites that mutate an already-constructed IR node; for sites that
- * build a node from a literal, write `{fieldUsage: [...]}` directly or use
- * `mkRefSummary` for possibly-undefined inputs.
- */
-export declare function setFieldUsage(target: {
-    refSummary?: RefSummary;
-}, usages: FieldUsage): void;
 export interface QuerySegment extends Filtered, Ordered, SegmentUsageSummary {
     type: 'reduce' | 'project' | 'partial';
     queryFields: QueryFieldDef[];

package/dist/model/malloy_types.js

@@ -64,7 +64,6 @@ exports.fieldUsageFrom = fieldUsageFrom;
 exports.givenUsageFrom = givenUsageFrom;
 exports.mkRefSummary = mkRefSummary;
 exports.mapFieldUsage = mapFieldUsage;
-exports.setFieldUsage = setFieldUsage;
 exports.isSegmentSQL = isSegmentSQL;
 exports.isSegmentSource = isSegmentSource;
 exports.isSourceRegistryReference = isSourceRegistryReference;
@@ -491,24 +490,6 @@ function mkRefSummary({ fieldUsage, givenUsage, }) {
 function mapFieldUsage(rs, fn) {
     return rs && { ...rs, fieldUsage: rs.fieldUsage.map(fn) };
 }
-/**
- * Mutating setter for a node's `fieldUsage`. When the node already has a
- * `refSummary`, replaces just the `fieldUsage` slice (preserving `givenUsage`
- * and any future RefSummary fields). When it doesn't, creates a fresh
- * `refSummary` with the supplied usages.
- *
- * Use at sites that mutate an already-constructed IR node; for sites that
- * build a node from a literal, write `{fieldUsage: [...]}` directly or use
- * `mkRefSummary` for possibly-undefined inputs.
- */
-function setFieldUsage(target, usages) {
-    if (target.refSummary) {
-        target.refSummary.fieldUsage = usages;
-    }
-    else {
-        target.refSummary = { fieldUsage: usages };
-    }
-}
 function isSegmentSQL(f) {
     return 'sql' in f;
 }

package/dist/model/persist_utils.d.ts

@@ -1,4 +1,4 @@
-import type { ModelDef, SourceDef, Query } from './malloy_types';
+import type { ModelDef, SourceDef, Query, SourceID } from './malloy_types';
 import type { LogMessage } from '../lang';
 import type { BuildNode } from '../api/foundation/types';
 /**
@@ -10,15 +10,50 @@ export declare function checkPersistAnnotation(source: SourceDef): {
     log: LogMessage[];
 };
 /**
- * Find persistent dependencies for a source or query, returning a nested DAG.
+ * One persistable source the walk found, and the sources it directly
+ * references.
  *
- * 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.
+ * Edges are sourceIDs rather than nested nodes, so there is no shared object
+ * to be careful about and nothing to recurse through — a consumer folds the
+ * stream in one pass.
+ */
+export interface PersistNode {
+    sourceID: SourceID;
+    /**
+     * Whether this source is itself something to build. `false` means it is a
+     * *route*: it materializes nothing, but it is how the walk reached something
+     * that does.
+     */
+    persistent: boolean;
+    /** The sources it reaches directly, each of which was yielded already */
+    dependsOn: SourceID[];
+}
+/**
+ * A walk in progress: yields a {@link PersistNode} per source kept, and
+ * finally returns the sources the roots themselves reached.
+ */
+export type PersistWalk = Generator<PersistNode, SourceID[]>;
+/**
+ * Walk everything a source or query references, and emit the sources that
+ * matter to persistence — in dependency order, each one after everything it
+ * depends on.
+ *
+ * A source is emitted if it is persistent — something to build — or if it
+ * is the *route* to something persistent. Everything else is dropped; a
+ * source with nothing persistent beneath it is of no interest to anybody.
+ *
+ * One rule decides both halves, applied on the way back up:
+ *
+ *     keep me if I am persistent, or if any child survived
  *
- * 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 second clause needs no lookahead. A child only survived under this same
+ * rule, so a surviving child *is* the proof that something persistent lies
+ * below. For `a(persist) → b → c(persist) → d`, d has nothing beneath it
+ * and is dropped, c is kept for being persistent, b is kept for leading to c.
+ *
+ * Because a node arrives only after everything it depends on, a consumer can
+ * fold the stream in a single pass with no second lookup — whether it wants
+ * every source touched, or only the ones that are tables.
  *
  * ## The 6 Dependency Paths in the IR
  *
@@ -35,9 +70,25 @@ export declare function checkPersistAnnotation(source: SourceDef): {
  * Note: CompositeSourceDef.sources[] is ignored - composite sources and
  * persistence may be incompatible features.
  *
- * @param root The source or query to find dependencies for
+ * Joins are followed whether or not a query activates them, so what comes back
+ * is what a source *could* depend on. An unused join is a dependency the SQL
+ * will not contain — an over-approximation, which costs ordering freedom and
+ * never correctness.
+ *
+ * @param roots The sources and queries to walk, sharing one memo
  * @param modelDef The model definition containing the source registry
- * @returns Array of BuildNode representing the persistent dependency DAG
+ * @param tagParseLog Collects errors from parsing `#@` annotations
+ */
+export declare function walkPersistentDependencies(roots: (SourceDef | Query)[], modelDef: ModelDef, tagParseLog?: LogMessage[]): PersistWalk;
+/**
+ * The persistent sources a source or query depends on, as a nested DAG.
+ *
+ * A source that is not itself persistent never appears; its persistent
+ * dependencies become direct dependencies of whoever referenced it. So
+ * `c (persist) → b → a (persist)` yields `[{sourceID: a, dependsOn: []}]`.
+ *
+ * @deprecated The nested shape exists for `Model.getBuildPlan()`, which is on
+ * its way out. Consume {@link walkPersistentDependencies} directly.
  */
 export declare function findPersistentDependencies(root: SourceDef | Query, modelDef: ModelDef, tagParseLog?: LogMessage[]): BuildNode[];
 /**