sql-code-graph 1.33.1__py3-none-any.whl → 1.34.1__py3-none-any.whl

{sql_code_graph-1.33.1.dist-info → sql_code_graph-1.34.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.33.1
+Version: 1.34.1
 Summary: SQL code graph analyzer and lineage tracer
 Project-URL: Homepage, https://github.com/Warhorze/sql-code-graph
 Project-URL: Repository, https://github.com/Warhorze/sql-code-graph

{sql_code_graph-1.33.1.dist-info → sql_code_graph-1.34.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sqlcg/__init__.py,sha256=Ah9v29nhYZBSzLC287CMtRK2RQvA-tt_cO0OTdKu_nU,116
+sqlcg/__init__.py,sha256=41PZf0zcZBhUQbwRo78_ftWrsT-lF8uXFf2sQm3NIKc,116
 sqlcg/__main__.py,sha256=1YoFLcqEgTwYq1J3TbUwpkdG0zeeLIf2fJvwWI-CLFU,109
 sqlcg/cli/__init__.py,sha256=W8fD0LpMq2xm_5WKGNMvJh2WBL1ho5E8hUeAqXQYT1g,28
 sqlcg/cli/coverage.py,sha256=Xm9ITzZDHv2mJ70Q5jCacVuhDStVrE3gq12_-Ypvtd8,43823
@@ -9,31 +9,31 @@ sqlcg/cli/commands/catalog.py,sha256=xCIWp_9xcDPHIMUB0xrZR3-G0WMvKbfq4yMwe2sDT2g
 sqlcg/cli/commands/db.py,sha256=QEDPs0boeFe8ETE8BWe7I2JLSXROUI571SHXMTUqxh8,7982
 sqlcg/cli/commands/find.py,sha256=uMdG08bU-AvB9RqsTKPfdVnJet7b3Ebj0xbsjqTclYA,2678
 sqlcg/cli/commands/gain.py,sha256=PQCWjlisjUY4Gz_MkppXPI1_w8xsB4DPlN7uAxx0GvY,10149
-sqlcg/cli/commands/git.py,sha256=OCqq5ApKgOyYouC_olJoyugaS2jsvEkq5MEcmFAXXEo,7255
+sqlcg/cli/commands/git.py,sha256=IB6Pypo_0RYd8rsKQLdP73OnlZUidZJ8_czQe1SNdOc,8857
 sqlcg/cli/commands/index.py,sha256=KGy0vPlvFcMetBjT5wIEvEcy9MEcLt7lhNaKfRWUkgU,19502
 sqlcg/cli/commands/install.py,sha256=4aZzvDNdl2Ea5v-ufR8Oj1qq30oGS_9jX17etYpoan8,10148
 sqlcg/cli/commands/mcp.py,sha256=drh5udcroZFddmJAG3q9JWxekDqTO9H4xC-oIqiis-Y,14871
-sqlcg/cli/commands/reindex.py,sha256=pNBonQYUhHwfJFWJjWq_uQorMmTcJ9HRT1MNH6v_YYo,19357
+sqlcg/cli/commands/reindex.py,sha256=6j1QL3TjrsnWaFSIKvpGJ3LF8CoCjAbue0UFtmk9FS0,22704
 sqlcg/cli/commands/report.py,sha256=JU0qjyMxwOukE7bN3XvvIzOI7zMg_Gsnvk_8F6pKNpA,4915
 sqlcg/cli/commands/uninstall.py,sha256=WrA1FnINxnd6mmE4-_QBK0aHBnibstJeAT8swnQKG4M,8962
 sqlcg/cli/commands/watch.py,sha256=_OvUQ4m_Pp2lAzI_f9UX2Gwb56zbsaSC4Tj8h51uciA,2806
 sqlcg/core/__init__.py,sha256=dXvLWpbQ72f5CM6sKSvBDnEGqGuIZaN5MmHyD8Vf1aA,154
 sqlcg/core/config.py,sha256=QxhIiF_let_ablMa-WttGbcAlCCDIpT4lR4tUVymIEI,19091
-sqlcg/core/duckdb_backend.py,sha256=Yc1TBYvR7Yc3jaz4cZ6VseFEhTemm9rBe4jAGK0Fx0s,40112
+sqlcg/core/duckdb_backend.py,sha256=zPsxiO2_qcE6axVZu8P3gUNHnJ1cgCCFv1XXy_t_LEw,42298
 sqlcg/core/freshness.py,sha256=Cm-w7jACPrt8TIstZpCzDJpYsHCiBo63ni5js8wCGbg,6248
-sqlcg/core/graph_db.py,sha256=QLkJk1bDA9s00QQlivBBfoUl6GSZiVSC6_9kY-IxsuY,10255
+sqlcg/core/graph_db.py,sha256=3iZ1J32cEn7_cVhNA1tLiNuJHCyatN4F40HXLLfmwHY,10815
 sqlcg/core/jobs.py,sha256=Je-fCdSKRgiSsv1W8SgNAlp36a7t7-pJZ-qKPbka9OE,3298
 sqlcg/core/noise_match.py,sha256=8jxMBum0HB7wnVyS8hHaklO279QOSNKDmPtv-0RujD8,4781
 sqlcg/core/queries.cypher,sha256=cvPOVe5GUOzJN4bxUvDxNI--xIIP8gm42TR-gUnea4U,4685
-sqlcg/core/queries.py,sha256=LgJcxMfienHD-ug2tAKMfcpfFrhtJvVXCsxrco9jAb0,3513
-sqlcg/core/queries.sql,sha256=EDSnJKz6gnWWYTlXBmyGmNYNhuX5V11CTP9IWVs0YlU,13695
+sqlcg/core/queries.py,sha256=mxpG_zBENG7kcoz3YolMvHv7s_HagWluakTUw3nYSts,3631
+sqlcg/core/queries.sql,sha256=gT8vl7CgOUZXjElpMZrHvuE_bs2ZJ4FLFA83EKaeRWM,15601
 sqlcg/core/schema.cypher,sha256=StaJqIzOLwF2X9HYvfHSdGiYGFb_YkiHubPrTu-Qpmg,2898
-sqlcg/core/schema.py,sha256=6KrMzbfceM4k0p2i7hPz8eNBco5_1eGXwdGTd3VUaok,1477
+sqlcg/core/schema.py,sha256=pVGzf__czAddmz-fsXgXqq2DTxN9EKom5RvIHLctIPU,1519
 sqlcg/indexer/__init__.py,sha256=Wh20Unz2OHs1oIyWLrpurPAasF0BET2g4iXtNk7mh2U,56
 sqlcg/indexer/dbt_adapter.py,sha256=EB5x1WU5Z9d-I97ADDj88S_hG1C4z4nbrv8JUCzXfy8,686
 sqlcg/indexer/error_classify.py,sha256=-sp8cRmuOBHu_CxnCtaXf34YxHFYwIFNjIrn4LaEv6M,7142
 sqlcg/indexer/git_delta.py,sha256=zYdH5q-jV7w_ne8Oxdywsy0N3rwUjpd5RjEDurlrMSA,5026
-sqlcg/indexer/indexer.py,sha256=qUTMkK3P3eCghjGzmM9QwzfUL23FOJ5siQ5HS_1l4nk,98037
+sqlcg/indexer/indexer.py,sha256=de-3aYaAP_EdG-bwtFwp4e2NGKw6kpDpxb_wsOsQhdU,101712
 sqlcg/indexer/pool.py,sha256=iMmCQtpDRKBTQBep2_EUq9THcsE18Zgk0hdaFB_CwiA,19006
 sqlcg/indexer/walker.py,sha256=Cft6JiJtdBFy0HR6L9pJdr5Fg0eRR3XBW1OMtM2apto,1947
 sqlcg/indexer/watcher.py,sha256=mJQq1LASRLKKwhz0WhCUWPLLqyPR2_-FD_8efYU6gE8,8442
@@ -43,8 +43,8 @@ sqlcg/lineage/schema_resolver.py,sha256=iXt6LYF6UVWsGUpcfbmjmGn9wCgXl721lTGf_8Aa
 sqlcg/metrics/__init__.py,sha256=hLJ6wm4St8qqYwKh3o9QG7lcEt1BEYM31ccqO9tGpIg,133
 sqlcg/metrics/store.py,sha256=KuDtxvyAgug9_KtiSCpvgKM2VZM7VSaI3D11uMLjJJk,10604
 sqlcg/parsers/__init__.py,sha256=AamA8wBbDZV9_zEtZCI4Hyen5UAVKHmBwjTghTt2PZE,785
-sqlcg/parsers/ansi_parser.py,sha256=KLbNapfPU20eWK-pullEFvhP78aroU9qlg2aj8ZcESo,37926
-sqlcg/parsers/base.py,sha256=D9FwirsitJEGoYNUvclWVbeMgvkePr4Frqbs3G29XEg,92871
+sqlcg/parsers/ansi_parser.py,sha256=Iayv93KDOs3qKrQlrPcpQRd4_K8dEsGHOaTY076e-GY,38032
+sqlcg/parsers/base.py,sha256=QDBDqF55vf4tmlfq_oyB9ZivHvhAuhMXU6sH3mQ5k5Q,97743
 sqlcg/parsers/bigquery_parser.py,sha256=mOnWTfXB_Dp4JwFE1PVYOB6CDPf5nYE0Dea8kJCl9uQ,2827
 sqlcg/parsers/postgres_parser.py,sha256=lYfUpQY6j4Qm7ndXBtXbgPoGzYqYddWt5YeFnWKdA6I,946
 sqlcg/parsers/registry.py,sha256=LXy1F6rqQI6VdxpRvZg_tNpoEucW3mXZHYBMlMONbX4,1496
@@ -65,7 +65,7 @@ sqlcg/utils/__init__.py,sha256=--iqt5ThTXmT8Wz7da8hs3n0zDfYPl8P-z5OgRJ_77E,154
 sqlcg/utils/hashing.py,sha256=H25-sYfxHKb3_IERFnHyAIYNiXN470Oqo5sJT_D3YOA,438
 sqlcg/utils/ignore.py,sha256=6__DfiYgynI2b8nH52O2BzI1EZcZ_LRazhqEOJVGGcE,1955
 sqlcg/utils/logging.py,sha256=u0fCmYsLj9o81vawm3xZTHaw68GQYVm7JxG-gP81u8A,840
-sql_code_graph-1.33.1.dist-info/METADATA,sha256=EUwN4XtkXO8s9Fp1qdtVTRLB-Xsm7Lj_3QOc8f1-OHU,17791
-sql_code_graph-1.33.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-sql_code_graph-1.33.1.dist-info/entry_points.txt,sha256=Wfe49sVzV9p4eVFGo5RxcV-frr3HOP0yzzst8JBxQLQ,46
-sql_code_graph-1.33.1.dist-info/RECORD,,
+sql_code_graph-1.34.1.dist-info/METADATA,sha256=UtXmf-S4GYLSS7MuPpYJxhaJ7fOmbZwSR54RnSyVGPw,17791
+sql_code_graph-1.34.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+sql_code_graph-1.34.1.dist-info/entry_points.txt,sha256=Wfe49sVzV9p4eVFGo5RxcV-frr3HOP0yzzst8JBxQLQ,46
+sql_code_graph-1.34.1.dist-info/RECORD,,

sqlcg/__init__.py

@@ -1,5 +1,5 @@
 """SQL Code Graph - SQL lineage and dependency analysis tool."""
 
-__version__ = "1.33.1"
+__version__ = "1.34.1"
 
 __all__ = ["__version__"]

sqlcg/cli/commands/git.py

@@ -23,6 +23,29 @@ class _HookSpec(NamedTuple):
 # Hook script templates — use {sqlcg_bin} as the placeholder for the resolved binary.
 # The sentinel comments (e.g. "# sqlcg post-checkout hook") must stay byte-for-byte
 # unchanged so R9 idempotency is preserved: _install_single_hook matches them verbatim.
+#
+# Run-time binary resolution (#126 + #1): the hook no longer trusts the single embedded
+# absolute literal to stay valid forever (a venv rebuild or tool upgrade makes the
+# install-time path stale and the resync would then run a wrong/missing binary). Instead
+# the shared _RESOLVE_PREAMBLE resolves the binary at *run time* with a hybrid order:
+#   1. the preferred path rendered in at install time ({sqlcg_bin}, normally the stable
+#      user-base binary from _resolve_sqlcg_bin) — the fast path, used if still executable;
+#   2. `command -v sqlcg` on $PATH — covers uv-tool, user-base-on-PATH, and active-venv;
+#   3. neither resolves → print a loud stderr error and exit non-zero (never silent).
+# The shell never recomputes getuserbase() — the preferred path is rendered in by Python.
+# It exports SQLCG_BIN for the hook body to invoke.
+_RESOLVE_PREAMBLE = (
+    'if [ -x "{sqlcg_bin}" ]; then\n'
+    '  SQLCG_BIN="{sqlcg_bin}"\n'
+    "elif command -v sqlcg >/dev/null 2>&1; then\n"
+    '  SQLCG_BIN="$(command -v sqlcg)"\n'
+    "else\n"
+    "  echo \"sqlcg: cannot find the sqlcg binary (tried '{sqlcg_bin}' and \\$PATH)"
+    " -- run 'sqlcg git install-hooks' to repoint this hook\" >&2\n"
+    "  exit 1\n"
+    "fi\n"
+)
+
 _HOOKS: list[_HookSpec] = [
     _HookSpec(
         filename="post-checkout",
@@ -32,7 +55,8 @@ _HOOKS: list[_HookSpec] = [
             "# sqlcg post-checkout hook — incremental resync after branch switch\n"
             "# $3 == 1 means branch checkout (not file checkout); skip file checkouts\n"
             '[ "$3" = "1" ] || exit 0\n'
-            '{sqlcg_bin} reindex --from "$1" --to "$2"'
+            + _RESOLVE_PREAMBLE
+            + '"$SQLCG_BIN" reindex --from "$1" --to "$2"'
             ' "$(git rev-parse --show-toplevel)" --dialect auto --quiet --notify'
             ' || echo "sqlcg: graph not updated (reindex failed)'
             " -- run 'sqlcg mcp status'\" >&2\n"
@@ -41,22 +65,27 @@ _HOOKS: list[_HookSpec] = [
     _HookSpec(
         filename="post-merge",
         sentinel="# sqlcg post-merge hook",
-        script_template="""\
-#!/bin/sh
-# sqlcg post-merge hook — incremental resync after pull/merge
-# git sets ORIG_HEAD to the pre-merge HEAD; pass it as --from so --notify can route
-# through a running server (same path as post-checkout). If ORIG_HEAD is unset (e.g.
-# first-ever merge / gc'd), fall back to the standalone stored-SHA delta (direct write).
-PREV=$(git rev-parse --verify --quiet ORIG_HEAD)
-TOP=$(git rev-parse --show-toplevel)
-if [ -n "$PREV" ]; then
-  {sqlcg_bin} reindex --from "$PREV" --to HEAD "$TOP" --dialect auto --quiet --notify \\
-    || echo "sqlcg: graph not updated (reindex failed) -- run 'sqlcg mcp status'" >&2
-else
-  {sqlcg_bin} reindex "$TOP" --dialect auto --quiet --notify \\
-    || echo "sqlcg: graph not updated (reindex failed) -- run 'sqlcg mcp status'" >&2
-fi
-""",
+        script_template=(
+            "#!/bin/sh\n"
+            "# sqlcg post-merge hook — incremental resync after pull/merge\n"
+            "# git sets ORIG_HEAD to the pre-merge HEAD; pass it as --from so --notify\n"
+            "# can route through a running server (same path as post-checkout). If\n"
+            "# ORIG_HEAD is unset (e.g. first-ever merge / gc'd), fall back to the\n"
+            "# standalone stored-SHA delta (direct write).\n"
+            + _RESOLVE_PREAMBLE
+            + "PREV=$(git rev-parse --verify --quiet ORIG_HEAD)\n"
+            "TOP=$(git rev-parse --show-toplevel)\n"
+            'if [ -n "$PREV" ]; then\n'
+            '  "$SQLCG_BIN" reindex --from "$PREV" --to HEAD "$TOP" --dialect auto'
+            " --quiet --notify \\\n"
+            '    || echo "sqlcg: graph not updated (reindex failed)'
+            " -- run 'sqlcg mcp status'\" >&2\n"
+            "else\n"
+            '  "$SQLCG_BIN" reindex "$TOP" --dialect auto --quiet --notify \\\n'
+            '    || echo "sqlcg: graph not updated (reindex failed)'
+            " -- run 'sqlcg mcp status'\" >&2\n"
+            "fi\n"
+        ),
     ),
 ]
 

sqlcg/cli/commands/reindex.py

@@ -129,6 +129,11 @@ def reindex_cmd(  # noqa: B008
     # below) and return to git immediately. The respawn guard env var prevents
     # the detached child from detaching again.
     if _is_hook_path and os.environ.get(_HOOK_DETACHED_ENV) != "1":
+        # #1 — loud foreground preflight BEFORE detaching. The detached child's
+        # schema gate (below) writes its Exit(1) to the hook-resync log, invisible
+        # to the user, so a stale-binary schema skew dies silently (exit 0 to git).
+        # Surface a real mismatch in the foreground, where git's terminal can see it.
+        _hook_preflight_schema_check()
         _spawn_detached_hook_resync(path)
         return
 
@@ -291,6 +296,66 @@ def _spawn_detached_hook_resync(path: Path) -> None:
     console.print(f"sqlcg: resyncing graph in background (log: {log_path})")
 
 
+def _hook_preflight_schema_check() -> None:
+    """Surface a stale-binary schema/version skew in the FOREGROUND hook process (#1).
+
+    On the hook path the resync is detached (#77), so the existing schema gate
+    (``reindex_cmd`` at ~:150) runs in the detached child whose stdout/stderr go to
+    ``hook-resync.log`` — its ``Exit(1)`` never reaches the user's terminal and the
+    graph silently never refreshes. This preflight runs *before* the detach and, on a
+    REAL mismatch, prints a visible, actionable stderr message and exits non-zero
+    without detaching.
+
+    Git runs post-checkout/post-merge AFTER the operation and ignores the hook exit
+    status, so the **stderr message** is the load-bearing part (not the exit code).
+
+    BOUNDED, FAIL-SOFT open (plan-review B1 — MANDATED). DuckDB takes an exclusive
+    file lock: per ``config.py`` ``get_backend`` docstring, a second process cannot
+    open the DB at all (even read-only) while another holds it — it raises
+    ``duckdb.IOException`` (#63). On rapid successive checkouts a prior detached
+    resync still holds the lock, so this open WILL contend. We therefore do a SINGLE
+    open attempt (NOT ``_open_backend_with_lock_retry``'s ~31 s retry, which would
+    stall ``git checkout`` — a #77-class regression) and, on ``IOException`` (lock
+    held ⇒ a resync is already in flight), treat it as "cannot determine — fall
+    through to the existing detach path unchanged": never block, never emit a
+    schema-mismatch error. Only a SUCCESSFUL read showing a real mismatch triggers
+    the loud exit. The backend is opened read-only and released before returning so
+    the detached child can still acquire the lock.
+    """
+    import duckdb
+
+    from sqlcg.core.config import get_backend
+    from sqlcg.core.schema import SCHEMA_VERSION
+
+    try:
+        backend = get_backend(read_only=True)
+    except duckdb.IOException:
+        # Lock held by an in-flight resync — cannot determine; fall through to detach.
+        return
+
+    try:
+        with backend:
+            stored_version = backend.get_schema_version()
+            if stored_version is None or stored_version == SCHEMA_VERSION:
+                # Matches (or no stored version yet on a fresh graph) — detach as today.
+                return
+            indexed_tool_version = backend.get_indexed_version()
+    except duckdb.IOException:
+        # Lock raced after the open (e.g. closed-then-reopened by the writer);
+        # fail soft exactly as the open-time IOException path.
+        return
+
+    skew = f" (graph last indexed by sqlcg {indexed_tool_version})" if indexed_tool_version else ""
+    print(
+        f"sqlcg: graph schema is v{stored_version} but this tool needs "
+        f"v{SCHEMA_VERSION}{skew} — the hook binary is stale. "
+        "Run 'sqlcg git install-hooks' to repoint the hook, then "
+        "'sqlcg db reset && sqlcg index <root>'.",
+        file=sys.stderr,
+    )
+    raise typer.Exit(1)
+
+
 def _open_backend_with_lock_retry() -> "GraphBackend":
     """Open the DuckDB backend, retrying with backoff if it is locked.
 

sqlcg/core/duckdb_backend.py

@@ -203,6 +203,14 @@ _EDGE_DDLS = [
         PRIMARY KEY (src_key, dst_key)
     )
     """,
+    """
+    CREATE TABLE IF NOT EXISTS "JOIN_COL_RESOLVE" (
+        src_key VARCHAR NOT NULL,
+        dst_key VARCHAR NOT NULL,
+        bare_col VARCHAR,
+        PRIMARY KEY (src_key, dst_key)
+    )
+    """,
 ]
 
 _INDEX_DDLS = [
@@ -230,6 +238,8 @@ _INDEX_DDLS = [
     'CREATE INDEX IF NOT EXISTS idx_STAR_SOURCE_dst ON "STAR_SOURCE" (dst_key)',
     'CREATE INDEX IF NOT EXISTS idx_CONSUMED_BY_src ON "CONSUMED_BY" (src_key)',
     'CREATE INDEX IF NOT EXISTS idx_CONSUMED_BY_dst ON "CONSUMED_BY" (dst_key)',
+    'CREATE INDEX IF NOT EXISTS idx_JOIN_COL_RESOLVE_src ON "JOIN_COL_RESOLVE" (src_key)',
+    'CREATE INDEX IF NOT EXISTS idx_JOIN_COL_RESOLVE_dst ON "JOIN_COL_RESOLVE" (dst_key)',
 ]
 
 # Node label → column list (all columns of that table, in order)
@@ -304,6 +314,7 @@ _EDGE_EXTRA_COLUMNS: dict[str, list[str]] = {
     RelType.DECLARES: [],
     RelType.STAR_SOURCE: ["qualifier", "target_table", "confidence"],
     RelType.CONSUMED_BY: [],
+    RelType.JOIN_COL_RESOLVE: ["bare_col"],
 }
 
 
@@ -752,6 +763,7 @@ class DuckDBBackend(GraphBackend):
                     "UPDATES",
                     "DECLARES",
                     "STAR_SOURCE",
+                    "JOIN_COL_RESOLVE",
                 ):
                     self._conn.execute(
                         f'DELETE FROM "{edge_table}" WHERE src_key IN ({placeholders})',
@@ -891,6 +903,39 @@ class DuckDBBackend(GraphBackend):
         row = result.fetchone()
         return int(row[0]) if row else 0
 
+    def resolve_join_columns(self) -> int:
+        """Resolve JOIN_COL_RESOLVE markers into concrete COLUMN_LINEAGE edges.
+
+        Runs AFTER ingestion AND after the catalog has been applied, so that
+        information_schema ``HAS_COLUMN`` rows are present.  For each parse-time
+        marker (a bare unqualified column in a >=2-table join projection), it
+        finds which of the query's source tables owns a column with that bare
+        name (any HAS_COLUMN source), normalising casing on both sides:
+
+          - exactly one owner  -> one high-confidence (0.9) edge (the dominant
+            live case: the second table is visible only via information_schema);
+          - more than one owner -> one low-confidence (0.5) edge per owner
+            (genuine ambiguity; over-attribute, never silently mis-pick);
+          - zero owners         -> emit nothing (honest empty; XML-DDL gap).
+
+        Mirrors :meth:`expand_star_sources` (post-index SQL pass).  The
+        suppressed sqlglot mis-bind edge is never emitted at parse time, so this
+        pass is the SOLE producer of these columns' edges — it MUST run in every
+        path that re-creates the markers (full index + both incremental paths).
+
+        Returns:
+            Number of COLUMN_LINEAGE JOIN_COL_RESOLVED edges present afterward.
+        """
+        from sqlcg.core.queries import RESOLVE_JOIN_COLUMNS_QUERY
+
+        self._conn.execute(RESOLVE_JOIN_COLUMNS_QUERY)
+        result = self._conn.execute(
+            'SELECT count(*) AS n FROM "COLUMN_LINEAGE" WHERE transform = ?',
+            ["JOIN_COL_RESOLVED"],
+        )
+        row = result.fetchone()
+        return int(row[0]) if row else 0
+
     # ------------------------------------------------------------------
     # Full-rebuild helpers
     # ------------------------------------------------------------------
@@ -927,6 +972,7 @@ class DuckDBBackend(GraphBackend):
             "DECLARES",
             "STAR_SOURCE",
             "CONSUMED_BY",
+            "JOIN_COL_RESOLVE",
         ]
         for tbl in edge_tables + node_tables:
             self._conn.execute(f'DELETE FROM "{tbl}"')

sqlcg/core/graph_db.py

@@ -273,6 +273,16 @@ class GraphBackend(ABC):
         """
         raise NotImplementedError(f"{type(self).__name__} does not support expand_star_sources")
 
+    def resolve_join_columns(self) -> int:
+        """Resolve JOIN_COL_RESOLVE markers into per-column COLUMN_LINEAGE edges.
+
+        Runs once per index after ingestion AND catalog apply, resolving bare
+        unqualified join columns against the full post-index HAS_COLUMN catalog
+        (including information_schema rows unavailable at parse time). Concrete
+        backends must override this; returns the total JOIN_COL_RESOLVED edge count.
+        """
+        raise NotImplementedError(f"{type(self).__name__} does not support resolve_join_columns")
+
 
 def indexed_repo_root(db: "GraphBackend") -> Path | None:
     """Return the indexed root path stored on the first Repo node, or None.

sqlcg/core/queries.py

@@ -51,6 +51,8 @@ LIST_DIALECTS_AND_REPOS_QUERY = _Q["LIST_DIALECTS_AND_REPOS"]
 EXPAND_STAR_SOURCES_QUERY = _Q["EXPAND_STAR_SOURCES"]
 EXPAND_STAR_SOURCES_HAS_COLUMN_QUERY = _Q["EXPAND_STAR_SOURCES_HAS_COLUMN"]
 EXPAND_STAR_SOURCES_LINEAGE_QUERY = _Q["EXPAND_STAR_SOURCES_LINEAGE"]
+RESOLVE_JOIN_COLUMNS_QUERY = _Q["RESOLVE_JOIN_COLUMNS"]
+COUNT_JOIN_COL_RESOLVED_QUERY = _Q["COUNT_JOIN_COL_RESOLVED"]
 COUNT_STAR_SOURCES_QUERY = _Q["COUNT_STAR_SOURCES"]
 COUNT_STAR_EXPANSIONS_QUERY = _Q["COUNT_STAR_EXPANSIONS"]
 FIND_DEFINITION_QUERY = _Q["FIND_DEFINITION"]

sqlcg/core/queries.sql

@@ -148,6 +148,53 @@ JOIN "SqlTable" tgt ON tgt.qualified = q.target_table
 WHERE q.target_table <> ''
   AND q.target_table <> t.qualified
 
+-- RESOLVE_JOIN_COLUMNS
+-- Resolve JOIN_COL_RESOLVE markers (bare unqualified join columns whose owning
+-- table was only knowable post-index, e.g. catalogued via information_schema)
+-- into concrete COLUMN_LINEAGE edges.
+--
+-- For each marker (src_key=query_id, dst_key=<dst_table>.<dst_col>, bare_col):
+--   find which of the query's SELECTS_FROM source tables OWNS a column named
+--   bare_col (any HAS_COLUMN source: ddl | information_schema | star_expansion |
+--   usage).  Casing is normalised on BOTH sides of the owner-match join because
+--   information_schema stores col_name as exported (e.g. STATUS) while the parsed
+--   bare name is lowercased (status).
+--
+-- Confidence contract:
+--   - exactly one owning table  -> HIGH confidence (0.9), the resolved edge
+--   - more than one owning table -> one LOW confidence (0.5) edge per owner
+--     (genuine ambiguity: over-attribute, never silently mis-pick)
+--   - zero owning tables         -> emit nothing (honest empty; XML-DDL gap)
+-- A window COUNT over the owning tables per marker selects the confidence in one
+-- pass.
+-- params: []
+INSERT OR REPLACE INTO "COLUMN_LINEAGE"
+  (src_key, dst_key, transform, confidence, query_id, inferred_from_source_name)
+SELECT
+  src_key,
+  dst_key,
+  'JOIN_COL_RESOLVED' AS transform,
+  CASE WHEN n_owners = 1 THEN 0.9 ELSE 0.5 END AS confidence,
+  query_id,
+  FALSE AS inferred_from_source_name
+FROM (
+  SELECT
+    c.id AS src_key,
+    m.dst_key AS dst_key,
+    m.src_key AS query_id,
+    count(*) OVER (PARTITION BY m.src_key, m.dst_key) AS n_owners
+  FROM "JOIN_COL_RESOLVE" m
+  JOIN "SELECTS_FROM" sf ON sf.src_key = m.src_key
+  JOIN "HAS_COLUMN" hc ON hc.src_key = sf.dst_key
+  JOIN "SqlColumn" c
+    ON c.id = hc.dst_key
+   AND lower(c.col_name) = lower(m.bare_col)
+) owners
+
+-- COUNT_JOIN_COL_RESOLVED
+-- params: []
+SELECT count(*) AS n FROM "COLUMN_LINEAGE" WHERE transform = 'JOIN_COL_RESOLVED'
+
 -- COUNT_STAR_SOURCES
 -- params: []
 SELECT count(*) AS n FROM "STAR_SOURCE"

sqlcg/core/schema.py

@@ -3,7 +3,7 @@
 from enum import StrEnum
 from importlib.resources import files
 
-SCHEMA_VERSION = "10"
+SCHEMA_VERSION = "11"
 
 
 class NodeLabel(StrEnum):
@@ -29,6 +29,7 @@ class RelType(StrEnum):
     DECLARES = "DECLARES"
     STAR_SOURCE = "STAR_SOURCE"
     CONSUMED_BY = "CONSUMED_BY"
+    JOIN_COL_RESOLVE = "JOIN_COL_RESOLVE"
 
 
 # Backward-compatible aliases

sqlcg/indexer/indexer.py

@@ -47,6 +47,7 @@ class FileRowSet:
     selects_from_edges: list[dict] = field(default_factory=list)
     column_lineage_edges: list[dict] = field(default_factory=list)
     star_source_edges: list[dict] = field(default_factory=list)
+    join_col_resolve_edges: list[dict] = field(default_factory=list)
     counts: dict = field(
         default_factory=lambda: {"tables": 0, "edges": 0, "columns_defined": 0, "star_sources": 0}
     )
@@ -71,6 +72,7 @@ class BatchRowBuffer:
     selects_from_edges: list[dict] = field(default_factory=list)
     column_lineage_edges: list[dict] = field(default_factory=list)
     star_source_edges: list[dict] = field(default_factory=list)
+    join_col_resolve_edges: list[dict] = field(default_factory=list)
 
     def extend(self, rows: FileRowSet) -> None:
         """Accumulate one file's row sets into this buffer."""
@@ -84,6 +86,7 @@ class BatchRowBuffer:
         self.selects_from_edges.extend(rows.selects_from_edges)
         self.column_lineage_edges.extend(rows.column_lineage_edges)
         self.star_source_edges.extend(rows.star_source_edges)
+        self.join_col_resolve_edges.extend(rows.join_col_resolve_edges)
 
     @classmethod
     def from_single(cls, rows: FileRowSet) -> "BatchRowBuffer":
@@ -292,6 +295,9 @@ def _flush_row_batch(
     star_source_edges = list(
         {(r["src_key"], r["dst_key"]): r for r in buf.star_source_edges}.values()
     )
+    join_col_resolve_edges = list(
+        {(r["src_key"], r["dst_key"]): r for r in buf.join_col_resolve_edges}.values()
+    )
 
     # --- Phase B2: usage-derived catalog harvest ---
     # Post-dedup: for each COLUMN_LINEAGE src endpoint whose table is a physical
@@ -345,6 +351,11 @@ def _flush_row_batch(
             star_source_edges = [
                 r for r in star_source_edges if r["dst_key"] not in excluded_tables
             ]
+            join_col_resolve_edges = [
+                r
+                for r in join_col_resolve_edges
+                if _table_of_column_id(r["dst_key"]) not in excluded_tables
+            ]
             column_lineage_edges = [
                 r
                 for r in column_lineage_edges
@@ -372,6 +383,9 @@ def _flush_row_batch(
         NodeLabel.COLUMN, NodeLabel.COLUMN, RelType.COLUMN_LINEAGE, column_lineage_edges
     )
     db.upsert_edges_bulk(NodeLabel.QUERY, NodeLabel.TABLE, RelType.STAR_SOURCE, star_source_edges)
+    db.upsert_edges_bulk(
+        NodeLabel.QUERY, NodeLabel.COLUMN, RelType.JOIN_COL_RESOLVE, join_col_resolve_edges
+    )
 
 
 def _subprocess_parse_worker(parser_cls, dialect, path, sql, q):
@@ -882,6 +896,12 @@ class Indexer:
         if profile:
             _t_catalog_end = time.perf_counter()
 
+        # Post-catalog: resolve JOIN_COL_RESOLVE markers against the full HAS_COLUMN
+        # catalog (Bug #5, PR-5 option b). MUST run after the catalog is applied so
+        # information_schema columns are present; the suppressed sqlglot mis-bind
+        # edge is never emitted, so this is the sole producer of the resolved edges.
+        join_cols_resolved = self._resolve_join_columns(db)
+
         # Classify all errors into buckets for measurement and reporting
         error_summary: dict[str, int] = {
             "E1": 0,
@@ -931,6 +951,7 @@ class Indexer:
             "columns_defined": nonlocal_counts["columns_defined"],
             "star_sources": nonlocal_counts["star_sources"],
             "star_edges_expanded": star_edges_expanded,
+            "join_cols_resolved": join_cols_resolved,
             "quality": nonlocal_counts["quality"],
             "error_summary": error_summary,
             "degraded_files": degraded_files,
@@ -1329,6 +1350,14 @@ class Indexer:
         # ---- Step 8: Single star expansion (same as index_repo) ------------------
         self._expand_star_sources(db)
 
+        # ---- Step 8b: Resolve JOIN_COL_RESOLVE markers (Bug #5, PR-5 option b) ----
+        # The incremental path does NOT reapply the catalog — it resolves against the
+        # information_schema HAS_COLUMN rows persisted by the prior full index. Without
+        # this, a delta touching a join file would re-create the markers but never
+        # resolve them, silently dropping the join-column edges until the next full
+        # index (plan-review BLOCKER).
+        self._resolve_join_columns(db)
+
         # ---- Step 9: Persist new SHA on success ----------------------------------
         db.set_indexed_sha(new_sha)
 
@@ -1382,6 +1411,13 @@ class Indexer:
         # Re-run star expansion after re-indexing
         self._expand_star_sources(db)
 
+        # Resolve JOIN_COL_RESOLVE markers (Bug #5, PR-5 option b) against the
+        # information_schema HAS_COLUMN rows persisted by the prior full index. The
+        # single-file path does NOT reapply the catalog; without re-resolving here a
+        # reindex of a join file would re-create the markers but drop the resolved
+        # join-column edges until the next full index (plan-review BLOCKER).
+        self._resolve_join_columns(db)
+
     def _index_single_file(self, parser, path: Path, sql: str, timeout: int) -> ParsedFile:
         """Parse one file, with optional timeout via subprocess isolation.
 
@@ -1706,6 +1742,21 @@ class Indexer:
                 )
                 rows.counts["star_sources"] += 1
 
+            # JOIN_COL_RESOLVE markers (Bug #5, PR-5 option b): bare unqualified
+            # join-projection columns whose owning source table is only knowable
+            # post-index (e.g. catalogued via information_schema). The sqlglot
+            # mis-bind edge was suppressed at parse time; the post-index resolver
+            # (DuckDBBackend.resolve_join_columns) is the SOLE producer of these
+            # columns' COLUMN_LINEAGE edges. src_key=query_id, dst_key=<dst>.<col>.
+            for jcr in stmt.join_col_resolves:
+                rows.join_col_resolve_edges.append(
+                    {
+                        "src_key": query_id,
+                        "dst_key": jcr.dst.full_id,
+                        "bare_col": jcr.bare_col,
+                    }
+                )
+
             # Upsert target table node (if not already a defined_table)
             # so that star expansion can create destination columns.
             # #44: when a canonical_by_bare index is available, attempt to resolve
@@ -1930,6 +1981,22 @@ class Indexer:
         """
         return db.expand_star_sources()
 
+    def _resolve_join_columns(self, db: GraphBackend) -> int:
+        """Run the post-index join-column resolution (Bug #5, PR-5 option b).
+
+        Calls DuckDBBackend.resolve_join_columns(), which resolves JOIN_COL_RESOLVE
+        markers (bare unqualified join columns) against the full post-index
+        HAS_COLUMN catalog — including information_schema rows unavailable at parse
+        time. MUST run AFTER the catalog is applied (full-index path) and AFTER star
+        expansion in every path that re-creates the markers; the suppressed sqlglot
+        mis-bind edge is never emitted, so this pass is the SOLE producer of these
+        columns' edges.
+
+        Returns:
+            Number of COLUMN_LINEAGE JOIN_COL_RESOLVED edges after resolution.
+        """
+        return db.resolve_join_columns()
+
     def _ingest_external_consumers(self, db: GraphBackend, path: Path) -> dict:
         """Ingest declared external downstream consumers from .sqlcg.toml.
 

sqlcg/parsers/ansi_parser.py

@@ -622,6 +622,7 @@ class AnsiParser(SqlParser):
             )
         column_lineage = extraction.edges
         star_sources = extraction.star_sources
+        join_col_resolves = extraction.join_col_resolves
         stmt_qualify_failed = extraction.qualify_failed
 
         # Extract defined columns for CREATE TABLE statements
@@ -666,6 +667,7 @@ class AnsiParser(SqlParser):
             parsing_mode="sqlglot",
             defined_columns=defined_columns,
             star_sources=star_sources,
+            join_col_resolves=join_col_resolves,
             defined_body=defined_body,
             clone_source=clone_source,
         )

sqlcg/parsers/base.py

@@ -204,6 +204,32 @@ class StarSource:
     qualifier: str | None = None
 
 
+@dataclass(frozen=True)
+class JoinColResolve:
+    """A deferred-resolution marker for a bare unqualified join-projection column.
+
+    Emitted (instead of the sqlglot mis-bind edge) when a top-level INSERT/CREATE
+    SELECT projection contains a bare column (``exp.Column`` with no ``.table``)
+    AND the statement has >=2 source tables.  The owning source table is only
+    knowable AFTER indexing (e.g. catalogued via information_schema), so the
+    binding is deferred to ``DuckDBBackend.resolve_join_columns`` — the post-index
+    pass is the SOLE producer of the resolved COLUMN_LINEAGE edge for this column.
+
+    Mirrors the over-attribution-instead-of-mis-bind discipline of the
+    ``CTE_PROJECTION_AMBIGUOUS`` precedent (see PR-5 in
+    plan/sprints/bugfix_lineage_correctness_validation.md).
+
+    Attributes:
+        dst: The destination ColumnRef the projection would have produced
+            (``<dst_table>.<dst_col_name>``); its full_id is the marker's dst_key.
+        bare_col: The bare (unqualified) column name to resolve against source
+            tables' HAS_COLUMN catalog.
+    """
+
+    dst: ColumnRef
+    bare_col: str = ""
+
+
 @dataclass(frozen=True)
 class LineageExtraction:
     """Result of column lineage extraction, including both edges and star markers.
@@ -211,6 +237,8 @@ class LineageExtraction:
     Attributes:
         edges: List of LineageEdge objects extracted from the statement
         star_sources: List of StarSource markers for SELECT * projections
+        join_col_resolves: List of JoinColResolve markers for bare unqualified
+            >=2-table join projections, resolved post-index against HAS_COLUMN.
         qualify_failed: True when the qualify() step raised an exception for
             this statement (schema-free retry may still yield a partial scope).
             Propagated to QueryNode.qualify_failed for per-statement storage.
@@ -218,6 +246,7 @@ class LineageExtraction:
 
     edges: list[LineageEdge]
     star_sources: list[StarSource]
+    join_col_resolves: list[JoinColResolve] = field(default_factory=list)
     qualify_failed: bool = False
 
 
@@ -268,6 +297,7 @@ class QueryNode:
     confidence: float = 1.0
     parsing_mode: str = "sqlglot"
     star_sources: list[StarSource] = field(default_factory=list)
+    join_col_resolves: list[JoinColResolve] = field(default_factory=list)
     defined_columns: list[str] = field(default_factory=list)
     defined_body: Any | None = None
     start_line: int = 0  # 1-based start line of statement in file; 0 = unknown
@@ -413,6 +443,22 @@ def normalize_keys(parsed: "ParsedFile", aliases: dict[str, str]) -> None:
         if stmt.clone_source is not None:
             stmt.clone_source = _norm_ref(stmt.clone_source)
 
+        # join_col_resolves (JoinColResolve.dst is a ColumnRef over a TableRef).
+        # The dst table is the INSERT/CREATE target, which is aliased above; keep
+        # the marker's dst_key in lockstep so the post-index resolver writes a
+        # COLUMN_LINEAGE edge with the same dst key as the rest of the graph.
+        new_join_col_resolves: list[JoinColResolve] = []
+        for jcr in stmt.join_col_resolves:
+            new_dst_table = _norm_ref(jcr.dst.table)
+            if new_dst_table is None:
+                # Empty-identity target — drop the marker (skip already logged).
+                continue
+            if new_dst_table is not jcr.dst.table:
+                new_dst = dataclasses.replace(jcr.dst, table=new_dst_table)
+                jcr = dataclasses.replace(jcr, dst=new_dst)
+            new_join_col_resolves.append(jcr)
+        stmt.join_col_resolves = new_join_col_resolves
+
         # column_lineage — LineageEdge and ColumnRef are frozen; rewrite via replace
         new_edges: list[LineageEdge] = []
         for edge in stmt.column_lineage:
@@ -1067,6 +1113,7 @@ class SqlParser(ABC):
 
         edges: list[LineageEdge] = []
         star_sources: list[StarSource] = []
+        join_col_resolves: list[JoinColResolve] = []
         _qualify_failed: bool = False
 
         # NEW (T-07-06): Record MERGE statements explicitly as deferred.
@@ -1417,6 +1464,23 @@ class SqlParser(ABC):
                         except Exception:
                             pass
 
+            # Bug #5 (PR-5, option b): count distinct PHYSICAL source tables ONCE per
+            # statement (never per column — CLAUDE.md hot-loop invariant). When a
+            # top-level INSERT/CREATE-SELECT join has >=2 physical sources, bare
+            # unqualified projection columns cannot be reliably bound at parse time
+            # (the owning table may be catalogued only via information_schema, which
+            # is unavailable to qualify()). For those columns we SUPPRESS the sqlglot
+            # mis-bind edge and record a JoinColResolve marker instead — resolved
+            # post-index against the full HAS_COLUMN catalog by
+            # DuckDBBackend.resolve_join_columns(). This mirrors the
+            # CTE_PROJECTION_AMBIGUOUS over-attribution discipline above, but defers
+            # resolution rather than over-attributing immediately. No new
+            # qualify/build_scope/exp.expand/sg_lineage call is added.
+            _physical_source_count = sum(
+                1 for _s in (query_sources or []) if getattr(_s, "role", "table") == "table"
+            )
+            _join_resolve_active = dst_table is not None and _physical_source_count >= 2
+
             # Extract output columns — skip positions handled by the positional INSERT block
             for loop_idx, col_expr in enumerate(col_expressions):
                 if loop_idx in positional_col_names:
@@ -1490,6 +1554,26 @@ class SqlParser(ABC):
                     expr_type = type(col_expr).__name__
                     out.errors.append(f"col_lineage_skip:func_fallback:{expr_type}")
                     continue
+
+                # Bug #5 (PR-5, option b): bare unqualified column in a >=2-physical-
+                # table join. SUPPRESS the sqlglot mis-bind edge (continue past
+                # sg_lineage) and record a JoinColResolve marker; the post-index
+                # resolver is the SOLE producer of this column's edge(s). A qualified
+                # reference (o.amount) has c.table set and fails the bare test, so it
+                # takes the existing sg_lineage path unchanged. This is the same
+                # cardinality as the existing edge append — no new hot-loop op.
+                if _join_resolve_active and dst_table is not None:
+                    _bare_cols = [c for c in col_expr.find_all(exp.Column) if not c.table]
+                    if _bare_cols:
+                        _bare_name = _bare_cols[0].name or col_name
+                        join_col_resolves.append(
+                            JoinColResolve(
+                                dst=ColumnRef(dst_table, col_name),
+                                bare_col=_bare_name,
+                            )
+                        )
+                        continue  # skip sg_lineage for this projection
+
                 # Schema validation: if schema is loaded and column isn't in it,
                 # emit a reduced-confidence edge rather than a full-confidence one.
                 # Skip when the expression has an explicit alias — the alias is the
@@ -1789,7 +1873,10 @@ class SqlParser(ABC):
             out.errors.append(f"col_lineage:statement:{exc}")
 
         return LineageExtraction(
-            edges=edges, star_sources=star_sources, qualify_failed=_qualify_failed
+            edges=edges,
+            star_sources=star_sources,
+            join_col_resolves=join_col_resolves,
+            qualify_failed=_qualify_failed,
         )
 
     def _resolve_star_source(