sqllens 1.3.0 → 1.5.0

package/README.md

@@ -17,6 +17,25 @@ The front end is error-tolerant and token-first, so the library drives editor
 features (completion, hover, diagnostics, go-to-definition) over incomplete,
 mid-edit text. See [Editor / language tooling](#editor--language-tooling).
 
+## Guiding principles
+
+Two principles govern every layer of this library, and they are duals of each other:
+
+- **Never wrong.** A wrong answer is worse than no answer. A name, type, or binding
+  that cannot be derived from a documented source stays absent or `unknown`; it is
+  never guessed. Where a function's return type depends on an argument's value, the
+  answer is `unknown`, not a plausible guess. Where a relation cannot be resolved,
+  its name is the text the user wrote, never something the library invented.
+- **Lossless.** Parsing never discards information the input carried. Every token
+  survives with its exact source span (even on broken input), identifiers keep their
+  as-written spelling and quoting alongside their folded identity, and what the parse
+  knew structurally the IR carries, so no downstream layer has to re-derive it by
+  heuristic.
+
+Never wrong constrains what the library claims; lossless constrains what it keeps.
+Together they are why analysis results can be trusted in an editor: what you are
+shown is derived, and what you wrote is still there.
+
 ```bash
 npm install sqllens
 ```

package/dist/bigquery/behavior.js

@@ -1,13 +1,14 @@
 import { acceptsFor } from "../dialect-behavior/coerce-rules.js";
 import { likePatternToRegExp } from "../scope/like-pattern.js";
 import { SIGNATURES } from "../signature/signatures.js";
-import { displayName, fold, foldTableName, matchesSourceKey } from "./fold.js";
+import { displayName, fold, foldTableName, matchesSourceKey, BIGQUERY_NAME_CONFIG } from "./fold.js";
 import { bigqueryLiteral, bigqueryParseType, bigquerySpecial, BIGQUERY_FUNCTION_RETURNS } from "./infer.js";
 export const bigqueryBehavior = {
     fold,
     displayName,
     foldTableName,
     matchesSourceKey,
+    nameConfig: BIGQUERY_NAME_CONFIG,
     likeMatch: (pattern, value) => likePatternToRegExp(pattern).test(value),
     literal: bigqueryLiteral,
     parseType: bigqueryParseType,

package/dist/bigquery/fold.d.ts

@@ -1,5 +1,11 @@
 import { type FoldRule, type IdentKind } from "../ident/fold.js";
+import type { QualifiedNameConfig } from "../ir/qualified-name.js";
 export declare const BIGQUERY_FOLD_RULE: FoldRule;
+/** project.dataset.table (cloud.google.com/bigquery/docs — "Qualifying table names").
+ *  Normalized vocabulary: catalog = project, schema = dataset. Relation-path parts keep case in
+ *  the identity key (this rule's tableCase: "preserve" — dataset and table names are
+ *  case-sensitive). */
+export declare const BIGQUERY_NAME_CONFIG: QualifiedNameConfig;
 /** Fold an identifier to its BigQuery identity key. */
 export declare function fold(raw: string, kind?: IdentKind): string;
 /** Presentation twin: strip delimiters, no case change. */

package/dist/bigquery/fold.js

@@ -23,6 +23,14 @@ export const BIGQUERY_FOLD_RULE = {
     tableCase: "preserve",
     escapeStyle: "backslash",
 };
+/** project.dataset.table (cloud.google.com/bigquery/docs — "Qualifying table names").
+ *  Normalized vocabulary: catalog = project, schema = dataset. Relation-path parts keep case in
+ *  the identity key (this rule's tableCase: "preserve" — dataset and table names are
+ *  case-sensitive). */
+export const BIGQUERY_NAME_CONFIG = {
+    roles: ["catalog", "schema"],
+    rule: BIGQUERY_FOLD_RULE,
+};
 /** Fold an identifier to its BigQuery identity key. */
 export function fold(raw, kind = "other") {
     return foldWith(BIGQUERY_FOLD_RULE, raw, kind);

package/dist/bigquery/lower.js

@@ -3,6 +3,17 @@ import { GoogleSQLParser as P } from "../generated/bigquery/GoogleSQLParser.js";
 import { keywordCategory, swallowedCategories, swallowedStatements } from "../ir/statement.js";
 import { partSpanOf, partSpansOf } from "../ir/part-span.js";
 import { freezeIR } from "../ir/freeze.js";
+import { synthesizedQualifiedName } from "../ir/qualified-name.js";
+import { BIGQUERY_NAME_CONFIG } from "./fold.js";
+/** The structured name for a table source's parts (issue #38). BigQuery's lower() strips
+ *  backtick delimiters from every identifier (the documented exception in
+ *  docs/identifier-delimiter-contract.md), so parts arrive BARE: the synthesized builder is the
+ *  correct one (identity is unaffected — quoted and unquoted fold identically in this dialect),
+ *  and `fqn` re-renders quoting only where a part needs it. The byte-exact written form stays
+ *  recoverable via namePartSpans, per the contract's own remedy. */
+function relationOf(rawParts) {
+    return synthesizedQualifiedName(rawParts, BIGQUERY_NAME_CONFIG);
+}
 // ---------------------------------------------------------------------------
 // Lowering — BigQuery / GoogleSQL (forked bytebase/parser googlesql/) CST ->
 // the shared, dialect-neutral IR (src/ir/ir.ts). The semantic layer runs on
@@ -224,10 +235,11 @@ function lowerQueryPrimary(primary) {
     // `TABLE name` ≡ `SELECT * FROM name`.
     const path = directChildrenOfRule(primary, P.RULE_path_expression)[0];
     if (path) {
+        const name = pathParts(path);
         return {
             kind: "select",
             projections: [implicitStar(primary)],
-            from: [{ kind: "table", name: pathParts(path), namePartSpans: pathPartSpans(path), cst: path }],
+            from: [{ kind: "table", relation: relationOf(name), namePartSpans: pathPartSpans(path), cst: path }],
             columns: [],
             aggregated: false,
             cst: primary,
@@ -374,10 +386,20 @@ function lowerPipeSetOperand(operand) {
     if (tc) {
         // table_clause: TABLE path_expression | TABLE tvf — `TABLE name` ≡ `SELECT * FROM name`.
         const path = directChildrenOfRule(tc, P.RULE_path_expression)[0];
+        const name = path ? pathParts(path) : undefined;
         const body = {
             kind: "select",
             projections: path ? [implicitStar(tc)] : [],
-            from: path ? [{ kind: "table", name: pathParts(path), namePartSpans: pathPartSpans(path), cst: path }] : [],
+            from: path && name
+                ? [
+                    {
+                        kind: "table",
+                        relation: relationOf(name),
+                        namePartSpans: pathPartSpans(path),
+                        cst: path,
+                    },
+                ]
+                : [],
             columns: [],
             aggregated: false,
             cst: tc,
@@ -414,7 +436,7 @@ function lowerPipeJoin(join, cst) {
     const tp = directChildrenOfRule(join, P.RULE_table_primary)[0];
     if (tp)
         collectTablePrimary(tp, out, unsupported);
-    const source = out[0] ?? { kind: "table", name: [], cst: join };
+    const source = out[0] ?? { kind: "table", relation: relationOf([]), cst: join };
     const joinConditions = [];
     const columns = [];
     const onUsing = directChildrenOfRule(join, P.RULE_on_or_using_clause)[0];
@@ -917,16 +939,18 @@ function buildSource(tp, unsupported) {
     if (tvf) {
         const path = firstOfRule(tvf, P.RULE_path_expression);
         const aliasInfo = aliasOf(directChildrenOfRule(tvf, P.RULE_pivot_or_unpivot_clause_and_aliases)[0]);
+        const name = path ? pathParts(path) : [tp.getText()];
         return {
             kind: "table",
-            name: path ? pathParts(path) : [tp.getText()],
+            relation: relationOf(name),
             namePartSpans: path ? pathPartSpans(path) : undefined,
             alias: aliasInfo?.alias,
             aliasCst: aliasInfo?.cst,
             cst: tp,
         };
     }
-    return { kind: "table", name: [stripBackticks(tp.getText())], cst: tp };
+    const name = [stripBackticks(tp.getText())];
+    return { kind: "table", relation: relationOf(name), cst: tp };
 }
 // --- graph / GQL -----------------------------------------------------------------
 // GRAPH_TABLE(graph MATCH … COLUMNS(…)) in FROM, and the standalone `GRAPH g … RETURN …` statement.
@@ -1072,7 +1096,14 @@ function buildPathSource(pathExpr) {
     const path = base ? firstOfRule(base, P.RULE_path_expression) : undefined;
     const name = path ? pathParts(path) : base ? dashedPathParts(base) : [stripBackticks(pathExpr.getText())];
     const namePartSpans = path ? pathPartSpans(path) : undefined;
-    return { kind: "table", name, namePartSpans, alias: aliasInfo?.alias, aliasCst: aliasInfo?.cst, cst: pathExpr };
+    return {
+        kind: "table",
+        relation: relationOf(name),
+        namePartSpans,
+        alias: aliasInfo?.alias,
+        aliasCst: aliasInfo?.cst,
+        cst: pathExpr,
+    };
 }
 /** table_path_alias_or_qualify / table_path_pivot_suffix / pivot_or_unpivot_clause_and_aliases → its leading identifier. */
 function aliasOf(node) {

package/dist/completion/complete.d.ts

@@ -5,7 +5,7 @@ import type { SchemaProvider } from "../qualify/schema-provider.js";
  *  `"template"` kind is a host candidate for a jinja call slot (a dbt model for a ref's arg). */
 export interface Completion {
     label: string;
-    kind: "keyword" | "column" | "table" | "function" | "template";
+    kind: "keyword" | "column" | "table" | "cte" | "namespace" | "function" | "template";
     /** Extra display info, e.g. a column's type when the schema knows it. */
     detail?: string;
 }

package/dist/completion/complete.js

@@ -20,6 +20,7 @@ import { nodeAt } from "../document/node-at.js";
 import { resolveBehavior } from "../dialect-behavior/registry.js";
 import { DefaultTemplateProvider } from "../qualify/template-provider.js";
 import { callOf } from "../minijinja/apply-tags.js";
+import { sourcesMatchingQualifier } from "../scope/scope.js";
 import { collectCandidates } from "./atn-walk.js";
 import { jinjaSlotAt } from "./jinja-slot.js";
 import { COMPLETION_CONFIG } from "./config.js";
@@ -33,8 +34,10 @@ export function completeAt(doc, offset, schema) {
     try {
         return collect(doc, offset, schema);
     }
-    catch {
+    catch (e) {
         // Total by contract: a walk/parse hiccup must not surface to the editor.
+        if (process.env.SQLLENS_DEBUG_COMPLETE)
+            throw e;
         return [];
     }
 }
@@ -98,27 +101,62 @@ function collect(doc, offset, schema) {
         if (label)
             add({ label, kind: "keyword" });
     }
+    // A RELATION PATH position (#38 stage 6): a dotted chain right before the caret whose anchor
+    // token is FROM/JOIN-family (cfg.relationKeywordTokens — the same per-dialect set the
+    // broken-input fallback uses). Mid-path the ATN reports a generic identifier slot, so the
+    // anchor, not the rule set, is the discriminator. The candidates are the typed prefix's NEXT
+    // SEGMENTS (segment labels only — a client replaces the caret token, so a full path would
+    // double-insert), never CTEs, and never the column/function noise the identifier slot would
+    // otherwise pour in.
+    const path = dottedPrefixAt(walkTokens, caretIdx);
+    const atRelationPath = path.parts.length > 0 && path.anchorIdx >= 0 && cfg.relationKeywordTokens.has(walkTokens[path.anchorIdx].type);
     const atTable = intersects(cand.rules, cfg.tableRules);
     const atColumn = intersects(cand.rules, cfg.columnRules);
-    // tables — relation-name slot, and only when a schema lists them.
-    if (atTable && schema) {
-        for (const t of schema.tables(dialect))
-            add({ label: t, kind: "table" });
+    if (atRelationPath) {
+        if (schema?.childrenOf) {
+            for (const child of schema.childrenOf(path.parts, dialect))
+                add({ label: child.name, kind: child.kind });
+        }
     }
-    // columns — value/column slot: the columns visible from the enclosing scope, plus a broken-input
-    // fallback that reads FROM/JOIN relation names straight off the token stream (the document's batch
-    // parse mis-reads a mid-edit `SELECT  FROM t` — see the fallback's comment).
-    if (atColumn) {
-        for (const c of visibleColumns(cellScopes, cellAst, dialect, cellOffset, schema))
+    else if (path.parts.length > 0) {
+        // A qualified MEMBER position (`o.|`, `gold.orders.|`) — anvil item 2: only the columns of
+        // the source the qualifier matches (the same validated any-depth primitive binding uses),
+        // no function/keyword noise. Deliberately NOT gated on the walk's rules: at a dangling dot
+        // mid-edit the walk often reports nothing, but the dot chain itself is the member-position
+        // evidence (it is the completion trigger character), and an unmatched qualifier answers [].
+        const scoped = qualifiedSourceColumns(cellScopes, cellAst, cellOffset, path.parts, dialect, schema);
+        for (const c of scoped)
             add(c);
-        if (schema)
-            for (const c of fromRelationColumns(walkTokens, cfg, schema, dialect, doc.templated?.tags, doc.text))
+        // Mid-edit the dangling dot often breaks the FROM parse and the scope is EMPTY — the same
+        // failure the bare-slot fallback covers. Its member twin: read `FROM/JOIN name [alias]`
+        // pairs off the token stream and answer the matching relation's schema columns.
+        if (scoped.length === 0 && schema) {
+            for (const c of qualifiedFallbackColumns(walkTokens, cfg, path.parts, schema, dialect))
                 add(c);
+        }
     }
-    // functions — value/column slot: the dialect's inference-registry function names.
-    if (atColumn) {
-        for (const fn of Object.keys(resolveBehavior(dialect).functions))
-            add({ label: fn, kind: "function" });
+    else {
+        if (atTable) {
+            // Bare relation slot: in-scope CTE names FIRST (they shadow same-named catalog tables),
+            // then the catalog's tables.
+            for (const name of visibleCteNames(cellScopes, cellAst, cellOffset))
+                add({ label: name, kind: "cte" });
+            if (schema)
+                for (const t of schema.tables(dialect))
+                    add({ label: t, kind: "table" });
+        }
+        // columns — value/column slot: the columns visible from the enclosing scope, plus a
+        // broken-input fallback reading FROM/JOIN relation names straight off the token stream.
+        if (atColumn) {
+            for (const c of visibleColumns(cellScopes, cellAst, dialect, cellOffset, schema))
+                add(c);
+            if (schema)
+                for (const c of fromRelationColumns(walkTokens, cfg, schema, dialect, doc.templated?.tags, doc.text))
+                    add(c);
+            // functions — value/column slot: the dialect's inference-registry function names.
+            for (const fn of Object.keys(resolveBehavior(dialect).functions))
+                add({ label: fn, kind: "function" });
+        }
     }
     return out;
 }
@@ -130,20 +168,70 @@ function collect(doc, offset, schema) {
 function templateCompletions(slot, schema) {
     if (!(schema instanceof DefaultTemplateProvider))
         return [];
-    return schema.templateCandidates(slot.callee, slot.argIndex, slot.packageName).map((c) => ({
+    return schema.templateCandidates(slot.call, slot.argIndex).map((c) => ({
         label: c.label,
         kind: "template",
         ...(c.detail !== undefined ? { detail: c.detail } : {}),
     }));
 }
-/** The walk's caret token index: the first default-channel token whose `.start >= offset`; for an
- *  end-of-input caret that is the EOF sentinel's index (last entry). Mirrors Task 10's tests' caret
- *  helper. `toks` is the document's own token stream (doc coordinates) with the EOF sentinel appended. */
+/** The dotted qualifier immediately before the caret (#38): `analytics.` → ["analytics"],
+ *  `analytics.sales.` → ["analytics","sales"], `analytics.sa|` (typing a segment) → ["analytics"].
+ *  Reads the walk's own token stream backwards from the caret token: an optional partial segment,
+ *  then (DOT ident)+ chains. `anchorIdx` is the default-channel token BEFORE the whole chain
+ *  (-1 at document start) — its type says what the chain qualifies (FROM/JOIN → a relation path).
+ *  parts: [] when no dot chain precedes the caret. Raw texts, delimiters intact — the schema
+ *  folds. */
+function dottedPrefixAt(toks, caretIdx) {
+    const prev = (i) => {
+        for (let j = i - 1; j >= 0; j--)
+            if (toks[j].channel === Token.DEFAULT_CHANNEL)
+                return j;
+        return -1;
+    };
+    let i = caretIdx;
+    // A word-like caret token is the partial segment being typed — the chain sits before it.
+    if (toks[i] && /^\w/.test(toks[i].text))
+        i = prev(i);
+    // `i` is now the DOT itself (partial-segment case) or the caret slot (then look back one).
+    let d = toks[i]?.text === "." ? i : prev(i);
+    const parts = [];
+    let anchorIdx = d;
+    while (d >= 0 && toks[d]?.text === ".") {
+        const ident = prev(d);
+        if (ident < 0 || !/^[\w"`[\]]/.test(toks[ident].text))
+            break;
+        parts.unshift(toks[ident].text);
+        anchorIdx = prev(ident);
+        d = anchorIdx;
+    }
+    return { parts, anchorIdx };
+}
+/** The CTE names visible from the caret's enclosing scope, as declared (display text). */
+function visibleCteNames(scopes, ast, offset) {
+    const scope = enclosingScope(scopes, ast, offset);
+    const out = [];
+    for (let s = scope; s; s = s.parent)
+        for (const cte of s.ctes.values())
+            out.push(cte.def.name);
+    return out;
+}
+/** The walk's caret token index. Two rules, in order (anvil 2026-07-15; antlr4-c3's own caret
+ *  convention):
+ *   1. the token being TYPED — a word-like token whose span CONTAINS the caret (start < offset <=
+ *      end). A caret at the end of `ifn` completes `ifn`; it does not mean the slot is filled.
+ *      Word-like only: punctuation is never partially typed, so `abs(|` keeps rule 2.
+ *   2. between tokens — the first default-channel token whose `.start >= offset`; for an
+ *      end-of-input caret that is the EOF sentinel's index (last entry).
+ *  `toks` is the document's own token stream (doc coordinates) with the EOF sentinel appended.
+ *  Source order makes one pass sufficient: a containing token starts before any `.start >= offset`
+ *  token, so rule 1 fires first whenever it applies. */
 function caretTokenIndex(toks, offset) {
     for (let i = 0; i < toks.length; i++) {
         const t = toks[i];
         if (!t || t.channel !== Token.DEFAULT_CHANNEL)
             continue;
+        if (/^\w/.test(t.text) && t.start < offset && offset <= t.start + t.text.length)
+            return i;
         if (t.start >= offset)
             return i;
     }
@@ -212,6 +300,64 @@ function fromRelationColumns(walkTokens, cfg, schema, dialect, tags, text) {
     }
     return out;
 }
+/** The columns of the ONE source a dotted qualifier matches from the caret's scope (anvil item 2):
+ *  `o.|` answers o's columns only. Matching is sourcesMatchingQualifier — the same validated,
+ *  any-depth primitive column BINDING uses — walking enclosing scopes nearest-first. Ambiguous or
+ *  unmatched qualifiers answer nothing (never a fabricated union). */
+function qualifiedSourceColumns(scopes, ast, offset, qualParts, dialect, schema) {
+    const scope = enclosingScope(scopes, ast, offset);
+    if (!scope)
+        return [];
+    const behavior = resolveBehavior(dialect);
+    for (let s = scope; s; s = s.parent) {
+        const matches = sourcesMatchingQualifier(s, qualParts);
+        if (matches.length > 1)
+            return [];
+        if (matches.length === 1) {
+            return columnsOf(matches[0], dialect, schema).map((c) => ({ ...c, label: behavior.displayName(c.label) }));
+        }
+    }
+    return [];
+}
+/** The member-position twin of `fromRelationColumns` (#38): when the scope is empty (the dangling
+ *  dot broke the FROM parse), read `FROM/JOIN name(.name)* [AS] [alias]` off the token stream and
+ *  answer the columns of the ONE relation the qualifier matches — the alias when present, else the
+ *  name's own trailing parts. No match (or several) answers [] — never a fabricated union. */
+function qualifiedFallbackColumns(walkTokens, cfg, qualParts, schema, dialect) {
+    if (cfg.relationKeywordTokens.size === 0)
+        return [];
+    const b = resolveBehavior(dialect);
+    const toks = walkTokens.filter((t) => t.channel === Token.DEFAULT_CHANNEL);
+    const hits = [];
+    for (let i = 0; i + 1 < toks.length; i++) {
+        if (!cfg.relationKeywordTokens.has(toks[i].type))
+            continue;
+        let j = i + 1;
+        if (!toks[j] || !cfg.nameTokens.has(toks[j].type))
+            continue;
+        const parts = [toks[j].text];
+        j++;
+        while (toks[j]?.text === "." && toks[j + 1] && cfg.nameTokens.has(toks[j + 1].type)) {
+            parts.push(toks[j + 1].text);
+            j += 2;
+        }
+        let alias;
+        if (toks[j] && b.fold(toks[j].text) === "as" && toks[j + 1] && cfg.nameTokens.has(toks[j + 1].type))
+            j++;
+        if (toks[j] && cfg.nameTokens.has(toks[j].type))
+            alias = toks[j].text;
+        const matches = alias
+            ? qualParts.length === 1 && b.fold(qualParts[0]) === b.fold(alias)
+            : qualParts.length <= parts.length &&
+                qualParts.every((p, k) => b.fold(p, "table") === b.fold(parts[parts.length - qualParts.length + k], "table"));
+        if (!matches)
+            continue;
+        const cols = schema.columnsFor(parts, dialect);
+        if (cols)
+            hits.push(cols.map((c) => ({ label: c.name, kind: "column", detail: c.type })));
+    }
+    return hits.length === 1 ? hits[0] : [];
+}
 /** The columns visible from the scope enclosing `offset` (a CELL-relative offset into `scopes`).
  *  Derived sources / CTEs expose their own output column names; base-table sources get their columns
  *  (and types) from the schema. */

package/dist/completion/jinja-slot.d.ts

@@ -1,3 +1,4 @@
+import type { TemplateCall } from "../qualify/template-provider.js";
 import type { TagNode } from "../minijinja/tag-ast.js";
 /** Where the caret sits inside a jinja call tag. NEUTRAL, the callee is a bare string; the dbt
  *  meaning of the slot (ref arg0 = a model) is the consumer's to apply. */
@@ -6,6 +7,11 @@ export interface JinjaSlot {
     callee: string;
     /** Dotted package before the callee (`dbt_utils` in `dbt_utils.star(...)`). */
     packageName?: string;
+    /** The WHOLE parsed call (issue #37): name, packageParts and every sibling arg's literal value
+     *  (null where computed) — the same TemplateCall shape every provider method receives. A slot's
+     *  candidates can depend on the other args (source('raw', '|')'s candidates are the tables OF
+     *  raw), so the provider callback gets the call, not just the callee name. */
+    call: TemplateCall;
     /** 0-based index of the positional arg the caret is in. The callee-name slot (caret still in the
      *  callee identifier, `{{ my_mac|`) is `-1`. */
     argIndex: number;

package/dist/completion/jinja-slot.js

@@ -18,6 +18,7 @@
 // Reuses the parse: it reads the tags the document already produced, never re-parses.
 // Total: returns undefined off any jinja completion slot; never throws.
 // ---------------------------------------------------------------------------
+import { callOf } from "../minijinja/apply-tags.js";
 /**
  * The jinja completion slot at `offset`, or undefined when the caret is not in a completable jinja
  * position. `tags` is `parseTemplated(...).tags` (or `doc.templated.tags`); `text` is the document
@@ -82,7 +83,15 @@ function macroHit(c) {
 }
 /** The slot for a caret inside a resolved call: the callee name, or the positional argument. */
 function slotFromCall(c, text, offset) {
-    const base = { callee: c.name, ...(c.packageName !== undefined ? { packageName: c.packageName } : {}) };
+    // The whole call rides the slot (#37): callOf reads name + literal args off the source text,
+    // the same extraction apply-tags feeds the provider everywhere else.
+    const call = callOf({
+        name: c.name,
+        nameSpan: c.nameSpan,
+        args: c.args,
+        ...(c.packageName !== undefined ? { packageName: c.packageName } : {}),
+    }, text);
+    const base = { callee: c.name, call, ...(c.packageName !== undefined ? { packageName: c.packageName } : {}) };
     // Callee-name slot: the caret is still within (or right at the end of) the callee identifier,
     // before the open paren, the user is typing the macro name itself.
     if (offset <= c.nameSpan.end) {
@@ -122,7 +131,8 @@ function bareCalleeSlot(tags, text, offset) {
     const m = /^\s*([A-Za-z_]\w*)$/.exec(before);
     if (!m)
         return undefined;
-    return { callee: m[1], argIndex: -1, prefix: m[1], incomplete: true };
+    // No parsed call exists yet (`{{ re`) — the slot's call is the bare callee with no args.
+    return { callee: m[1], call: { name: m[1], args: [] }, argIndex: -1, prefix: m[1], incomplete: true };
 }
 /** Drop a single leading quote from a partial string arg (`'cu` -> `cu`) so the prefix is the value
  *  the consumer filters by. Leaves a non-string arg untouched. */

package/dist/databricks/behavior.js

@@ -1,13 +1,14 @@
 import { acceptsFor } from "../dialect-behavior/coerce-rules.js";
 import { likePatternToRegExp } from "../scope/like-pattern.js";
 import { SIGNATURES } from "../signature/signatures.js";
-import { displayName, fold, foldTableName, matchesSourceKey } from "./fold.js";
+import { displayName, fold, foldTableName, matchesSourceKey, DATABRICKS_NAME_CONFIG } from "./fold.js";
 import { databricksLiteral, databricksParseType, DATABRICKS_FUNCTION_RETURNS } from "./infer.js";
 export const databricksBehavior = {
     fold,
     displayName,
     foldTableName,
     matchesSourceKey,
+    nameConfig: DATABRICKS_NAME_CONFIG,
     likeMatch: (pattern, value) => likePatternToRegExp(pattern).test(value),
     literal: databricksLiteral,
     parseType: databricksParseType,

package/dist/databricks/fold.d.ts

@@ -1,5 +1,9 @@
 import { type FoldRule, type IdentKind } from "../ident/fold.js";
+import type { QualifiedNameConfig } from "../ir/qualified-name.js";
 export declare const DATABRICKS_FOLD_RULE: FoldRule;
+/** Unity Catalog's three-level namespace: catalog.schema.object
+ *  (docs.databricks.com/en/data-governance/unity-catalog — "three-level namespace"). */
+export declare const DATABRICKS_NAME_CONFIG: QualifiedNameConfig;
 /** Fold an identifier to its Databricks identity key. */
 export declare function fold(raw: string, kind?: IdentKind): string;
 /** Presentation twin: strip delimiters, no case change. */

package/dist/databricks/fold.js

@@ -11,6 +11,12 @@ export const DATABRICKS_FOLD_RULE = {
     unquoted: "lower",
     quoted: "lower",
 };
+/** Unity Catalog's three-level namespace: catalog.schema.object
+ *  (docs.databricks.com/en/data-governance/unity-catalog — "three-level namespace"). */
+export const DATABRICKS_NAME_CONFIG = {
+    roles: ["catalog", "schema"],
+    rule: DATABRICKS_FOLD_RULE,
+};
 /** Fold an identifier to its Databricks identity key. */
 export function fold(raw, kind = "other") {
     return foldWith(DATABRICKS_FOLD_RULE, raw, kind);

package/dist/databricks/lower.js

@@ -3,6 +3,13 @@ import { ArithmeticBinaryContext, ArithmeticUnaryContext, CastByColonContext, Ca
 import { keywordCategory, swallowedCategories, swallowedStatements } from "../ir/statement.js";
 import { partSpansOf } from "../ir/part-span.js";
 import { freezeIR } from "../ir/freeze.js";
+import { qualifiedNameOf } from "../ir/qualified-name.js";
+import { DATABRICKS_NAME_CONFIG } from "./fold.js";
+/** The structured name for a table source's raw parts (issue #38) — role assignment + identity
+ *  key + fqn happen HERE, at lowering, where the dialect's namespace shape is known. */
+function relationOf(rawParts) {
+    return qualifiedNameOf(rawParts, DATABRICKS_NAME_CONFIG);
+}
 // ---------------------------------------------------------------------------
 // CST navigation helpers
 // ---------------------------------------------------------------------------
@@ -367,7 +374,7 @@ function lowerSparkPipeRhs(rhs) {
     const join = directChildrenOfRule(rhs, P.RULE_joinRelation)[0];
     if (join) {
         const rel = directChildrenOfRule(join, P.RULE_relationPrimary)[0];
-        const source = rel ? buildSource(rel) : { kind: "table", name: [], cst: rhs };
+        const source = rel ? buildSource(rel) : { kind: "table", relation: relationOf([]), cst: rhs };
         const joinConditions = [];
         const columns = [];
         const crit = directChildrenOfRule(join, P.RULE_joinCriteria)[0];
@@ -491,7 +498,7 @@ function buildTableShorthand(queryPrimary) {
     return {
         kind: "select",
         projections: [{ isStar: true, expr: star, cst: queryPrimary }],
-        from: [{ kind: "table", name, namePartSpans, cst: queryPrimary }],
+        from: [{ kind: "table", relation: relationOf(name), namePartSpans, cst: queryPrimary }],
         columns: [],
         aggregated: false,
         cst: queryPrimary,
@@ -1438,7 +1445,7 @@ function buildSource(relationPrimary) {
     const namePartSpans = partNodes.length ? partSpansOf(partNodes) : multipart ? partSpansOf([multipart]) : undefined;
     return {
         kind: "table",
-        name: parts,
+        relation: relationOf(parts),
         namePartSpans,
         alias,
         aliasCst,

package/dist/dialect-behavior/behavior.d.ts

@@ -1,4 +1,5 @@
 import type { IdentKind } from "../ident/fold.js";
+import type { QualifiedNameConfig } from "../ir/qualified-name.js";
 import type { FnRule } from "../infer/functions.js";
 import type { Type } from "../infer/types.js";
 import type { Expr } from "../ir/ir.js";
@@ -8,6 +9,10 @@ export interface DialectBehavior {
     displayName(raw: string): string;
     foldTableName(parts: string[]): string[];
     matchesSourceKey(key: string, rawPart: string): boolean;
+    /** The dialect's namespace shape + fold rule for building QualifiedNames outside lower()
+     *  (shared layers synthesizing sources, apply-tags renaming templated ones). Same object the
+     *  dialect's own lower() uses; declared in src/<dialect>/fold.ts (issue #38). */
+    nameConfig: QualifiedNameConfig;
     likeMatch(pattern: string, name: string): boolean;
     literal(text: string): Type;
     parseType(text: string): Type;

package/dist/duckdb/behavior.js

@@ -1,7 +1,7 @@
 import { acceptsFor } from "../dialect-behavior/coerce-rules.js";
 import { likePatternToRegExp } from "../scope/like-pattern.js";
 import { SIGNATURES } from "../signature/signatures.js";
-import { displayName, fold, foldTableName, matchesSourceKey } from "./fold.js";
+import { displayName, fold, foldTableName, matchesSourceKey, DUCKDB_NAME_CONFIG } from "./fold.js";
 import { duckdbLiteral, duckdbParseType, DUCKDB_FUNCTION_RETURNS } from "./infer.js";
 // DuckDB implicit coercion: a quoted constant is initially UNKNOWN and coerces to whatever the call
 // needs (str->num), no bool<->num.
@@ -11,6 +11,7 @@ export const duckdbBehavior = {
     displayName,
     foldTableName,
     matchesSourceKey,
+    nameConfig: DUCKDB_NAME_CONFIG,
     likeMatch: (pattern, value) => likePatternToRegExp(pattern).test(value),
     literal: duckdbLiteral,
     parseType: duckdbParseType,

package/dist/duckdb/fold.d.ts

@@ -1,5 +1,9 @@
 import { type FoldRule, type IdentKind } from "../ident/fold.js";
+import type { QualifiedNameConfig } from "../ir/qualified-name.js";
 export declare const DUCKDB_FOLD_RULE: FoldRule;
+/** catalog.schema.table — an attached database is a catalog
+ *  (duckdb.org/docs/current/sql/statements/attach). */
+export declare const DUCKDB_NAME_CONFIG: QualifiedNameConfig;
 /** Fold an identifier to its DuckDB identity key. */
 export declare function fold(raw: string, kind?: IdentKind): string;
 /** Presentation twin: strip delimiters, no case change. */

package/dist/duckdb/fold.js

@@ -15,6 +15,12 @@ export const DUCKDB_FOLD_RULE = {
     unquoted: "ascii-lower",
     quoted: "ascii-lower",
 };
+/** catalog.schema.table — an attached database is a catalog
+ *  (duckdb.org/docs/current/sql/statements/attach). */
+export const DUCKDB_NAME_CONFIG = {
+    roles: ["catalog", "schema"],
+    rule: DUCKDB_FOLD_RULE,
+};
 /** Fold an identifier to its DuckDB identity key. */
 export function fold(raw, kind = "other") {
     return foldWith(DUCKDB_FOLD_RULE, raw, kind);