sqllens 1.0.0 → 1.2.0

package/dist/qualify/check-calls.js

@@ -1,51 +1,42 @@
 import { endPosition } from "../ir/span.js";
 import { inferType } from "../infer/infer.js";
-import { inferDialect } from "../infer/dialect.js";
-import { FUNCTION_SIGNATURES, HARVESTED_SIGNATURES } from "../signature/signatures.js";
+import { behaviorOf } from "../dialect-behavior/carrier.js";
 // ---------------------------------------------------------------------------
-// Call-signature diagnostics — arity + operand types, over the modelled function
+// Call-signature diagnostics: arity + operand types, over the modelled function
 // calls in the IR. Never-wrong: a diagnostic fires ONLY when the checker is
 // certain the call is wrong. Two rules, in order of strictness:
 //
-//  - ARITY (curated only): the name is in the CURATED signature table AND the
-//    call's arg count is matched by NO overload's [min, max] window → wrong-arity.
-//    A variadic signature accepts any count (the last param repeats), so it never
-//    flags. min = the count of non-optional params; max = the param count.
+//  - ARITY (both origins): the name is in the dialect's merged signature table
+//    (src/<dialect>/signatures.generated.ts, curated overrides folded over the
+//    harvested long tail), and it maps to an ORDERED OVERLOAD SET, not a single
+//    shape. It fires wrong-arity only when the call's arg count is matched by
+//    NO overload's [min, max] window. A variadic overload accepts any count at
+//    or above its own min (the last param repeats), so it never itself causes a
+//    flag. min = the count of non-optional params; max = the param count. Every
+//    overload's origin is trusted for arity (the harvested tables carry a
+//    trustworthy optional/variadic encoding, tools/harvest-signatures.mjs's
+//    NEVER-WRONG CONTRACT), so this is a union check across the whole set.
 //
-//  - OPERAND TYPE (curated only): every argument type is inferable (≠ unknown)
-//    AND some argument position is rejected under `accepts()` (no implicit
-//    widening path to the declared param type) → wrong-argument-type. Any
-//    `unknown` argument type anywhere makes the whole call silent.
-//
-// HARVESTED signatures are NOT trusted for either rejection: their param lists
-// (tools/harvest-signatures.mjs, T-SQL 151 entries) carry no optional/variadic
-// encoding and no reliable types, so an arity/type check over them would fire on
-// valid SQL (see ARITY_USES_HARVESTED below). They still drive signatureAt() hints.
+//  - OPERAND TYPE: only when the name has EXACTLY ONE overload and its origin is
+//    "curated", the unambiguous case. A 2+-overload name skips type checking
+//    entirely (which specific overload the call means isn't decided here, so no
+//    operand-type rejection can be trusted). When it does apply: every argument
+//    type is inferable (not unknown) AND some argument position is rejected
+//    under `accepts()` (no implicit widening path to the declared param type),
+//    so it fires wrong-argument-type. Any `unknown` argument type anywhere makes
+//    the whole call silent. A harvested-origin overload never drives a
+//    wrong-argument-type diagnostic (its param types aren't reliable enough).
 //
 // A qualified/dotted call (`ns.fn(...)`, sequence `.NEXTVAL`) does NOT match a
-// bare-name curated entry — the tables are bare-name only, so it stays silent.
+// bare-name signature: the table is bare-name only, so it stays silent.
 // A named-argument call (`fn(x => v)`) can't be mapped to a positional arg list
 // confidently, so it too stays silent.
 //
 // The checker walks the scope tree; for each scope it inspects THAT scope's own
-// expressions (not nested subquery/EXISTS bodies — those are checked when their
+// expressions (not nested subquery/EXISTS bodies: those are checked when their
 // child scope is visited), so an argument's type is inferred in the scope where
 // the call actually lives.
 // ---------------------------------------------------------------------------
