@smoothbricks/cli 0.11.16 → 0.11.17

package/src/secrets/index.ts

@@ -0,0 +1,183 @@
+/**
+ * Reconciles the three places a repository's secrets are described, all of
+ * which smoo already owns:
+ *
+ * 1. **Workers declare names.** `.dev.vars.example` per wrangler project — the
+ *    file `wrangler types --env-file` reads and `prepare-env` prompts from.
+ * 2. **Workflows declare where values come from.** `smoo.github.deploySecrets`
+ *    and `e2eSecrets` map an env name to a repository secret, and the managed
+ *    workflows render exactly those into the job environment.
+ * 3. **A developer shell declares how to fetch one locally.** `smoo.secrets`
+ *    names a command whose stdout is the value.
+ *
+ * Nothing joined them, so a Worker could declare a secret no workflow supplies
+ * and no repository holds. That fails at deploy time, on a stage, with a
+ * fail-closed message about the value rather than about the missing
+ * declaration — the shape that costs an afternoon: a Worker declares
+ * `STRIPE_PUBLISHABLE_KEY`, `ci.yml` passes `secrets.STRIPE_PUBLISHABLE_KEY`,
+ * the repository holds no such secret, and the empty value surfaces as the
+ * payment library's own `publishable_key_mismatch` refusal.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { repositoryOwnerFromUrl, repositorySecretMapping } from '../lib/secret-names.js';
+import { readPackageJsonObject, repositoryInfo } from '../lib/workspace.js';
+import { parseDevVarsExample } from '../wrangler/prepare-env.js';
+
+/** Where an env name is described, which repository secret carries it, and whether that exists. */
+export interface SecretRow {
+  name: string;
+  /** The repository secret this env name reads from, by convention or declaration. */
+  repositorySecret: string;
+  /** Wrangler projects whose `.dev.vars.example` declares it. */
+  declaredByWorkers: string[];
+  /** True when a managed workflow renders `secrets.<name>` into a job. */
+  suppliedByWorkflow: boolean;
+  /** True when `smoo.secrets` can fetch it for a developer shell. */
+  fetchableLocally: boolean;
+  /** True when the repository holds a secret of this name. */
+  onRepository: boolean;
+}
+
+export interface SecretSources {
+  /** Worker label -> env names it declares. */
+  workerSecrets: Record<string, readonly string[]>;
+  /** Env names a managed workflow passes into a job. */
+  workflowSecrets: readonly string[];
+  /** Env name -> repository secret, by convention with declared exceptions. */
+  secretNames: Readonly<Record<string, string>>;
+  /** Env names `smoo.secrets` can fetch locally. */
+  localCommands: readonly string[];
+  /** Repository secret names GitHub currently holds. */
+  repositorySecrets: readonly string[];
+}
+
+/**
+ * One row per name known to any source, sorted, so a reader sees the whole
+ * picture rather than one source's view of it.
+ */
+export function reconcileSecrets(sources: SecretSources): SecretRow[] {
+  const declaredByAnyWorker: string[] = Object.values(sources.workerSecrets).flatMap((names) => [...names]);
+  const names = new Set<string>([...declaredByAnyWorker, ...sources.workflowSecrets, ...sources.localCommands]);
+  // A repository secret that already carries a known env name is that name's
+  // row, not a row of its own: listing ACME_GITHUB_CLIENT_SECRET beside
+  // GITHUB_CLIENT_SECRET would report one value as two secrets, one of them
+  // permanently "declared by nothing".
+  const carriesKnownEnvName = new Set(
+    names.size > 0 ? [...names].map((name) => sources.secretNames[name] ?? name) : [],
+  );
+  for (const secret of sources.repositorySecrets) {
+    if (!carriesKnownEnvName.has(secret)) names.add(secret);
+  }
+  return [...names]
+    .sort((left, right) => left.localeCompare(right))
+    .map((name) => ({
+      name,
+      repositorySecret: sources.secretNames[name] ?? name,
+      declaredByWorkers: Object.entries(sources.workerSecrets)
+        .filter(([, declared]) => declared.includes(name))
+        .map(([label]) => label)
+        .sort((left, right) => left.localeCompare(right)),
+      suppliedByWorkflow: sources.workflowSecrets.includes(name),
+      fetchableLocally: sources.localCommands.includes(name),
+      onRepository: sources.repositorySecrets.includes(sources.secretNames[name] ?? name),
+    }));
+}
+
+/**
+ * The rows a CI deploy cannot satisfy: a Worker declares the name, a workflow
+ * promises to pass it, and the repository has no value to pass. Reported
+ * separately from "declared but not wired into any workflow", because the
+ * remedies differ — set a secret, versus declare it in `smoo.github`.
+ */
+export function unsatisfiedSecrets(rows: readonly SecretRow[]): SecretRow[] {
+  return rows.filter((row) => row.suppliedByWorkflow && !row.onRepository);
+}
+
+/** Worker-declared names no managed workflow passes: a CI deploy will run without them. */
+export function unwiredSecrets(rows: readonly SecretRow[]): SecretRow[] {
+  return rows.filter((row) => row.declaredByWorkers.length > 0 && !row.suppliedByWorkflow);
+}
+
+/** Env names the managed workflows pass into a job, from the declarations that render them. */
+export function workflowSecretNames(root: string): string[] {
+  const manifest = readPackageJsonObject(join(root, 'package.json'));
+  const smoo = manifest?.smoo;
+  const github = smoo?.github;
+  const names = new Set<string>([
+    ...Object.keys(github?.deploySecrets ?? {}),
+    ...Object.keys(github?.e2eSecrets ?? {}),
+  ]);
+  if (smoo?.remoteCache?.tokenSecret) names.add(smoo.remoteCache.tokenSecret);
+  for (const origin of github?.cargoCredentials?.gitOrigins ?? []) {
+    if (origin.tokenEnv) names.add(origin.tokenEnv);
+  }
+  for (const source of github?.sourceCheckouts ?? []) {
+    if (source.tokenEnv) names.add(source.tokenEnv);
+  }
+  if (smoo?.privateNpm?.readTokenEnv) names.add(smoo.privateNpm.readTokenEnv);
+  if (smoo?.privateNpm?.publishTokenEnv) names.add(smoo.privateNpm.publishTokenEnv);
+  return [...names].sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * Env name -> repository secret for every name in play, following the naming
+ * convention and honouring the declared exceptions a repository still needs.
+ */
+export function secretNameMapping(root: string, envNames: readonly string[]): Record<string, string> {
+  const manifest = readPackageJsonObject(join(root, 'package.json'));
+  const declared = { ...(manifest?.smoo?.github?.deploySecrets ?? {}), ...(manifest?.smoo?.github?.e2eSecrets ?? {}) };
+  const repository = manifest ? repositoryInfo(manifest) : null;
+  const owner = repository ? (repositoryOwnerFromUrl(repository.url) ?? '') : '';
+  return repositorySecretMapping(envNames, owner, declared);
+}
+
+/** Every wrangler project's declared secret names, keyed by the project directory. */
+export function workerSecretNames(root: string, workspaceDirs: readonly string[]): Record<string, string[]> {
+  const byWorker: Record<string, string[]> = {};
+  for (const dir of workspaceDirs) {
+    const examplePath = join(root, dir, '.dev.vars.example');
+    if (!existsSync(examplePath)) continue;
+    const names = parseDevVarsExample(readFileSync(examplePath, 'utf8'));
+    if (names.length > 0) byWorker[dir] = names;
+  }
+  return byWorker;
+}
+
+/** Names `smoo.secrets` declares a fetch command for. */
+export function localSecretCommandNames(root: string): string[] {
+  const manifest = readPackageJsonObject(join(root, 'package.json'));
+  return Object.keys(manifest?.smoo?.secrets ?? {}).sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * Resolve one declared secret through its command. The value is returned, never
+ * logged: callers hand it to `gh secret set` over stdin.
+ */
+export function fetchLocalSecret(
+  root: string,
+  name: string,
+): { ok: true; value: string } | { ok: false; reason: string } {
+  const manifest = readPackageJsonObject(join(root, 'package.json'));
+  const declared = manifest?.smoo?.secrets?.[name];
+  if (!declared) {
+    return { ok: false, reason: `smoo.secrets declares no command for ${name}` };
+  }
+  const [command, ...args] = declared.command;
+  const result = spawnSync(command, args, { encoding: 'utf8' });
+  if (result.status !== 0) {
+    // Name the command, never its output: a failing secret fetch prints
+    // credentials often enough that it is worth refusing to.
+    return {
+      ok: false,
+      reason: `${name}: \`${declared.command.join(' ')}\` exited ${result.status ?? 'without status'}`,
+    };
+  }
+  const value = result.stdout.replace(/\n$/, '');
+  if (value.length === 0) {
+    return { ok: false, reason: `${name}: \`${declared.command.join(' ')}\` produced no value` };
+  }
+  return { ok: true, value };
+}

package/src/wrangler/deploy-stage.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from 'bun:test';
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, statSync } from 'node:fs';
 import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -22,6 +22,12 @@ import {
   type ProcessRunOptions,
   writeTemporaryConfigForTest,
 } from './deploy-stage.js';
+import {
+  type FetchLike,
+  findVersionIdByTag,
+  LIVE_VERSION_CACHE_TTL_MS,
+  readCachedLiveVersion,
+} from './live-version.js';
 import type { LiveKvNamespace } from './stage.js';
 
 const HASH = '16577780061662788004';
@@ -58,19 +64,49 @@ class FakeRunner implements ProcessRunner {
   secretsJson: string | undefined;
   /** Runs before the fake reports success, so a test can read a temporary file the command was handed. */
   onCall: ((args: string[], cwd: string) => Promise<void>) | undefined;
+  /**
+   * How many `deployments status` reads still answer with the OLD version after a traffic shift.
+   * This is the whole point of the fake: Cloudflare accepts the shift before it serves it.
+   */
+  propagationPolls = 0;
+
+  private pendingVersionId: string | null = null;
 
   constructor(
-    private readonly versions: unknown = [],
-    private readonly deployment: unknown = {},
+    private versions: unknown = [],
+    private deployment: unknown = {},
   ) {}
 
+  /** The versions payload as a growable list, so an upload can add the version it just created. */
+  private versionList(): unknown[] {
+    const list: unknown[] = Array.isArray(this.versions) ? this.versions : [this.versions];
+    this.versions = list;
+    return list;
+  }
+
+  private shiftTrafficTo(versionId: string): void {
+    this.pendingVersionId = versionId;
+  }
+
+  private readDeployment(): unknown {
+    if (this.pendingVersionId !== null) {
+      if (this.propagationPolls > 0) {
+        this.propagationPolls -= 1;
+      } else {
+        this.deployment = { versions: [{ version_id: this.pendingVersionId, percentage: 100 }] };
+        this.pendingVersionId = null;
+      }
+    }
+    return this.deployment;
+  }
+
   async run(command: string, args: string[], options: ProcessRunOptions): Promise<ProcessResult> {
     this.calls.push({ command, args, cwd: options.cwd, env: childEnvironment(options) });
     if (args[0] === 'versions' && args[1] === 'list') {
       return success(this.versions);
     }
     if (args[0] === 'deployments' && args[1] === 'status') {
-      return success(this.deployment);
+      return success(this.readDeployment());
     }
     const configIndex = args.indexOf('--config');
     if (configIndex >= 0) {
@@ -84,6 +120,21 @@ class FakeRunner implements ProcessRunner {
       this.secretsMode = statSync(secretsPath).mode & 0o777;
       this.secretsJson = readFileSync(secretsPath, 'utf8');
     }
+    if (args[0] === 'versions' && args[1] === 'deploy') {
+      // Resolved with the same reader the deploy uses, so the fake cannot agree with a lookup
+      // production would miss.
+      const tag = args[args.indexOf('--version-tag') + 1];
+      const existing = tag ? findVersionIdByTag(this.versions, tag) : null;
+      if (existing) this.shiftTrafficTo(existing);
+    }
+    if (args[0] === 'deploy') {
+      const tagIndex = args.indexOf('--tag');
+      if (tagIndex >= 0) {
+        const versionId = `uploaded-${args[tagIndex + 1]}`;
+        this.versionList().push({ id: versionId, annotations: { 'workers/tag': args[tagIndex + 1] } });
+        this.shiftTrafficTo(versionId);
+      }
+    }
     await this.onCall?.(args, options.cwd);
     return success({});
   }
@@ -179,8 +230,8 @@ class FakeCloudflare implements CloudflareClient {
   }
 }
 
-describe('deploy-stage remote version fallback', () => {
-  it('returns a remote cache hit for the active tagged 100% version', async () => {
+describe('deploy-stage against live state', () => {
+  it('uploads nothing and shifts no traffic when the live version already is the task hash', async () => {
     const root = await fixtureRoot();
     const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
       versions: [{ version_id: 'version-1', percentage: 100 }],
@@ -189,14 +240,17 @@ describe('deploy-stage remote version fallback', () => {
     const result = await deployStage(root, { stage: 'pr123' }, dependencies(runner, new FakeCloudflare()));
 
     expect(result.action).toBe('remote-cache-hit');
+    // Two reads and nothing else. This is what makes a redundant deploy — the one a cross-project
+    // `dependsOn` edge adds — provably free instead of assumed free.
     expect(runner.calls.map((call) => call.args.slice(0, 2))).toEqual([
       ['versions', 'list'],
       ['deployments', 'status'],
     ]);
   });
 
-  it('activates an existing tagged version that is not current', async () => {
+  it('redeploys after a rollback, when the live version is no longer the task hash', async () => {
     const root = await fixtureRoot();
+    // The build for this hash is still uploaded; someone rolled traffic back to the older version.
     const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
       versions: [{ version_id: 'version-2', percentage: 100 }],
     });
@@ -204,11 +258,108 @@ describe('deploy-stage remote version fallback', () => {
     const result = await deployStage(root, { stage: 'pr123' }, dependencies(runner, new FakeCloudflare()));
 
     expect(result.action).toBe('activated');
-    expect(runner.calls.at(-1)?.args.slice(0, 3)).toEqual(['versions', 'deploy', '--version-tag']);
-    expect(runner.configPathSeen).toBeDefined();
+    const shiftIndex = runner.calls.findIndex((call) => call.args[0] === 'versions' && call.args[1] === 'deploy');
+    expect(runner.calls[shiftIndex]?.args.slice(0, 4)).toEqual(['versions', 'deploy', '--version-tag', `nx-${HASH}`]);
+    // And the step does not return until it has read live state again after that shift.
+    expect(runner.calls.slice(shiftIndex + 1).some((call) => call.args[0] === 'deployments')).toBe(true);
     expect(existsSync(requiredTestValue(runner.configPathSeen, 'config path'))).toBe(false);
   });
 
+  it('waits out propagation before reporting the deploy done', async () => {
+    const root = await fixtureRoot();
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+    runner.propagationPolls = 3;
+
+    const result = await deployStage(root, { stage: 'pr123' }, dependencies(runner, new FakeCloudflare()));
+
+    expect(result.action).toBe('activated');
+    const statusReads = runner.calls.filter((call) => call.args[0] === 'deployments').length;
+    expect(statusReads).toBe(5);
+  });
+
+  it('fails with what it expected and what it saw when the version never becomes live', async () => {
+    const root = await fixtureRoot();
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+    runner.propagationPolls = Number.POSITIVE_INFINITY;
+
+    await expect(deployStage(root, { stage: 'pr123' }, dependencies(runner, new FakeCloudflare()))).rejects.toThrow(
+      `fixture-worker-pr123: deployed version nx-${HASH} was not serving traffic after 10s; live is an untagged version (version-2)`,
+    );
+  });
+
+  it('leaves the cache holding the tag it made live, so the next query needs no API call', async () => {
+    const root = await fixtureRoot();
+    const cacheDirectory = await mkdtemp(join(tmpdir(), 'smoo-live-version-'));
+    roots.push(cacheDirectory);
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+
+    await deployStage(
+      root,
+      { stage: 'pr123' },
+      { ...dependencies(runner, new FakeCloudflare()), liveVersionCacheDirectory: cacheDirectory },
+    );
+
+    const cached = await readCachedLiveVersion(
+      cacheDirectory,
+      { accountId: 'account-1', workerName: 'fixture-worker-pr123', stage: 'pr123' },
+      LIVE_VERSION_CACHE_TTL_MS,
+    );
+    expect(cached).toMatchObject({ versionTag: `nx-${HASH}`, versionId: 'version-1' });
+  });
+
+  it('is not done until a declared version endpoint answers with the new tag', async () => {
+    const root = await fixtureRoot();
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+    const bodies = [`nx-${'0'.repeat(20)}`, `nx-${'0'.repeat(20)}`, `nx-${HASH}`];
+    const requested: string[] = [];
+    const stubFetch: FetchLike = async (input) => {
+      requested.push(String(input));
+      return new Response(bodies.shift() ?? `nx-${HASH}`);
+    };
+
+    const result = await deployStage(
+      root,
+      { stage: 'pr123', versionEndpoint: 'https://fixture.example.test/__version' },
+      {
+        ...dependencies(runner, new FakeCloudflare()),
+        wait: { ...fakeWait(), fetch: stubFetch },
+      },
+    );
+
+    expect(result.action).toBe('activated');
+    expect(requested).toEqual([
+      'https://fixture.example.test/__version',
+      'https://fixture.example.test/__version',
+      'https://fixture.example.test/__version',
+    ]);
+  });
+
+  it('fails naming the endpoint answer when the edge never reports the new tag', async () => {
+    const root = await fixtureRoot();
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+    const stubFetch: FetchLike = async () => new Response('nx-previous');
+
+    await expect(
+      deployStage(
+        root,
+        { stage: 'pr123', versionEndpoint: 'https://fixture.example.test/__version' },
+        { ...dependencies(runner, new FakeCloudflare()), wait: { ...fakeWait(), fetch: stubFetch } },
+      ),
+    ).rejects.toThrow(
+      `fixture-worker-pr123: https://fixture.example.test/__version did not report version nx-${HASH} after 10s; it reported nx-previous`,
+    );
+  });
+
   it('uploads a missing tag with a temporary config and secure secrets file, then removes both', async () => {
     const root = await fixtureRoot();
     await writeFile(join(root, '.dev.vars.example'), 'FIXTURE_SECRET=""\nFIXTURE_TOKEN=""\n');
@@ -231,9 +382,12 @@ describe('deploy-stage remote version fallback', () => {
     );
 
     expect(result.action).toBe('deployed');
-    expect(runner.calls.at(-1)?.args[0]).toBe('deploy');
-    expect(runner.calls.at(-1)?.args).toContain('--tag');
-    expect(runner.calls.at(-1)?.args).toContain(`nx-${HASH}`);
+    const upload = requiredTestValue(
+      runner.calls.find((call) => call.args[0] === 'deploy'),
+      'upload call',
+    );
+    expect(upload.args).toContain('--tag');
+    expect(upload.args).toContain(`nx-${HASH}`);
     expect(runner.secretsMode).toBe(0o600);
     expect(JSON.parse(requiredTestValue(runner.secretsJson, 'secrets JSON'))).toEqual({
       FIXTURE_SECRET: 'shared-secret',
@@ -615,6 +769,10 @@ describe('deployStage with a flat JSON config', () => {
       ['deployments', 'status'],
       ['d1', 'migrations'],
       ['versions', 'deploy'],
+      // The traffic shift is not the end of the deploy: the step re-reads live state and only
+      // returns once the tag it activated is the one being served.
+      ['deployments', 'status'],
+      ['versions', 'list'],
     ]);
   });
 
@@ -736,10 +894,30 @@ async function fixtureRoot(toml = FIXTURE): Promise<string> {
   return root;
 }
 
+/**
+ * A wait whose clock only advances when the code under test sleeps: real bounds, no real seconds,
+ * and a deterministic poll count a test can assert on.
+ */
+function fakeWait(): { budgetMs: number; intervalMs: number; now: () => number; sleep: (ms: number) => Promise<void> } {
+  let clock = 0;
+  return {
+    budgetMs: 10_000,
+    intervalMs: 1_000,
+    now: () => clock,
+    sleep: async (ms: number) => {
+      clock += ms;
+    },
+  };
+}
+
 function dependencies(runner: ProcessRunner, cloudflare: CloudflareClient) {
+  const cacheDirectory = mkdtempSync(join(tmpdir(), 'smoo-live-version-'));
+  roots.push(cacheDirectory);
   return {
     runner,
     cloudflare,
+    wait: fakeWait(),
+    liveVersionCacheDirectory: cacheDirectory,
     processEnv: {
       CLOUDFLARE_ACCOUNT_ID: 'account-1',
       CLOUDFLARE_API_TOKEN: 'token',

package/src/wrangler/deploy-stage.ts

@@ -2,11 +2,20 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import typia from 'typia';
 import { parseJsonFileText } from '../lib/json.js';
 import { mergeEnv, printCommandOutput } from '../lib/run.js';
 import { type CloudflareClient, CloudflareRestClient, type D1DatabaseRecord } from './cloudflare.js';
 import { type FlatWranglerConfig, parseFlatWranglerConfig, planFlatStageResources } from './flat-config.js';
+import {
+  awaitLiveVersion,
+  awaitVersionEndpoint,
+  currentDeploymentVersionId,
+  findVersionIdByTag,
+  type LiveVersionProbe,
+  liveVersionCacheDirectory,
+  type VersionEndpointWaitOptions,
+  writeCachedLiveVersion,
+} from './live-version.js';
 import { parseDevVarsExample } from './prepare-env.js';
 import {
   type ConfiguredStageResourcePlan,
@@ -69,6 +78,10 @@ export interface WranglerCommandDependencies {
   runner?: ProcessRunner;
   cloudflare?: CloudflareClient;
   processEnv?: NodeJS.ProcessEnv;
+  /** Bounds and clock for the post-deploy wait; tests drive it without sleeping. */
+  wait?: VersionEndpointWaitOptions;
+  /** Where a successful deploy records the tag it made live, for `smoo wrangler deployed-version`. */
+  liveVersionCacheDirectory?: string;
 }
 
 export interface DeployStageResult {
@@ -78,13 +91,17 @@ export interface DeployStageResult {
   versionTag?: string;
 }
 
-const isUnknownRecord = typia.createIs<Record<string, unknown>>();
-
 export interface DeployStageOptions {
   /** `staging`, `production`, or `prN`. */
   stage: string;
   /** A build-generated flat wrangler.json to deploy instead of `./wrangler.toml` (see `prepareFlatConfig`). */
   config?: string;
+  /**
+   * A URL, served by this worker, whose trimmed body is the running version tag. When given, the
+   * deploy is not done until that URL answers with the tag it just made live — the control plane
+   * accepting a traffic shift is not the edge serving it.
+   */
+  versionEndpoint?: string;
 }
 
 export async function deployStage(
@@ -124,16 +141,24 @@ export async function deployStage(
     // `reconcileStageResources` nor `versions list` looks at.
     const run: ProcessRunOptions = prepared.envFlag ? { cwd } : { cwd, unsetEnv: ['CLOUDFLARE_ENV'] };
     const workerName = prepared.plan.workerName;
+    const probe: LiveVersionProbe = {
+      deployments: () => wranglerJson(runner, ['deployments', 'status', '--name', workerName, '--json'], run),
+      versions: () => wranglerJson(runner, ['versions', 'list', '--name', workerName, '--json'], run),
+    };
 
     // The tagged-version lookup runs before the migrations: a cache hit means this exact build is
     // already live, so its migrations ran with it and re-applying them would touch the remote
     // database for nothing. The activation and upload paths below still migrate first.
+    //
+    // This reads Cloudflare every time and never the local cache. A cache hit here would mean
+    // "we believe this hash is live" — exactly the belief a rollback falsifies — and believing it
+    // would skip the deploy that repairs the rollback. Reading live state is what makes a
+    // redundant deploy a proven no-op instead of an assumed one, which is in turn what makes a
+    // cross-project `dependsOn: ["<other>:deploy"]` edge cheap enough to be the ordering mechanism.
     let taggedVersionId: string | null = null;
     if (versionTag && workerExists) {
-      const versions = await wranglerJson(runner, ['versions', 'list', '--name', workerName, '--json'], run);
-      const deployments = await wranglerJson(runner, ['deployments', 'status', '--name', workerName, '--json'], run);
-      taggedVersionId = findVersionIdByTag(versions, versionTag);
-      if (taggedVersionId && isFullCurrentDeployment(deployments, taggedVersionId)) {
+      taggedVersionId = findVersionIdByTag(await probe.versions(), versionTag);
+      if (taggedVersionId && currentDeploymentVersionId(await probe.deployments()) === taggedVersionId) {
         return { stage, workerName, action: 'remote-cache-hit', versionTag };
       }
     }
@@ -163,6 +188,7 @@ export async function deployStage(
         ],
         run,
       );
+      await confirmVersionIsLive(probe, versionTag, { stage, workerName, accountId }, options, dependencies, cwd);
       return { stage, workerName, action: 'activated', versionTag };
     }
 
@@ -174,6 +200,9 @@ export async function deployStage(
       deployArgs.push('--secrets-file', temporarySecretsPath);
     }
     await wrangler(runner, deployArgs, run);
+    if (versionTag) {
+      await confirmVersionIsLive(probe, versionTag, { stage, workerName, accountId }, options, dependencies, cwd);
+    }
     return { stage, workerName, action: 'deployed', ...(versionTag ? { versionTag } : {}) };
   } finally {
     if (temporaryConfigPath) {
@@ -578,49 +607,47 @@ export function nxTaskVersionTag(environment: NodeJS.ProcessEnv): string | undef
   throw new Error('NX_TASK_HASH must be canonical decimal digits or at least 32 hexadecimal characters.');
 }
 
-export function findVersionIdByTag(value: unknown, tag: string): string | null {
-  if (Array.isArray(value)) {
-    for (const entry of value) {
-      const found = findVersionIdByTag(entry, tag);
-      if (found) return found;
-    }
-    return null;
-  }
-  if (!isUnknownRecord(value)) return null;
-  const annotations = isUnknownRecord(value.annotations) ? value.annotations : undefined;
-  const metadata = isUnknownRecord(value.metadata) ? value.metadata : undefined;
-  const annotationTag = annotations?.['workers/tag'];
-  const candidateTag =
-    typeof annotationTag === 'string' ? annotationTag : typeof value.tag === 'string' ? value.tag : metadata?.tag;
-  if (candidateTag === tag) {
-    if (typeof value.id === 'string') return value.id;
-    if (typeof value.version_id === 'string') return value.version_id;
-  }
-  for (const nested of Object.values(value)) {
-    const found = findVersionIdByTag(nested, tag);
-    if (found) return found;
-  }
-  return null;
+/** What a freshly activated version has to be true of, and where the fact gets recorded. */
+interface DeployedVersionIdentity {
+  stage: DeploymentStage;
+  workerName: string;
+  accountId: string;
 }
 
-export function isFullCurrentDeployment(value: unknown, versionId: string): boolean {
-  if (Array.isArray(value)) return value.some((entry) => isFullCurrentDeployment(entry, versionId));
-  if (!isUnknownRecord(value)) return false;
-  if (Array.isArray(value.versions)) {
-    return (
-      value.versions.length === 1 &&
-      value.versions.some(
-        (version) =>
-          isUnknownRecord(version) &&
-          (version.version_id === versionId || version.id === versionId) &&
-          Number(version.percentage) === 100,
-      )
-    );
+/**
+ * Turns "Cloudflare accepted the traffic shift" into "the new version answers".
+ *
+ * Without this the deploy step goes green while the edge still serves the previous version — the
+ * measured gap was about 20 s — so anything ordered after this deploy could call into code that
+ * has not shipped yet. The wait is what a `dependsOn: ["<other>:deploy"]` edge actually buys; an
+ * edge onto a step that returns early orders nothing.
+ */
+async function confirmVersionIsLive(
+  probe: LiveVersionProbe,
+  versionTag: string,
+  identity: DeployedVersionIdentity,
+  options: DeployStageOptions,
+  dependencies: WranglerCommandDependencies,
+  cwd: string,
+): Promise<void> {
+  const wait = dependencies.wait ?? {};
+  const live = await awaitLiveVersion(probe, versionTag, wait);
+  if (!live.ok) throw new Error(`${identity.workerName}: ${live.error.message}`);
+  if (options.versionEndpoint) {
+    const answered = await awaitVersionEndpoint(options.versionEndpoint, versionTag, wait);
+    if (!answered.ok) throw new Error(`${identity.workerName}: ${answered.error.message}`);
   }
-  return Object.values(value).some((entry) => isFullCurrentDeployment(entry, versionId));
+  const processEnv = dependencies.processEnv ?? process.env;
+  const directory = dependencies.liveVersionCacheDirectory ?? liveVersionCacheDirectory(cwd, processEnv);
+  await writeCachedLiveVersion(
+    directory,
+    { accountId: identity.accountId, workerName: identity.workerName, stage: identity.stage },
+    { versionTag, versionId: live.value.versionId, fetchedAt: Date.now() },
+  );
 }
 
-async function wranglerJson(runner: ProcessRunner, args: string[], run: ProcessRunOptions): Promise<unknown> {
+/** One wrangler invocation whose stdout must be JSON; shared by the deploy and the read-only query. */
+export async function wranglerJson(runner: ProcessRunner, args: string[], run: ProcessRunOptions): Promise<unknown> {
   const result = await wrangler(runner, args, run);
   try {
     return JSON.parse(result.stdout);