test(scripts): add the consumer-resolution regression control (#16186)

Pinning the version fixes today's break and leaves the repository exactly
as blind as it was: `pnpm-lock.yaml` held `@better-auth/core@1.7.2`, so
every job here imported the version that still had
`createLocalAccountIssuer` while every consumer resolved `^1.7.2` to
1.7.3 and could not load the plugin at all.

`scripts/check-vendor-export-contract.mjs` closes that class. For every
governed vendor a publishable package statically imports runtime values
from, it asserts the declared range is an EXACT version, that the
installed copy IS that version, and that importing each specifier really
yields every symbol our shipped source takes from it — so "what CI
imported" and "what a consumer resolves" are the same string.

`--resolve` measures the same property instead of proving it: it
enumerates every registry version the DECLARED range admits, installs
each outside this workspace, and fails if any is missing a symbol we
import. Wired into validate-deps.yml, which already has the network and
runs daily; the offline leg runs in the lint farm on every PR.

`check-override-consistency.mjs` structurally cannot cover this — it asks
whether the override target is reachable from the declared range, and
`^1.7.2` agreed with `^1.7.2` all the way onto the broken version.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: hotlong

.github/workflows/lint.yml

@@ -2615,6 +2615,24 @@ jobs:
       - name: Auth mount-vs-ledger guard
         run: pnpm check:auth-mount-ledger
 
+      # Vendor export contract (#16186). `@better-auth/core@1.7.3` deleted
+      # `createLocalAccountIssuer` in a PATCH; plugin-auth imports it statically
+      # through a caret range, so published 17.1.0-17.3.0 could not load at all
+      # on a fresh install -- while every job here stayed green, because
+      # pnpm-lock.yaml held 1.7.2. The lockfile protected the producer from the
+      # defect it was shipping. This gate asserts that a governed vendor's
+      # DECLARED range is exact, that the installed version IS that version, and
+      # that importing it really yields every symbol our shipped source takes
+      # from it -- so "what CI imported" and "what a consumer resolves" are the
+      # same string. Cheap and offline: it imports what `pnpm install` already
+      # put on disk. The network half (`--resolve`, which enumerates every
+      # registry version the range admits) runs in validate-deps.yml, which
+      # already installs from the registry. No `paths:` filter: a manifest edit,
+      # a lockfile refresh and a new vendor import can each move it. Runs its
+      # own --self-test first.
+      - name: Vendor export contract
+        run: pnpm check:vendor-export-contract
+
       # Optional-`error` sink contract (#9754, wired by #10608). A sink TYPE that
       # declares `error` as OPTIONAL must also declare `warn` as NON-optional, so
       # every value of that type has somewhere to put a durability report —

.github/workflows/validate-deps.yml

@@ -9,6 +9,9 @@ on:
       - 'pnpm-workspace.yaml'
       - 'scripts/check-changeset-fixed.mjs'
       - 'scripts/check-override-consistency.mjs'
+      # The consumer-resolution half of the same question (#16186) — an edit to
+      # the gate must be exercised on the PR that makes it.
+      - 'scripts/check-vendor-export-contract.mjs'
       # The OSV exemption ledger and its check: a PR that touches either must
       # run this workflow, or an exemption could be added without the gate
       # that governs it ever running on the PR that adds it.
@@ -83,6 +86,29 @@ jobs:
       - name: Verify overrides are reflected in published manifests
         run: pnpm check:override-consistency
 
+      # The half check-override-consistency structurally cannot cover (#16186).
+      # It asks whether the override TARGET is reachable from the declared
+      # range; `^1.7.2` and `^1.7.2` agreed perfectly while both floated onto
+      # `@better-auth/core@1.7.3`, a PATCH that deleted the export plugin-auth
+      # imports statically. Three published releases could not load on a fresh
+      # install and nothing here went red, because pnpm-lock.yaml held 1.7.2.
+      #
+      # `--resolve` deliberately ignores the lockfile: for every version the
+      # DECLARED range admits on the registry -- the way a downstream project
+      # resolves -- it installs that version outside this workspace and checks
+      # the export surface. It fails if ANY admitted version is missing a symbol
+      # we import. With the ranges pinned exact that is one small install per
+      # vendor; under a caret it is one per published version, which is the cost
+      # of the risk being taken.
+      #
+      # It lives HERE rather than in the lint farm because it needs the network,
+      # which this job already has, and because the daily schedule is what turns
+      # "a vendor published something today" into a red in this repo instead of
+      # in a customer's install. An unreachable registry exits 3
+      # (PREREQUISITE NOT MET), never a green.
+      - name: Verify the declared ranges cannot resolve past our import surface
+        run: pnpm check:vendor-export-contract-resolve
+
       # Fail the workflow if known vulnerabilities are found — enforces
       # security compliance before merging.
       #

package.json

@@ -125,6 +125,8 @@
     "check:adr-0087-registration": "node scripts/check-adr-0087-registration.mjs --self-test && node scripts/check-adr-0087-registration.mjs",
     "check:changeset-gate-self-tests": "node scripts/check-empty-changeset.mjs --self-test && node scripts/check-adr-0087-registration.mjs --self-test && node scripts/check-changeset-no-major.mjs --self-test",
     "check:override-consistency": "node scripts/check-override-consistency.mjs --self-test && node scripts/check-override-consistency.mjs",
+    "check:vendor-export-contract": "node scripts/check-vendor-export-contract.mjs --self-test && node scripts/check-vendor-export-contract.mjs",
+    "check:vendor-export-contract-resolve": "node scripts/check-vendor-export-contract.mjs --self-test && node scripts/check-vendor-export-contract.mjs --resolve",
     "check:release-notes": "node scripts/check-release-notes.mjs",
     "check:release-page-status": "node scripts/check-release-page-status.mjs --self-test && node scripts/check-release-page-status.mjs",
     "check:release-body": "node scripts/release-github-releases.mjs --self-test",