@@ -1,21 +1,38 @@
 #!/usr/bin/env bash
-# Pins every `codeql/<name>` dependency in this repo's qlpack.yml files to the
-# exact library version shipped in the official CodeQL Bundle for a given CLI
+# Pins every `codeql/<name>` `dependencies:` entry in this repo's query/library
+# pack qlpack.yml files (`<language>/src`, `<language>/lib`, etc.) to the exact
+# library version shipped in the official CodeQL Bundle for a given CLI
 # release - overwriting whatever value is currently there (an unconstrained
 # `'*'`, or an exact version pinned by a previous run of this script against
 # an older CLI).
 #
-# Why this exists: `codeql pack upgrade` resolves an unconstrained `'*'`
-# dependency to the *latest-ever-published* version in the configured
-# registry (GHCR) - completely independent of whatever CodeQL CLI version is
-# pinned in `.codeqlversion`. That mismatch can jump `codeql/<lang>-all`
-# several major versions ahead of what the pinned CLI actually ships/tests
-# against, which can silently break analyses (see CONTRIBUTING.md's
-# "Updating the pinned CodeQL CLI/library version" section for a worked
-# example). Pinning these `codeql/*` deps to the exact bundle-paired version
-# before running `codeql pack upgrade` makes that resolution deterministic
-# and keeps every pack's declared library dependency in lockstep with the
-# CLI version this repo says it supports.
+# Deliberately does NOT touch `<language>/ext` or `<language>/ext-library-sources`
+# - those are model/extension packs that declare `extensionTargets:`, not
+# `dependencies:`, and are excluded from this script's file list entirely. See
+# CONTRIBUTING.md's "Supported CodeQL versions" section ("Why `extensionTargets`
+# is a floor, not an exact pin") for why: unlike `dependencies:`, an unsatisfied
+# `extensionTargets` constraint doesn't fail loudly, it silently drops the whole
+# extension pack, so re-pinning it to an exact version on every CLI bump (the
+# way this script handles `dependencies:`) turns routine consumer CLI drift into
+# silent, undetected loss of coverage (GitHubSecurityLab/CodeQL-Community-Packs#206).
+# `extensionTargets` floors are maintained by hand instead, as open-ended ranges.
+#
+# Why this exists (for `dependencies:`): `codeql pack upgrade` resolves an
+# unconstrained `'*'` dependency to the *latest-ever-published* version in the
+# configured registry (GHCR) - completely independent of whatever CodeQL CLI
+# version is pinned in `.codeqlversion`. That mismatch can jump
+# `codeql/<lang>-all` several major versions ahead of what the pinned CLI
+# actually ships/tests against, which can silently break analyses (see
+# CONTRIBUTING.md's "Updating the pinned CodeQL CLI/library version" section
+# for a worked example). Pinning these `codeql/*` deps to the exact
+# bundle-paired version before running `codeql pack upgrade` makes that
+# resolution deterministic and keeps every pack's declared library dependency
+# in lockstep with the CLI version this repo says it supports. This is safe
+# for `dependencies:` (unlike `extensionTargets:`) because a genuinely
+# unsatisfiable `dependencies:` constraint fails loudly at `codeql pack
+# install`/`resolve-dependencies` time (`ERROR: No valid pack solution
+# found...`), and any incompatibility in the CLI-bundled `codeql/<lang>-all`
+# itself surfaces as an ordinary QL compile error - never a silent drop.
 #
 # This script is idempotent and must be re-run (with a new target version)
 # on every subsequent CLI bump: once a dependency is pinned to an exact
@@ -67,8 +84,25 @@ echo "Discovered $(wc -l < "$VERSIONS_FILE") bundled codeql/* packages for CLI $
 # artifacts (.codeql/ pack caches, the /codeql cloned-repo checkout dir, and
 # /codeql_home, where .github/actions/install-codeql downloads/extracts the
 # CodeQL CLI - which ships its own small vendored qlpack.yml packs, e.g.
