@gjsify/cli 0.51.0 → 0.52.0

package/lib/utils/install-extraneous.js

@@ -0,0 +1,120 @@
+/**
+ * The half of `--immutable` that was missing: every locked package is present AND
+ * NOTHING ELSE IS.
+ *
+ * The installer only ever ADDED. Handed a `node_modules` carrying a package the
+ * lockfile never mentions, `--immutable` extracted whatever was missing, left the
+ * stranger in place and exited 0 — a green install over a tree its own lockfile does
+ * not describe.
+ *
+ * THE INCIDENT (gjsify#1683, 2026-09-15). CI caches `node_modules` keyed on
+ * `hashFiles('gjsify-lock.json')` with a prefix fallback `restore-keys:
+ * node-modules-v1-`. An earlier run of a `@girs` bump genuinely nested
+ * `node_modules/@girs/gtk-4.0/node_modules/@girs/graphene-1.0` and saved that tree.
+ * The fix push changed the lockfile → new key → miss → the FALLBACK restored the
+ * nested tree. `--immutable` added what was missing, pruned nothing, and `tsc` then
+ * saw one type under two identities: TS2883. Worse, the still-nested tree was saved
+ * under the NEW key, so no plain re-run could go green — the failure reproduced
+ * itself until the caches were deleted by hand. Nothing about the PR's code was
+ * wrong, and any lockfile-changing PR could poison itself the same way.
+ *
+ * WHY NAMING, NOT DELETING. The peers split: `npm ci` removes `node_modules` first,
+ * yarn's `--immutable` fails on a mismatch. This follows yarn, for three reasons.
+ * The flag's own name promises not to mutate, and this repo already refuses
+ * automatic deletion under it ({@link automaticPruneRefusal} returns `'--immutable'`).
+ * A verifier that deletes can delete the wrong thing — a `link`ed dep, a package
+ * some other tool put there — while a verifier that reports cannot. And the failure
+ * mode is asymmetric: a wrong deletion loses work, a wrong refusal costs one red run
+ * carrying the exact paths and the fix.
+ *
+ * That choice has a price, paid in `.github/actions/gjsify-setup/action.yml`: with
+ * this check fatal, a restored FOREIGN tree stops being silent corruption and
+ * becomes a hard failure on every lockfile-changing PR. So the `restore-keys`
+ * fallback is gone — see the comment there. The two decisions are one decision.
+ */
+import { relative, sep } from 'node:path';
+/** `/`-separated, no trailing slash — lockfile key shape on every host. */
+function normalizePath(p) {
+    const slashed = sep === '/' ? p : p.split(sep).join('/');
+    return slashed.endsWith('/') ? slashed.slice(0, -1) : slashed;
+}
+/**
+ * Package directories under `prefix` that no entry of `expected` accounts for.
+ *
+ * Pure: it takes the scan rows ({@link scanPrefix}) and the resolved set rather than
+ * reading either, so every branch — nested placements, symlinks, subtree collapsing —
+ * is decidable without a filesystem.
+ *
+ * Three things are deliberately NOT extraneous:
+ *   - a SYMLINK, which is a workspace source tree linked in by `workspaceInstall`
+ *     and by construction absent from the lockfile (`scanPrefix` does not descend
+ *     into one either, so the user's own sources are never walked);
+ *   - a dot-entry like `.bin` or `.cache`, already dropped by the scan;
+ *   - a package the lockfile describes but the PLATFORM filter skipped on this host.
+ *     It is described, so it is not a stranger; removing the foreign-platform residue
+ *     is `prune-prefix.ts`'s separate job under a separate rule.
+ *
+ * Descendants of an extraneous directory are collapsed away: reporting the parent
+ * says everything, and the nested `@girs` tree of the incident would otherwise list
+ * its whole subtree.
+ */
+export function findExtraneous(opts) {
+    const described = new Set(opts.expected.map((n) => normalizePath(n.installPath)));
+    const found = [];
+    for (const pkg of opts.installed) {
+        if (pkg.linked)
+            continue;
+        const installPath = normalizePath(relative(opts.prefix, pkg.dir));
+        // Outside the prefix, or the prefix itself: not this install's to judge.
+        if (installPath === '' || installPath.startsWith('..'))
+            continue;
+        if (described.has(installPath))
+            continue;
+        found.push({ installPath, name: pkg.name, version: pkg.version });
+    }
+    found.sort((a, b) => (a.installPath < b.installPath ? -1 : a.installPath > b.installPath ? 1 : 0));
+    const roots = [];
+    for (const entry of found) {
+        const parent = roots[roots.length - 1];
+        // Sorted, so an enclosing extraneous directory is always the last one kept.
+        if (parent && entry.installPath.startsWith(`${parent.installPath}/`))
+            continue;
+        roots.push(entry);
+    }
+    return roots;
+}
+/** How many paths the message names before it starts counting. */
+export const EXTRANEOUS_REPORT_LIMIT = 20;
+/**
+ * The refusal, built to be actionable from the CI log alone: what is wrong, which
+ * paths, and the one thing that fixes it. Truncated past
+ * {@link EXTRANEOUS_REPORT_LIMIT} so a wholly foreign tree does not bury the advice
+ * under a thousand lines.
+ *
+ * It says DELETE, and says so as the only remedy, because that is what was measured:
+ * a plain `gjsify install` — and an explicit `--prune` — leave both a top-level and a
+ * nested stranger exactly where they were. The installer only adds, and `prune-prefix`
+ * judges one thing, npm's `os`/`cpu`/`libc`, so a package that is merely UNDESCRIBED
+ * matches no rule either owns. Sending a developer to `gjsify install` instead would
+ * hand them a command that changes nothing and a refusal that repeats verbatim.
+ */
+export function formatExtraneousError(entries, prefix) {
+    const shown = entries.slice(0, EXTRANEOUS_REPORT_LIMIT);
+    const lines = shown.map((e) => `  ${e.installPath}  (${e.name}@${e.version})`);
+    if (entries.length > shown.length)
+        lines.push(`  … and ${entries.length - shown.length} more`);
+    return [
+        `install: --immutable, but ${prefix}/node_modules holds ${entries.length} package(s) ` +
+            'that gjsify-lock.json does not describe.',
+        '--immutable installs the lockfile and removes nothing, so each of these would survive ' +
+            'the install and be resolved, bundled and type-checked as if it belonged ' +
+            '(gjsify#1683: a nested copy of an already-hoisted package → TS2883, one type ' +
+            'with two identities).',
+        ...lines,
+        'Fix: delete those directories — or the whole node_modules — and re-run. A plain ' +
+            '`gjsify install` does NOT clear them: it only ever adds, and its prune pass judges ' +
+            'foreign-PLATFORM packages alone (prune-prefix.ts), so an undescribed package ' +
+            'survives both. Deleting is currently the only thing that removes one. ' +
+            'In CI this usually means a cache entry was restored from a DIFFERENT lockfile.',
+    ].join('\n');
+}

