greprag 5.80.0 → 5.82.0

package/dist/deploy-locks.js

@@ -0,0 +1,339 @@
+"use strict";
+/** deploy-locks.ts — the lock primitives shared by the deploy gate and the merge lock.
+ *
+ *  WHY A SEPARATE MODULE. `evaluateDeployGate` is read-only by construction, which
+ *  is what makes it safe to run in shadow beside a live gate. A lock is a write.
+ *  Keeping the primitives here lets the gate READ a lock without the gate module
+ *  ever gaining a write path, and without the two implementations drifting.
+ *
+ *  # adr: adr/deploy-gate-cli.md
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAIM_MAX_AGE_MS = exports.MERGE_STALE_MS = exports.DEPLOY_STALE_MS = void 0;
+exports.lockSession = lockSession;
+exports.lockOwnership = lockOwnership;
+exports.describeLockOwner = describeLockOwner;
+exports.gitDir = gitDir;
+exports.lockPath = lockPath;
+exports.deployLockPath = deployLockPath;
+exports.mergeLockPath = mergeLockPath;
+exports.lockIsStale = lockIsStale;
+exports.readLock = readLock;
+exports.readMergeLock = readMergeLock;
+exports.acquireLock = acquireLock;
+exports.releaseLock = releaseLock;
+exports.landedClaimsPath = landedClaimsPath;
+exports.isAncestorOfHead = isAncestorOfHead;
+exports.commitExists = commitExists;
+exports.readLandedClaims = readLandedClaims;
+exports.openClaims = openClaims;
+exports.recordLandedClaim = recordLandedClaim;
+exports.dropLandedClaim = dropLandedClaim;
+exports.readMergeState = readMergeState;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const proc_1 = require("./proc");
+const session_id_1 = require("./session-id");
+/** The basename already on disk in the repos that have a deploy lock today. The
+ *  CLI inspects the real file rather than a parallel one. */
+const PREFIX = process.env.GREPRAG_DEPLOY_LOCK_PREFIX || 'sift';
+/** A deploy is minutes. A merge with a human or an agent resolving conflicts can
+ *  legitimately be much longer, so it gets its own ceiling rather than sharing
+ *  the deploy's. Past it, the lock is treated as abandoned. */
+exports.DEPLOY_STALE_MS = 15 * 60 * 1000;
+exports.MERGE_STALE_MS = 60 * 60 * 1000;
+/**
+ * THE identity a lock records, resolved through the CLI's single session resolver.
+ *
+ * WHY NOT AN INLINE ENV CHAIN. This used to read
+ * `GREPRAG_SESSION_ID || CLAUDE_SESSION_ID || 'unknown'` here and again in
+ * `recordLandedClaim`. Claude Code exports `CLAUDE_CODE_SESSION_ID`, so both sites
+ * fell straight through to the sentinel, and the merge guard then read a session's
+ * OWN lock as a stranger's and refused its merge — with no way out but releasing the
+ * lock. A copied chain cannot be kept correct; `readSessionEnv` is the one place that
+ * knows every harness's variable, and adding a harness there fixes locks for free.
+ *
+ * Returns the short form the guard compares, or null when no harness identifies us.
+ */
+function lockSession() {
+    return (0, session_id_1.truncateSessionId)((0, session_id_1.readSessionEnv)());
+}
+/** Pure. `sessionId` may be a full UUID (a hook payload) or a short id (a lock record);
+ *  both are normalised through the shared helper rather than sliced by hand, so a
+ *  UUIDv7 harness compares on the same 16 hex digits everywhere. */
+function lockOwnership(held, sessionId) {
+    if (!held || held.stale)
+        return 'unlocked';
+    const owner = (0, session_id_1.truncateSessionId)(held.record.session);
+    const asker = (0, session_id_1.truncateSessionId)(sessionId);
+    // An owner that does not resolve covers locks written before identity was recorded
+    // properly, whose `session` is the literal string `unknown`.
+    if (!owner || !asker)
+        return 'unattributable';
+    return (0, session_id_1.sameSessionId)(owner, asker) ? 'mine' : 'peer';
+}
+/** For display only. Never let a missing owner print as `undefined`. */
+function describeLockOwner(record) {
+    return (0, session_id_1.truncateSessionId)(record.session) || 'unidentified';
+}
+function gitDir(cwd) {
+    const result = (0, proc_1.safeSpawnSync)('git', ['rev-parse', '--absolute-git-dir'], {
+        encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0)
+        throw new Error('not a git checkout');
+    return String(result.stdout).trim();
+}
+/** Locks live inside `.git`, so they are never tree dirt and can never be committed. */
+function lockPath(cwd, name) {
+    return path.join(gitDir(cwd), `${PREFIX}-${name}.lock`);
+}
+function deployLockPath(cwd, target) {
+    return lockPath(cwd, `deploy-${target}`);
+}
+/** A merge is repo-wide, not per-target: there is one working tree to conflict in. */
+function mergeLockPath(cwd) {
+    return lockPath(cwd, 'merge');
+}
+/**
+ * Pure: a lock whose owner died, or which outlived any plausible run, is not a lock.
+ *
+ * `checkPid` is the difference between the two kinds of holder, and getting it wrong
+ * makes a lock silently useless. A DEPLOY lock is held by a running script, so its pid
+ * is alive for the whole window and a dead pid means a crash. A MERGE lock is held by
+ * an agent session across many separate commands — the process that ran
+ * `merge-lock acquire` exited immediately, so its pid is always dead and pid-checking
+ * would mark every merge lock stale the instant it was taken. For that kind, elapsed
+ * time is the only honest signal.
+ */
+function lockIsStale(record, nowMs, staleMs = exports.DEPLOY_STALE_MS, { checkPid = true } = {}) {
+    if (!record || typeof record !== 'object')
+        return true;
+    const value = record;
+    const startedAt = Date.parse(String(value.startedAt ?? ''));
+    if (!Number.isFinite(startedAt))
+        return true;
+    if (nowMs - startedAt > staleMs)
+        return true;
+    if (!checkPid)
+        return false;
+    if (!Number.isInteger(value.pid))
+        return true;
+    try {
+        process.kill(value.pid, 0);
+        return false;
+    }
+    catch (error) {
+        // ESRCH means the owner is gone. EPERM means it is alive under another user.
+        return error?.code === 'ESRCH';
+    }
+}
+/** Read-only. Returns null when no lock file exists or it cannot be parsed. */
+function readLock(file, staleMs = exports.DEPLOY_STALE_MS, options = {}) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let record;
+    try {
+        record = JSON.parse(raw);
+    }
+    catch {
+        // An unparseable lock is not a claim anyone can honour, and holding a deploy
+        // on it forever would be worse than reclaiming it.
+        return null;
+    }
+    const startedAt = Date.parse(record?.startedAt ?? '');
+    return {
+        record,
+        stale: lockIsStale(record, Date.now(), staleMs, options),
+        ageMs: Number.isFinite(startedAt) ? Date.now() - startedAt : Number.NaN,
+    };
+}
+/** The merge lock is session-held, so it never pid-checks. One helper so no caller
+ *  has to remember that, which is exactly the mistake this shape prevents. */
+function readMergeLock(cwd) {
+    return readLock(mergeLockPath(cwd), exports.MERGE_STALE_MS, { checkPid: false });
+}
+/** Exclusive create, then reclaim only if the existing lock is provably stale. */
+function acquireLock(file, label, staleMs = exports.DEPLOY_STALE_MS, options = {}) {
+    const session = lockSession();
+    const record = {
+        // A process-held lock must record the process that is actually DEPLOYING, which for
+        // a script that shells out to this CLI is the caller, not this short-lived command.
+        // Recording our own pid there would make the lock read as stale the moment it exists.
+        pid: options.pid ?? process.pid,
+        startedAt: new Date().toISOString(),
+        // Omitted, never a placeholder: a lock that claims an owner it does not have is
+        // read as a stranger's by everyone, its holder included.
+        ...(session ? { session } : {}),
+        label,
+    };
+    try {
+        const fd = fs.openSync(file, 'wx');
+        fs.writeSync(fd, JSON.stringify(record));
+        fs.closeSync(fd);
+        return { ok: true, path: file };
+    }
+    catch (error) {
+        if (error?.code !== 'EEXIST')
+            throw error;
+    }
+    const held = readLock(file, staleMs, options);
+    if (held && !held.stale)
+        return { ok: false, path: file, held };
+    fs.writeFileSync(file, JSON.stringify(record));
+    return { ok: true, path: file, ...(held ? { held } : {}) };
+}
+function releaseLock(file) {
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch {
+        // A lock we cannot remove goes stale on its own; never fail completed work over it.
+    }
+}
+// ---------------------------------------------------------------------------
+// Landed claims — "I merged this; prove it is in what ships."
+// ---------------------------------------------------------------------------
+/** A claim outlives one deploy but must not block production forever. A session that
+ *  recorded a claim and then vanished would otherwise wedge the checkout. */
+exports.CLAIM_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+function landedClaimsPath(cwd) {
+    return path.join(gitDir(cwd), `${PREFIX}-landed.json`);
+}
+/** True when `sha` is reachable from HEAD. False for an orphan, a rewritten commit,
+ *  or one that never existed — the caller distinguishes those with `commitExists`. */
+function isAncestorOfHead(cwd, sha) {
+    const result = (0, proc_1.safeSpawnSync)('git', ['merge-base', '--is-ancestor', sha, 'HEAD'], {
+        encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return result.status === 0;
+}
+function commitExists(cwd, sha) {
+    const result = (0, proc_1.safeSpawnSync)('git', ['cat-file', '-e', `${sha}^{commit}`], {
+        encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return result.status === 0;
+}
+function readLandedClaims(cwd) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(landedClaimsPath(cwd), 'utf8'));
+        return Array.isArray(raw) ? raw.filter(c => c && typeof c.sha === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Claims still worth checking: not yet shipped, and not older than the age cap.
+ *  A claim that IS an ancestor is satisfied permanently, so dropping it is safe and
+ *  keeps the file to exactly the open questions. */
+function openClaims(cwd, claims, nowMs = Date.now()) {
+    return claims.filter(c => {
+        const at = Date.parse(c.at ?? '');
+        if (Number.isFinite(at) && nowMs - at > exports.CLAIM_MAX_AGE_MS)
+            return false;
+        return !isAncestorOfHead(cwd, c.sha);
+    });
+}
+function recordLandedClaim(cwd, sha, label) {
+    const session = lockSession();
+    const claim = {
+        sha,
+        label,
+        ...(session ? { session } : {}),
+        at: new Date().toISOString(),
+    };
+    const kept = openClaims(cwd, readLandedClaims(cwd)).filter(c => c.sha !== sha);
+    try {
+        fs.writeFileSync(landedClaimsPath(cwd), JSON.stringify([...kept, claim], null, 2));
+    }
+    catch {
+        // A claim we cannot record is a claim nobody will check — say so rather than pretend.
+        throw new Error(`could not record the landed claim at ${landedClaimsPath(cwd)}`);
+    }
+    return claim;
+}
+function dropLandedClaim(cwd, sha) {
+    const claims = readLandedClaims(cwd);
+    const kept = claims.filter(c => !c.sha.startsWith(sha) && !sha.startsWith(c.sha));
+    if (kept.length === claims.length)
+        return false;
+    fs.writeFileSync(landedClaimsPath(cwd), JSON.stringify(kept, null, 2));
+    return true;
+}
+/**
+ * Detect a half-finished merge, cherry-pick, revert or rebase.
+ *
+ * This is the check that was missing on 2026-09-04: a chip session died mid-merge
+ * and left the canonical checkout conflicted. Three separate sessions then
+ * discovered it independently, each reasoning from scratch about whether the owner
+ * was still alive, before one of them completed it. Git knows this state exactly
+ * and answers for free.
+ */
+function readMergeState(cwd) {
+    const dir = gitDir(cwd);
+    const markers = [
+        ['MERGE_HEAD', 'merge'],
+        ['CHERRY_PICK_HEAD', 'cherry-pick'],
+        ['REVERT_HEAD', 'revert'],
+        ['rebase-merge', 'rebase'],
+        ['rebase-apply', 'rebase'],
+    ];
+    for (const [name, kind] of markers) {
+        const marker = path.join(dir, name);
+        let stat;
+        try {
+            stat = fs.statSync(marker);
+        }
+        catch {
+            continue;
+        }
+        return { inProgress: true, kind, ageMs: Date.now() - stat.mtimeMs, unresolved: unresolvedPaths(cwd) };
+    }
+    return { inProgress: false, kind: null, ageMs: 0, unresolved: [] };
+}
+function unresolvedPaths(cwd) {
+    const result = (0, proc_1.safeSpawnSync)('git', ['diff', '--name-only', '--diff-filter=U'], {
+        encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0)
+        return [];
+    return String(result.stdout).split('\n').map(line => line.trim()).filter(Boolean);
+}

package/dist/deploy-verify.js

@@ -0,0 +1,209 @@
+"use strict";
+/** deploy-verify.ts — did production actually take the upload?
+ *
+ *  WHY THIS MOVED. Every other check describes an artifact on disk. This one asks
+ *  production what it is serving, and it is the only correct answer to "is my change
+ *  live?". Sift and the site each carried their own copy inside the shared block;
+ *  onboarding greprag, paybot and discord would have meant three more. It depends on
+ *  nothing repo-specific — an origin, a commit, and HTTP — so it belongs here.
+ *
+ *  CACHE DISCIPLINE IS LOAD-BEARING, and a port that keeps only half of it looks
+ *  correct while silently reintroducing the bug. On 2026-09-04 the gate was found
+ *  confirming against a CDN copy: the site's build stamp was a plain static asset
+ *  served with a cacheable default, so the edge answered the deploy's own liveness
+ *  check with the PREVIOUS deploy's commit. Both halves are required — the origin
+ *  returns `Cache-Control: no-store`, and every request here is sent uncacheable.
+ *  `assertUncacheable` checks the origin half, because the request half alone cannot
+ *  save you: static assets are cached without regard to the query string, so no
+ *  caller can opt out from the client side.
+ *
+ *  # adr: adr/deploy-gate-cli.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILD_STAMP_PATH = void 0;
+exports.fetchHerokuReleases = fetchHerokuReleases;
+exports.verifyHerokuRelease = verifyHerokuRelease;
+exports.sameCommit = sameCommit;
+exports.describeStampDrift = describeStampDrift;
+exports.describeStampCacheability = describeStampCacheability;
+exports.verifyDeployedBuildStamp = verifyDeployedBuildStamp;
+exports.parseHerokuDeploySha = parseHerokuDeploySha;
+exports.describeHerokuRelease = describeHerokuRelease;
+exports.assertBuildStampUncacheable = assertBuildStampUncacheable;
+const proc_1 = require("./proc");
+exports.BUILD_STAMP_PATH = '/__build.json';
+/** Read an app's releases via the Heroku CLI. Returns null when the CLI is missing,
+ *  unauthenticated, or the app is unknown — the caller reports that as a failure to
+ *  verify, never as a pass. */
+function fetchHerokuReleases(app, num = 10) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(app))
+        return null;
+    // One command string through a shell: `heroku` is a `.cmd` shim on Windows, which
+    // Node refuses to spawn directly. `app` is validated above.
+    const result = (0, proc_1.safeSpawnSync)(`heroku releases --app ${app} --num ${num} --json`, [], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+        shell: true, windowsHide: true, timeout: 30_000,
+    });
+    if (result.status !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(String(result.stdout));
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Poll Heroku until the app is running `sha`. A push returns as soon as the slug is
+ *  received; the build and release follow, so the first look is usually too early. */
+async function verifyHerokuRelease({ app, sha, attempts = 12, intervalMs = 5000, fetchReleases = fetchHerokuReleases, sleep = (ms) => new Promise(resolve => { setTimeout(resolve, ms); }), }) {
+    let last = 'Heroku was never reached';
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        const releases = fetchReleases(app);
+        if (releases === null) {
+            last = `could not read Heroku releases for ${app} — is the Heroku CLI installed and logged in?`;
+        }
+        else {
+            const drift = describeHerokuRelease(releases, sha);
+            if (!drift)
+                return { ok: true, attempts: attempt };
+            last = drift;
+        }
+        if (attempt < attempts)
+            await sleep(intervalMs);
+    }
+    return { ok: false, attempts, reason: last };
+}
+/** Pure. Equal, or one an unambiguous abbreviation of the other. The two targets stamp
+ *  at different widths — a worker can only report the short tag Cloudflare recorded,
+ *  while a site writes the full sha into a file — so a short sha that prefixes the long
+ *  one names the same commit. Seven characters is the floor; shorter is not a match. */
+function sameCommit(a, b) {
+    if (!a || !b)
+        return false;
+    if (a === b)
+        return true;
+    const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+    return short.length >= 7 && long.startsWith(short);
+}
+/** Pure: the whole decision, so this is testable without a network or a real deploy. */
+function describeStampDrift(body, expectedSha) {
+    if (body == null)
+        return 'production did not return a build stamp';
+    let record;
+    try {
+        record = typeof body === 'string' ? JSON.parse(body) : body;
+    }
+    catch {
+        return 'production returned a build stamp that is not JSON';
+    }
+    const served = typeof record?.sha === 'string' ? record.sha : '';
+    // An empty sha — an unbound binding — reads as no answer, never as agreement.
+    if (!served)
+        return 'production returned a build stamp with no commit';
+    if (!sameCommit(served, expectedSha)) {
+        return `production is serving ${served.slice(0, 10)}, not the ${expectedSha.slice(0, 10)} just uploaded`;
+    }
+    return null;
+}
+/** Pure: is this `Cache-Control` value one an edge may answer from cache? */
+function describeStampCacheability(cacheControl) {
+    const value = (cacheControl || '').toLowerCase();
+    if (!value)
+        return 'production returned no Cache-Control on the build stamp';
+    if (/\bno-store\b/.test(value))
+        return null;
+    return `production serves the build stamp as \`${cacheControl}\`, which an edge may cache`;
+}
+/**
+ * Confirm the deployed origin is serving this commit. Retries because the edge takes a
+ * few seconds to pick up a new version, and a strict first-try check would fail every
+ * healthy deploy.
+ */
+async function verifyDeployedBuildStamp({ origin, sha, attempts = 8, intervalMs = 5000, fetchImpl = fetch, sleep = (ms) => new Promise(resolve => { setTimeout(resolve, ms); }), }) {
+    let last = 'production was never reached';
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        let body = null;
+        let cacheControl = null;
+        try {
+            // Three request-side defences, and the first is the only one that always works:
+            // a unique query string, an explicit no-cache header, and `cache: 'no-store'`.
+            // Node's fetch types do not declare `cache` and undici ignores it, so it is cast
+            // rather than dropped — it is honoured in browser-like runtimes and costs nothing
+            // here. None of these can save a target whose ORIGIN serves a cacheable stamp,
+            // which is why `assertBuildStampUncacheable` exists.
+            const init = {
+                cache: 'no-store',
+                headers: { 'Cache-Control': 'no-cache' },
+            };
+            const response = await fetchImpl(`${origin}${exports.BUILD_STAMP_PATH}?t=${Date.now()}`, init);
+            cacheControl = response.headers.get('cache-control');
+            body = response.ok ? await response.text() : null;
+            if (!response.ok)
+                last = `production answered ${response.status} for the build stamp`;
+        }
+        catch (error) {
+            last = `could not reach production: ${error instanceof Error ? error.message : String(error)}`;
+            body = null;
+        }
+        if (body != null) {
+            const drift = describeStampDrift(body, sha);
+            if (!drift)
+                return { ok: true, attempts: attempt, cacheControl };
+            last = drift;
+        }
+        if (attempt < attempts)
+            await sleep(intervalMs);
+    }
+    return { ok: false, attempts, reason: last };
+}
+/** Pure: the commit a `git push heroku` release names, or null for any other release.
+ *  Heroku writes `Deploy <short sha>` for a git push; everything else — config vars,
+ *  add-on changes, rollbacks — has a different description and names no commit. */
+function parseHerokuDeploySha(description) {
+    const match = /^Deploy\s+([0-9a-f]{7,40})\b/i.exec(String(description || '').trim());
+    return match ? match[1].toLowerCase() : null;
+}
+/**
+ * Pure: does this release list prove the app is running `expectedSha`?
+ *
+ * Two things make this more than a string compare on the newest entry.
+ *
+ * A config-var change creates a NEW current release whose description names no commit
+ * — the dyno restarts on the same slug, so the running code is still whatever the last
+ * actual deploy put there. Walking back to the most recent release that names a deploy
+ * is therefore correct, and comparing only the current release would fail spuriously
+ * every time someone touched a config var after deploying.
+ *
+ * And a release can be `pending` or `failed`: the push was accepted, the build was not.
+ * That is the case most worth catching, because the git push succeeded and looks fine.
+ */
+function describeHerokuRelease(releases, expectedSha) {
+    const list = [...(releases || [])].sort((a, b) => (b.version ?? 0) - (a.version ?? 0));
+    if (list.length === 0)
+        return 'Heroku reported no releases for this app';
+    const current = list.find(r => r.current) || list[0];
+    const status = String(current.status || '').toLowerCase();
+    if (status && status !== 'succeeded') {
+        return `the current Heroku release v${current.version} is ${status} — the push was accepted but the build was not`;
+    }
+    const deployed = list.find(r => parseHerokuDeploySha(r.description));
+    if (!deployed)
+        return 'no Heroku release names a deployed commit';
+    const sha = parseHerokuDeploySha(deployed.description);
+    if (!sameCommit(sha, expectedSha)) {
+        return `Heroku is running ${sha} (release v${deployed.version}), not the ${expectedSha.slice(0, 10)} just pushed`;
+    }
+    return null;
+}
+/** The origin half of the cache discipline. A cacheable stamp makes every liveness
+ *  answer untrustworthy, including the ones that happen to be right today. */
+async function assertBuildStampUncacheable(origin, fetchImpl = fetch) {
+    try {
+        const response = await fetchImpl(`${origin}${exports.BUILD_STAMP_PATH}`);
+        return describeStampCacheability(response.headers.get('cache-control'));
+    }
+    catch (error) {
+        return `could not read the build stamp headers: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}