-# codeql/<lang>/downgrades, that have nothing to do with this repo).
-mapfile -t QLPACK_FILES < <(find . -name qlpack.yml -not -path "*/.codeql/*" -not -path "./codeql/*" -not -path "./codeql_home/*")
+# codeql/<lang>/downgrades, that have nothing to do with this repo) - and
+# excluding every `<language>/ext` and `<language>/ext-library-sources`
+# model/extension pack. Those use `extensionTargets:` instead of
+# `dependencies:`, and deliberately do NOT get re-pinned to the exact bundle
+# version on every CLI bump the way `dependencies:` does here (see
+# CONTRIBUTING.md's "Supported CodeQL versions" section, "Why
+# `extensionTargets` is a floor, not an exact pin"). Unlike `dependencies:`,
+# an unsatisfied `extensionTargets` constraint doesn't fail loudly - the CLI
+# just silently drops the whole extension pack (zero data-extension rows
+# applied, only a low-visibility `WARNING: ... is unused`) - so constantly
+# re-pinning it to whatever this repo's own CI happens to test against turns
+# every routine consumer CLI/version mismatch into silent, undetected loss of
+# coverage (see GitHubSecurityLab/CodeQL-Community-Packs#206). Instead,
+# `extensionTargets` is set by hand as an open-ended floor
+# (`codeql/<lang>-all: '>=X.Y.Z'`) and only ever raised when a maintainer
+# confirms an actual breaking change to the models-as-data schema (e.g. an
+# extensible predicate's arity/column set changed) - our own test suite
+# failing is the trigger to look for that, not a routine CLI bump.
+mapfile -t QLPACK_FILES < <(find . -name qlpack.yml -not -path "*/.codeql/*" -not -path "./codeql/*" -not -path "./codeql_home/*" -not -path "*/ext/*" -not -path "*/ext-library-sources/*")
 
 declare -A PINNED_COUNT=()
 while read -r pkg ver; do
 
@@ -84,6 +84,12 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
+          # NOTE: this only re-pins `dependencies:` in query/library packs
+          # (<language>/src, <language>/lib, etc.) - it deliberately skips
+          # <language>/ext and <language>/ext-library-sources, whose
+          # `extensionTargets:` floors are maintained by hand (see
+          # pin-codeql-library-versions.sh's header comment and
+          # CONTRIBUTING.md's "Supported CodeQL versions" section).
           .github/scripts/pin-codeql-library-versions.sh "${{ steps.version.outputs.version }}"
 
       - name: Upgrade every pack's dependencies
@@ -234,11 +240,13 @@ jobs:
             echo
             echo "This PR:"
             echo '- Updates `.codeqlversion` to `'"${{ steps.version.outputs.version }}"'`.'
-            echo '- Pins every `codeql/<lang>-all` / `codeql/<lang>-queries` dependency across all'
-            echo '  `qlpack.yml` files to the exact version shipped in the official CodeQL Bundle'
-            echo '  for this CLI release (see `.github/scripts/pin-codeql-library-versions.sh`) -'
-            echo '  this keeps `codeql pack upgrade` from jumping those libraries to'
-            echo '  registry-latest instead of the version this CLI actually ships/tests against.'
+            echo '- Pins every `codeql/<lang>-all` / `codeql/<lang>-queries` `dependencies:`'
+            echo '  entry across query/library `qlpack.yml` files (not `*/ext` or'
+            echo '  `*/ext-library-sources`, whose `extensionTargets` floors are maintained by'
+            echo '  hand) to the exact version shipped in the official CodeQL Bundle for this CLI'
+            echo '  release (see `.github/scripts/pin-codeql-library-versions.sh`) - this keeps'
+            echo '  `codeql pack upgrade` from jumping those libraries to registry-latest instead'
+            echo '  of the version this CLI actually ships/tests against.'
             echo '- Runs `codeql pack upgrade <dir>` for every pack directory to refresh its'
             echo '  `codeql-pack.lock.yml` against the new CLI and pinned library versions.'
             echo
 
@@ -118,6 +118,47 @@ The pinning is codified per language across:
 > this shortly after this pinning behavior was introduced and a pack's `qlpack.yml` still shows
 > `codeql/<pkg>: '*'`, that just means its dependencies haven't been re-resolved since, not that the
 > convention doesn't apply to it.