package/lib/utils/install-tarball-cache.d.ts

@@ -1,9 +1,31 @@
 /**
- * Read a cached tarball by SRI integrity — raw bytes on a HIT, `null` otherwise. A
- * read failure (e.g. a partial write from an interrupted run) is a MISS, and the
- * file is left untouched so a follow-up writer's atomic rename is not tripped.
+ * Read a cached tarball by SRI integrity — raw bytes on a VERIFIED hit, `null`
+ * otherwise. A read failure (e.g. a partial write from an interrupted run) is a MISS,
+ * and the file is left untouched so a follow-up writer's atomic rename is not tripped.
+ *
+ * The bytes are re-hashed against the integrity that named them, through the SAME
+ * {@link verifyIntegrity} the download path uses — so both paths agree by
+ * construction instead of by comment.
+ *
+ * This used to trust the path: "content-addressed, so a hash hit is byte-identical to
+ * what the registry would return". That is a claim ABOUT the bytes, and nothing read
+ * them to check it. It held while the store was a local directory this machine had
+ * written itself. It stops holding the moment the store is a restorable CI artifact —
+ * a GitHub Actions cache entry that is truncated, corrupted, or written by a workflow
+ * on another branch would have been consumed as authentic, because the only thing
+ * asserting its contents was its filename. `gjsify-setup` now restores exactly such an
+ * artifact, so the check is no longer optional. Yarn re-hashes on every install for
+ * this reason (refs/yarn-berry Cache.ts, "we check the file hashes during each install
+ * anyway"); measured here, it costs ~0.5 s over this repo's ~420 MB closure, against
+ * an extract phase of minutes.
+ *
+ * A mismatch DELETES the entry rather than merely skipping it. That is not the prune
+ * this repo refuses elsewhere — the name asserts the content and the content
+ * disproves the name, so the file is garbage by its own definition. It has to go:
+ * {@link putCachedTarball} is idempotent on existence, so a corrupt blob left in place
+ * would never be replaced and every future install would re-download it forever.
  */
