@miller-tech/uap 1.210.8 → 1.211.0

package/tools/agents/tests/test_schema_diff_gate.py

@@ -10,8 +10,10 @@ from __future__ import annotations
 
 import json
 import os
+import shutil
 import sqlite3
 import subprocess
+import sys
 import tempfile
 import unittest
 from datetime import datetime, timedelta, timezone
@@ -19,16 +21,41 @@ from pathlib import Path
 
 REPO = Path(__file__).resolve().parents[3]
 ENFORCER = REPO / "src" / "policies" / "enforcers" / "schema_diff_gate.py"
+GIT_BIN = "git"
+
+
+def _git_only_path() -> str:
+    """A PATH holding git and nothing else, so no checker can be found.
+
+    Every test in this file is about the MARKER layer, which the gate reaches
+    only when the inline checker cannot answer. Left to the ambient PATH these
+    tests passed for an accidental reason: the globally installed `uap`
+    predates --json, so the inline layer errored and fell through. The day that
+    binary is updated the inline layer would answer first and roughly a third
+    of the assertions below would silently invert -- green either way, but
+    testing something else entirely. Pinning the layer makes the choice
+    deliberate; the inline layer has its own suite in
+    test_schema_diff_inline.py.
+    """
+    d = Path(tempfile.mkdtemp(prefix="schema-gate-gitonly-"))
+    found = shutil.which(GIT_BIN)
+    if found:
+        (d / GIT_BIN).symlink_to(found)
+    return str(d)
+
+
+_GIT_ONLY_PATH = _git_only_path()
 
 
 def run_gate(op: str, args: dict, root: Path, tz: str | None = None):
     env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
     env["UAP_REPO_ROOT"] = str(root)
     env["UAP_WORKTREE_ROOT"] = str(root)
