From d8f0506d64d4bc924b985fa25c5b68f966ee9b91 Mon Sep 17 00:00:00 2001
From: Devin Foley <devin@paperclip.ing>
Date: Thu, 10 Sep 2026 18:44:45 -0700
Subject: [PATCH] ci: add a source and artifact cloud readiness gate

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 .github/workflows/cloud-readiness.yml | 59 +++++++++++++++++++++++++++
 scripts/cloud-readiness.mjs           | 46 +++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 .github/workflows/cloud-readiness.yml
 create mode 100644 scripts/cloud-readiness.mjs

diff --git a/.github/workflows/cloud-readiness.yml b/.github/workflows/cloud-readiness.yml
new file mode 100644
index 0000000000..7594d48688
--- /dev/null
+++ b/.github/workflows/cloud-readiness.yml
@@ -0,0 +1,59 @@
+name: Cloud readiness
+run-name: Cloud readiness ${{ github.sha }}
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions: {}
+
+# Source verification must start outside the full npm release's queue.
+concurrency:
+  group: cloud-readiness-${{ github.sha }}
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    if: github.repository == 'paperclipai/paperclip' && github.ref == 'refs/heads/master'
+    permissions:
+      contents: read
+    uses: ./.github/workflows/release-verify.yml
+    with:
+      ref: ${{ github.sha }}
+
+  artifacts:
+    if: github.repository == 'paperclipai/paperclip' && github.ref == 'refs/heads/master'
+    name: Wait for exact-source cloud artifacts
+    runs-on: ubuntu-latest
+    timeout-minutes: 35
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 24
+      - name: Wait for verified image and exact-source migrator
+        env:
+          SOURCE_SHA: ${{ github.sha }}
+        run: node scripts/cloud-readiness.mjs "$SOURCE_SHA"
+
+  ready:
+    # Versioned consumer contract. Never add always() or continue-on-error:
+    # failed, cancelled, or skipped prerequisites must not report readiness.
+    name: Cloud deployable v1
+    needs: [verify, artifacts]
+    if: github.repository == 'paperclipai/paperclip' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Record cloud readiness
+        env:
+          SOURCE_SHA: ${{ github.sha }}
+        run: |
+          echo "Cloud deployable v1: $SOURCE_SHA" >> "$GITHUB_STEP_SUMMARY"
+          echo "Source verification passed; the full-SHA image and exact-source migrator are available." >> "$GITHUB_STEP_SUMMARY"
+          echo "Deployment tooling must still resolve and pin the image and migrator and validate migration compatibility." >> "$GITHUB_STEP_SUMMARY"
diff --git a/scripts/cloud-readiness.mjs b/scripts/cloud-readiness.mjs
new file mode 100644
index 0000000000..09ad83a938
--- /dev/null
+++ b/scripts/cloud-readiness.mjs
@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { imageExists, packageExists, versionFor } from "./preview-artifacts.mjs";
+
+/** Read-only availability gate. Deployment still resolves and pins artifacts. */
+export async function waitForCloudArtifacts(sha, {
+  fetchImpl = fetch,
+  now = () => performance.now(),
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  timeoutMs = 30 * 60_000,
+  intervalMs = 20_000,
+  log = console.log,
+} = {}) {
+  const version = versionFor(sha);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || !Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new Error("Cloud readiness requires positive finite timeout and poll interval.");
+  }
+  const deadline = now() + timeoutMs;
+  let previous;
+  let missing = ["image", "shared", "db"];
+  while (now() < deadline) {
+    // Recheck every artifact on the successful poll. Only an explicit 404
+    // means publication is pending; identity errors and upstream outages fail.
+    const results = await Promise.all([
+      imageExists(sha, fetchImpl),
+      packageExists("@paperclipai/shared", sha, fetchImpl),
+      packageExists("@paperclipai/db", sha, fetchImpl),
+    ]);
+    missing = ["image", "shared", "db"].filter((_, index) => !results[index]);
+    if (missing.length === 0) {
+      log(`Cloud artifacts available for ${sha}: verified image and exact-source migrator ${version}.`);
+      return { version: 1, sha, packageVersion: version };
+    }
+    const state = missing.join(", ");
+    if (state !== previous) log(`Waiting for cloud artifacts for ${sha}: ${state}.`);
+    previous = state;
+    const remaining = deadline - now();
+    if (remaining > 0) await sleep(Math.min(intervalMs, remaining));
+  }
+  throw new Error(`Cloud artifacts timed out for ${sha}; missing: ${missing.join(", ")}.`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try { await waitForCloudArtifacts(process.argv[2]); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}