+>
+> **This exact-pin treatment applies to `dependencies:` only** (query/library packs: `src`, `lib`,
+> etc.) - `<language>/ext` and `<language>/ext-library-sources` model/extension packs use
+> `extensionTargets:` instead, and are handled completely differently; see the next warning box.
+
+> [!WARNING]
+> <a id="extensiontargets-floor"></a>**Why `extensionTargets` is an open-ended floor, not an exact
+> pin (unlike `dependencies:` above):** `extensionTargets` and `dependencies:` look similar but fail
+> very differently when a consumer's CodeQL CLI doesn't bundle the exact version this repo pinned
+> against. An unsatisfiable `dependencies:` constraint fails **loudly** - `codeql pack
+> install`/`resolve-dependencies` refuses with `ERROR: No valid pack solution found...` - and even a
+> stale/incompatible pin on the CLI-bundled `codeql/<lang>-all` itself is harmless in practice,
+> because the CLI always resolves that specific dependency to whatever `-all` version it actually
+> bundles regardless of the declared range, and any genuine incompatibility then surfaces as an
+> ordinary QL compile error. An unsatisfiable `extensionTargets` constraint does neither: the CLI
+> just **silently drops the entire extension pack** - zero data-extension rows applied, no compile
+> error, no SARIF-level signal, job stays green - and surfaces only a low-visibility
+> `WARNING: Extension pack '<name>' is unused.` that's easy to miss in CI logs. Exact-pinning
+> `extensionTargets` to whatever this repo's own CI happens to test against on every routine CLI bump
+> (the way [`pin-codeql-library-versions.sh`][pin-codeql-library-versions-script] handles
+> `dependencies:`) therefore turns *any* drift between this repo's tested CLI version and a
+> consumer's actual CLI version into silent, undetected loss of coverage - this is exactly what
+> happened in [#206][issue-206], reproduced and confirmed there across a local CLI, a genuine GHCR
+> registry install, and a real hosted GitHub Actions run.
+>
+> The fix: `extensionTargets` is set **by hand** as an open-ended floor
+> (`codeql/<lang>-all: '>=X.Y.Z'`, no upper bound) instead of an exact pin, and
+> [`pin-codeql-library-versions.sh`][pin-codeql-library-versions-script] explicitly excludes
+> `*/ext` and `*/ext-library-sources` from its rewrite loop so a routine CLI bump can never silently
+> re-tighten it back to an exact version. An open floor works because the models-as-data extensible
+> predicates (`sinkModel`, `sourceModel`, `summaryModel`, etc.) these packs contribute rows to are a
+> stable schema that only changes on a genuine breaking change (an extensible predicate's
+> arity/column set changing) - which is rare and would show up as real compilation/test failures in
+> this repo's own CI, not something that needs to be guarded against on every release. Only raise an
+> `extensionTargets` floor by hand when there's evidence of an actual such breaking change (upstream
+> `github/codeql` CHANGELOG "Breaking Changes" entries are a good place to check, though in practice
+> most of those are QL library API changes that affect query/library packs, not the data-extension
+> row format) - not just because a newer CLI happens to be available. As of this writing, Java's
+> `<language>/ext`/`ext-library-sources` packs pilot this open-floor approach; other languages still
+> use an exact `extensionTargets` pin pending the same conversion.
+
 
 **This section no longer hand-maintains a version table** - it used to, but that table went stale
 across multiple CLI bumps in a row (nobody remembered to update it, and there was no CI check
@@ -313,6 +354,10 @@ coding agent) in the loop for the hard part — fixing whatever the new CLI brea
 > If you run `codeql pack install`/`upgrade` against one of these directories locally while
 > developing (e.g. to sanity-check a new data extension), delete the resulting
 > `codeql-pack.lock.yml` before committing.
+>
+> This is a separate concern from how `extensionTargets`' *version value* itself is chosen and
+> maintained — see the ["Why `extensionTargets` is an open-ended floor, not an exact
+> pin"](#extensiontargets-floor) warning box above.
 
 > [!WARNING]
 > The `.codeqlversion` bump and the pack version bumps don't have to land in the same PR, but
@@ -463,3 +508,4 @@ Please do get in touch (privacy@github.com) if you have any questions about this
 [pr-155]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/155
 [pr-158]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/158
 [pr-159]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/159
+[issue-206]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/issues/206
@@ -2,7 +2,7 @@ library: true
 name: githubsecuritylab/codeql-java-library-sources
 version: 0.7.3
 extensionTargets:
-  codeql/java-all: '9.2.2'
+  codeql/java-all: '>=9.2.2'
 dataExtensions:
   - 'manual/*.yml'
   - 'manual/**/*.yml'
 
@@ -2,7 +2,7 @@ library: true
 name: githubsecuritylab/codeql-java-extensions
 version: 0.7.3
 extensionTargets:
-  codeql/java-all: '9.2.2'
+  codeql/java-all: '>=9.2.2'
 dataExtensions:
   - 'manual/*.yml'
   - 'manual/**/*.yml'