+    env["PATH"] = _GIT_ONLY_PATH
     if tz:
         env["TZ"] = tz
     r = subprocess.run(
-        ["python3", str(ENFORCER), "--operation", op, "--args", json.dumps(args)],
+        [sys.executable, str(ENFORCER), "--operation", op, "--args", json.dumps(args)],
         cwd=root,
         env=env,
         capture_output=True,
@@ -152,6 +179,171 @@ class SchemaDiffGateTest(unittest.TestCase):
         _, allowed, _ = run_gate("git-commit", {}, self.root)
         self.assertTrue(allowed, "a marker from the previous CLI release must still clear the gate")
 
+    def _blob_sha(self, rel: str) -> str:
+        """FULL 40-char sha. The enforcer compares exactly: a 7-hex prefix
+        matched with startswith is a 28-bit binding, grindable in minutes
+        against fully attacker-chosen SQL."""
+        out = subprocess.run(
+            ["git", "hash-object", "--", rel], cwd=self.root, capture_output=True, text=True
+        )
+        return out.stdout.strip()
+
+    def test_a_content_scoped_marker_covering_the_staged_bytes_clears_it(self):
+        rel = "migrations/001_add_table.sql"
+        self.write_marker(
+            datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            content=f"schema-diff pass: base HEAD~1 | files: {rel}@{self._blob_sha(rel)}",
+        )
+        _, allowed, reason = run_gate("git-commit", {}, self.root)
+        self.assertTrue(allowed, reason)
+        self.assertIn("covers the committed content", reason)
+
+    def test_a_pass_stops_covering_content_once_it_changes(self):
+        """THE REDESIGN. A marker vouches for BYTES, not for a time window.
+
+        Before this, one pass cleared every watched path for an hour no matter
+        what happened next — so a reviewed migration could be swapped for an
+        unreviewed one and committed inside the window.
+        """
+        rel = "migrations/001_add_table.sql"
+        self.write_marker(
+            datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            content=f"schema-diff pass: base HEAD~1 | files: {rel}@{self._blob_sha(rel)}",
+        )
+        # STAGE the change: what a plain `git commit` will store is what must
+        # be covered. (A worktree-only edit is deliberately NOT a block for a
+        # plain commit — see the companion test — because those bytes are not
+        # what gets stored, and blocking on them made partial staging
+        # unclearable.)
+        (self.root / rel).write_text("CREATE TABLE t (id int);\nDROP TABLE t;\n")
+        subprocess.run(["git", "add", rel], cwd=self.root, check=True)
+        _, allowed, reason = run_gate("git-commit", {}, self.root)
+        self.assertFalse(allowed, "staged content changed after the pass must re-arm the gate")
+        self.assertIn("no recent pass covers the CURRENT content", reason)
+
+    def test_a_diverging_worktree_must_be_covered_too(self):
+        """When the index and the worktree disagree, BOTH have to be covered.
+
+        This used to assert that a plain `git commit` was allowed here, on the
+        grounds that it stores the index and only `-a` stores the worktree.
+        That reasoning was right about those two forms and wrong about git:
+        `git commit -- <path>`, `--only`, `--include`, `-o` and `-i` also store
+        the worktree copy, and none of them contains `-a`. Reading the source
+        off the command string was a demonstrated bypass -- stage something
+        benign, edit the file, `git commit -m x -- <path>`, and the dropped
+        column landed while the gate reported the staged content clean.
+
+        The command-form space is bigger than it looks and this gate had
+        already got it wrong twice, so the inference is gone: there are only
+        two candidate byte-strings, and when they differ both must be clear.
+
+        Note what this is NOT. An earlier over-correction demanded that a
+        single MARKER cover both versions, which was unclearable -- no
+        sequence of commands produced such a marker. Here each version is
+        checked on its own, so ordinary partial staging passes; only an
+        actually-breaking copy refuses, and the reason names which one.
+        """
+        rel = "migrations/001_add_table.sql"
+        self.write_marker(
+            datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            content=f"schema-diff pass: base HEAD~1 | files: {rel}@{self._blob_sha(rel)}",
+        )
+        (self.root / rel).write_text("CREATE TABLE t (id int);\nDROP TABLE t;\n")  # unstaged
+        for command in ("git commit -m x", "git commit -am x", "git commit -m x -- " + rel):
+            with self.subTest(command=command):
+                _, allowed, _ = run_gate("git-commit", {"command": command}, self.root)
+                self.assertFalse(
+                    allowed,
+                    "the worktree copy is breaking and several commit forms store it",
+                )
+
+    def test_a_watched_path_the_CLI_cannot_parse_is_still_coverable(self):
+        """P0: the gate watched a SUPERSET of what the CLI examined.
+
+        `infra/helm_charts/**` and `infra/postgres-spock/**` are watched but are
+        YAML, which the CLI's filter skipped — so they could never enter a
+        marker, coverage always failed, and the refusal told the operator to
+        re-run a command that produced the identical marker. Verified as a
+        permanent block on the policy's headline file class before the fix.
+        Here the marker CAN name it, which is only true because the CLI now
+        examines everything the gate watches.
+        """
+        helm = self.root / "infra" / "helm_charts" / "pgdog"
+        helm.mkdir(parents=True)
+        rel = "infra/helm_charts/pgdog/values.yaml"
+        (self.root / rel).write_text("replicas: 2\n")
+        subprocess.run(["git", "add", "-A"], cwd=self.root, check=True)
+        sql = "migrations/001_add_table.sql"
+        self.write_marker(
+            datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            content=(
+                f"schema-diff pass: base HEAD~1 | files: {rel}@{self._blob_sha(rel)},"
+                f"{sql}@{self._blob_sha(sql)}"
+            ),
+        )
+        _, allowed, reason = run_gate("git-commit", {}, self.root)
+        self.assertTrue(allowed, reason)
+
+    def test_staged_bytes_are_judged_not_only_the_worktree(self):
+        """P0: the marker vouched for the WORKTREE while `git commit` takes the
+        INDEX.
+
+        Stage malicious, restore benign on disk, run the remedy against the
+        benign bytes — the gate announced "covers the staged content" and
+        allowed, while the commit would have taken the drop. Verified.
+        """
+        rel = "migrations/001_add_table.sql"
+        (self.root / rel).write_text("DROP TABLE t;")           # index = malicious
+        subprocess.run(["git", "add", rel], cwd=self.root, check=True)
+        (self.root / rel).write_text("CREATE TABLE t (id int);")  # worktree = benign
+        self.write_marker(
+            datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            content=f"schema-diff pass: base HEAD~1 | files: {rel}@{self._blob_sha(rel)}",
+        )
+        _, allowed, reason = run_gate("git-commit", {}, self.root)
+        self.assertFalse(allowed, "staged bytes the pass never saw must not be committable")
+
+    def test_a_second_worktrees_marker_does_not_invalidate_this_ones(self):
+        """Every worktree writes to the SAME main-checkout database. Consulting
+        only the newest marker made two concurrent worktrees invalidate each
+        other forever — a livelock this repo's .worktrees workflow would hit,
+        and a regression versus the old time-only rule."""
+        rel = "migrations/001_add_table.sql"
+        now = datetime.now(timezone.utc)
+        # ours first...
+        self.write_marker(
+            (now - timedelta(seconds=30)).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            content=f"schema-diff pass: base HEAD~1 | files: {rel}@{self._blob_sha(rel)}",
+        )
+        # ...then a NEWER one from another worktree, covering unrelated files
+        self.write_marker(
+            now.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            content="schema-diff pass: base HEAD~1 | files: other/999.sql@" + "0" * 40,
+        )
+        _, allowed, reason = run_gate("git-commit", {}, self.root)
+        self.assertTrue(allowed, "any in-window marker covering these bytes must clear: " + reason)
+
+    def test_PRESERVE_a_legacy_marker_without_shas_still_clears_it(self):
+        """Markers from the installed older CLI carry bare paths. Judging them
+        for coverage would block every operator who has not upgraded, with no
+        way to produce a covering marker — so they keep the time-only rule."""
+        self.write_marker(
+            datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            content="schema-diff pass: base HEAD~1 | files: migrations/001_add_table.sql",
+        )
+        _, allowed, reason = run_gate("git-commit", {}, self.root)
+        self.assertTrue(allowed, reason)
+
+    def test_PRESERVE_a_truncated_marker_does_not_deadlock(self):
+        """A change too large to enumerate records "(truncated)". Coverage is
+        unknowable, so it falls back rather than blocking unclearably."""
+        self.write_marker(
+            datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            content="schema-diff pass: base HEAD~1 | files: (truncated: 412 files)",
+        )
+        _, allowed, _ = run_gate("git-commit", {}, self.root)
+        self.assertTrue(allowed)
+
     def test_a_note_saying_the_diff_FAILED_does_not_clear_it(self):
         self.write_marker(
             datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),

package/tools/agents/tests/test_schema_diff_inline.py

@@ -0,0 +1,373 @@
+"""Tests for the inline-check pivot in the schema-diff gate.
+
+The gate used to ask "is there a marker saying somebody ran the checker?" and
+spent three review rounds trying to bind that marker to the bytes being
+committed. It now runs the checker itself, on the exact bytes the command will
+store.
+
+Nearly every test here exists because an adversarial review got past an earlier
+version of this code and the transcript is in the docstring. The through-line:
+the gate must believe the checker ONLY when the checker demonstrably read the
+right bytes and understood them. "No breaking changes" from something that
+could not open the file, or had no analyser for it, or answered about a
+different blob, is not an all-clear -- and every one of those was, at some
+point, reported to the operator as one.
+
+The checker is stubbed at the path the gate invokes, so these also pin the
+invocation contract: --paths-from, --source, and the verdict shape.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[3]
+ENFORCER = REPO / "src" / "policies" / "enforcers" / "schema_diff_gate.py"
+
+WATCHED = "migrations/001_add_table.sql"
+BASE_SQL = "CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT);\n"
+BREAKING_SQL = "CREATE TABLE t (id INTEGER PRIMARY KEY);\n"
+
+
+def run_gate(op: str, args: dict, root: Path, env_extra: dict | None = None):
+    env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+    env["UAP_REPO_ROOT"] = str(root)
+    env["UAP_WORKTREE_ROOT"] = str(root)
+    env.update(env_extra or {})
+    r = subprocess.run(
+        ["python3", str(ENFORCER), "--operation", op, "--args", json.dumps(args)],
+        cwd=root,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    try:
+        payload = json.loads(r.stdout or "{}")
+    except json.JSONDecodeError:
+        payload = {}
+    return payload.get("allowed", False), payload.get("reason", "")
+
+
+@unittest.skipIf(shutil.which("node") is None, "node is required to stub the checker")
+class InlineSchemaDiffTest(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory(prefix="schema-inline-")
+        self.root = Path(self._tmp.name)
+        git = ["git", "-c", "user.email=t@t", "-c", "user.name=t"]
+        subprocess.run(["git", "init", "-q"], cwd=self.root, check=True)
+        # The gate only prefers a tree-local dist/ when the tree IS the UAP
+        # checkout; see test_a_local_build_in_someone_elses_repo_is_not_run.
+        (self.root / "package.json").write_text('{"name":"@miller-tech/uap"}\n')
+        (self.root / "migrations").mkdir()
+        (self.root / WATCHED).write_text(BASE_SQL)
+        subprocess.run(["git", "add", "-A"], cwd=self.root, check=True)
+        subprocess.run(git + ["commit", "-q", "-m", "base"], cwd=self.root, check=True)
+        (self.root / WATCHED).write_text(BREAKING_SQL)
+        subprocess.run(["git", "add", "-A"], cwd=self.root, check=True)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    # -- helpers ------------------------------------------------------------
+
+    def staged_sha(self, path: str = WATCHED) -> str:
+        return subprocess.run(
+            ["git", "rev-parse", f":{path}"],
+            cwd=self.root, capture_output=True, text=True, check=True,
+        ).stdout.strip()
+
+    def stub_checker(self, payload, *, log_argv: bool = False):
+        """Install a fake checker where the gate looks for it.
+
+        `payload` is emitted verbatim as the last stdout line: a dict for a
+        well-formed verdict, a string to test how the gate handles noise.
+        """
+        bin_dir = self.root / "dist" / "bin"
+        bin_dir.mkdir(parents=True, exist_ok=True)
+        body = payload if isinstance(payload, str) else json.dumps(payload)
+        # Logged relative to cwd, not via an env var: the gate allowlists the
+        # child's environment (it must not hand an agent's credentials to a
+        # subprocess chosen partly by filesystem contents), so ARGV_LOG would
+        # never arrive.
+        prelude = (
+            "require('fs').appendFileSync('argv.log', "
+            "JSON.stringify(process.argv.slice(2)) + '\\n');"
+            if log_argv
+            else ""
+        )
+        (bin_dir / "cli.js").write_text(f"{prelude}\nconsole.log({json.dumps(body)});\n")
+
+    def verdict(self, *, breaking=(), sha=None, analysed=True, contract=1, path=WATCHED):
+        return {
+            "contract": contract,
+            "ran": True,
+            "base": "HEAD",
+            "files": [
+                {
+                    "path": path,
+                    "sha": self.staged_sha() if sha is None else sha,
+                    "analysed": analysed,
+                    "breaking": list(breaking),
+                }
+            ],
+        }
+
+    BREAK = ['Field "t.name" (TEXT) was removed']
+
+    def commit(self, command="git commit -m x", **env):
+        return run_gate("Bash", {"command": command}, self.root, env_extra=env or None)
+
+    # -- the pivot ----------------------------------------------------------
+
+    def test_a_clean_inline_run_clears_the_gate_with_no_marker_at_all(self):
+        """The point of the change: evidence is produced, not looked up."""
+        self.stub_checker(self.verdict())
+        allowed, reason = self.commit()
+        self.assertTrue(allowed, reason)
+        self.assertIn("no breaking changes", reason)
+
+    def test_a_breaking_change_is_refused_and_named(self):
+        self.stub_checker(self.verdict(breaking=self.BREAK))
+        allowed, reason = self.commit()
+        self.assertFalse(allowed, "a breaking schema change must not commit")
+        self.assertIn("BREAKING", reason)
+        self.assertIn("t.name", reason, "the refusal must say what broke")
+
+    # -- believing the checker ----------------------------------------------
+
+    def test_a_verdict_about_different_bytes_is_not_an_answer(self):
+        """The sha is re-derived, not taken on trust.
+
+        The first version compared the paths it sent against the paths echoed
+        back -- two copies of its own argument. That can fail on a whitespace
+        artefact and on nothing else, so it could not detect the case it was
+        written for: a checker reporting clean for bytes it never read.
+        """
+        self.stub_checker(self.verdict(sha="0" * 40))
+        allowed, reason = self.commit()
+        self.assertFalse(allowed, f"sha mismatch must not clear the gate: {reason}")
+        self.assertIn("uap schema-diff", reason, "must fall back to the shipped remedy")
+
+    def test_a_file_no_analyser_understood_is_not_clean(self):
+        """`analysed: false` is the helm/spock case, and it is the big one.
+
+        WATCHED_RE covers infra/helm_charts/** and infra/postgres-spock/**,
+        which are YAML; the differ has branches for .ts/.js, .sql and .json
+        only. Those paths produced an empty change list, and the gate published
+        it as "schema-diff ran ... no breaking changes" -- an affirmative
+        safety claim about a file nothing could parse, replacing master's
+        requirement that a human run the checker first.
+        """
+        self.stub_checker(self.verdict(analysed=False))
+        allowed, reason = self.commit()
+        self.assertFalse(allowed, f"unanalysed must not read as clean: {reason}")
+
+    def test_a_verdict_in_an_unknown_contract_is_not_an_answer(self):
+        self.stub_checker(self.verdict(contract=99))
+        allowed, _ = self.commit()
+        self.assertFalse(allowed, "an unrecognised verdict shape must not clear the gate")
+
+    def test_a_missing_entry_is_not_an_answer(self):
+        """Silence about a watched path is not a clean bill of health."""
+        self.stub_checker({"contract": 1, "ran": True, "base": "HEAD", "files": []})
+        allowed, _ = self.commit()
+        self.assertFalse(allowed)
+
+    def test_ran_false_is_not_an_answer(self):
+        self.stub_checker({"contract": 1, "ran": False, "base": "HEAD", "files": []})
+        allowed, _ = self.commit()
+        self.assertFalse(allowed)
+
+    def test_noise_on_stdout_is_not_an_answer(self):
+        self.stub_checker("not json at all")
+        allowed, _ = self.commit()
+        self.assertFalse(allowed)
+
+    def test_a_malformed_verdict_cannot_crash_the_gate_open(self):
+        """A crash IS an allow.
+
+        .claude/hooks/uap-policy-gate.sh maps a non-zero exit or unparseable
+        output to allowed for every enforcer except self-protect. Two shapes
+        reachable from a future CLI raised TypeError out of main(): a
+        `breaking` that is a bool rather than a list, and `files` entries that
+        are objects where strings were expected.
+        """
+        for payload in (
+            {"contract": 1, "ran": True, "files": [{"path": WATCHED, "sha": "x", "analysed": True, "breaking": True}]},
+            {"contract": 1, "ran": True, "files": [{"path": WATCHED, "sha": "x", "analysed": True, "breaking": {"a": 1}}]},
+            {"contract": 1, "ran": True, "files": ["not-an-object"]},
+            {"contract": 1, "ran": True, "files": {"not": "a list"}},
+        ):
+            with self.subTest(payload=payload):
+                self.stub_checker(payload)
+                allowed, reason = self.commit()
+                self.assertFalse(allowed, f"malformed verdict cleared the gate: {reason}")
+                self.assertNotEqual(reason, "", "the gate must answer, not die silently")
+
+    def test_a_missing_checker_leaves_the_shipped_behaviour_untouched(self):
+        allowed, reason = self.commit()
+        self.assertFalse(allowed, f"missing checker must not open the gate: {reason}")
+        self.assertIn("uap schema-diff", reason)
+
+    # -- what gets examined --------------------------------------------------
+
+    def test_the_gate_names_the_paths_and_the_source(self):
+        log = self.root / "argv.log"
+        self.stub_checker(self.verdict(), log_argv=True)
+        self.commit()
+        argv = json.loads(log.read_text().splitlines()[0])
+        self.assertIn("--json", argv)
+        self.assertIn("--source", argv)
+        self.assertEqual(argv[argv.index("--source") + 1], "index")
+        # Paths travel in a NUL-separated file, never on the command line: a
+        # comma split one path into two, and git C-quotes newlines and unicode
+        # into strings that name no file at all -- which the checker then
+        # reported clean.
+        self.assertIn("--paths-from", argv)
+        self.assertEqual(
+            Path(argv[argv.index("--paths-from") + 1]).name.startswith("uap-schema-paths-"),
+            True,
+        )
+
+    def test_a_diverging_worktree_is_checked_as_well_as_the_index(self):
+        """Both candidate byte-strings, because the command form cannot be read.
+
+        `git commit -- <path>`, `--only`, `--include`, `-o` and `-i` all store
+        the WORKTREE copy and contain no `-a`; meanwhile the `-A` in
+        `git add -A && git commit` matched the old short-flag test and pushed
+        the gate to the worktree for a commit that stores the index. Both
+        directions were demonstrated bypasses, so the inference is gone.
+        """
+        (self.root / WATCHED).write_text(BASE_SQL + "-- diverged\n")  # unstaged
+        log = self.root / "argv.log"
+        self.stub_checker(self.verdict(), log_argv=True)
+        self.commit()
+        sources = [
+            json.loads(line)[json.loads(line).index("--source") + 1]
+            for line in log.read_text().splitlines()
+            if line.strip()
+        ]
+        self.assertEqual(sorted(sources), ["index", "worktree"])
+
+    def test_only_one_check_when_index_and_worktree_agree(self):
+        """The common case must not pay for the rare one."""
+        log = self.root / "argv.log"
+        self.stub_checker(self.verdict(), log_argv=True)
+        self.commit()
+        self.assertEqual(len([x for x in log.read_text().splitlines() if x.strip()]), 1)
+
+    # -- the escape hatch ----------------------------------------------------
+
+    def _write_waiver(self, body: str, *, commit: bool) -> None:
+        waivers = self.root / "policies" / "waivers"
+        waivers.mkdir(parents=True, exist_ok=True)
+        (waivers / "deliberate-schema-diff.md").write_text(body)
+        if commit:
+            subprocess.run(["git", "add", "policies"], cwd=self.root, check=True)
+            subprocess.run(
+                ["git", "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q",
+                 "-m", "waiver", "--only", "policies"],
+                cwd=self.root, check=True,
+            )
+
+    def test_a_committed_waiver_naming_the_path_clears_a_breaking_change(self):
+        self.stub_checker(self.verdict(breaking=self.BREAK))
+        self._write_waiver(f"Deliberate: dropping name from {WATCHED}\n", commit=True)
+        allowed, reason = self.commit()
+        self.assertTrue(allowed, reason)
+        self.assertIn("waived", reason)
+
+    def test_an_uncommitted_waiver_does_not(self):
+        """`touch policies/waivers/x-schema-diff.md` was a total off-switch.
+
+        The check was Path.is_file() on the working tree, and
+        enforcement_self_protect deliberately exempts policies/waivers/ so that
+        agents CAN write there -- a carve-out justified when a waiver only
+        satisfied expert-review. An empty, never-committed file cleared every
+        breaking change. Verified.
+        """
+        self.stub_checker(self.verdict(breaking=self.BREAK))
+        self._write_waiver("", commit=False)
+        allowed, reason = self.commit()
+        self.assertFalse(allowed, f"an uncommitted waiver must not clear it: {reason}")
+
+    def test_a_waiver_for_a_different_path_does_not(self):
+        self.stub_checker(self.verdict(breaking=self.BREAK))
+        self._write_waiver("Deliberate: migrations/999_unrelated.sql\n", commit=True)
+        allowed, reason = self.commit()
+        self.assertFalse(allowed, f"a waiver must name what it excuses: {reason}")
+
+    # -- the gate's own subprocess ------------------------------------------
+
+    def test_the_inline_guard_stands_down_but_does_not_allow(self):
+        """The 2026-07-08 self-deadlock mechanism, without a new off-switch.
+
+        The guard has to exist so a nested gate does not call the checker
+        recursively. It must not ALLOW, though: the variable travels with the
+        shell, and the first version emitted allowed:true before looking at
+        anything, which made `UAP_SCHEMA_DIFF_INLINE=1` a complete disable for
+        a security control -- and unlike every comparable switch it was not in
+        self-protect's BYPASS_PATTERNS. Skipping to the fallback costs a forger
+        exactly what they already had.
+        """
+        self.stub_checker(self.verdict(breaking=self.BREAK))
+        allowed, reason = self.commit(UAP_SCHEMA_DIFF_INLINE="1")
+        self.assertFalse(allowed, f"the guard must not be an off-switch: {reason}")
+        self.assertIn("uap schema-diff", reason, "it should land in the fallback")
+
+
+@unittest.skipIf(shutil.which("node") is None, "node is required to stub the checker")
+class CheckerProvenanceTest(unittest.TestCase):
+    """Where the verdict comes from is part of the trust boundary."""
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory(prefix="schema-prov-")
+        self.root = Path(self._tmp.name)
+        subprocess.run(["git", "init", "-q"], cwd=self.root, check=True)
+        (self.root / "migrations").mkdir()
+        (self.root / WATCHED).write_text(BASE_SQL)
+        subprocess.run(["git", "add", "-A"], cwd=self.root, check=True)
+        subprocess.run(
+            ["git", "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "-m", "base"],
+            cwd=self.root, check=True,
+        )
+        (self.root / WATCHED).write_text(BREAKING_SQL)
+        subprocess.run(["git", "add", "-A"], cwd=self.root, check=True)
+        bin_dir = self.root / "dist" / "bin"
+        bin_dir.mkdir(parents=True)
+        # A rubber stamp: three lines, and it attests to anything.
+        (bin_dir / "cli.js").write_text(
+            "console.log(JSON.stringify({contract:1,ran:true,base:'HEAD',files:"
+            "[{path:'" + WATCHED + "',sha:'x',analysed:true,breaking:[]}]}));\n"
+        )
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_a_local_build_in_someone_elses_repo_is_not_run(self):
+        """dist/bin/cli.js is gitignored build output in any Node project.
+
+        Preferring it handed the verdict to a file inside the tree being gated
+        -- an easier forgery than the marker row this design replaced, and in a
+        consumer repo it means committing a migration executes that project's
+        unrelated build output. It is only trusted when the tree IS the UAP
+        checkout, where it is the same artefact `npm i -g .` installs.
+        """
+        (self.root / "package.json").write_text('{"name":"totally-normal-app"}\n')
+        allowed, reason = run_gate("Bash", {"command": "git commit -m x"}, self.root)
+        self.assertFalse(allowed, f"a foreign dist/ must not be the oracle: {reason}")
+
+    def test_no_package_json_is_also_not_the_uap_checkout(self):
+        allowed, reason = run_gate("Bash", {"command": "git commit -m x"}, self.root)
+        self.assertFalse(allowed, f"unidentified tree must not be trusted: {reason}")
+
+
+if __name__ == "__main__":
+    unittest.main()