-export declare function getCachedTarball(integrity: string | undefined): Uint8Array | null;
+export declare function getCachedTarball(integrity: string | undefined): Promise<Uint8Array | null>;
 /**
  * Persist a tarball to the cache, via a `<path>.tmp.<pid>` sibling and an atomic
  * rename so concurrent installs never observe a half-written entry. No-op when
@@ -17,9 +39,15 @@ export declare function cacheRootForLogging(): string;
 export declare function isCacheHit(integrity: string | undefined): boolean;
 /**
  * Read a tarball from npm's cacache content store by SRI integrity — raw `.tgz`
- * bytes on a HIT, `null` on a MISS, disabled interop or read failure. Like
- * {@link getCachedTarball} it trusts the content-addressed path rather than
- * re-hashing: cacache verified the bytes on write, and the extractor surfaces a
- * genuinely corrupt tarball loudly.
+ * bytes on a VERIFIED hit, `null` on a MISS, disabled interop or read failure.
+ *
+ * Re-hashed like {@link getCachedTarball}, and with more reason: these bytes come
+ * from ANOTHER tool's store, on a path this code does not control and cannot assume
+ * was written by a cacache that verified anything. The old note argued cacache
+ * verified on write and a corrupt tarball would fail loudly in the extractor — but
+ * "the next stage will probably notice" is not verification, and the caller
+ * write-throughs a foreign hit into OUR store, which would launder an unchecked blob
+ * into a first-class entry. A mismatch is left alone here rather than deleted: this
+ * store belongs to npm, and removing another tool's files is not this code's call.
  */
-export declare function getForeignCachedTarball(integrity: string | undefined): Uint8Array | null;
+export declare function getForeignCachedTarball(integrity: string | undefined): Promise<Uint8Array | null>;

package/lib/utils/install-tarball-cache.js

@@ -25,9 +25,10 @@
 // on too. Tarballs without an integrity hash (older registries) fall through to a
 // no-op cache and download every time.
 import { Buffer } from 'node:buffer';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { verifyIntegrity } from '@gjsify/npm-registry';
 import { atomicWrite, gjsifyCacheRoot, readCacheFile } from './install-cache-fs.js';
 const CACHE_LAYOUT_VERSION = 'v1';
 /** Root of the tarball cache: `$XDG_CACHE_HOME/gjsify/tarballs/v1`. */
