deepline 0.3.118 → 0.3.119

package/dist/bundling-sources/shared_libs/plays/deploy/run-deployment.ts

@@ -0,0 +1,1355 @@
+import { join } from 'node:path';
+import { rm } from 'node:fs/promises';
+import type { PlayCompilerManifest } from '../compiler-manifest';
+import {
+  DeployApiClient,
+  DeployApiError,
+  type DeploymentPlayState,
+  type RegisterArtifactEntry,
+} from './api-client';
+import {
+  discoverPlayFiles,
+  readDeeplineManifest,
+  DeeplineManifestError,
+  DEFAULT_MANIFEST_FILE,
+} from './manifest';
+import type { SerializedPlayDeployment } from './project-serializer';
+import { resolveOwnedPlayReferenceName } from '../play-reference';
+import type { BundledPlayFileResult } from '../bundling/index';
+import type { PlayBundleArtifact } from '../artifact-types';
+import { isAstNode, parsePlaySourceForAnalysis, type AstNode } from '../ts-ast';
+
+const RUN_PLAY_METHOD_NAMES = new Set(['runPlay', 'runPlayAsync']);
+
+function isRunPlayReceiver(node: unknown): boolean {
+  return (
+    isAstNode(node) &&
+    node.type === 'Identifier' &&
+    typeof node.name === 'string' &&
+    (node.name === 'ctx' || node.name.endsWith('Ctx'))
+  );
+}
+
+function stringLiteralValue(node: unknown): string | null {
+  if (!isAstNode(node)) return null;
+  if (node.type === 'Literal' && typeof node.value === 'string') {
+    return node.value;
+  }
+  // A template with no substitutions is a string literal too.
+  if (
+    node.type === 'TemplateLiteral' &&
+    Array.isArray(node.expressions) &&
+    node.expressions.length === 0 &&
+    Array.isArray(node.quasis) &&
+    node.quasis.length === 1
+  ) {
+    const cooked = (node.quasis[0] as { value?: { cooked?: unknown } }).value
+      ?.cooked;
+    return typeof cooked === 'string' ? cooked : null;
+  }
+  return null;
+}
+
+/**
+ * Cheap, standalone scan for ctx.runPlay(...)/ctx.runPlayAsync(...) calls
+ * whose second argument is an inline string literal - the only playRef form
+ * the cloud-tool typecheck accepts for ctx.runPlay (an imported handle or a
+ * const-indirected identifier both fail validateRunPlayCall's string-literal
+ * requirement), so it is also the only form worth graphing here. Lets a play
+ * that calls another brand-new play in this same push, by name, compile
+ * after its target - the same way an imported play already does - instead of
+ * only ever finding it (or not) in already-published Convex state.
+ */
+export async function extractRunPlayStringTargets(
+  sourceCode: string,
+): Promise<string[]> {
+  const program = parsePlaySourceForAnalysis(sourceCode);
+  // acorn cannot parse some valid TypeScript (`<T>value` casts). Where the
+  // compiler is installed (the deploy worker) it reads those; elsewhere the
+  // play gets no ordering edges, and compile-manifest owns any syntax error.
+  if (!program) return (await extractWithCompiler(sourceCode)) ?? [];
+  const targets = new Set<string>();
+  const visit = (node: AstNode) => {
+    const callee = node.callee;
+    if (
+      node.type === 'CallExpression' &&
+      isAstNode(callee) &&
+      callee.type === 'MemberExpression' &&
+      callee.computed !== true &&
+      isAstNode(callee.property) &&
+      RUN_PLAY_METHOD_NAMES.has(String(callee.property.name)) &&
+      isRunPlayReceiver(callee.object) &&
+      Array.isArray(node.arguments)
+    ) {
+      const playRef = stringLiteralValue(node.arguments[1]);
+      const ownedName =
+        playRef === null ? null : resolveOwnedPlayReferenceName(playRef);
+      if (ownedName) targets.add(ownedName);
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === 'loc') continue;
+      for (const child of Array.isArray(value) ? value : [value]) {
+        if (isAstNode(child)) visit(child);
+      }
+    }
+  };
+  visit(program);
+  return [...targets];
+}
+
+async function extractWithCompiler(
+  sourceCode: string,
+): Promise<string[] | null> {
+  let ts: typeof import('typescript');
+  try {
+    const loaded = await import('typescript');
+    // CommonJS through ESM: the compiler API is the default export.
+    ts = loaded.default ?? loaded;
+  } catch {
+    return null;
+  }
+  const sourceFile = ts.createSourceFile(
+    'play.ts',
+    sourceCode,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const targets = new Set<string>();
+  const visit = (node: import('typescript').Node) => {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      RUN_PLAY_METHOD_NAMES.has(node.expression.name.text) &&
+      ts.isIdentifier(node.expression.expression) &&
+      (node.expression.expression.text === 'ctx' ||
+        node.expression.expression.text.endsWith('Ctx'))
+    ) {
+      const playRefArgument = node.arguments[1];
+      if (playRefArgument && ts.isStringLiteralLike(playRefArgument)) {
+        const ownedName = resolveOwnedPlayReferenceName(playRefArgument.text);
+        if (ownedName) targets.add(ownedName);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return [...targets];
+}
+
+export type PlayDeployOutcome = {
+  name: string;
+  file: string;
+  status: 'promoted' | 'registered' | 'unchanged' | 'failed';
+  version?: number;
+  /**
+   * The version that was live BEFORE this deployment promoted over it, so a
+   * receipt can show the transition rather than only the destination. Absent
+   * for a play's first deploy, and for outcomes that never moved the live
+   * pointer.
+   */
+  previousVersion?: number;
+  /**
+   * Something the reader must see about a play that still deployed. Kept
+   * orthogonal to `status` on purpose: "what happened to this play" and "is
+   * there something wrong with it" are different questions, and a play can be
+   * promoted normally and still be worth flagging. One warning anywhere turns
+   * the deployment into `succeeded_with_warnings`.
+   */
+  warning?: string;
+  error?: string;
+};
+
+export type PlayDeploymentRunResult = {
+  finalStatus:
+    | 'succeeded'
+    | 'succeeded_with_warnings'
+    | 'failed'
+    | 'superseded'
+    | 'cancelled';
+  outcomes: PlayDeployOutcome[];
+  checkRunId?: number;
+};
+
+export type CheckRunAnnotation = {
+  path: string;
+  start_line: number;
+  end_line: number;
+  annotation_level: 'notice' | 'warning' | 'failure';
+  message: string;
+  raw_details?: string;
+};
+
+export type DeploymentCheckVerdict = {
+  conclusion: 'success' | 'failure' | 'neutral';
+  title: string;
+  summary: string;
+  annotations?: CheckRunAnnotation[];
+};
+
+/**
+ * Where a deployment's plays come from, and what the git host (if there is
+ * one) can tell or be told about them.
+ *
+ * A managed build of a linked repository fetches the commit, asks the host
+ * whether its branch head moved, and writes a Check Run. A workspace
+ * deploying a directory of plays supplies only `open`, which hands back the
+ * directory it was given: no git, no host, no checks.
+ */
+export type DeploymentSource = {
+  /** Make the plays readable; returns the root to build from. */
+  open(workDir: string): Promise<{ repoRoot: string }>;
+  /** The branch's current head, when the host can be asked. */
+  branchHead?: (branch: string) => Promise<string | null>;
+  /** Post (or replace, by deployment id) this commit's check. */
+  postCheck?: (
+    verdict: DeploymentCheckVerdict & { name?: string; externalId: string },
+  ) => Promise<{ checkRunId: number }>;
+  /** Production only: the pull request whose merge produced the commit. */
+  findMergedPullRequest?: () => Promise<number | null>;
+};
+
+export type DeploymentRunParams = {
+  deploymentId: string;
+  deployToken: string;
+  appBaseUrl: string;
+};
+
+export type DeploymentRunHooks = {
+  bundle: (
+    entryFile: string,
+    options: { sourceIdentityRoot: string },
+  ) => Promise<BundledPlayFileResult>;
+  /**
+   * Opened inside the build's failure boundary, so a host outage still ends
+   * in a terminal status rather than a stranded deployment.
+   */
+  openSource: (input: {
+    client: DeployApiClient;
+    deployment: SerializedPlayDeployment;
+  }) => Promise<DeploymentSource>;
+  /**
+   * What to build, for a deployment with no linked repository to read it
+   * from. A linked deployment takes these from its project.
+   */
+  target?: { rootDirectory: string; manifestPath: string };
+  fetchImpl?: typeof fetch;
+  workRoot: string;
+  /** Test hook: delay between Check Run write retries (default 1000ms). */
+  checkRunRetryDelayMs?: number;
+};
+
+/**
+ * Thrown when this attempt failed for a reason a fresh attempt can fix (e.g.
+ * a GitHub Checks outage after the build itself succeeded). The outer catch
+ * rethrows it WITHOUT writing a terminal status, so the deployment stays
+ * `building` and the Absurd retry (or ultimately the stale sweeper) takes
+ * over, instead of the row being failed while its token still burns.
+ */
+export class RetryableDeploymentError extends Error {}
+
+const TERMINAL_TOKEN_CODES = new Set([
+  'PLAY_DEPLOYMENT_SUPERSEDED',
+  'PLAY_DEPLOYMENT_TERMINAL',
+  'PLAY_PROJECT_DISABLED',
+  'GITHUB_INSTALLATION_INACTIVE',
+]);
+
+/**
+ * The control plane revoked this deployment's token: it was cancelled,
+ * superseded, or its project/installation went away. The attempt must stop
+ * without writing anything — no status (the row is already terminal) and no
+ * Check Run (the build did not fail; someone stopped it).
+ */
+function revokedFinalStatus(error: unknown): 'cancelled' | 'superseded' | null {
+  if (
+    !(error instanceof DeployApiError) ||
+    !error.code ||
+    !TERMINAL_TOKEN_CODES.has(error.code)
+  ) {
+    return null;
+  }
+  return error.code === 'PLAY_DEPLOYMENT_SUPERSEDED'
+    ? 'superseded'
+    : 'cancelled';
+}
+
+/**
+ * A revision already carries this bundle when all four identity hashes agree.
+ * One definition, used for both the live and the working revision.
+ */
+function carriesArtifact(
+  revision: DeploymentPlayState['liveRevision'],
+  artifact: Pick<
+    PlayBundleArtifact,
+    'sourceHash' | 'artifactHash' | 'graphHash' | 'artifactKind'
+  >,
+): boolean {
+  return Boolean(
+    revision &&
+    revision.sourceHash === artifact.sourceHash &&
+    revision.artifactHash === artifact.artifactHash &&
+    revision.graphHash === artifact.graphHash &&
+    revision.artifactKind === artifact.artifactKind,
+  );
+}
+
+function annotationForFailure(input: {
+  file: string;
+  message: string;
+}): CheckRunAnnotation {
+  return {
+    path: input.file,
+    start_line: 1,
+    end_line: 1,
+    annotation_level: 'failure',
+    message: input.message.slice(0, 4000),
+  };
+}
+
+/**
+ * The deploy build, host-agnostic: everything flows through the deploy API
+ * client (per-deployment token) and the injected bundler, so the Absurd
+ * task handler and tests drive the same body. Retries are safe end to end:
+ * the deployment fetch aborts superseded work, registration retries are
+ * absorbed by the hash-based skip, and promote is idempotent per revision.
+ */
+export async function runDeployment(
+  params: DeploymentRunParams,
+  hooks: DeploymentRunHooks,
+): Promise<PlayDeploymentRunResult> {
+  const startedAt = Date.now();
+  const client = new DeployApiClient({
+    appBaseUrl: params.appBaseUrl,
+    deployToken: params.deployToken,
+    deploymentId: params.deploymentId,
+    fetchImpl: hooks.fetchImpl,
+  });
+
+  let state;
+  try {
+    state = await client.getDeployment();
+  } catch (error) {
+    const revoked = revokedFinalStatus(error);
+    if (revoked) {
+      console.info('[deploy-worker] aborting: deployment no longer buildable', {
+        deploymentId: params.deploymentId,
+        code: (error as DeployApiError).code,
+      });
+      return { finalStatus: revoked, outcomes: [] };
+    }
+    if (error instanceof DeployApiError && error.status === 401) {
+      // The deploy token is dead (expired past the queue-aware TTL or
+      // invalid) and can never become valid again — retrying burns attempts
+      // for nothing. Abort cleanly; the stale-deployment sweeper cron
+      // terminalizes the stranded row.
+      console.error('[deploy-worker] aborting: deploy token rejected', {
+        deploymentId: params.deploymentId,
+        error: error.message.slice(0, 200),
+      });
+      return { finalStatus: 'cancelled', outcomes: [] };
+    }
+    throw error;
+  }
+  const { deployment, project } = state;
+  // A deployment of a directory has no project; its caller states the target.
+  const target = project ?? hooks.target;
+  if (!target) {
+    throw new Error(
+      `Deployment ${params.deploymentId} has no linked repository and no target directory was given.`,
+    );
+  }
+  // Server-computed; qualified when several targets build one repo (A2).
+  const checkRunName = state.checkRunName?.trim() || undefined;
+
+  // Production push only: the PR whose merge produced this commit, so the
+  // dashboard links the PR and not only the commit. Resolved once the
+  // installation token exists and stamped on EVERY status write after that
+  // through this one wrapper — a failed or superseded merge deploy is
+  // exactly where the reader wants the PR, and a per-site spread would be
+  // one more thing each terminal path could forget. Decoration, never a
+  // gate: a lookup failure logs and the deployment proceeds without it.
+  let mergedPullRequestNumber: number | null = null;
+  // Set once this deployment's live-pointer flip committed. From then on its
+  // plays are live, so no cancel can make its Check Run untrue.
+  let promoted = false;
+  const setStatus: DeployApiClient['setStatus'] = (input) =>
+    client.setStatus({
+      ...input,
+      ...(mergedPullRequestNumber ? { mergedPullRequestNumber } : {}),
+    });
+
+  try {
+    await setStatus({ status: 'building' });
+  } catch (error) {
+    // A retried attempt may already be past 'building'; that is fine.
+    if (
+      !(
+        error instanceof DeployApiError &&
+        error.code === 'PLAY_DEPLOYMENT_INVALID_TRANSITION'
+      )
+    ) {
+      throw error;
+    }
+  }
+
+  const buildSeconds = () => Math.max(0, (Date.now() - startedAt) / 1000);
+  const finishFailed = async (input: {
+    error: string;
+    outcomes: PlayDeployOutcome[];
+    checkRunId?: number;
+  }): Promise<PlayDeploymentRunResult> => {
+    try {
+      await setStatus({
+        status: 'failed',
+        error: input.error.slice(0, 2000),
+        results: { plays: input.outcomes },
+        buildSeconds: buildSeconds(),
+        ...(input.checkRunId ? { checkRunId: input.checkRunId } : {}),
+      });
+    } catch (statusError) {
+      // The terminal status MUST land: swallowing it here would ACK the
+      // Absurd task and strand the deployment non-terminal. Rethrow so the
+      // task retries until the terminal write persists.
+      console.error(
+        '[deploy-worker] failed-status write failed; retrying task',
+        {
+          deploymentId: params.deploymentId,
+          error:
+            statusError instanceof Error
+              ? statusError.message
+              : String(statusError),
+        },
+      );
+      throw new Error(
+        `Terminal status write failed for ${params.deploymentId} (original failure: ${input.error.slice(0, 300)})`,
+      );
+    }
+    return {
+      finalStatus: 'failed',
+      outcomes: input.outcomes,
+      checkRunId: input.checkRunId,
+    };
+  };
+  const finishSucceeded = async (
+    outcomes: PlayDeployOutcome[],
+    checkRun: { checkRunId: number } | null,
+  ): Promise<PlayDeploymentRunResult> => {
+    // Carried by the terminal status rather than per-play results so every
+    // reader — API, CLI, dashboard, alerting — sees it without parsing them.
+    const finalStatus = outcomes.some((outcome) => outcome.warning)
+      ? ('succeeded_with_warnings' as const)
+      : ('succeeded' as const);
+    try {
+      await setStatus({
+        status: finalStatus,
+        results: { plays: outcomes },
+        buildSeconds: buildSeconds(),
+        ...(checkRun ? { checkRunId: checkRun.checkRunId } : {}),
+      });
+    } catch (statusError) {
+      // The work this status reports (promotion included) already happened,
+      // so a terminal `failed` here would be a lie about a live deployment —
+      // and terminal status kills the token, so no retry could ever correct
+      // the record. Stay non-terminal and retry the task instead: the rerun
+      // is idempotent (register dedupes, promote re-flips the same
+      // revisions) and ends at this same write.
+      const message =
+        statusError instanceof Error
+          ? statusError.message
+          : String(statusError);
+      console.warn(
+        '[deploy-worker] succeeded-status write failed; retrying task',
+        { deploymentId: params.deploymentId, error: message.slice(0, 300) },
+      );
+      throw new RetryableDeploymentError(
+        `SUCCEEDED_STATUS_WRITE_FAILED: ${message}`,
+      );
+    }
+    return {
+      finalStatus,
+      outcomes,
+      checkRunId: checkRun?.checkRunId,
+    };
+  };
+
+  const workDir = join(hooks.workRoot, `deploy-${params.deploymentId}`);
+  // Check writes are customer-visible; give transient host failures bounded
+  // retries before any caller decides to swallow or fail.
+  const postCheck = async (
+    postCheckOnce: NonNullable<DeploymentSource['postCheck']>,
+    input: Parameters<NonNullable<DeploymentSource['postCheck']>>[0],
+  ) => {
+    let lastError: unknown;
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        return await postCheckOnce(input);
+      } catch (error) {
+        lastError = error;
+        if (attempt >= 2) {
+          throw lastError;
+        }
+        await new Promise((resolve) =>
+          setTimeout(resolve, hooks.checkRunRetryDelayMs ?? 1000),
+        );
+      }
+    }
+  };
+  // Assigned once the GitHub token exists. The terminal catch below is
+  // reached by every non-retryable crash — a rejected registration, a bad
+  // promote — and without this those land as a `failed` row with nothing on
+  // the commit, so the push looks to GitHub like it never happened.
+  let postFailureCheck:
+    | ((summary: string) => Promise<number | undefined>)
+    | null = null;
+  try {
+    // Inside the try so a GitHub outage / revoked installation still writes
+    // a terminal `failed` status instead of stranding the deployment in
+    // `building` (loud failures over silent fallbacks).
+    const source = await hooks.openSource({ client, deployment });
+    // Every production trigger, not only 'push': a 'redeliver' recovery of a
+    // superseded head, or a manual re-deploy, is still deploying the commit
+    // some PR produced — and the recovery is the row that actually reaches
+    // production. PR builds are never production and already know their PR.
+    if (deployment.isProduction) {
+      try {
+        mergedPullRequestNumber =
+          (await source.findMergedPullRequest?.()) ?? null;
+      } catch (error) {
+        console.warn('[deploy-worker] merged PR lookup failed', {
+          deploymentId: params.deploymentId,
+          error: (error instanceof Error ? error.message : String(error)).slice(
+            0,
+            300,
+          ),
+        });
+      }
+    }
+
+    // Every Check Run in this deployment targets the same repo, commit, and
+    // (server-computed) name; call sites supply only the verdict.
+    //
+    // For PR builds a Check Run — success OR failure — is THE deliverable: if
+    // it cannot be written even with retries, keep the attempt retryable (no
+    // terminal write) instead of ACKing a PR that never got its check. For
+    // production the status row is authoritative, so a lost check is logged
+    // and swallowed.
+    type CheckVerdict = DeploymentCheckVerdict;
+    const writeCheck = async (input: CheckVerdict) => {
+      // No host check surface (a directory deploy): the status row is the
+      // only verdict, which is exactly what its caller reads.
+      if (!source.postCheck) return null;
+      try {
+        return await postCheck(source.postCheck, {
+          name: checkRunName,
+          // Idempotency key: a retry after a lost create response updates
+          // the existing run instead of posting a duplicate check.
+          externalId: params.deploymentId,
+          ...input,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!deployment.isProduction) {
+          throw new RetryableDeploymentError(
+            `GITHUB_CHECK_WRITE_FAILED: could not post the PR Check Run after retries: ${message}`,
+          );
+        }
+        console.warn(
+          '[deploy-worker] check write lost; status row is authoritative',
+          {
+            deploymentId: params.deploymentId,
+            error: message.slice(0, 300),
+          },
+        );
+        return null;
+      }
+    };
+    // Throws the control plane's revocation of this deployment, if any. Any
+    // other read failure is not evidence of a cancel, so it is ignored here.
+    const assertNotRevoked = async () => {
+      try {
+        await client.getDeployment();
+      } catch (error) {
+        if (revokedFinalStatus(error)) throw error;
+      }
+    };
+    // Check Runs use the GitHub App's token, not the deploy token, so a
+    // cancel does not stop them. Before promotion a cancel makes any verdict
+    // untrue: check for one before posting, and again after — a cancel that
+    // landed in between turns the posted check neutral (same external id, so
+    // it replaces the verdict) and aborts the attempt.
+    const postCheckOrNull = async (input: CheckVerdict) => {
+      if (promoted) return writeCheck(input);
+      await assertNotRevoked();
+      const checkRun = await writeCheck(input);
+      await assertNotRevoked().catch(async (revocation: unknown) => {
+        const stopped = revokedFinalStatus(revocation);
+        await writeCheck({
+          conclusion: 'neutral',
+          title: `Deployment ${stopped}`,
+          summary:
+            'This deployment was stopped before it finished. Nothing from it went live.',
+        }).catch(() => undefined);
+        throw revocation;
+      });
+      return checkRun;
+    };
+    // The common failure shape: a failure Check Run, then the terminal
+    // `failed` status carrying the same diagnostics.
+    const failWithCheck = async (input: {
+      title: string;
+      summary: string;
+      error: string;
+      outcomes: PlayDeployOutcome[];
+      annotations?: CheckRunAnnotation[];
+    }): Promise<PlayDeploymentRunResult> => {
+      const checkRun = await postCheckOrNull({
+        conclusion: 'failure',
+        title: input.title,
+        summary: input.summary,
+        ...(input.annotations ? { annotations: input.annotations } : {}),
+      });
+      return finishFailed({
+        error: input.error,
+        outcomes: input.outcomes,
+        checkRunId: checkRun?.checkRunId,
+      });
+    };
+
+    postFailureCheck = async (summary) =>
+      (
+        await postCheckOrNull({
+          conclusion: 'failure',
+          title: 'Deploy failed',
+          summary,
+        })
+      )?.checkRunId;
+
+    // Out-of-order guard: if GitHub delivered an OLDER push after the new
+    // head, enqueue-time supersede may already have retired the true head's
+    // queued build — so every terminal path in this function must only be
+    // reachable while this commit is still the branch head. When it is not,
+    // supersede with observedHeadSha so the control plane re-enqueues the
+    // uncovered head. Runs here (before any early return: empty tree, bad
+    // manifest, org guard, bundle failures) and again right before promote.
+    // The guard's question is "is MY commit still the head of MY ref" — so
+    // the branch comes from the deployment's own ref, never the project's
+    // live productionBranch setting. An admin retargeting the project
+    // mid-build must not make an old deployment observe the NEW branch and
+    // re-enqueue (or promote) a foreign SHA under its old ref. (Settings
+    // changes also cancel in-flight deployments control-plane-side; this
+    // keeps the worker correct even inside that race window.)
+    const deploymentBranch = deployment.ref?.startsWith('refs/heads/')
+      ? deployment.ref.slice('refs/heads/'.length)
+      : (project?.productionBranch ?? null);
+    const supersedeIfHeadMoved = async () => {
+      // Only a host that can be asked about a branch can supersede on it.
+      if (!deployment.isProduction || !source.branchHead || !deploymentBranch) {
+        return null;
+      }
+      const head = await source.branchHead(deploymentBranch);
+      if (head === deployment.commitSha) return null;
+      console.info('[deploy-worker] superseding: branch head moved', {
+        deploymentId: params.deploymentId,
+        commitSha: deployment.commitSha,
+        head: head ?? '<branch deleted>',
+      });
+      // Terminal write must persist; a failure retries the task.
+      await setStatus({
+        status: 'superseded',
+        error: `Branch ${deploymentBranch} is now at ${head?.slice(0, 12) ?? '<deleted>'}; this deployment's commit is no longer the head.`,
+        buildSeconds: buildSeconds(),
+        ...(head ? { observedHeadSha: head } : {}),
+      });
+      return { finalStatus: 'superseded' as const, outcomes: [] };
+    };
+    {
+      const superseded = await supersedeIfHeadMoved();
+      if (superseded) return superseded;
+    }
+    const { repoRoot } = await source.open(workDir);
+    const projectRoot = target.rootDirectory
+      ? join(repoRoot, target.rootDirectory)
+      : repoRoot;
+
+    const manifestFile = target.manifestPath || DEFAULT_MANIFEST_FILE;
+    let manifest;
+    let playFiles: string[];
+    try {
+      manifest = await readDeeplineManifest(projectRoot, manifestFile);
+      playFiles = await discoverPlayFiles({
+        projectRoot,
+        globs: manifest.plays,
+      });
+    } catch (error) {
+      if (error instanceof DeeplineManifestError) {
+        return await failWithCheck({
+          title: `${manifestFile} is invalid`,
+          summary: error.message,
+          error: error.message,
+          outcomes: [],
+        });
+      }
+      throw error;
+    }
+
+    // The manifest's optional `org` field is the repo's tenant guard: a repo
+    // that declares which workspace it expects must never deploy anywhere
+    // else. This is what keeps a shared-repo misbinding from publishing one
+    // push into the wrong tenant.
+    if (manifest.org) {
+      const expected = manifest.org.trim().toLowerCase();
+      const actual = (state.workspaceSlug ?? '').trim().toLowerCase();
+      if (expected !== actual) {
+        const message = `DEEPLINE_MANIFEST_ORG_MISMATCH: ${manifestFile} declares org "${manifest.org}", but this deployment targets workspace "${state.workspaceSlug ?? '<unknown>'}". Fix the manifest or unbind the repo from this workspace.`;
+        return await failWithCheck({
+          title: 'Workspace guard rejected this deployment',
+          summary: message,
+          error: message,
+          outcomes: [],
+        });
+      }
+    }
+
+    if (playFiles.length === 0) {
+      const checkRun = await postCheckOrNull({
+        conclusion: 'neutral',
+        title: 'No plays matched',
+        summary: `No files matched ${manifest.plays.join(', ')} under ${target.rootDirectory || 'the deployed directory'}.`,
+      });
+      return await finishSucceeded([], checkRun);
+    }
+
+    // One deployment handles at most 100 plays: promote enforces it
+    // (PLAY_DEPLOY_BATCH_TOO_LARGE in promote.ts) and plays-state caps its
+    // name list at 100. Refuse at discovery, before any bundling — the
+    // rejection is guaranteed, so burning metered build compute (or, later,
+    // control-plane writes that churn revision history on retries) to reach
+    // it would be pure waste.
+    if (playFiles.length > 100) {
+      const message = `PLAY_DEPLOY_BATCH_TOO_LARGE: this deployment contains ${playFiles.length} plays (max 100). Split the repo into multiple projects.`;
+      return await failWithCheck({
+        title: 'Too many plays in one deployment',
+        summary: message,
+        error: message,
+        outcomes: [],
+      });
+    }
+
+    // Bundle every play. Any failure fails the whole deploy (all-or-nothing
+    // through every phase).
+    type BundledPlay = {
+      /**
+       * Repo-relative, decided once here. Every later reader — outcomes,
+       * annotations, the stored source path — means "where this play lives in
+       * the repository", so there is no second form to convert to and no site
+       * that can forget.
+       */
+      file: string;
+      name: string;
+      result: Extract<BundledPlayFileResult, { success: true }>;
+      /** ctx.runPlay(...)/ctx.runPlayAsync(...) string-literal targets, by
+       * owned name. Only names that are ALSO in this push (seenNames) become
+       * dependency-graph edges; anything else falls through to Convex
+       * exactly as before. */
+      runPlayStringTargets: string[];
+    };
+    const bundled: BundledPlay[] = [];
+    const failures: PlayDeployOutcome[] = [];
+    const annotations: CheckRunAnnotation[] = [];
+    const seenNames = new Map<string, string>();
+    const repoRelative = (file: string) =>
+      target.rootDirectory ? `${target.rootDirectory}/${file}` : file;
+    const failPlay = (name: string, file: string, message: string) => {
+      failures.push({ name, file, status: 'failed', error: message });
+      annotations.push(annotationForFailure({ file, message }));
+    };
+
+    for (const file of playFiles) {
+      const entryFile = join(projectRoot, file);
+      const result = await hooks.bundle(entryFile, {
+        sourceIdentityRoot: projectRoot,
+      });
+      const repoRelativeFile = repoRelative(file);
+      if (!result.success) {
+        // Bundler errors embed the absolute entry path under the worker's
+        // temp workDir. Those strings become the customer-visible failure
+        // card and Check Run annotations — rewrite them repo-relative so
+        // the message names the file the customer actually has, and the
+        // worker's filesystem layout never leaks.
+        const message =
+          result.errors
+            .join('\n')
+            .split(`${projectRoot}/`)
+            .join(target.rootDirectory ? `${target.rootDirectory}/` : '')
+            .split(`${repoRoot}/`)
+            .join('') || 'Bundle failed.';
+        failPlay(file, repoRelativeFile, message);
+        continue;
+      }
+      const name = result.playName?.trim() ?? '';
+      if (!name) {
+        failPlay(
+          file,
+          repoRelativeFile,
+          `${file} does not export a definePlay(...) play with a name.`,
+        );
+        continue;
+      }
+      const duplicateOf = seenNames.get(name);
+      if (duplicateOf) {
+        // A name that resolves to two files has no right answer. Deploying
+        // either one silently picks code the author may not have meant, so
+        // fail and name both files: the reader cannot fix a collision they
+        // can only see one half of.
+        failPlay(
+          name,
+          repoRelativeFile,
+          `The play name "${name}" is declared by more than one file: ${repoRelative(duplicateOf)} and ${repoRelativeFile}. A play name must be unique across the repository. Rename one of them or delete it.`,
+        );
+        continue;
+      }
+      seenNames.set(name, file);
+
+      // v1 dependency policy: the deepline SDK and node builtins only. This
+      // is a build-environment policy, not a security boundary — the same
+      // artifact could be produced by any client bundler.
+      const disallowed = (result.artifact.importPolicy?.packages ?? [])
+        .map((pkg) =>
+          typeof pkg === 'string'
+            ? pkg
+            : ((pkg as { name?: string }).name ?? ''),
+        )
+        .filter((pkgName) => pkgName && pkgName !== 'deepline');
+      if (disallowed.length > 0) {
+        failPlay(
+          name,
+          repoRelativeFile,
+          `PLAY_DEPLOY_DEPENDENCY_NOT_ALLOWED: ${file} imports npm package(s) ${disallowed.join(', ')}. Deploy-on-push builds support only the deepline SDK and node builtins.`,
+        );
+        continue;
+      }
+      bundled.push({
+        file: repoRelativeFile,
+        name,
+        result,
+        runPlayStringTargets: await extractRunPlayStringTargets(
+          result.sourceCode,
+        ),
+      });
+    }
+
+    if (failures.length > 0) {
+      return await failWithCheck({
+        title: `${failures.length} play${failures.length === 1 ? '' : 's'} failed to build`,
+        summary: failures
+          .map((failure) => `- \`${failure.file}\`: ${failure.error}`)
+          .join('\n'),
+        annotations,
+        error: `Build failed for ${failures.length} play file(s).`,
+        outcomes: failures,
+      });
+    }
+
+    // Compile manifests in dependency order so same-deploy play imports AND
+    // same-deploy ctx.runPlay(...) string refs both resolve from this
+    // deployment, not stale (or absent) Convex state.
+    const manifestByName = new Map<string, PlayCompilerManifest>();
+    const ordered = topoSortByPlayDependencies(bundled);
+    const validationFailures: PlayDeployOutcome[] = [];
+    for (const play of ordered) {
+      const dependencyNames = new Set([
+        ...(play.result.importedPlayDependencies ?? []).map(
+          (dependency) => dependency.playName,
+        ),
+        ...play.runPlayStringTargets,
+      ]);
+      const dependencies = [...dependencyNames]
+        .map((dependencyName) => manifestByName.get(dependencyName))
+        .filter((entry): entry is PlayCompilerManifest => Boolean(entry));
+      try {
+        const compiled = await client.compileManifest({
+          name: play.name,
+          sourceCode: play.result.sourceCode,
+          sourceFiles: play.result.sourceFiles,
+          artifact: play.result.artifact,
+          ...(dependencies.length
+            ? { importedPlayDependencies: dependencies }
+            : {}),
+        });
+        manifestByName.set(play.name, compiled.compilerManifest);
+      } catch (error) {
+        // A revoked token is not a validation failure of this play.
+        if (revokedFinalStatus(error)) throw error;
+        const body =
+          error instanceof DeployApiError
+            ? (error.body as { errors?: unknown } | null)
+            : null;
+        const messages =
+          body && Array.isArray(body.errors)
+            ? body.errors.map(String)
+            : [error instanceof Error ? error.message : String(error)];
+        const message = messages.join('\n');
+        validationFailures.push({
+          name: play.name,
+          file: play.file,
+          status: 'failed',
+          error: message,
+        });
+        annotations.push(annotationForFailure({ file: play.file, message }));
+      }
+    }
+
+    if (validationFailures.length > 0) {
+      return await failWithCheck({
+        title: `${validationFailures.length} play${validationFailures.length === 1 ? '' : 's'} failed validation`,
+        summary: validationFailures
+          .map((failure) => `- \`${failure.name}\`: ${failure.error}`)
+          .join('\n'),
+        annotations,
+        error: `Validation failed for ${validationFailures.length} play(s).`,
+        outcomes: validationFailures,
+      });
+    }
+
+    // A4: every deployment registers changed plays; only production
+    // promotes. A PR's revisions are runnable pre-merge via
+    // `plays run --revision-id` and never touch the live pointer.
+    //
+    // Production re-checks that this commit is STILL the branch head after
+    // bundling: two pushes 200ms apart can arrive reversed, and promoting
+    // the older tree would silently revert production. (The same guard
+    // already ran before the build; bundling takes long enough that it must
+    // run again here, and a final check runs right before promote because
+    // registration is slower still.)
+    {
+      const superseded = await supersedeIfHeadMoved();
+      if (superseded) return superseded;
+    }
+
+    await setStatus({ status: 'publishing' }).catch(() => undefined);
+    const states = await client.playsState(ordered.map((play) => play.name));
+    const stateByName = new Map<string, DeploymentPlayState>(
+      states.plays.map((play) => [play.name, play]),
+    );
+
+    // A name owned by another ACTIVE target cannot be taken: the control
+    // plane refuses that write. Decide it here, from state already fetched,
+    // so the customer gets a named per-play failure — the same shape as a
+    // duplicate name — instead of a mid-registration server error. A DISABLED
+    // owner has released the name; that takeover is allowed and only warns.
+    //
+    // A directory deploy owns no name: it is a manual publish of each play,
+    // which the control plane allows for a repo-owned play and marks drifted.
+    // It warns (below) instead of refusing.
+    const conflicts: PlayDeployOutcome[] = [];
+    for (const play of ordered) {
+      const owner = stateByName.get(play.name);
+      if (
+        !project ||
+        !owner?.playProjectRepo ||
+        owner.playProjectRepo === project?.repoFullName ||
+        owner.playProjectDisabled
+      ) {
+        continue;
+      }
+      const message = `The play name "${play.name}" is already deployed from ${owner.playProjectRepo}. A play name belongs to one repository at a time. Rename it here, or disable that deployment target first.`;
+      conflicts.push({
+        name: play.name,
+        file: play.file,
+        status: 'failed',
+        error: message,
+      });
+      annotations.push(annotationForFailure({ file: play.file, message }));
+    }
+    if (conflicts.length > 0) {
+      return await failWithCheck({
+        title: `${conflicts.length} play name${conflicts.length === 1 ? '' : 's'} owned by another repository`,
+        summary: conflicts
+          .map((conflict) => `- \`${conflict.file}\`: ${conflict.error}`)
+          .join('\n'),
+        annotations,
+        error: `${conflicts.length} play name(s) are deployed from another repository.`,
+        outcomes: conflicts,
+      });
+    }
+
+    const playByName = new Map(ordered.map((play) => [play.name, play]));
+    const outcomes: PlayDeployOutcome[] = [];
+    const toRegister: Array<{
+      play: (typeof ordered)[number];
+      entry: RegisterArtifactEntry;
+    }> = [];
+    const toPromote: Array<{ name: string; revisionId: string }> = [];
+
+    // A play has one source of truth, and the control plane already refuses a
+    // registration that would take a play from an ACTIVE project
+    // (PLAY_PROJECT_NAME_CONFLICT). What reaches here is the takeover the
+    // system deliberately allows: the previous owner's target is disabled,
+    // which is the supported "moved repos" flow. That move is legitimate and
+    // silent, and a play changing which repository it answers to is exactly
+    // the kind of durable change a reader must be told about.
+    //
+    // Keyed on the repo, not the project row, so a monorepo re-binding its own
+    // play at a new base path is not flagged.
+    const takeoverWarning = (
+      state?: DeploymentPlayState,
+    ): string | undefined => {
+      const owner = state?.playProjectRepo;
+      if (!owner || owner === project?.repoFullName) return undefined;
+      if (!project) {
+        // A directory deploy of a repo-owned play: live now differs from
+        // that repository, and a later push from it will replace this.
+        return `This play is deployed from ${owner}. This directory deploy made a different revision live, so it is marked drifted from ${owner} until that repository deploys again.`;
+      }
+      return `This play was deployed from ${owner} and now deploys from ${project.repoFullName}. Taking it over was allowed because the old deployment target is disabled; re-enabling that target will not give the play back — its deploys will fail on this name instead.`;
+    };
+
+    for (const play of ordered) {
+      const playState = stateByName.get(play.name);
+      // Directory deploys warn only where they changed what is live.
+      const warning = project ? takeoverWarning(playState) : undefined;
+      const artifact = play.result.artifact;
+      // Imported plays are PROXIED by the bundler: the parent's hashes cover
+      // the child's (filePath, playName) but not its content, so a child
+      // change leaves the parent's hashes identical while its server-compiled
+      // contract moves. Importer plays therefore never hash-skip.
+      const importsOtherPlays =
+        (play.result.importedPlayDependencies ?? []).length > 0;
+      const matches = (revision: DeploymentPlayState['liveRevision']) =>
+        !importsOtherPlays && carriesArtifact(revision, artifact);
+      if (matches(playState?.liveRevision ?? null)) {
+        // A live-identical play still needs binding + provenance on its
+        // FIRST deploy from this project — otherwise it never carries
+        // playProjectId and later manual publishes escape the drift flag.
+        // Re-promoting the identical revision is idempotent and stamps both.
+        // Same when driftFromGit is set with matching hashes (a manual
+        // republish of the identical bundle): only the git-synced flip
+        // clears the flag, so skipping as unchanged would leave the play
+        // falsely marked drifted forever.
+        //
+        // A directory deploy binds nothing and never clears drift, so an
+        // identical bundle is simply unchanged: re-promoting it would churn
+        // revision history for no change in what is live.
+        if (
+          deployment.isProduction &&
+          project &&
+          (playState?.playProjectId !== project.id || playState?.driftFromGit)
+        ) {
+          toPromote.push({
+            name: play.name,
+            revisionId: playState!.liveRevision!.revisionId,
+          });
+          continue;
+        }
+        outcomes.push({
+          name: play.name,
+          file: play.file,
+          status: 'unchanged',
+          version: playState?.liveRevision?.version ?? undefined,
+          ...(warning ? { warning } : {}),
+        });
+        continue;
+      }
+      if (matches(playState?.workingRevision ?? null)) {
+        // Registered before (an earlier attempt, another push of this PR, or
+        // a sibling PR); reuse the revision instead of writing a duplicate.
+        if (deployment.isProduction) {
+          toPromote.push({
+            name: play.name,
+            revisionId: playState!.workingRevision!.revisionId,
+          });
+        } else {
+          outcomes.push({
+            name: play.name,
+            file: play.file,
+            status: 'registered',
+            version: playState?.workingRevision?.version ?? undefined,
+            ...(warning ? { warning } : {}),
+          });
+        }
+        continue;
+      }
+      toRegister.push({
+        play,
+        entry: {
+          name: play.name,
+          sourceCode: play.result.sourceCode,
+          sourceFiles: play.result.sourceFiles,
+          ...(play.result.playDescription
+            ? { description: play.result.playDescription }
+            : {}),
+          artifact: play.result.artifact,
+          compilerManifest: manifestByName.get(play.name)!,
+          sourceFilePath: play.file,
+        },
+      });
+    }
+
+    if (toRegister.length > 0) {
+      const registered = await client.registerArtifacts(
+        toRegister.map((item) => item.entry),
+      );
+      registered.forEach((artifact, index) => {
+        const item = toRegister[index];
+        if (!artifact.revisionId) {
+          throw new Error(
+            `Registration returned no revision id for ${item.play.name}.`,
+          );
+        }
+        if (deployment.isProduction) {
+          toPromote.push({
+            name: item.play.name,
+            revisionId: String(artifact.revisionId),
+          });
+        } else {
+          const warning = takeoverWarning(stateByName.get(item.play.name));
+          outcomes.push({
+            name: item.play.name,
+            file: item.play.file,
+            status: 'registered',
+            version:
+              typeof artifact.version === 'number'
+                ? artifact.version
+                : undefined,
+            ...(warning ? { warning } : {}),
+          });
+        }
+      });
+    }
+
+    // PR deployments stop here: registered but never promoted (A4).
+    if (!deployment.isProduction) {
+      const registeredCount = outcomes.filter(
+        (outcome) => outcome.status === 'registered',
+      ).length;
+      // postCheckOrNull throws RetryableDeploymentError for PR builds when
+      // the check cannot be written even with retries: the deployment stays
+      // `building` for the task retry instead of recording `succeeded` with
+      // no validation signal (the deploy token dies with a terminal status).
+      const checkRun = await postCheckOrNull({
+        conclusion: 'success',
+        title: `${ordered.length} play${ordered.length === 1 ? '' : 's'} validated and registered (not deployed)`,
+        ...(annotations.length > 0 ? { annotations } : {}),
+        summary: outcomes
+          .map(
+            (outcome) =>
+              `- \`${outcome.name}\`: ${outcome.status}${outcome.version !== undefined ? ` (v${outcome.version})` : ''}${outcome.warning ? `\n  - :warning: ${outcome.warning}` : ''}`,
+          )
+          .join('\n'),
+      });
+      const result = await finishSucceeded(outcomes, checkRun);
+      console.info('[deploy-worker] PR registration complete', {
+        deploymentId: params.deploymentId,
+        registered: registeredCount,
+        unchanged: outcomes.filter((o) => o.status === 'unchanged').length,
+      });
+      return result;
+    }
+
+    // Third head check, immediately before the flip: registration is the
+    // slowest phase (up to 100 plays, batched), so a push landing during it
+    // would otherwise let this older commit promote over the new head. The
+    // registered-but-unpromoted revisions are harmless — the newer
+    // deployment registers its own.
+    {
+      const superseded = await supersedeIfHeadMoved();
+      if (superseded) return superseded;
+    }
+
+    if (toPromote.length > 0) {
+      try {
+        const promotion = await client.promote(toPromote);
+        promoted = true;
+        for (const outcome of promotion.outcomes) {
+          // Read from the pre-promote snapshot: whatever was live when this
+          // build started is what the new version replaced.
+          const previousVersion =
+            stateByName.get(outcome.name)?.liveRevision?.version ?? null;
+          const warning = takeoverWarning(stateByName.get(outcome.name));
+          outcomes.push({
+            name: outcome.name,
+            file: playByName.get(outcome.name)?.file ?? outcome.name,
+            status: outcome.status === 'promoted' ? 'promoted' : 'failed',
+            version: outcome.version,
+            ...(outcome.status === 'promoted' &&
+            typeof previousVersion === 'number' &&
+            previousVersion !== outcome.version
+              ? { previousVersion }
+              : {}),
+            ...(outcome.status === 'promoted' && warning ? { warning } : {}),
+            ...(outcome.error ? { error: outcome.error } : {}),
+          });
+        }
+      } catch (error) {
+        if (revokedFinalStatus(error)) throw error;
+        const body =
+          error instanceof DeployApiError
+            ? (error.body as {
+                error?: string;
+                outcomes?: Array<{
+                  name: string;
+                  status: string;
+                  error?: string;
+                }>;
+              } | null)
+            : null;
+        const errorText =
+          body?.error ??
+          (error instanceof Error ? error.message : String(error));
+        if (/PLAY_DEPLOYMENT_NOT_ACTIVE/.test(errorText)) {
+          // Unbind/uninstall cancelled this deployment mid-publish; the row
+          // is already terminal, so abort without further writes.
+          console.info('[deploy-worker] cancelled at promote', {
+            deploymentId: params.deploymentId,
+          });
+          return { finalStatus: 'cancelled', outcomes: [] };
+        }
+        if (/PLAY_DEPLOYMENT_STALE/.test(errorText)) {
+          // The atomic flip guard fired: a newer production deployment
+          // exists. Retire this one instead of failing it.
+          console.info('[deploy-worker] superseded at promote', {
+            deploymentId: params.deploymentId,
+          });
+          // Terminal write must persist; a failure retries the task.
+          await setStatus({
+            status: 'superseded',
+            error: errorText.slice(0, 2000),
+            buildSeconds: buildSeconds(),
+          });
+          return { finalStatus: 'superseded', outcomes: [] };
+        }
+        return await failWithCheck({
+          title: 'Deploy failed during promotion',
+          summary: errorText,
+          error: errorText,
+          outcomes: [
+            ...outcomes,
+            ...(body?.outcomes ?? toPromote).map((entry) => ({
+              name: entry.name,
+              file: playByName.get(entry.name)?.file ?? entry.name,
+              status: 'failed' as const,
+              error: ('error' in entry ? entry.error : undefined) ?? errorText,
+            })),
+          ],
+        });
+      }
+    }
+
+    const checkRun = await postCheckOrNull({
+      conclusion: 'success',
+      title: `Deployed ${outcomes.filter((o) => o.status === 'promoted').length} play(s) (${outcomes.filter((o) => o.status === 'unchanged').length} unchanged)`,
+      ...(annotations.length > 0 ? { annotations } : {}),
+      summary: outcomes
+        .map(
+          (outcome) =>
+            `- \`${outcome.name}\`: ${outcome.status}${outcome.warning ? `\n  - :warning: ${outcome.warning}` : ''}`,
+        )
+        .join('\n'),
+    });
+    return await finishSucceeded(outcomes, checkRun);
+  } catch (error) {
+    const revoked = revokedFinalStatus(error);
+    if (revoked) {
+      console.info('[deploy-worker] aborting: deployment revoked mid-build', {
+        deploymentId: params.deploymentId,
+        code: (error as DeployApiError).code,
+      });
+      return { finalStatus: revoked, outcomes: [] };
+    }
+    if (error instanceof RetryableDeploymentError) {
+      // Deliberately no terminal write: the deployment stays `building` for
+      // the task retry (or the stale sweeper as the final backstop).
+      console.warn('[deploy-worker] retryable failure, leaving non-terminal', {
+        deploymentId: params.deploymentId,
+        error: error.message.slice(0, 300),
+      });
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    console.error('[deploy-worker] deployment crashed', {
+      deploymentId: params.deploymentId,
+      error: message.slice(0, 500),
+    });
+    // Never let a check-write failure mask the real error — except when it
+    // is itself the PR retry signal: postCheckOrNull throws
+    // RetryableDeploymentError when a PR's Check Run cannot be written even
+    // after retries, precisely so the deployment stays non-terminal rather
+    // than finalizing with no check. Swallowing it here to reach setStatus
+    // below would finalize that PR deployment anyway, killing the deploy
+    // token before any retry could publish the check it is missing.
+    let checkRunId: number | undefined;
+    try {
+      checkRunId = await postFailureCheck?.(message.slice(0, 2000));
+    } catch (checkError) {
+      const revokedAtCheck = revokedFinalStatus(checkError);
+      if (revokedAtCheck) {
+        return { finalStatus: revokedAtCheck, outcomes: [] };
+      }
+      if (checkError instanceof RetryableDeploymentError) {
+        console.warn(
+          '[deploy-worker] retryable failure, leaving non-terminal',
+          {
+            deploymentId: params.deploymentId,
+            error: checkError.message.slice(0, 300),
+          },
+        );
+        throw checkError;
+      }
+    }
+    await setStatus({
+      status: 'failed',
+      error: message.slice(0, 2000),
+      buildSeconds: buildSeconds(),
+      ...(checkRunId ? { checkRunId } : {}),
+    }).catch(() => undefined);
+    throw error;
+  } finally {
+    await rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+type SortablePlay = {
+  name: string;
+  result: { importedPlayDependencies?: Array<{ playName: string }> };
+  runPlayStringTargets: string[];
+};
+
+/**
+ * Dependencies compile first so same-deploy file imports AND same-deploy
+ * ctx.runPlay(...) string refs both resolve. A dependency name outside this
+ * push (not in `byName`) is simply not an edge here - it still resolves
+ * against Convex when this play compiles, unchanged from today.
+ */
+function topoSortByPlayDependencies<T extends SortablePlay>(plays: T[]): T[] {
+  const byName = new Map(plays.map((play) => [play.name, play]));
+  const visited = new Set<string>();
+  const ordered: T[] = [];
+  const visit = (play: T, stack: Set<string>) => {
+    if (visited.has(play.name)) return;
+    if (stack.has(play.name)) {
+      // A genuine cycle (import or ctx.runPlay name) fails later in
+      // preflight with a clearer, per-play message; do not infinite-loop
+      // here. ctx.runPlay is synchronous inline composition - a real cycle
+      // can never resolve, so detection belongs to the compile step that
+      // already reports an unresolvable reference, not to this sort.
+      return;
+    }
+    stack.add(play.name);
+    const dependencyNames = new Set([
+      ...(play.result.importedPlayDependencies ?? []).map(
+        (dependency) => dependency.playName,
+      ),
+      ...play.runPlayStringTargets,
+    ]);
+    for (const dependencyName of dependencyNames) {
+      const target = byName.get(dependencyName);
+      if (target) visit(target, stack);
+    }
+    stack.delete(play.name);
+    visited.add(play.name);
+    ordered.push(play);
+  };
+  for (const play of plays) visit(play, new Set());
+  return ordered;
+}