-/** Risk-flag (c) escape hatch. Harvested arity data (T-SQL's 151-entry generated table is the only
- *  one today) does not encode which params are optional, nor mark variadic reliably, so an arity
- *  check over it fires on valid SQL. Kept curated-only, VISIBLY, for every dialect. Flip a dialect
- *  on only once its harvested table earns it (optional/variadic encoding proven against the corpus). */
-const ARITY_USES_HARVESTED = {
-    databricks: false,
-    tsql: false,
-    snowflake: false,
-    bigquery: false,
-    redshift: false,
-    postgres: false,
-    duckdb: false,
-    trino: false,
-};
 export function checkCalls(tree, schema, diagnostics) {
     const visit = (scope) => {
         for (const expr of ownExprs(scope))
@@ -161,140 +152,95 @@ function checkOneCall(fn, scope, schema, diagnostics) {
     // A named-argument invocation (fn(x => v)) can't be mapped to a positional arg list confidently.
     if (fn.argNames?.some((n) => n !== undefined))
         return;
-    // A qualified/dotted call must not borrow a bare-name signature (the tables are bare-name only).
+    // A qualified/dotted call must not borrow a bare-name signature (the table is bare-name only).
     if (fn.qualifier !== undefined)
         return;
     // Aggregate / window / DISTINCT forms carry modifiers the IR folds into (or out of) the arg list
-    // unevenly — count(*)→0 args, sum(x) FILTER/OVER/WITHIN GROUP, a dropped DISTINCT keyword — so the
-    // positional arg count isn't a reliable signal. Per the never-wrong contract, stay SILENT on them.
+    // unevenly: count(*) becomes 0 args, sum(x) FILTER/OVER/WITHIN GROUP, a dropped DISTINCT keyword,
+    // so the positional arg count isn't a reliable signal. Per the never-wrong contract, stay SILENT.
     if (fn.aggregate || fn.window || fn.distinct)
         return;
-    const dialect = scope.dialect;
+    const b = behaviorOf(scope);
     const name = fn.name.toLowerCase();
-    const curated = FUNCTION_SIGNATURES[dialect]?.[name];
-    // Arity overloads: the curated signature always; the harvested one ONLY for a dialect whose
-    // harvested arity data is trusted (none today — see ARITY_USES_HARVESTED). The rule fires when NO
-    // overload accepts the arg count.
-    const overloads = [];
-    if (curated)
-        overloads.push(curated);
-    if (ARITY_USES_HARVESTED[dialect]) {
-        const harvested = HARVESTED_SIGNATURES[dialect]?.[name];
-        if (harvested && harvested !== curated)
-            overloads.push(harvested);
-    }
-    if (overloads.length === 0)
-        return; // uncurated (and no trusted harvested) — silent
+    const overloads = b.signatures[name];
+    if (!overloads)
+        return; // unknown name, silent
     const args = fn.args;
     // Trust the IR arg list ONLY when it faithfully mirrors what was written. Some special call forms
     // lower to an arg list that doesn't match the source positionally: a keyword arg the lowering drops
     // (T-SQL/BigQuery DATEADD/DATE_DIFF's datepart), a boolean condition split into comparands (T-SQL
     // IIF), or the SQL-standard `f(x FROM y FOR z)` / nested-call over-capture (Postgres-family TRIM/
     // SUBSTRING). Comparing the IR arg count to the top-level comma count in the written call catches all
-    // of these generically — a mismatch means the positional shape isn't reliable, so stay SILENT.
+    // of these generically: a mismatch means the positional shape isn't reliable, so stay SILENT.
     const written = writtenArgCount(fn.cst);
     if (written !== null && written !== args.length)
         return;
-    // --- arity: fire only when NO overload accepts the count ---
-    if (overloads.every((s) => !arityAccepts(s, args.length))) {
+    // --- arity: fires only when NO overload's [min, max] window accepts the count ---
+    if (!arityAccepts(overloads, args.length)) {
         diagnostics.push(callDiag("wrong-arity", fn.cst, arityMessage(overloads, args.length)));
         return; // one diagnostic per call — don't also type-check a call of the wrong shape
     }
-    // --- operand type (CURATED only — harvested param types are never trusted for rejection) ---
-    if (!curated)
+    // --- operand type: only the unambiguous case, exactly one overload and it's curated-origin ---
+    if (overloads.length !== 1)
+        return;
+    const sig = overloads[0];
+    if (sig.origin !== "curated")
         return;
     const types = args.map((a) => inferType(a, scope, schema));
     if (types.some((t) => t.kind === "unknown"))
         return; // any unknown → silent
     for (let i = 0; i < types.length; i++) {
-        const param = curated.variadic ? curated.params[Math.min(i, curated.params.length - 1)] : curated.params[i];
-        if (param && !accepts(types[i], param.type, dialect)) {
-            diagnostics.push(callDiag("wrong-argument-type", fn.cst, argMessage(curated, i, param.type ?? "?", types[i])));
+        const param = sig.variadic ? sig.params[Math.min(i, sig.params.length - 1)] : sig.params[i];
+        if (param && !b.accepts(types[i], param.type)) {
+            diagnostics.push(callDiag("wrong-argument-type", fn.cst, argMessage(sig, i, param.type ?? "?", types[i])));
             return; // one diagnostic per call
         }
     }
 }
-/** Whether a signature accepts `n` positional args. A variadic signature accepts any count (its last
- *  param repeats); a fixed one accepts [non-optional count, param count]. */
-function arityAccepts(sig, n) {
-    if (sig.variadic)
-        return true;
-    const min = sig.params.filter((p) => !p.optional).length;
-    return n >= min && n <= sig.params.length;
-}
-const NUMERIC = new Set(["tinyint", "smallint", "int", "bigint", "float", "double", "decimal"]);
-const TEMPORAL = new Set(["date", "timestamp", "time", "interval"]);
-function familyOf(name) {
-    if (NUMERIC.has(name))
-        return "num";
-    if (name === "string")
-        return "str";
-    if (name === "boolean")
-        return "bool";
-    if (TEMPORAL.has(name))
-        return "temporal";
-    if (name === "binary")
-        return "binary";
-    return "other";
-}
-/** Dialects that implicitly bridge STRING→numeric in a function argument, so a str→num mismatch must
- *  NOT be flagged. Doc-cited per dialect:
- *  - databricks: implicit crosscasting casts STRING to the expected numeric type
- *    (docs.databricks.com/sql/language-manual/sql-ref-datatype-rules — the docs corpus itself carries
- *    `substring('hello', '1', 2)` and `date_add(date'2011-11-30', '5')` as documented-valid examples);
- *  - tsql: char/varchar→int/decimal is an implicit conversion in the CAST/CONVERT conversion chart
- *    (learn.microsoft.com/sql/t-sql/functions/cast-and-convert-transact-sql) — `ABS('1')` is valid;
- *  - snowflake: VARCHAR containing a number coerces to NUMBER
- *    (docs.snowflake.com/en/sql-reference/data-type-conversion — implicit casting/coercion);
- *  - redshift: PG-8.0 lineage keeps pre-8.3 implicit text→numeric casts
- *    (docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html — type compatibility:
- *    CHAR/VARCHAR→numeric implicit);
- *  - postgres / duckdb: a quoted constant is initially of UNKNOWN type (postgresql.org/docs/18
- *    sql-syntax-lexical §4.1.2.1) and coerces to whatever the call needs — `abs('1')` is valid — but
- *    our inference types every quoted literal as `string`, so a str-typed arg may really be an
- *    untyped literal; rejecting would false-fire on valid SQL.
- *  NOT in the set (rejection stays live, corpus-proven): bigquery — no STRING→numeric coercion in the
- *  conversion rules (`ABS('1')` is "No matching signature"; 14.7k analyzer positives sweep clean);
- *  trino — implicit coercion is numeric/character widening only (`abs('1')` is "Unexpected
- *  parameters"; 635 docs-corpus positives sweep clean). */
-const IMPLICIT_STR_TO_NUM = new Set([
-    "databricks",
-    "tsql",
-    "snowflake",
-    "redshift",
-    "postgres",
-    "duckdb",
-]);
-/** Dialects that implicitly bridge boolean↔numeric: T-SQL only, whose `bit` (aliased to boolean by
- *  TSQL_ALIASES) converts to/from int implicitly per the same CAST/CONVERT chart. Everywhere else
- *  bool→num / num→bool rejection is safe (Spark: "cannot resolve 'abs(true)' due to data type
- *  mismatch"; Snowflake: "Invalid argument types for function 'ABS': (BOOLEAN)"; PG/DuckDB/BigQuery/
- *  Trino likewise reject) — and corpus-proven across all eight sweeps. */
-const IMPLICIT_BOOL_NUM = new Set(["tsql"]);
-function accepts(argType, paramText, dialect) {
-    if (!paramText)
-        return true; // untyped param → no information, accept
-    const param = inferDialect(dialect).parseType(paramText);
-    if (param.kind !== "scalar" || argType.kind !== "scalar")
-        return true; // complex/unknown → accept
-    const fa = familyOf(argType.name);
-    const fp = familyOf(param.name);
-    if (fa === fp)
-        return true; // same family → accept
-    if (fa === "str" && fp === "num")
-        return IMPLICIT_STR_TO_NUM.has(dialect);
-    if ((fa === "bool" && fp === "num") || (fa === "num" && fp === "bool"))
-        return IMPLICIT_BOOL_NUM.has(dialect);
-    return true; // every other cross-family pair (incl. → str, temporal, binary, other) — accept
+/** Whether ANY overload in the set accepts `n` positional args. A variadic overload accepts any count
+ *  at or above its own min (its last param repeats); a fixed one accepts [non-optional count, param
+ *  count]. */
+function arityAccepts(overloads, n) {
+    return overloads.some((sig) => {
+        if (sig.variadic)
+            return true;
+        const min = sig.params.filter((p) => !p.optional).length;
+        return n >= min && n <= sig.params.length;
+    });
 }
 // ---------------------------------------------------------------------------
 // Diagnostics
 // ---------------------------------------------------------------------------
+/** One overload's own [min, max] arity window (max is Infinity for a variadic overload). */
+function windowOf(sig) {
+    return [sig.params.filter((p) => !p.optional).length, sig.variadic ? Infinity : sig.params.length];
+}
+/** One [lo, hi] window rendered the way a single contiguous range has always been rendered: an exact
+ *  count, an unbounded "lo+", or a "lo–hi" span (the en dash there is intentional and frozen, this
+ *  exact message shape is corpus-pinned, see tests/corpus/bigquery.analyzer.test.ts). */
+function rangeStr([lo, hi]) {
+    return lo === hi ? `${lo}` : hi === Infinity ? `${lo}+` : `${lo}–${hi}`;
+}
+/** The arity-window UNION across every overload, merged into the fewest disjoint ranges (windows that
+ *  overlap or touch collapse into one). A single-overload name always reduces to exactly one range, so
+ *  this reproduces the pre-overload-aware message byte-for-byte in that case; a genuine multi-overload
+ *  name with a gap between ranges (e.g. 2 args or 4 args, nothing in between) renders each range and
+ *  joins them with " or ". */
 function arityMessage(overloads, got) {
-    const lo = Math.min(...overloads.map((s) => s.params.filter((p) => !p.optional).length));
-    const hi = Math.max(...overloads.map((s) => (s.variadic ? Infinity : s.params.length)));
-    const want = lo === hi ? `${lo}` : hi === Infinity ? `${lo}+` : `${lo}–${hi}`;
-    return `${overloads[0].name} expects ${want} argument${hi === 1 ? "" : "s"}, got ${got}`;
+    const windows = overloads.map(windowOf).sort((a, b) => a[0] - b[0]);
+    const groups = [];
+    for (const w of windows) {
+        const last = groups[groups.length - 1];
+        if (last && w[0] <= last[1] + 1) {
+            last[1] = Math.max(last[1], w[1]);
+        }
+        else {
+            groups.push([w[0], w[1]]);
+        }
+    }
+    const want = groups.map(rangeStr).join(" or ");
+    const overallHi = Math.max(...groups.map((g) => g[1]));
+    return `${overloads[0].name} expects ${want} argument${overallHi === 1 ? "" : "s"}, got ${got}`;
 }
 function argMessage(sig, i, paramType, got) {
     const gotName = got.kind === "scalar" ? got.name : got.kind;

package/dist/qualify/qualify.js

@@ -1,5 +1,6 @@
-import { foldIdentifier, matchesSourceKey } from "../ident/fold.js";
-import { applyPivotCols, applyStarModifiers, applyUnpivotCols, likePatternToRegExp, mergeByName, pivotSourceOutputs, splitColumnRefInScope, } from "../scope/scope.js";
+import { behaviorOf } from "../dialect-behavior/carrier.js";
+import { resolveBehavior } from "../dialect-behavior/registry.js";
+import { applyPivotCols, applyStarModifiers, applyUnpivotCols, mergeByName, pivotSourceOutputs, splitColumnRefInScope, } from "../scope/scope.js";
 import { endPosition } from "../ir/span.js";
 import { inferType } from "../infer/infer.js";
 import { checkCalls } from "./check-calls.js";
@@ -161,7 +162,7 @@ function resolvePipeStage(scope, schema, resolved, diagnostics, starPairs) {
             return [...aggs, ...keys];
         }
         case "drop": {
-            const fold = (n) => foldIdentifier(n, scope.dialect);
+            const fold = (n) => behaviorOf(scope).fold(n);
             return incoming === "unknown"
                 ? "unknown"
                 : incoming.filter((c) => !stage.drop.some((d) => fold(d) === fold(c)));
@@ -169,7 +170,7 @@ function resolvePipeStage(scope, schema, resolved, diagnostics, starPairs) {
         case "rename": {
             if (incoming === "unknown")
                 return "unknown";
-            const fold = (n) => foldIdentifier(n, scope.dialect);
+            const fold = (n) => behaviorOf(scope).fold(n);
             const map = new Map(stage.renames.map((r) => [fold(r.from), r.to]));
             return incoming.map((c) => map.get(fold(c)) ?? c);
         }
@@ -211,7 +212,7 @@ function expandStarPairs(scope, schema, resolved, diagnostics, qualifier) {
     const cols = [];
     let matched = false;
     for (const [key, src] of scope.sources) {
-        if (want !== undefined && !matchesSourceKey(key, want, scope.dialect))
+        if (want !== undefined && !behaviorOf(scope).matchesSourceKey(key, want))
             continue;
         // A pseudo-column source (Snowflake/Oracle CONNECT BY's LEVEL) resolves by name but is
         // excluded from a bare `*` — real pseudo-column semantics. A qualified star can't target
@@ -237,15 +238,16 @@ function expandStar(scope, schema, resolved, diagnostics, qualifier) {
  *  has its own established call sites (e.g. projectionColumns below) that don't need sourceKey and
  *  whose signature this task leaves untouched. */
 function applyStarModifiersToPairs(pairs, star, dialect) {
-    const fold = (n) => foldIdentifier(n, dialect);
+    const fold = (n) => resolveBehavior(dialect).fold(n);
     let out = pairs;
     if (star.exclude) {
         const removed = new Set(star.exclude.map(fold));
         out = out.filter((p) => !removed.has(fold(p.name)));
     }
     if (star.ilike !== undefined) {
-        const rx = likePatternToRegExp(star.ilike);
-        out = out.filter((p) => rx.test(fold(p.name)));
+        const b = resolveBehavior(dialect);
+        const pat = star.ilike;
+        out = out.filter((p) => b.likeMatch(pat, fold(p.name)));
     }
     if (star.rename) {
         const renames = new Map(star.rename.map((r) => [fold(r.from), r.to]));
@@ -282,7 +284,7 @@ function checkSourceColumns(src, schema, resolved, diagnostics, dialect) {
     if (src.kind === "graphtable")
         return known(resolved.get(src.scope));
     if (src.kind === "pivot") {
-        return known(pivotSourceOutputs(src, (s) => checkSourceColumns(s, schema, resolved, diagnostics, dialect) ?? "unknown"));
+        return known(pivotSourceOutputs(src, (s) => checkSourceColumns(s, schema, resolved, diagnostics, dialect) ?? "unknown", dialect));
     }
     return src.source.columnAliases ?? known(resolved.get(src.scope));
 }
@@ -323,14 +325,14 @@ function checkColumn(scope, ref, schema, resolved, diagnostics) {
     // path `f` against `c`'s struct type — resolved from a table schema or threaded through a
     // derived (CTE/subquery) column; see checkFieldPath.
     const split = splitColumnRefInScope(scope, ref.parts);
-    const name = foldIdentifier(split.column, scope.dialect);
+    const name = behaviorOf(scope).fold(split.column);
     if (split.qualifier !== undefined) {
         for (let s = scope; s; s = s.parent) {
             const src = s.sources.get(split.qualifier);
             if (!src)
                 continue;
             const cols = sourceColumns(src, schema, resolved, s.dialect);
-            if (cols && !cols.some((c) => foldIdentifier(c, s.dialect) === name)) {
+            if (cols && !cols.some((c) => behaviorOf(s).fold(c) === name)) {
                 diagnostics.push(columnDiag("unknown-column", ref, `Unknown column: ${ref.parts.join(".")}`));
                 return; // base column missing — don't also walk its (nonexistent) fields
             }
@@ -350,7 +352,7 @@ function checkColumn(scope, ref, schema, resolved, diagnostics) {
             const cols = sourceColumns(src, schema, resolved, s.dialect);
             if (!cols)
                 unknown++;
-            else if (cols.some((c) => foldIdentifier(c, s.dialect) === name))
+            else if (cols.some((c) => behaviorOf(s).fold(c) === name))
                 matches++;
         }
         if (matches > 1) {
@@ -385,7 +387,7 @@ function checkFieldPath(fields, scope, schema, ref, diagnostics) {
             return; // unknown / non-struct — don't flag
         // Struct-field names on a Type are stored FOLDED (parseType folds them at parse time), so
         // only the reference side folds here — re-folding a preserved-case stored name would corrupt it.
-        const hit = type.fields.find((f) => f.name === foldIdentifier(field, scope.dialect));
+        const hit = type.fields.find((f) => f.name === behaviorOf(scope).fold(field));
         if (!hit) {
             diagnostics.push(columnDiag("unknown-field", ref, `Unknown field: ${ref.parts.join(".")}`));
             return;
@@ -412,7 +414,7 @@ function sourceColumns(src, schema, resolved, dialect) {
     if (src.kind === "graphtable")
         return known(resolved.get(src.scope));
     if (src.kind === "pivot")
-        return known(pivotSourceOutputs(src, (s) => sourceColumns(s, schema, resolved, dialect) ?? "unknown"));
+        return known(pivotSourceOutputs(src, (s) => sourceColumns(s, schema, resolved, dialect) ?? "unknown", dialect));
     return src.source.columnAliases ?? known(resolved.get(src.scope));
 }
 /** Full positioned span of a CST node — 1-based line, 0-based column, endColumn one past the last

package/dist/qualify/schema-provider.js

@@ -21,7 +21,7 @@
 // FOLDED name parts (the catalog identity key), never the raw source text. A host
 // keys its cache by that folded path.
 // ---------------------------------------------------------------------------
-import { foldIdentifier } from "../ident/fold.js";
+import { resolveBehavior } from "../dialect-behavior/registry.js";
 /** A resolve-on-demand catalog. Implements SchemaProvider by delegating each folded lookup to a
  *  TableResolver and recording the misses; prime() drains those misses through the resolver's
  *  async fetch, re-probes, and bumps `version` when anything new arrived. */
@@ -48,7 +48,7 @@ export class CallbackSchema {
         return this._misses;
     }
     columnsFor(parts, dialect) {
-        const folded = parts.map((p) => foldIdentifier(p, dialect, "table"));
+        const folded = parts.map((p) => resolveBehavior(dialect).fold(p, "table"));
         const cols = this.resolver.resolve(folded);
         if (cols === undefined) {
             this.recordMiss(folded);

package/dist/qualify/schema.js

@@ -16,7 +16,7 @@
 // "table") — same as an unquoted table reference in the query. Quoted-key support (a mapping key
 // meant to represent a quoted/case-exact identifier) is out of scope.
 // ---------------------------------------------------------------------------
-import { foldIdentifier } from "../ident/fold.js";
+import { resolveBehavior } from "../dialect-behavior/registry.js";
 export class Schema {
     /** A declared mapping is a CLOSED world: a miss means the table does not exist (unknown-table fires). */
     world = "closed";
@@ -35,7 +35,7 @@ export class Schema {
      *  (unfolded) — the fold for `dialect` happens here, once. */
     columnsFor(parts, dialect) {
         const idx = this.indexFor(dialect);
-        const fold = (p) => foldIdentifier(p, dialect, "table");
+        const fold = (p) => resolveBehavior(dialect).fold(p, "table");
         const full = parts.map(fold).join(".");
         return idx.byPath.get(full) ?? idx.byTable.get(fold(parts[parts.length - 1] ?? ""));
     }
@@ -59,7 +59,7 @@ export class Schema {
         const isTable = entries.length > 0 && entries.every(([, v]) => typeof v === "string" || isLeaf(v));
         if (isTable) {
             const cols = entries.map(([name, leaf]) => toColumn(name, leaf));
-            const fold = (p) => foldIdentifier(p, dialect, "table");
+            const fold = (p) => resolveBehavior(dialect).fold(p, "table");
             idx.byPath.set(path.map(fold).join("."), cols);
             const bare = fold(path[path.length - 1] ?? "");
             if (!idx.byTable.has(bare))

package/dist/qualify/template-provider.d.ts

@@ -37,6 +37,14 @@ export interface ResolvedRelation {
     /** The relation's columns, or undefined until an async describe lands (async warm). */
     columns?: Column[];
 }
+/** A completion candidate a host offers for a template call slot (a dbt model for a ref's arg 0, a
+ *  source name for a source's arg 0). `label` is what the editor inserts at the caret; `detail` is
+ *  optional display text (a schema, a path). The neutral provider offers none. See
+ *  `TemplateProvider.templateCandidates`. */
+export interface TemplateCandidate {
+    label: string;
+    detail?: string;
+}
 /** Everything known about one call's expansion. Every field optional; `undefined` = unknown. */
 export interface ResolvedExpansion {
     /** Parse-time shape. When absent, derived from the strongest present field:
@@ -80,23 +88,30 @@ export declare class DefaultTemplateProvider implements SchemaProvider {
     tables(_dialect?: string): string[];
     /** Monotonic invalidation signal — bumps when `prime()` warmed anything new. */
     get version(): number;
-    /** The relation a call produces. Default knowledge: `ref(...)` → the dbt-LOGICAL model name,
-     *  `source(a,b)` → the logical [source, table] — literal args only, never fabricated. An
-     *  overriding provider answers the PHYSICAL relation (+columns) from its manifest/describe. */
-    relationOf(call: TemplateCall): ResolvedRelation | undefined;
-    /** The scalar value a call yields. Default knowledge: `env_var` returns a string (dbt docs);
-     *  `var` and user macros are unknown. */
-    valueOf(call: TemplateCall): {
+    /** The relation a call produces. The NEUTRAL floor knows no macro vocabulary, so it answers
+     *  undefined for everything: `ref`/`source` are dbt macros, not minijinja knowledge, and live in
+     *  `DbtTemplateProvider`. An overriding provider answers the relation (+columns) it knows. */
+    relationOf(_call: TemplateCall): ResolvedRelation | undefined;
+    /** The scalar value a call yields. Neutral floor: unknown (no macro vocabulary). `env_var` is a
+     *  dbt builtin known by `DbtTemplateProvider`. */
+    valueOf(_call: TemplateCall): {
         type: ValueType;
     } | undefined;
-    /** The rendered-output shape of a call. Default knowledge: the no-output builtins → "nothing".
-     *  Everything else unknown (the engine derives a shape from stronger fields, or falls back to
-     *  its positional fill). */
-    shapeOf(call: TemplateCall): ExpansionShape | undefined;
+    /** The rendered-output shape of a call. Neutral floor: unknown (the engine derives a shape from
+     *  stronger fields, or falls back to its positional fill). The dbt no-output builtins → "nothing"
+     *  is `DbtTemplateProvider` knowledge. */
+    shapeOf(_call: TemplateCall): ExpansionShape | undefined;
     /** The columns a column-list-producing macro emits. Default: unknown. */
     columnsOf(_call: TemplateCall): Column[] | undefined;
     /** The items a loop collection holds. Default: unknown (loops analyze one representative pass). */
     collectionOf(_call: TemplateCall): string[] | undefined;
+    /** Completion candidates for a template call slot: the caret sits in `callee`'s positional argument
+     *  `argIndex` (a dbt ref's arg 0 answers the model names, a source's arg 0 the source names, arg 1
+     *  the table names). `argIndex` is -1 when the caret is still in the callee name itself, so a host
+     *  can answer the macro/callee names it knows. `packageName` is the dotted package (`dbt_utils` in
+     *  `dbt_utils.star(...)`). The NEUTRAL provider knows no vocabulary and offers none; a host answers
+     *  from its catalog. `completeAt` reads this when the caret is inside a jinja tag. */
+    templateCandidates(_callee: string, _argIndex: number, _packageName?: string): TemplateCandidate[];
     /**
      * Everything known about `call`, composed from the granular methods. Field precedence for the
      * shape (channel-agreed): an EXPLICIT `shapeOf` answer always wins; absent, derived
@@ -134,7 +149,25 @@ export declare class DefaultTemplateProvider implements SchemaProvider {
     prime(): Promise<boolean>;
     private drain;
 }
-/** The provider type the engine consults — the shipped base (or any subclass of it). */
+/**
+ * The shipped dbt overlay: a `DefaultTemplateProvider` that knows dbt's built-in macros and nothing
+ * more. `ref(...)` resolves to the dbt-LOGICAL model name, `source(a,b)` to the logical
+ * [source, table], `env_var` to a string, and the no-output builtins
+ * (config/docs/print/log/return/exceptions) render nothing. Static famous-macro knowledge ONLY: no
+ * manifest, no warehouse, no project config, no runtime. A dbt consumer with runtime knowledge
+ * extends THIS (not the neutral `DefaultTemplateProvider`) and overrides the granular methods with
+ * what its manifest / describe cache resolve to. This class is where the dbt vocabulary lives so the
+ * neutral core and default do not carry it.
+ */
+export declare class DbtTemplateProvider extends DefaultTemplateProvider {
+    relationOf(call: TemplateCall): ResolvedRelation | undefined;
+    valueOf(call: TemplateCall): {
+        type: ValueType;
+    } | undefined;
+    shapeOf(call: TemplateCall): ExpansionShape | undefined;
+}
+/** The provider type the engine consults — the shipped base (or any subclass of it, e.g.
+ *  `DbtTemplateProvider`). */
 export type TemplateProvider = DefaultTemplateProvider;
 /**
  * The ONE shared no-configuration default — an OPEN world that answers nothing and diagnoses