@@ -68,15 +69,50 @@ function pathFor(integrity) {
     return join(cacheRoot(), sri.algorithm, shard, `${sri.hex}.tgz`);
 }
 /**
- * Read a cached tarball by SRI integrity — raw bytes on a HIT, `null` otherwise. A
- * read failure (e.g. a partial write from an interrupted run) is a MISS, and the
- * file is left untouched so a follow-up writer's atomic rename is not tripped.
+ * Read a cached tarball by SRI integrity — raw bytes on a VERIFIED hit, `null`
+ * otherwise. A read failure (e.g. a partial write from an interrupted run) is a MISS,
+ * and the file is left untouched so a follow-up writer's atomic rename is not tripped.
+ *
+ * The bytes are re-hashed against the integrity that named them, through the SAME
+ * {@link verifyIntegrity} the download path uses — so both paths agree by
+ * construction instead of by comment.
+ *
+ * This used to trust the path: "content-addressed, so a hash hit is byte-identical to
+ * what the registry would return". That is a claim ABOUT the bytes, and nothing read
+ * them to check it. It held while the store was a local directory this machine had
+ * written itself. It stops holding the moment the store is a restorable CI artifact —
+ * a GitHub Actions cache entry that is truncated, corrupted, or written by a workflow
+ * on another branch would have been consumed as authentic, because the only thing
+ * asserting its contents was its filename. `gjsify-setup` now restores exactly such an
+ * artifact, so the check is no longer optional. Yarn re-hashes on every install for
+ * this reason (refs/yarn-berry Cache.ts, "we check the file hashes during each install
+ * anyway"); measured here, it costs ~0.5 s over this repo's ~420 MB closure, against
+ * an extract phase of minutes.
+ *
+ * A mismatch DELETES the entry rather than merely skipping it. That is not the prune
+ * this repo refuses elsewhere — the name asserts the content and the content
+ * disproves the name, so the file is garbage by its own definition. It has to go:
+ * {@link putCachedTarball} is idempotent on existence, so a corrupt blob left in place
+ * would never be replaced and every future install would re-download it forever.
  */
-export function getCachedTarball(integrity) {
+export async function getCachedTarball(integrity) {
     const path = pathFor(integrity);
-    if (!path)
+    if (!path || !integrity)
+        return null;
+    const bytes = readCacheFile(path);
+    if (!bytes)
         return null;
-    return readCacheFile(path);
+    if (await verifyIntegrity(bytes, integrity))
+        return bytes;
+    // Best-effort: a read-only cache volume must not break the install, and the
+    // caller falls through to a verifying download either way.
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        /* keep going — the download path replaces the value we return as a MISS */
+    }
+    return null;
 }
 /**
  * Persist a tarball to the cache, via a `<path>.tmp.<pid>` sibling and an atomic
@@ -158,14 +194,23 @@ function npmCachePathFor(integrity) {
 }
 /**
  * Read a tarball from npm's cacache content store by SRI integrity — raw `.tgz`
- * bytes on a HIT, `null` on a MISS, disabled interop or read failure. Like
- * {@link getCachedTarball} it trusts the content-addressed path rather than
- * re-hashing: cacache verified the bytes on write, and the extractor surfaces a
- * genuinely corrupt tarball loudly.
+ * bytes on a VERIFIED hit, `null` on a MISS, disabled interop or read failure.
+ *
+ * Re-hashed like {@link getCachedTarball}, and with more reason: these bytes come
+ * from ANOTHER tool's store, on a path this code does not control and cannot assume
+ * was written by a cacache that verified anything. The old note argued cacache
+ * verified on write and a corrupt tarball would fail loudly in the extractor — but
+ * "the next stage will probably notice" is not verification, and the caller
+ * write-throughs a foreign hit into OUR store, which would launder an unchecked blob
+ * into a first-class entry. A mismatch is left alone here rather than deleted: this
+ * store belongs to npm, and removing another tool's files is not this code's call.
  */
