docs: add an EQL pin resolver so patch bumps stop relying on memory

[coderdan]

Adds scripts/check-eql-pin.ts: reports whether a newer EQL release exists for the pinned minor, and with --apply rewrites the pin. The companion workflow (#76, on main) runs it daily and opens a PR.

The goal is to stop remembering to bump the pin — not to stop reviewing it.

Why it proposes rather than follows

The pin exists because the drift check validates every schema-qualified symbol in the hand-written pages against the pinned release's manifest and fails the build on a mismatch. A floating pin means an upstream rename lands as a red build on whoever happens to have a PR open, with no commit of theirs to explain it — which is exactly what eql-3.0.0-alpha.4 did when it replaced eql_v3.ore_cllw.

So a bump arrives as a PR with the drift check already run, and the PR body says whether it is a rubber stamp or needs doc edits.

Why even patch bumps go through review

Ahead of Stack 1.0, EQL patch releases are not additive-only. Counting occurrences in the shipped cipherstash-encrypt.sql across what was a patch bump:

	eql-3.0.0	eql-3.0.1
eql_v3.contains	15	0 (removed)
eql_v3.matches	0	15 (added)
eql_v3_json_search	0	162 (new surface)

Auto-following would have swapped the entire fuzzy-match and encrypted-JSON surface underneath the docs silently. Once EQL semver tightens post-1.0, the natural next step is auto-merging these PRs when drift is clean — the workflow is shaped so that becomes a small change rather than a rewrite.

A newer minor or major is reported in the PR body but never proposed: that is migration work, not a pin change.

Details worth knowing

• Tag selection matches eql-X.Y.Z exactly and honours the API's prerelease flag, so it ignores prereleases (eql-3.0.1-alpha.0) and the sibling tags cut by the same release (eql-bindings-v3.0.3, @cipherstash/eql@3.0.3).
• The release bodies claim Preview (prerelease) even on stable releases — stale boilerplate that contradicts the actual flag. This trusts the flag, which is correct (eql-3.0.3 → prerelease=false).
• The regex rewrites only the fallback literal, leaving the EQL_RELEASE_TAG env override intact.

Verified

Run against this branch, which is pinned at eql-3.0.0:

Pinned:              eql-3.0.0
Latest in 3.0.x:     eql-3.0.3
Latest overall:      eql-3.0.3

→ Patch bump available: eql-3.0.0 → eql-3.0.3

--apply rewrites the pin to eql-3.0.3 and nothing else; Actions outputs (bump/from/to/newer_minor) emit correctly; biome check clean.

Note

Merge this before #76 — the workflow runs this script from the v2 checkout.

https://claude.ai/code/session_01NkuQNMvw9BpB4BWWeKtfV8

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
public-docs	Ready	Preview, Comment	Jul 28, 2026 4:27am