From 3e427be1f760f6148e00565977f091d67bf56f55 Mon Sep 17 00:00:00 2001
From: nia-sg-bot <nia-sg-bot@users.noreply.github.com>
Date: Fri, 25 Sep 2026 21:05:31 +0530
Subject: [PATCH] fix(contract): preserve ambiguous merge-base warnings

---
 diffgraph/schema/diffgraph-v2.schema.json |  1 +
 diffgraph/structural.py                   |  1 +
 tests/test_structural.py                  | 31 ++++++++++++++++++++++-
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/diffgraph/schema/diffgraph-v2.schema.json b/diffgraph/schema/diffgraph-v2.schema.json
index 4d89a0d..0afc939 100644
--- a/diffgraph/schema/diffgraph-v2.schema.json
+++ b/diffgraph/schema/diffgraph-v2.schema.json
@@ -413,6 +413,7 @@
             "invalid_head_ref",
             "merge_base_failed",
             "malformed_merge_base",
+            "ambiguous_merge_base",
             "malformed_git_output",
             "undecodable_path",
             "missing_object_id",
diff --git a/diffgraph/structural.py b/diffgraph/structural.py
index e48d061..bbef6e0 100644
--- a/diffgraph/structural.py
+++ b/diffgraph/structural.py
@@ -48,6 +48,7 @@
     "invalid_head_ref",
     "merge_base_failed",
     "malformed_merge_base",
+    "ambiguous_merge_base",
     "malformed_git_output",
     "undecodable_path",
     "missing_object_id",
diff --git a/tests/test_structural.py b/tests/test_structural.py
index 1ac12fe..eaf2703 100644
--- a/tests/test_structural.py
+++ b/tests/test_structural.py
@@ -7,7 +7,12 @@
 import jsonschema
 import pytest
 
-from diffgraph.git_snapshot import GitSnapshotError, ResolutionWarning, SnapshotResolution
+from diffgraph.git_snapshot import (
+    CommitRangeResolution,
+    GitSnapshotError,
+    ResolutionWarning,
+    SnapshotResolution,
+)
 from diffgraph.structural import analyze_local_diff
 
 SCHEMA = json.loads((Path(__file__).parents[1] / "diffgraph/schema/diffgraph-v2.schema.json").read_text())
@@ -1098,6 +1103,30 @@ def test_resolution_warning_preserves_machine_readable_code(monkeypatch, tmp_pat
     ]
 
 
+def test_ambiguous_merge_base_warning_is_not_downgraded(monkeypatch, tmp_path):
+    """Three-dot ambiguity remains actionable for JSON consumers."""
+    root = repo(tmp_path)
+    warning = ResolutionWarning(
+        "ambiguous_merge_base", "Git returned 2 merge bases; choose a base", None
+    )
+    monkeypatch.setattr(
+        "diffgraph.structural.resolve_commit_range",
+        lambda *args, **kwargs: CommitRangeResolution(
+            (), (warning,), "left", "right", None, None, None, True
+        ),
+    )
+
+    artifact = analyze_local_diff(
+        str(root), base_ref="left", head_ref="right", three_dot=True
+    )
+
+    assert_valid(artifact)
+    assert artifact["metadata"]["warnings"] == [{
+        "code": "ambiguous_merge_base",
+        "detail": "ambiguous_merge_base: Git returned 2 merge bases; choose a base",
+    }]
+
+
 def test_undecodable_path_warning_is_schema_valid(monkeypatch, tmp_path):
     root = repo(tmp_path)
     warning = ResolutionWarning(