-export function getForeignCachedTarball(integrity) {
+export async function getForeignCachedTarball(integrity) {
     const path = npmCachePathFor(integrity);
-    if (!path)
+    if (!path || !integrity)
+        return null;
+    const bytes = readCacheFile(path);
+    if (!bytes)
         return null;
-    return readCacheFile(path);
+    return (await verifyIntegrity(bytes, integrity)) ? bytes : null;
 }

package/lib/utils/normalize-bundler-options.js

@@ -130,6 +130,17 @@ export function mergeBundlerOptions(base, overrides) {
         if (base.transform?.define || overrides.transform?.define) {
             out.transform.define = { ...base.transform?.define, ...overrides.transform?.define };
         }
+        // `inject` is a map like `define` and merges the same way. Replacing it wholesale
+        // meant a user who injected ONE identifier silently lost the orchestrator's
+        // `console` → `@gjsify/rolldown-plugin-gjsify/shims/console-gjs` rewrite, which
+        // `--app gjs` cannot express any other way: GJS defines `globalThis.console`
+        // non-writable and non-configurable, so assigning to it from a register module
+        // no-ops. It also has to stay in lockstep with `mergeTransformOptions` in the
+        // plugin's auto-globals analyser — when the two merge the same options
+        // differently, the detector measures a bundle that is not the one that ships.
+        if (base.transform?.inject || overrides.transform?.inject) {
+            out.transform.inject = { ...base.transform?.inject, ...overrides.transform?.inject };
+        }
     }
     if (base.resolve || overrides.resolve) {
         out.resolve = { ...base.resolve, ...overrides.resolve };

package/lib/utils/publish-pins.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The intra-repo pins a publish is about to ship, enumerated from the manifest
+ * PAIR — the workspace's own `package.json` and the rewritten one that comes
+ * back out of the tarball.
+ *
+ * Why the pair and not just the rewritten manifest: after
+ * `rewriteWorkspaceDeps` (see `commands/pack.ts`) a sibling pin is an ordinary
+ * `^0.51.1` and indistinguishable from a third-party dependency. The `workspace:`
+ * prefix survives only in the SOURCE manifest, so which edges are this repo's
+ * own is a fact that exists in one file and the version they will ship at exists
+ * in the other.
+ */
+/** The blocks `rewriteWorkspaceDeps` rewrites and a consumer install resolves. */
+export type DependencyBlock = 'dependencies' | 'optionalDependencies' | 'peerDependencies';
+/**
+ * The one block whose unresolvable edge fails EVERY consumer install.
+ *
+ * Measured, npm 11.17.0, against the live registry, on an edge to a name that
+ * did not exist: `optionalDependencies` installs clean (exit 0, silently),
+ * `dependencies` is `npm error 404`, exit 1. Yarn refuses both (`YN0035`),
+ * which is why an optional edge is still reported — just not fatal.
+ */
+export declare const REQUIRED_BLOCK: DependencyBlock;
+export interface WorkspacePin {
+    name: string;
+    /** The concrete range the tarball will carry, after the rewrite. */
+    spec: string;
+    block: DependencyBlock;
+}
+/**
+ * Every edge that was a `workspace:` spec before the rewrite, with the version
+ * it will ship at.
+ *
+ * A name appearing in two blocks yields two pins: `dependencies` and
+ * `optionalDependencies` do not cost the same at install time, so collapsing
+ * them would throw away the distinction the caller decides on.
+ */
+export declare function collectWorkspacePins(source: Record<string, unknown>, rewritten: Record<string, unknown>): WorkspacePin[];

package/lib/utils/publish-pins.js

@@ -0,0 +1,47 @@
+/**
+ * The intra-repo pins a publish is about to ship, enumerated from the manifest
+ * PAIR — the workspace's own `package.json` and the rewritten one that comes
+ * back out of the tarball.
+ *
+ * Why the pair and not just the rewritten manifest: after
+ * `rewriteWorkspaceDeps` (see `commands/pack.ts`) a sibling pin is an ordinary
+ * `^0.51.1` and indistinguishable from a third-party dependency. The `workspace:`
+ * prefix survives only in the SOURCE manifest, so which edges are this repo's
+ * own is a fact that exists in one file and the version they will ship at exists
+ * in the other.
+ */
+const BLOCKS = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+/**
+ * The one block whose unresolvable edge fails EVERY consumer install.
+ *
+ * Measured, npm 11.17.0, against the live registry, on an edge to a name that
+ * did not exist: `optionalDependencies` installs clean (exit 0, silently),
+ * `dependencies` is `npm error 404`, exit 1. Yarn refuses both (`YN0035`),
+ * which is why an optional edge is still reported — just not fatal.
+ */
+export const REQUIRED_BLOCK = 'dependencies';
+const depsOf = (pkg, block) => {
+    const value = pkg[block];
+    return value && typeof value === 'object' ? value : {};
+};
+/**
+ * Every edge that was a `workspace:` spec before the rewrite, with the version
+ * it will ship at.
+ *
+ * A name appearing in two blocks yields two pins: `dependencies` and
+ * `optionalDependencies` do not cost the same at install time, so collapsing
+ * them would throw away the distinction the caller decides on.
+ */
+export function collectWorkspacePins(source, rewritten) {
+    const pins = [];
+    for (const block of BLOCKS) {
+        const before = depsOf(source, block);
+        const after = depsOf(rewritten, block);
+        for (const [name, spec] of Object.entries(before)) {
+            if (typeof spec !== 'string' || !spec.startsWith('workspace:'))
+                continue;
+            pins.push({ name, spec: after[name] ?? spec, block });
+        }
+    }
+    return pins;
+}

package/lib/utils/publish-readback.d.ts

@@ -19,9 +19,42 @@ export type ReadbackProbe = {
     status?: number;
     detail: string;
 };
+/**
+ * What the read-back CONCLUDED — the three outcomes a caller may act on, plus
+ * the one it may not.
+ *
+ * `absent` on its own is not a conclusion. The install document not carrying a
+ * version has two causes with opposite remedies — the write never landed
+ * (re-publish) and the write landed but that document does not serve it yet
+ * (wait; a re-publish is answered 409) — and until this type existed both left
+ * through one message asserting the first. Observed live on the ts-for-gir
+ * v5.1.0 release: `@ts-for-gir/reporter` was recorded by the registry at
+ * 21:43:00.983Z and a cache-busted abbreviated read ~40 min later still did not
+ * carry 5.1.0, while the full packument's `time` map did; two minutes after
+ * that, both agreed.
+ */
+export type ReadbackVerdict = 
+/** The install document serves `name@version` and advertises a tarball. */
+'confirmed'
+/** The registry has no record of this version at all — the v0.46.0 shape. */
+ | 'not-published'
+/** The registry RECORDS the write; the document npm installs from does not serve it. */
+ | 'recorded-not-served'
+/**
+ * Nothing was established. A 5xx, a timeout, DNS, an auth wall — or an
+ * install document without the version whose registry record could then
+ * not be read, which leaves BOTH other verdicts unearned. NEVER "published".
+ */
+ | 'unknown';
 export interface ReadbackResult {
     /** True iff a probe saw the exact version with a tarball on it. */
     confirmed: boolean;
+    /** What the read-back concluded. `confirmed === (verdict === 'confirmed')`. */
+    verdict: ReadbackVerdict;
+    /** One line naming the evidence the verdict rests on — it goes in the report. */
+    verdictDetail: string;
+    /** `time[version]` from the registry's own record, when the corroboration read one. */
+    recordedAt?: string;
     /** Probes actually sent (≥ 1). */
     attempts: number;
     elapsedMs: number;
@@ -80,29 +113,42 @@ export declare function backoffFor(round: number): number;
  */
 export declare function probeTimeoutFor(configuredMs: number, remainingMs: number): number;
 /**
- * Default polling budget: 300 s.
+ * Default polling budget: 600 s.
  *
- * The measured maximum lag between a 2xx and the registry recording the version
- * was 251.7 s (@gjsify/child_process, v0.46.0), so a budget below ~4.2 minutes
- * turns npm's normal queueing into a false red — and a false red at release time
- * costs a manual re-run of a workflow that did its job. 300 s clears that
- * maximum and is still short enough that a genuinely lost write is reported by
- * the job that lost it rather than by a later sweep.
+ * The lag between a 2xx and the registry recording the version has been measured
+ * on two releases, and the second broke the first's ceiling. v0.46.0 (199
+ * packages): 19 late writes, maximum 251.7 s (@gjsify/child_process). ts-for-gir
+ * v5.1.0 (12 packages, run 34899018849, PUT lines against `time["5.1.0"]`):
+ * four recorded ~0.7 s BEFORE the 2xx, eight after it — +74, +74, +75, +75,
+ * +96, +248, +248 and +368 s (@ts-for-gir/reporter) — the last past the 300 s
+ * this constant used to be, so "above the measured maximum" had quietly
+ * stopped being true of it. A budget below the lag turns npm's normal queueing into a false
+ * red, and a false red at release time costs a manual re-run of a workflow that
+ * did its job. A budget above it costs nothing on the nine in ten that confirm
+ * on the first probe; all it delays is the report of a genuinely LOST write —
+ * one in 199, measured — by the difference. 600 s is ~1.6x the larger maximum.
  *
- * THAT MAXIMUM IS A SAMPLE MAXIMUM, and the sample does not look truncated by
- * nature. The 19 lags fall in buckets ~20-30 s apart — 56(2), 76(3), 96(3),
+ * BOTH MAXIMA ARE SAMPLE MAXIMA, and neither sample looks truncated by nature.
+ * The v0.46.0 lags fall in buckets ~20-30 s apart — 56(2), 76(3), 96(3),
  * 127(4), 157(3), 189(1), 251(3) — and the TOP bucket is as populated as the
  * middle ones, which is the shape of a distribution cut off by the observation
- * rather than one decaying to zero. One release is one sample, so a lag past
- * 300 s is not ruled out; what makes 300 s affordable anyway is that the
- * remediation is verified rather than assumed. The re-run this reports lands on
- * the 409 path, and that path READS BACK too (see the conflict branch in
- * `commands/publish.ts`), so a window that turns out to be too short costs one
- * re-run that confirms — it does not hand back an unverified success.
+ * rather than one decaying to zero; the next release then produced a value past
+ * it. So a lag past 600 s is not ruled out either. What makes any finite window
+ * affordable is that the remediation is verified rather than assumed: the
+ * re-run this reports lands on the 409 path, and that path READS BACK too (see
+ * the conflict branch in `commands/publish.ts`), so a window that turns out too
+ * short costs one re-run that confirms — never an unverified success.
+ *
+ * `time[version]` is when the registry RECORDED the write, a lower bound on
+ * when the document npm installs from SERVES it: the reporter above was
+ * recorded at +368 s and a cache-busted read of its install document still
+ * lacked 5.1.0 ~40 min later. No budget waits that out, and none should — that
+ * state is what the `recorded-not-served` verdict names.
  */
-export declare const DEFAULT_VERIFY_BUDGET_MS = 300000;
+export declare const DEFAULT_VERIFY_BUDGET_MS = 600000;
 /**
- * Poll the registry until `name@version` resolves, or the budget runs out.
+ * Poll the registry until `name@version` resolves, or the budget runs out, then
+ * say WHICH of the three states it found (see {@link ReadbackVerdict}).
  *
  * No side effects, no exits, no printing beyond the injected `log` — the caller
  * owns presentation, same contract as {@link import('./publish-diagnose.js')}.
@@ -130,3 +176,43 @@ export declare function formatUnconfirmedPublish(opts: {
      */
     claim?: 'accepted' | 'already-published';
 }): string;
+/** Whether the registry serves a packument for a NAME at all. */
+export type NamePresence = {
+    state: 'present';
+    status: number;
+    versions: number;
+} | {
+    state: 'absent';
+    status: number;
+    detail: string;
+}
+/**
+ * We do not KNOW — a 5xx, a timeout, an auth wall. A caller that blocks a
+ * publish on this must treat it as "not established", never as "absent":
+ * the whole point of the guard is that it cannot manufacture a red.
+ */
+ | {
+    state: 'unknown';
+    status?: number;
+    detail: string;
+};
+export interface ProbePackageNameInput {
+    registry: string;
+    name: string;
+    probeTimeoutMs?: number;
+    authorization?: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Ask ONE question: does this NAME exist on the registry at all.
+ *
+ * Deliberately not a version question, and that is what makes it safe to gate a
+ * publish on. A version is eventually consistent — measured on v0.46.0, 19 of
+ * 199 packages were recorded 56-252 s AFTER their own 2xx — so "is name@version
+ * there" answers "not yet" for minutes and a gate built on it would manufacture
+ * a red on a publish that worked. Presence of the NAME does not move once the
+ * first version lands, which is the same reason
+ * `verify-published-closure.mjs --phase pre-release` asks it rather than the
+ * version: an answer that does not move when the train moves.
+ */
+export declare function probePackageName(input: ProbePackageNameInput): Promise<NamePresence>;