sqllens 1.3.0 → 1.5.0

package/dist/duckdb/lower.js

@@ -3,7 +3,13 @@ import { DuckdbParser as P } from "../generated/duckdb/DuckdbParser.js";
 import { keywordCategory, swallowedCategories, swallowedStatements } from "../ir/statement.js";
 import { partSpansOf } from "../ir/part-span.js";
 import { freezeIR } from "../ir/freeze.js";
-import { displayName } from "./fold.js";
+import { qualifiedNameOf } from "../ir/qualified-name.js";
+import { displayName, DUCKDB_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, DUCKDB_NAME_CONFIG);
+}
 // ---------------------------------------------------------------------------
 // Lowering — DuckDB (fork of this repo's grammars/postgres pair, TVL lineage)
 // CST -> the shared dialect-neutral IR (src/ir/ir.ts). The semantic layer runs
@@ -270,8 +276,15 @@ function lowerPivotStmt(stmt) {
     const isPivot = stmt.ruleIndex === P.RULE_pivotstmt;
     const from = [];
     const qn = directChildrenOfRule(stmt, P.RULE_qualified_name)[0];
-    if (qn)
-        from.push({ kind: "table", name: nameParts(qn), namePartSpans: columnPartSpans(qn), cst: qn });
+    if (qn) {
+        const pivotParts = nameParts(qn);
+        from.push({
+            kind: "table",
+            relation: relationOf(pivotParts),
+            namePartSpans: columnPartSpans(qn),
+            cst: qn,
+        });
+    }
     const sw = directChildrenOfRule(stmt, P.RULE_select_with_parens)[0];
     if (sw) {
         const inner = innerSelect(sw);
@@ -649,9 +662,10 @@ function buildPrimarySource(tr, unsupported) {
     // FROM 'file.parquet' — a string-literal relation (replacement scan, data/overview.md).
     const fileRel = directChildrenOfRule(tr, P.RULE_sconst)[0];
     if (fileRel) {
+        const fileRelName = [stripStringQuotes(fileRel.getText())];
         return {
             kind: "table",
-            name: [stripStringQuotes(fileRel.getText())],
+            relation: relationOf(fileRelName),
             namePartSpans: partSpansOf([fileRel]),
             alias,
             aliasCst,
@@ -680,9 +694,10 @@ function buildPrimarySource(tr, unsupported) {
     if (funcTable) {
         const fname = firstShallow(funcTable, P.RULE_func_name);
         const funcAlias = directChildrenOfRule(tr, P.RULE_func_alias_clause)[0];
+        const funcTableName = [fname ? lastName(fname) : funcTable.getText()];
         return {
             kind: "table",
-            name: [fname ? lastName(fname) : funcTable.getText()],
+            relation: relationOf(funcTableName),
             alias: alias ?? (funcAlias ? funcAliasName(funcAlias) : undefined),
             aliasCst,
             cst: tr,
@@ -690,7 +705,14 @@ function buildPrimarySource(tr, unsupported) {
     }
     const jsonTable = directChildrenOfRule(tr, P.RULE_json_table)[0];
     if (jsonTable) {
-        return { kind: "table", name: ["json_table"], alias, aliasCst, columnAliases, cst: tr };
+        return {
+            kind: "table",
+            relation: relationOf(["json_table"]),
+            alias,
+            aliasCst,
+            columnAliases,
+            cst: tr,
+        };
     }
     const nestedTr = directChildrenOfRule(tr, P.RULE_table_ref)[0];
     if (nestedTr) {
@@ -703,14 +725,23 @@ function buildPrimarySource(tr, unsupported) {
         if (innerFrom.length)
             return innerFrom[0];
     }
-    return { kind: "table", name: [textOrEmpty(tr)], alias, aliasCst, columnAliases, cst: tr };
+    const tableName = [textOrEmpty(tr)];
+    return { kind: "table", relation: relationOf(tableName), alias, aliasCst, columnAliases, cst: tr };
 }
 const nestedJoinConditions = [];
 function buildTableFromRelation(rel, alias, aliasCst, columnAliases) {
     const qn = directChildrenOfRule(rel, P.RULE_qualified_name)[0];
     const parts = qn ? nameParts(qn) : [textOrEmpty(rel)];
     const namePartSpans = qn ? columnPartSpans(qn) : undefined;
-    return { kind: "table", name: parts, namePartSpans, alias, aliasCst, columnAliases, cst: rel };
+    return {
+        kind: "table",
+        relation: relationOf(parts),
+        namePartSpans,
+        alias,
+        aliasCst,
+        columnAliases,
+        cst: rel,
+    };
 }
 /** The alias identifier node — under table_alias (AS slot) or bare_table_alias (AS-less slot). */
 function aliasIdentNode(aliasClause) {

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { lower as lowerSqlite } from "./sqlite/lower.js";
 export { lower as lowerMysql } from "./mysql/lower.js";
 export type { ParseResult } from "./parse-result.js";
 export { type TemplatedParseResult, type TemplatedParseOptions } from "./template/engine.js";
-export type { Clause, ColumnRef, CteDef, Expr, GraphElement, GraphTableSource, Join, JoinKind, LateralViewSource, LimitInfo, PartSpan, PipeBranch, PipeExpr, PipeSetItem, PipeStage, PivotInfo, Projection, QueryBody, QueryExpr, SelectExpr, SetOpExpr, Source, SubquerySource, TableSource, TemplateExprInfo, TemplateSourceInfo, UnpivotInfo, UnsupportedFlag, WindowSpec, } from "./ir/ir.js";
+export type { Clause, ColumnRef, CteDef, Expr, GraphElement, GraphTableSource, Join, JoinKind, LateralViewSource, LimitInfo, PartSpan, PipeBranch, PipeExpr, PipeSetItem, PipeStage, PivotInfo, Projection, QualifiedName, QueryBody, QueryExpr, SelectExpr, SetOpExpr, Source, SubquerySource, TableSource, TemplateExprInfo, TemplateSourceInfo, UnpivotInfo, UnsupportedFlag, WindowSpec, } from "./ir/ir.js";
 export { partSpanOf, partSpansOf } from "./ir/part-span.js";
 export { endPosition } from "./ir/span.js";
 export { childExprs, walkExprs, allQueryExprs } from "./ir/walk.js";

package/dist/ir/ir.d.ts

@@ -1,7 +1,9 @@
 import type { ParserRuleContext } from "antlr4ng";
 import type { PartSpan } from "./part-span.js";
+import type { QualifiedName } from "./qualified-name.js";
 import type { StatementCategory } from "./statement.js";
 export type { PartSpan } from "./part-span.js";
+export type { QualifiedName, QualifiedNameConfig, NameRole } from "./qualified-name.js";
 /**
  * The identity of one template call, the `expansion()` key. Args are LITERAL
  * string values: quote-stripped, escapes NOT resolved — an argument whose
@@ -647,12 +649,16 @@ export interface TemplateSourceInfo {
 }
 export interface TableSource {
     kind: "table";
-    /** Multipart name parts as written, e.g. ["catalog","schema","t"]. */
-    name: string[];
-    /** Per-part spans PARALLEL to `name`, one per multipart segment — same all-or-nothing convention
-     *  as `ColumnRef.partSpans` (absent when any part lacks a real token). Lets a consumer hit-test a
-     *  cursor on `catalog` vs `schema` vs `t` in `catalog.schema.t`, and recover each part's raw
-     *  (delimiter-included) source text via span + document text without re-scanning the token stream. */
+    /** The STRUCTURED name (issue #38): the object's own `name`, `parts` exactly as written, roles
+     *  right-aligned per the dialect's namespace, the folded identity `key`, and a display-ready
+     *  `fqn`. Built by the dialect's lower() (the one layer that knows the namespace shape);
+     *  consumers read structure here and never re-derive it from a parts array. */
+    relation: QualifiedName;
+    /** Per-part spans PARALLEL to `relation.parts`, one per multipart segment — same all-or-nothing
+     *  convention as `ColumnRef.partSpans` (absent when any part lacks a real token). Lets a
+     *  consumer hit-test a cursor on `catalog` vs `schema` vs `t` in `catalog.schema.t`, and recover
+     *  each part's raw (delimiter-included) source text via span + document text without re-scanning
+     *  the token stream. */
     namePartSpans?: PartSpan[];
     alias?: string;
     /** The alias identifier's own CST node (for its precise span), when aliased. */
@@ -670,6 +676,10 @@ export interface TableSource {
     /** Present when this source was written as a minijinja template tag in a FROM/JOIN slot; attached
      *  post-lower by the jinja front end (src/minijinja/apply-tags.ts). See TemplateSourceInfo. */
     template?: TemplateSourceInfo;
+    /** True when the LIBRARY built this node rather than lowering it from user syntax (a graph
+     *  element variable exposed as a relation). Catalog existence semantics don't apply: a closed
+     *  world's unknown-table never fires for a synthesized source. */
+    synthesized?: true;
     cst: ParserRuleContext;
 }
 export interface SubquerySource {

package/dist/ir/qualified-name.d.ts

@@ -0,0 +1,43 @@
+import { type FoldRule } from "../ident/fold.js";
+/** Qualifier roles, normalized across dialects (vendor vocabulary noted per dialect at its
+ *  config): "catalog" covers database/project, "schema" covers dataset/attached-database,
+ *  "server" is tsql's linked-server level. The object's own name is never a role — it is the
+ *  final part, always. */
+export type NameRole = "server" | "catalog" | "schema";
+/** A dialect's namespace shape: its qualifier roles OUTER→INNER, and the fold/delimiter rule
+ *  its identifiers obey. Declared once per dialect in src/<dialect>/fold.ts, doc-cited there. */
+export interface QualifiedNameConfig {
+    roles: readonly NameRole[];
+    rule: FoldRule;
+}
+/** A structured, dialect-resolved name. Plain frozen data like every IR node. */
+export interface QualifiedName {
+    /** The object's OWN name (the last part), delimiters stripped, as written. */
+    name: string;
+    /** Every part as written, outermost first, delimiters stripped. An elided middle part is "". */
+    parts: string[];
+    /** tsql linked-server level. Absent = not written. */
+    server?: string;
+    /** Catalog level (vendor: catalog / database / project). Absent = not written. */
+    catalog?: string;
+    /** Schema level (vendor: schema / dataset / attached database). Absent = not written;
+     *  "" = written-and-elided (`db..table`). */
+    schema?: string;
+    /** Folded identity parts (the dialect's own quoting-aware fold). COMPARE with these — never
+     *  display them, never re-fold. */
+    key: string[];
+    /** The qualified name as ONE display-ready string. Source-derived: the raw parts joined as
+     *  written (quoting kept). Synthesized: parts joined with dialect quoting where needed. */
+    fqn: string;
+}
+/**
+ * Build a QualifiedName from SOURCE-derived raw parts (as they appear in the text, delimiters
+ * intact where the user wrote them). `fqn` preserves the user's spelling and quoting exactly.
+ */
+export declare function qualifiedNameOf(rawParts: string[], config: QualifiedNameConfig): QualifiedName;
+/**
+ * Build a QualifiedName from SYNTHESIZED plain parts (a provider's resolved relation — no source
+ * text exists). `fqn` renders each part with the dialect's quoting exactly where the part needs
+ * delimiters to round-trip; plain identifier parts stay bare.
+ */
+export declare function synthesizedQualifiedName(parts: string[], config: QualifiedNameConfig): QualifiedName;

package/dist/ir/qualified-name.js

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// QualifiedName — the structured relation/column name the IR carries (issue #38).
+//
+// Root cause this type exists to fix: LOSS OF INFORMATION AT LOWERING. A dotted name's
+// structure (which part is the catalog, which the schema; what was quoted; what identity each
+// part folds to) was flattened to string[] at lower time, and every downstream layer re-derived
+// it by heuristic — collapsing, in practice, to last-part matching. The two standing principles
+// applied to names:
+//
+//   lossless    — `parts` is exactly what was written (partial qualification represented, never
+//                 defaulted; a tsql elided middle part `db..table` is an EXPLICITLY EMPTY part);
+//                 `fqn` joins the raw parts as written, quoting included. Nothing re-cased,
+//                 nothing invented.
+//   never-wrong — roles are assigned only to parts that exist, right-aligned against the
+//                 dialect's namespace; a part beyond the dialect's depth gets NO role. `key` is
+//                 the folded identity under the dialect's own quoting semantics; consumers
+//                 compare keys and never fold or parse dotted strings themselves.
+//
+// The dialect's lower() builds these (it is the one layer that knows both the CST shape and the
+// dialect's namespace); each dialect's config lives next to its fold rule in
+// src/<dialect>/fold.ts. This module is dialect-agnostic mechanics only.
+// ---------------------------------------------------------------------------
+import { displayWith, foldWith } from "../ident/fold.js";
+/** Right-align the dialect's roles onto the qualifier parts (everything before the last part).
+ *  Only parts that exist get a role; qualifier parts beyond the dialect's depth get none. */
+function assignRoles(q, stripped, roles) {
+    const qualifiers = stripped.slice(0, -1);
+    const n = Math.min(qualifiers.length, roles.length);
+    for (let j = 0; j < n; j++) {
+        const role = roles[roles.length - 1 - j];
+        q[role] = qualifiers[qualifiers.length - 1 - j];
+    }
+}
+/**
+ * Build a QualifiedName from SOURCE-derived raw parts (as they appear in the text, delimiters
+ * intact where the user wrote them). `fqn` preserves the user's spelling and quoting exactly.
+ */
+export function qualifiedNameOf(rawParts, config) {
+    const parts = rawParts.map((p) => displayWith(config.rule, p));
+    const q = {
+        name: parts[parts.length - 1] ?? "",
+        parts,
+        key: rawParts.map((p) => foldWith(config.rule, p, "table")),
+        fqn: rawParts.join("."),
+    };
+    assignRoles(q, parts, config.roles);
+    return q;
+}
+/**
+ * Build a QualifiedName from SYNTHESIZED plain parts (a provider's resolved relation — no source
+ * text exists). `fqn` renders each part with the dialect's quoting exactly where the part needs
+ * delimiters to round-trip; plain identifier parts stay bare.
+ */
+export function synthesizedQualifiedName(parts, config) {
+    const q = {
+        name: parts[parts.length - 1] ?? "",
+        parts: [...parts],
+        key: parts.map((p) => foldWith(config.rule, p, "table")),
+        fqn: parts.map((p) => renderPart(p, config.rule)).join("."),
+    };
+    assignRoles(q, parts, config.roles);
+    return q;
+}
+/** True when `part` round-trips as a bare identifier (letters/digits/underscore, non-digit lead).
+ *  Anything else needs the dialect's delimiters. Reserved words are a documented boundary: this
+ *  renderer does not consult keyword lists. */
+const PLAIN_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function renderPart(part, rule) {
+    if (PLAIN_IDENT.test(part))
+        return part;
+    const [open, close] = rule.delimiters[0] ?? ['"', '"'];
+    const body = rule.escapeStyle === "backslash" ? part.split(close).join(`\\${close}`) : part.split(close).join(close + close);
+    return `${open}${body}${close}`;
+}

package/dist/lineage/hops.js

@@ -129,10 +129,14 @@ function followColumn(scope, parts, walk, trail = []) {
         return [{ kind: "unresolved", via }];
     const { source, column } = binding;
     if (source.kind === "table") {
-        // A recursive CTE's self-reference is a plain table here (see Walk.activeCtes) — cycle-guard it.
-        if (source.name.length === 1 && walk.activeCtes.has(behaviorOf(scope).fold(source.name[0])))
+        // A recursive CTE's self-reference is a plain table here (see Walk.activeCtes) — cycle-guard
+        // it. activeCtes keys are the DEFAULT ("other") fold of the declared raw name, so fold the
+        // self-reference's raw text the same way (single-part ⇒ relation.fqn IS the raw text).
+        if (source.name.length === 1 && walk.activeCtes.has(behaviorOf(scope).fold(source.source.relation.fqn))) {
             return [{ kind: "unresolved", via }];
-        return [{ kind: "origin", origin: { table: source.name, column }, via }];
+        }
+        // Origins are DISPLAY-facing: the as-written parts, never the folded key.
+        return [{ kind: "origin", origin: { table: source.source.relation.parts, column }, via }];
     }
     const child = childScopeOf(source);
     if (!child) {

package/dist/lineage/lineage.js

@@ -172,8 +172,9 @@ function columnRefOrigins(parts, scope, schema, seen) {
  *  lineage walk (src/lineage/hops.ts) can defer pipe/lateral/graphtable/pivot sources — the ones
  *  it has no hop model for — to this exact shared origin walk, so the two walks can't drift. */
 export function columnOrigins(src, column, schema, seen) {
+    // Origins are DISPLAY-facing: the as-written parts (relation.parts), never the folded key.
     if (src.kind === "table")
-        return [{ table: src.name, column }];
+        return [{ table: src.source.relation.parts, column }];
     if (src.kind === "cte")
         return derivedOrigins(src.ref.scope, column, src.ref.def.columnAliases, schema, seen);
     if (src.kind === "subquery")

package/dist/minijinja/apply-tags.js

@@ -17,8 +17,9 @@
 // TemplateProvider for a call's relation (`provider.relationOf`) and carries no ref/source vocabulary
 // itself. The NEUTRAL provider answers nothing, so a bare parse leaves calls opaque; a
 // DbtTemplateProvider names ref/source. Naming is never-wrong: a resolved name comes from the call's
-// literal args, and a call whose relation the provider does not resolve keeps its placeholder name and
-// stays opaque. We NEVER fabricate a name.
+// literal args, and a call whose relation the provider does not resolve takes the RAW TAG TEXT as its
+// name ({{ ref('m') }} verbatim) and stays opaque. We NEVER fabricate a name — in particular the
+// placeholder fill (scaffolding this library invented) never escapes as one (issue #35).
 //
 // The IR is frozen after lower(); this transform REBUILDS with STRUCTURAL SHARING (new objects only on
 // changed paths, an unchanged subtree keeps its original already-frozen reference) and re-freezes the
@@ -26,6 +27,8 @@
 // returns the input `ast` unchanged.
 // ---------------------------------------------------------------------------
 import { freezeIR } from "../ir/freeze.js";
+import { qualifiedNameOf, synthesizedQualifiedName } from "../ir/qualified-name.js";
+import { resolveBehavior } from "../dialect-behavior/registry.js";
 /** Record a freshly built node's correlation to the tag it came from, then return it unchanged
  *  (a passthrough so call sites stay expression-shaped). A scalar-slot tag lowers to BOTH a
  *  column Expr (`kind: "column"`) and a parallel ColumnRef record (`kind: "columnref"`, same
@@ -56,7 +59,16 @@ export function applyTemplateTags(ast, tags, text, provider) {
         const relTags = tags.filter((t) => (t.kind === "call" && !t.incomplete) || t.kind === "other");
         if (relTags.length === 0)
             return { ast, byNode, byTag };
-        const ctx = { relTags, sets: resolveSets(tags, text, provider), text, provider, byNode, byTag };
+        const nameConfig = ast.dialect !== undefined ? resolveBehavior(ast.dialect).nameConfig : undefined;
+        const ctx = {
+            relTags,
+            sets: resolveSets(tags, text, provider),
+            text,
+            provider,
+            byNode,
+            byTag,
+            ...(nameConfig ? { nameConfig } : {}),
+        };
         const next = transformQuery(ast, ctx);
         // Scalar-slot marking: every column-shaped node whose token is a tag's placeholder
         // fill gets a `template` marker (span + provider key), so inference resolves it
@@ -152,7 +164,10 @@ function markTemplateExprs(node, ctx) {
 // never wrong.
 // ---------------------------------------------------------------------------
 /** Match a direct string-literal argument's raw text (no escapes, one token). */
-const LITERAL_ARG = /^(['"])([^'"\\]*)\1$/;
+/** A literal argument's value: a quoted string (quote-stripped) or a bare numeric literal —
+ *  both are the user's own text, never computed. Everything else stays `null` (computed). */
+const LITERAL_ARG = /^(?:(['"])([^'"\\]*)\1|(-?\d+(?:\.\d+)?))$/;
+const literalValueOf = (m) => m[2] ?? m[3];
 /** The raw text of a span. */
 function sliceSpan(text, span) {
     return text.slice(span.start, span.end);
@@ -172,11 +187,11 @@ export function callOf(mc, text) {
         const kw = KWARG_RE.exec(raw);
         if (kw) {
             const m = LITERAL_ARG.exec(kw[2].trim());
-            kwargs.push({ name: kw[1], value: m ? m[2] : null });
+            kwargs.push({ name: kw[1], value: m ? literalValueOf(m) : null });
         }
         else {
             const m = LITERAL_ARG.exec(raw);
-            args.push(m ? m[2] : null);
+            args.push(m ? literalValueOf(m) : null);
         }
     }
     return {
@@ -398,6 +413,23 @@ function transformTableSource(src, ctx) {
     // where `jjj…` was a fabrication.
     const aliasTok = src.aliasCst?.start;
     const base = aliasTok != null && inSpan(aliasTok.start, tag.tagSpan) ? withoutAlias(src) : src;
+    // An unresolved source's name is the RAW TAG TEXT — the bytes the user actually wrote. The
+    // placeholder fill is scaffolding this library invented so the grammar parses; letting it
+    // escape as a relation name (scope sources, lineage dependencies, go-to-def) is fabrication
+    // under the never-wrong rule (issue #35, reported by anvil).
+    const rawTagName = [ctx.text.slice(tag.tagSpan.start, tag.tagSpan.end)];
+    // Renaming a source rebuilds `relation` (#38): a provider-resolved name is SYNTHESIZED (plain
+    // logical parts, quoted where rendering needs it); the raw-tag-text fallback is source text.
+    // Without a dialect tag on the ast (never the parseTemplated path) the source keeps its
+    // original relation — the documented degrade.
+    const renamed = (b, parts, synthesized) => {
+        if (!ctx.nameConfig)
+            return b;
+        const relation = synthesized
+            ? synthesizedQualifiedName(parts, ctx.nameConfig)
+            : qualifiedNameOf(parts, ctx.nameConfig);
+        return { ...b, relation };
+    };
     // NOTE: `template.span` intentionally aliases `tag.tagSpan` BY REFERENCE. freezeIR
     // therefore also freezes the TagNode.tagSpan object returned in `.tags`, benign
     // since spans are read-only. Every call marker carries its `call`, the provider key
@@ -406,24 +438,24 @@ function transformTableSource(src, ctx) {
         const call = callOf(tag, ctx.text);
         const rel = ctx.provider.relationOf(call);
         // A call in a FROM slot (ref/source/a TVF-like macro). When the provider resolves its
-        // relation, carry the resolved name; otherwise keep the placeholder name (never fabricated).
+        // relation, carry the resolved name; otherwise the raw tag text (never the fill).
         // Either way the `call` keeps it consultable, so an unresolved call is not a dead end: a
         // provider added later resolves it. ref vs source is not stored here, it is call.name.
-        const named = rel ? { ...base, name: [...rel.nameParts] } : base;
+        const named = rel ? renamed(base, [...rel.nameParts], true) : renamed(base, rawTagName, false);
         const template = { kind: "call", span: tag.tagSpan, call };
         return attach(ctx, { ...named, template }, tag);
     }
     // Non-call expression tag (var / env_var / other) in a FROM slot. A bare `{{ t }}` resolving
     // through a `{% set t = … %}` single-call RHS carries the resolved relation name (when the
     // provider resolved it) or the call identity alone; every other case gets the opaque "expr"
-    // marker, so the placeholder name stops posing as a real table.
+    // marker. In every unresolved case the name is the raw tag text, never the fill.
     const ident = tag.kind === "other" ? bareIdentOf(tag, ctx.text) : undefined;
     const resolved = ident !== undefined ? ctx.sets.get(ident) : undefined;
     if (resolved) {
-        const named = resolved.name ? { ...base, name: [...resolved.name] } : base;
+        const named = resolved.name ? renamed(base, [...resolved.name], true) : renamed(base, rawTagName, false);
         const template = { kind: "call", span: tag.tagSpan, indirect: true, call: resolved.call };
         return attach(ctx, { ...named, template }, tag);
     }
     const template = { kind: "expr", span: tag.tagSpan, opaque: true };
-    return attach(ctx, { ...base, template }, tag);
+    return attach(ctx, { ...renamed(base, rawTagName, false), template }, tag);
 }

package/dist/mysql/behavior.js

@@ -1,7 +1,7 @@
 // The mysql DialectBehavior: everything the semantic layer needs for mysql, assembled from
 // this folder's own pieces. The registry wires it; nothing here reaches a central per-dialect table.
 import { mysqlLiteral, mysqlParseType, MYSQL_FUNCTION_RETURNS } from "./infer.js";
-import { displayName, fold, foldTableName, matchesSourceKey } from "./fold.js";
+import { displayName, fold, foldTableName, matchesSourceKey, MYSQL_NAME_CONFIG } from "./fold.js";
 import { likePatternToRegExp } from "../scope/like-pattern.js";
 import { SIGNATURES } from "../signature/signatures.js";
 import { acceptsFor } from "../dialect-behavior/coerce-rules.js";
@@ -10,6 +10,7 @@ export const mysqlBehavior = {
     displayName,
     foldTableName,
     matchesSourceKey,
+    nameConfig: MYSQL_NAME_CONFIG,
     likeMatch: (pattern, value) => likePatternToRegExp(pattern).test(value),
     literal: mysqlLiteral,
     parseType: mysqlParseType,

package/dist/mysql/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 MYSQL_FOLD_RULE: FoldRule;
+/** schema.table, two levels — MySQL's database IS its schema
+ *  (dev.mysql.com/doc/refman/8.4/en/identifier-qualifiers.html). */
+export declare const MYSQL_NAME_CONFIG: QualifiedNameConfig;
 /** Fold an identifier to its MySQL identity key. */
 export declare function fold(raw: string, kind?: IdentKind): string;
 /** Presentation twin: strip delimiters, no case change. */

package/dist/mysql/fold.js

@@ -33,6 +33,12 @@ export const MYSQL_FOLD_RULE = {
     unquoted: "lower",
     quoted: "lower",
 };
+/** schema.table, two levels — MySQL's database IS its schema
+ *  (dev.mysql.com/doc/refman/8.4/en/identifier-qualifiers.html). */
+export const MYSQL_NAME_CONFIG = {
+    roles: ["schema"],
+    rule: MYSQL_FOLD_RULE,
+};
 /** Fold an identifier to its MySQL identity key. */
 export function fold(raw, kind = "other") {
     return foldWith(MYSQL_FOLD_RULE, raw, kind);

package/dist/mysql/lower.js

@@ -3,6 +3,13 @@ import { MysqlParser as P } from "../generated/mysql/MysqlParser.js";
 import { keywordCategory, swallowedCategories, swallowedStatements } from "../ir/statement.js";
 import { collapsePartSpans, dotIdPartSpanOf, partSpanOf } from "../ir/part-span.js";
 import { freezeIR } from "../ir/freeze.js";
+import { qualifiedNameOf } from "../ir/qualified-name.js";
+import { MYSQL_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, MYSQL_NAME_CONFIG);
+}
 // ---------------------------------------------------------------------------
 // Lowering — MySQL (grammars-v4 sql/mysql/Positive-Technologies fork, Ivan
 // Kochurkin's split MySqlLexer/MySqlParser) CST -> the shared, dialect-neutral
@@ -636,7 +643,7 @@ function buildFrom(fromClause) {
         // tableSource: tableSourceItem joinPart* | '(' tableSourceItem joinPart* ')' | jsonTable.
         const jt = directChildrenOfRule(ts, P.RULE_jsonTable)[0];
         if (jt) {
-            from.push({ kind: "table", name: [jt.getText()], cst: jt });
+            from.push({ kind: "table", relation: relationOf([jt.getText()]), cst: jt });
             continue;
         }
         const base = directChildrenOfRule(ts, P.RULE_tableSourceItem)[0];
@@ -709,16 +716,24 @@ function buildSourceItem(item, fromSubqueries) {
     const seq = directChildrenOfRule(item, P.RULE_sequenceFunctionName)[0];
     if (seq) {
         const alias = directChildrenOfRule(item, P.RULE_uid)[0];
-        return [{ kind: "table", name: [seq.getText()], alias: alias?.getText(), aliasCst: alias, cst: item }];
+        return [
+            {
+                kind: "table",
+                relation: relationOf([seq.getText()]),
+                alias: alias?.getText(),
+                aliasCst: alias,
+                cst: item,
+            },
+        ];
     }
-    return [{ kind: "table", name: [item.getText()], cst: item }];
+    return [{ kind: "table", relation: relationOf([item.getText()]), cst: item }];
 }
 function tableSourceFromName(tn, alias, cst) {
     const fullId = directChildrenOfRule(tn, P.RULE_fullId)[0] ?? tn;
     const { parts, spans } = dottedParts(fullId);
     return {
         kind: "table",
-        name: parts.length ? parts : [tn.getText()],
+        relation: relationOf(parts.length ? parts : [tn.getText()]),
         namePartSpans: collapsePartSpans(spans),
         alias: alias?.getText(),
         aliasCst: alias,

package/dist/postgres/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, POSTGRES_NAME_CONFIG } from "./fold.js";
 import { postgresLiteral, postgresParseType, POSTGRES_FUNCTION_RETURNS } from "./infer.js";
 // PostgreSQL implicit coercion: str->num=true, bool<->num=false.
 export const postgresBehavior = {
@@ -9,6 +9,7 @@ export const postgresBehavior = {
     displayName,
     foldTableName,
     matchesSourceKey,
+    nameConfig: POSTGRES_NAME_CONFIG,
     likeMatch: (pattern, value) => likePatternToRegExp(pattern).test(value),
     literal: postgresLiteral,
     parseType: postgresParseType,

package/dist/postgres/fold.d.ts

@@ -1,5 +1,10 @@
 import { type FoldRule, type IdentKind } from "../ident/fold.js";
+import type { QualifiedNameConfig } from "../ir/qualified-name.js";
 export declare const POSTGRES_FOLD_RULE: FoldRule;
+/** database.schema.table (postgresql.org/docs/18/sql-syntax-lexical + ddl-schemas — cross-
+ *  database references are rejected at runtime but the three-part form parses). Normalized
+ *  vocabulary: catalog = database. */
+export declare const POSTGRES_NAME_CONFIG: QualifiedNameConfig;
 /** Fold an identifier to its PostgreSQL identity key. */
 export declare function fold(raw: string, kind?: IdentKind): string;
 /** Presentation twin: strip delimiters, no case change. */

package/dist/postgres/fold.js

@@ -20,6 +20,13 @@ export const POSTGRES_FOLD_RULE = {
     unquoted: "ascii-lower",
     quoted: "preserve",
 };
+/** database.schema.table (postgresql.org/docs/18/sql-syntax-lexical + ddl-schemas — cross-
+ *  database references are rejected at runtime but the three-part form parses). Normalized
+ *  vocabulary: catalog = database. */
+export const POSTGRES_NAME_CONFIG = {
+    roles: ["catalog", "schema"],
+    rule: POSTGRES_FOLD_RULE,
+};
 /** Fold an identifier to its PostgreSQL identity key. */
 export function fold(raw, kind = "other") {
     return foldWith(POSTGRES_FOLD_RULE, raw, kind);

package/dist/postgres/lower.js

@@ -3,7 +3,13 @@ import { PostgresParser as P } from "../generated/postgres/PostgresParser.js";
 import { keywordCategory, swallowedCategories, swallowedStatements } from "../ir/statement.js";
 import { partSpansOf } from "../ir/part-span.js";
 import { freezeIR } from "../ir/freeze.js";
-import { displayName } from "./fold.js";
+import { qualifiedNameOf } from "../ir/qualified-name.js";
+import { displayName, POSTGRES_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, POSTGRES_NAME_CONFIG);
+}
 // ---------------------------------------------------------------------------
 // Lowering — PostgreSQL (bytebase/parser postgresql/ fork, TVL-lineage grammar)
 // CST -> the shared dialect-neutral IR (src/ir/ir.ts). The semantic layer runs
@@ -559,7 +565,7 @@ function buildPrimarySource(tr, unsupported) {
     if (jsonTable) {
         return {
             kind: "table",
-            name: ["json_table"],
+            relation: relationOf(["json_table"]),
             alias,
             aliasCst,
             columnAliases: columnAliases ?? jsonTableColumns(jsonTable),
@@ -571,9 +577,10 @@ function buildPrimarySource(tr, unsupported) {
     if (funcTable) {
         const fname = firstShallow(funcTable, P.RULE_func_name);
         const funcAlias = directChildrenOfRule(tr, P.RULE_func_alias_clause)[0];
+        const funcTableName = [fname ? lastName(fname) : funcTable.getText()];
         return {
             kind: "table",
-            name: [fname ? lastName(fname) : funcTable.getText()],
+            relation: relationOf(funcTableName),
             alias: alias ?? (funcAlias ? funcAliasName(funcAlias) : undefined),
             aliasCst,
             cst: tr,
@@ -592,7 +599,8 @@ function buildPrimarySource(tr, unsupported) {
         if (innerFrom.length)
             return innerFrom[0];
     }
-    return { kind: "table", name: [textOrEmpty(tr)], alias, aliasCst, columnAliases, cst: tr };
+    const tableName = [textOrEmpty(tr)];
+    return { kind: "table", relation: relationOf(tableName), alias, aliasCst, columnAliases, cst: tr };
 }
 /** The output column names of a JSON_TABLE: every named column definition, NESTED levels included
  *  (they flatten into the same row type). */
@@ -618,7 +626,15 @@ function buildTableFromRelation(rel, alias, aliasCst, columnAliases) {
     const qn = directChildrenOfRule(rel, P.RULE_qualified_name)[0];
     const parts = qn ? nameParts(qn) : [textOrEmpty(rel)];
     const namePartSpans = qn ? columnPartSpans(qn) : undefined;
-    return { kind: "table", name: parts, namePartSpans, alias, aliasCst, columnAliases, cst: rel };
+    return {
+        kind: "table",
+        relation: relationOf(parts),
+        namePartSpans,
+        alias,
+        aliasCst,
+        columnAliases,
+        cst: rel,
+    };
 }
 function aliasName(aliasClause) {
     const ta = firstShallow(aliasClause, P.RULE_table_alias);

package/dist/qualify/qualify.d.ts

@@ -4,7 +4,7 @@ import type { Column } from "./schema.js";
 import { type SchemaProvider } from "./schema-provider.js";
 import { type ResolvedColumn } from "../sema/resolve.js";
 export interface Diagnostic {
-    kind: "unknown-table" | "unknown-column" | "ambiguous-column" | "unknown-field" | "wrong-arity" | "wrong-argument-type";
+    kind: "unknown-table" | "ambiguous-table" | "unknown-column" | "ambiguous-column" | "unknown-field" | "wrong-arity" | "wrong-argument-type";
     message: string;
     /** Start of the offending node: 1-based line, 0-based column. */
     line: number;