@hyperframes/gcp-cloud-run 0.6.79

package/dist/sdk/index.js

@@ -0,0 +1,390 @@
+// src/sdk/deploySite.ts
+import { mkdtempSync, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Storage } from "@google-cloud/storage";
+import { hashProjectDir } from "@hyperframes/producer/distributed";
+
+// src/gcsTransport.ts
+import { createWriteStream, existsSync, mkdirSync, rmSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import * as tar from "tar";
+function parseGcsUri(uri) {
+  if (!uri.startsWith("gs://")) {
+    throw new Error(`[gcsTransport] expected gs:// URI, got: ${JSON.stringify(uri)}`);
+  }
+  const rest = uri.slice("gs://".length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) {
+    throw new Error(`[gcsTransport] missing key in gs URI: ${JSON.stringify(uri)}`);
+  }
+  const bucket = rest.slice(0, slash);
+  const key = rest.slice(slash + 1);
+  if (!bucket || !key) {
+    throw new Error(`[gcsTransport] empty bucket or key in gs URI: ${JSON.stringify(uri)}`);
+  }
+  return { bucket, key };
+}
+function formatGcsUri(loc) {
+  return `gs://${loc.bucket}/${loc.key}`;
+}
+async function uploadFileToGcs(storage, localPath, uri, contentType) {
+  if (!existsSync(localPath)) {
+    throw new Error(`[gcsTransport] upload source missing: ${localPath}`);
+  }
+  const { bucket, key } = parseGcsUri(uri);
+  await storage.bucket(bucket).upload(localPath, {
+    destination: key,
+    // `resumable: false` (simple upload) is faster for the small-to-medium
+    // objects this adapter moves and avoids the extra round-trip a resumable
+    // session start costs; GCS recommends resumable only past ~8 MB but our
+    // chunks are reliably above that, so let the client pick by default.
+    contentType
+  });
+}
+async function tarDirectory(sourceDir, destTarball) {
+  if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) {
+    throw new Error(`[gcsTransport] tar source must be an existing directory: ${sourceDir}`);
+  }
+  mkdirSync(dirname(destTarball), { recursive: true });
+  await tar.create({ gzip: true, file: destTarball, cwd: sourceDir }, ["."]);
+}
+
+// src/sdk/deploySite.ts
+async function deploySite(opts) {
+  if (!statSync2(opts.projectDir).isDirectory()) {
+    throw new Error(`[deploySite] projectDir is not a directory: ${opts.projectDir}`);
+  }
+  const siteId = opts.siteId ?? hashProjectDir(opts.projectDir);
+  const key = `sites/${siteId}/project.tar.gz`;
+  const projectGcsUri = formatGcsUri({ bucket: opts.bucketName, key });
+  const storage = opts.storage ?? new Storage();
+  const file = storage.bucket(opts.bucketName).file(key);
+  const existing = await headObject(file);
+  if (existing) {
+    return {
+      siteId,
+      bucketName: opts.bucketName,
+      projectGcsUri,
+      bytes: existing.bytes,
+      uploadedAt: existing.lastModified,
+      uploaded: false
+    };
+  }
+  const workdir = mkdtempSync(join(tmpdir(), "hf-deploy-site-"));
+  try {
+    const tarball = join(workdir, "project.tar.gz");
+    await tarDirectory(opts.projectDir, tarball);
+    const size = statSync2(tarball).size;
+    await uploadFileToGcs(storage, tarball, projectGcsUri, "application/gzip");
+    return {
+      siteId,
+      bucketName: opts.bucketName,
+      projectGcsUri,
+      bytes: size,
+      uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      uploaded: true
+    };
+  } finally {
+    rmSync2(workdir, { recursive: true, force: true });
+  }
+}
+async function headObject(file) {
+  const [exists] = await file.exists();
+  if (!exists) return null;
+  const [meta] = await file.getMetadata();
+  const sizeRaw = meta.size;
+  const bytes = typeof sizeRaw === "string" ? Number(sizeRaw) : typeof sizeRaw === "number" ? sizeRaw : 0;
+  return {
+    bytes: Number.isFinite(bytes) ? bytes : 0,
+    lastModified: meta.updated ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/sdk/renderToCloudRun.ts
+import { randomUUID } from "node:crypto";
+
+// src/formatExtension.ts
+var FORMAT_EXTENSIONS = {
+  mp4: ".mp4",
+  mov: ".mov",
+  webm: ".webm",
+  "png-sequence": ""
+};
+function formatExtension(format) {
+  return FORMAT_EXTENSIONS[format];
+}
+
+// src/sdk/validateConfig.ts
+import { InvalidConfigError } from "@hyperframes/producer/distributed";
+import {
+  InvalidConfigError as InvalidConfigError2,
+  validateDistributedRenderConfig,
+  validateVariablesPayload
+} from "@hyperframes/producer/distributed";
+var MAX_WORKFLOWS_INPUT_BYTES = 512 * 1024;
+var LARGE_VARIABLES_DOCS_URL = "https://hyperframes.heygen.com/deploy/templates-on-lambda#working-with-large-variables";
+function validateWorkflowsInputSize(input) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(input);
+  } catch (err) {
+    throw new InvalidConfigError(
+      "config",
+      `Cloud Workflows execution argument is not JSON-serializable: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (serialized === void 0) {
+    throw new InvalidConfigError(
+      "config",
+      "Cloud Workflows execution argument is not JSON-serializable (JSON.stringify returned undefined). Check that all fields, including config.variables, are plain JSON values."
+    );
+  }
+  const byteLength = Buffer.byteLength(serialized, "utf8");
+  if (byteLength > MAX_WORKFLOWS_INPUT_BYTES) {
+    throw new InvalidConfigError(
+      "config",
+      `Cloud Workflows execution argument is ${byteLength} bytes, which exceeds the ${MAX_WORKFLOWS_INPUT_BYTES}-byte (512 KiB) limit. Variables are for typed data (strings, numbers, structured records); media assets (images, audio, video) should be passed as URL references the composition resolves at render time, not inlined as base64. See ${LARGE_VARIABLES_DOCS_URL} for the URL-your-assets convention.`
+    );
+  }
+}
+
+// src/sdk/renderToCloudRun.ts
+async function renderToCloudRun(opts) {
+  validateDistributedRenderConfig(opts.config);
+  if (!opts.bucketName) throw new Error("[renderToCloudRun] bucketName is required");
+  if (!opts.projectId) throw new Error("[renderToCloudRun] projectId is required");
+  if (!opts.location) throw new Error("[renderToCloudRun] location is required");
+  if (!opts.workflowId) throw new Error("[renderToCloudRun] workflowId is required");
+  if (!opts.serviceUrl) throw new Error("[renderToCloudRun] serviceUrl is required");
+  if (!opts.siteHandle && !opts.projectDir) {
+    throw new Error("[renderToCloudRun] either siteHandle or projectDir must be supplied");
+  }
+  const renderId = opts.renderId ?? `hf-render-${randomUUID()}`;
+  if (!/^[A-Za-z0-9._-]+$/.test(renderId) || renderId.includes("..")) {
+    throw new Error(
+      `[renderToCloudRun] renderId must match [A-Za-z0-9._-]+ and not contain "..": ${JSON.stringify(renderId)}`
+    );
+  }
+  const ext = formatExtension(opts.config.format);
+  const outputKey = opts.outputKey ?? `renders/${renderId}/output${ext}`;
+  const planOutputGcsPrefix = formatGcsUri({
+    bucket: opts.bucketName,
+    key: `renders/${renderId}/`
+  });
+  const outputGcsUri = formatGcsUri({ bucket: opts.bucketName, key: outputKey });
+  const site = opts.siteHandle ?? await deploySite({
+    projectDir: opts.projectDir,
+    bucketName: opts.bucketName,
+    storage: opts.storage
+  });
+  const argument = {
+    RenderId: renderId,
+    ProjectGcsUri: site.projectGcsUri,
+    PlanOutputGcsPrefix: planOutputGcsPrefix,
+    OutputGcsUri: outputGcsUri,
+    ServiceUrl: opts.serviceUrl,
+    Config: opts.config
+  };
+  validateWorkflowsInputSize(argument);
+  const executions = opts.executions ?? await defaultExecutionsClient();
+  const parent = executions.workflowPath(opts.projectId, opts.location, opts.workflowId);
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const [execution] = await executions.createExecution({
+    parent,
+    execution: { argument: JSON.stringify(argument) }
+  });
+  if (!execution.name) {
+    throw new Error("[renderToCloudRun] CreateExecution returned no execution name");
+  }
+  return {
+    renderId,
+    executionName: execution.name,
+    bucketName: opts.bucketName,
+    workflowId: opts.workflowId,
+    outputGcsUri,
+    projectGcsUri: site.projectGcsUri,
+    startedAt
+  };
+}
+async function defaultExecutionsClient() {
+  const mod = await import("@google-cloud/workflows");
+  const client = new mod.ExecutionsClient();
+  return client;
+}
+
+// src/sdk/costAccounting.ts
+var CLOUD_RUN_USD_PER_VCPU_SECOND = 24e-6;
+var CLOUD_RUN_USD_PER_GIB_SECOND = 25e-7;
+var CLOUD_RUN_USD_PER_REQUEST = 4e-7;
+var WORKFLOWS_USD_PER_STEP = 1e-5;
+function computeRenderCost(invocations, workflowSteps) {
+  let cloudRunUsd = 0;
+  let anyEstimated = false;
+  for (const inv of invocations) {
+    const seconds = inv.durationMs / 1e3;
+    cloudRunUsd += seconds * inv.vcpu * CLOUD_RUN_USD_PER_VCPU_SECOND;
+    cloudRunUsd += seconds * inv.memoryGib * CLOUD_RUN_USD_PER_GIB_SECOND;
+    cloudRunUsd += CLOUD_RUN_USD_PER_REQUEST;
+    if (inv.estimated) anyEstimated = true;
+  }
+  const workflowsUsd = workflowSteps * WORKFLOWS_USD_PER_STEP;
+  const accruedSoFarUsd = roundUsd(cloudRunUsd + workflowsUsd);
+  return {
+    accruedSoFarUsd,
+    displayCost: formatUsd(accruedSoFarUsd),
+    breakdown: {
+      cloudRunUsd: roundUsd(cloudRunUsd),
+      workflowsUsd: roundUsd(workflowsUsd),
+      gcsEstimate: "not-included",
+      estimated: anyEstimated
+    }
+  };
+}
+function roundUsd(usd) {
+  return Math.round(usd * 1e4) / 1e4;
+}
+function formatUsd(usd) {
+  return `$${usd.toFixed(4)}`;
+}
+
+// src/sdk/getRenderProgress.ts
+var DEFAULT_VCPU = 4;
+var DEFAULT_MEMORY_GIB = 16;
+async function getRenderProgress(opts) {
+  if (!opts.executionName) {
+    throw new Error("[getRenderProgress] executionName is required");
+  }
+  const executions = opts.executions ?? await defaultExecutionsClient2();
+  const vcpu = opts.vcpu ?? DEFAULT_VCPU;
+  const memoryGib = opts.memoryGib ?? DEFAULT_MEMORY_GIB;
+  const [execution] = await executions.getExecution({ name: opts.executionName });
+  const status = mapState(execution.state);
+  const startedAt = toIso(execution.startTime) ?? (/* @__PURE__ */ new Date(0)).toISOString();
+  const endedAt = toIso(execution.endTime);
+  const errors = [];
+  if (execution.error) {
+    errors.push({
+      state: execution.error.context ?? "<execution>",
+      error: extractErrorName(execution.error.payload) ?? "ExecutionError",
+      cause: execution.error.payload ?? ""
+    });
+  }
+  if (status !== "succeeded") {
+    return {
+      status,
+      overallProgress: 0,
+      framesRendered: 0,
+      totalFrames: null,
+      invocationsObserved: 0,
+      costs: computeRenderCost([], 0),
+      outputFile: null,
+      errors,
+      fatalErrorEncountered: status === "failed" || status === "cancelled",
+      startedAt,
+      endedAt
+    };
+  }
+  const acc = parseAccumulated(execution.result);
+  const chunks = acc.Chunks?.filter((c) => c != null) ?? [];
+  const framesRendered = chunks.reduce((sum, c) => sum + (c.FramesEncoded ?? 0), 0);
+  const totalFrames = typeof acc.Plan?.TotalFrames === "number" ? acc.Plan.TotalFrames : null;
+  const invocations = [];
+  const pushInv = (durationMs) => {
+    invocations.push({
+      durationMs: typeof durationMs === "number" ? durationMs : 0,
+      vcpu,
+      memoryGib,
+      estimated: typeof durationMs !== "number"
+    });
+  };
+  if (acc.Plan) pushInv(acc.Plan.DurationMs);
+  for (const c of chunks) pushInv(c.DurationMs);
+  if (acc.Assemble) pushInv(acc.Assemble.DurationMs);
+  const workflowSteps = invocations.length + 4;
+  const costs = computeRenderCost(invocations, workflowSteps);
+  const outputGcsUri = acc.Assemble?.OutputGcsUri;
+  const outputFile = outputGcsUri ? {
+    gcsUri: outputGcsUri,
+    bytes: typeof acc.Assemble?.FileSize === "number" ? acc.Assemble.FileSize : null
+  } : null;
+  return {
+    status,
+    overallProgress: 1,
+    framesRendered,
+    totalFrames,
+    invocationsObserved: invocations.length,
+    costs,
+    outputFile,
+    errors,
+    fatalErrorEncountered: false,
+    startedAt,
+    endedAt
+  };
+}
+function mapState(state) {
+  switch (state) {
+    case "ACTIVE":
+    case "QUEUED":
+      return "running";
+    case "SUCCEEDED":
+      return "succeeded";
+    case "FAILED":
+    case "UNAVAILABLE":
+      return "failed";
+    case "CANCELLED":
+      return "cancelled";
+    default:
+      return "unknown";
+  }
+}
+function parseAccumulated(result) {
+  if (!result) return {};
+  try {
+    const parsed = JSON.parse(result);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch {
+  }
+  return {};
+}
+function extractErrorName(payload) {
+  if (!payload) return void 0;
+  try {
+    const outer = JSON.parse(payload);
+    if (typeof outer.error === "string") return outer.error;
+    if (typeof outer.body === "string") {
+      const inner = JSON.parse(outer.body);
+      if (typeof inner.error === "string") return inner.error;
+    } else if (outer.body && typeof outer.body === "object") {
+      const inner = outer.body;
+      if (typeof inner.error === "string") return inner.error;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function toIso(ts) {
+  if (ts == null) return null;
+  if (typeof ts === "string") return ts;
+  const seconds = ts.seconds == null ? null : Number(ts.seconds);
+  if (seconds == null || !Number.isFinite(seconds)) return null;
+  const ms = seconds * 1e3 + (ts.nanos ?? 0) / 1e6;
+  return new Date(ms).toISOString();
+}
+async function defaultExecutionsClient2() {
+  const mod = await import("@google-cloud/workflows");
+  const client = new mod.ExecutionsClient();
+  return client;
+}
+export {
+  InvalidConfigError2 as InvalidConfigError,
+  MAX_WORKFLOWS_INPUT_BYTES,
+  computeRenderCost,
+  deploySite,
+  getRenderProgress,
+  renderToCloudRun,
+  validateDistributedRenderConfig,
+  validateVariablesPayload,
+  validateWorkflowsInputSize
+};
+//# sourceMappingURL=index.js.map

package/dist/sdk/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/sdk/deploySite.ts", "../../src/gcsTransport.ts", "../../src/sdk/renderToCloudRun.ts", "../../src/formatExtension.ts", "../../src/sdk/validateConfig.ts", "../../src/sdk/costAccounting.ts", "../../src/sdk/getRenderProgress.ts"],
+  "sourcesContent": ["/**\n * `deploySite` \u2014 upload a project directory to GCS once per content hash\n * and return a reusable handle.\n *\n * `renderToCloudRun` calls this implicitly when no `siteHandle` is passed,\n * but exposing it as a standalone verb lets adopters bundle a project ahead\n * of time and reuse the handle across many renders without re-tarring the\n * project tree on every call.\n *\n * The handle is **content-addressed**: `siteId` is derived from a SHA-256\n * over the project files. Two `deploySite` calls on an unchanged tree\n * produce the same `siteId` and short-circuit the upload after a single\n * existence check.\n */\n\nimport { mkdtempSync, rmSync, statSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { Storage } from \"@google-cloud/storage\";\nimport { hashProjectDir } from \"@hyperframes/producer/distributed\";\nimport { formatGcsUri, tarDirectory, uploadFileToGcs } from \"../gcsTransport.js\";\n\n/** Options for {@link deploySite}. */\nexport interface DeploySiteOptions {\n  /** Local project directory containing `index.html` (and any composition assets). */\n  projectDir: string;\n  /** GCS bucket the Terraform module provisioned. */\n  bucketName: string;\n  /**\n   * Override the content-addressed site id. Useful when the caller has a\n   * stable external identifier they want to use (e.g. a git SHA); if unset,\n   * the hash of the project tree picks it.\n   */\n  siteId?: string;\n  /** Injection seam for tests. Production callers leave unset. */\n  storage?: Storage;\n}\n\n/** Stable handle returned by {@link deploySite}. Pass back to {@link renderToCloudRun}. */\nexport interface SiteHandle {\n  /** Content-addressed (or caller-supplied) identifier; stable across re-uploads of the same tree. */\n  siteId: string;\n  /** Bucket the site landed in. Surfaced separately so callers don't have to re-parse `projectGcsUri`. */\n  bucketName: string;\n  /** Full `gs://bucket/sites/<siteId>/project.tar.gz` URI; pass through to `renderToCloudRun`. */\n  projectGcsUri: string;\n  /** Tarball size in bytes; useful for \"did we actually skip the upload?\" assertions. */\n  bytes: number;\n  /** ISO timestamp of the most recent upload OR the existing object the short-circuit found. */\n  uploadedAt: string;\n  /** `false` if the object already existed and we skipped the upload. */\n  uploaded: boolean;\n}\n\n/**\n * Upload `projectDir` to `gs://bucketName/sites/<siteId>/project.tar.gz`.\n *\n * Short-circuits when an object with the same key already exists in the\n * bucket \u2014 `siteId` derives from the project's content hash, so the same\n * bytes produce the same key, and re-uploading would be redundant.\n */\n// fallow-ignore-next-line complexity\nexport async function deploySite(opts: DeploySiteOptions): Promise<SiteHandle> {\n  if (!statSync(opts.projectDir).isDirectory()) {\n    throw new Error(`[deploySite] projectDir is not a directory: ${opts.projectDir}`);\n  }\n\n  const siteId = opts.siteId ?? hashProjectDir(opts.projectDir);\n  const key = `sites/${siteId}/project.tar.gz`;\n  const projectGcsUri = formatGcsUri({ bucket: opts.bucketName, key });\n  const storage = opts.storage ?? new Storage();\n  const file = storage.bucket(opts.bucketName).file(key);\n\n  // Existence short-circuit. Adopters re-rendering the same project on a\n  // tight inner loop (CI smoke, demo flows) save the tar+gzip+upload pass\n  // on every iteration.\n  const existing = await headObject(file);\n  if (existing) {\n    return {\n      siteId,\n      bucketName: opts.bucketName,\n      projectGcsUri,\n      bytes: existing.bytes,\n      uploadedAt: existing.lastModified,\n      uploaded: false,\n    };\n  }\n\n  const workdir = mkdtempSync(join(tmpdir(), \"hf-deploy-site-\"));\n  try {\n    const tarball = join(workdir, \"project.tar.gz\");\n    await tarDirectory(opts.projectDir, tarball);\n    const size = statSync(tarball).size;\n    await uploadFileToGcs(storage, tarball, projectGcsUri, \"application/gzip\");\n    return {\n      siteId,\n      bucketName: opts.bucketName,\n      projectGcsUri,\n      bytes: size,\n      uploadedAt: new Date().toISOString(),\n      uploaded: true,\n    };\n  } finally {\n    rmSync(workdir, { recursive: true, force: true });\n  }\n}\n\n/**\n * Narrow surface of the `@google-cloud/storage` `File` this module uses \u2014\n * lets the test double implement just `exists()` + `getMetadata()` without\n * pulling the full client type.\n */\ninterface FileLike {\n  exists(): Promise<[boolean, ...unknown[]]>;\n  getMetadata(): Promise<[{ size?: string | number; updated?: string }, ...unknown[]]>;\n}\n\n// fallow-ignore-next-line complexity\nasync function headObject(file: FileLike): Promise<{ bytes: number; lastModified: string } | null> {\n  const [exists] = await file.exists();\n  if (!exists) return null;\n  const [meta] = await file.getMetadata();\n  const sizeRaw = meta.size;\n  const bytes =\n    typeof sizeRaw === \"string\" ? Number(sizeRaw) : typeof sizeRaw === \"number\" ? sizeRaw : 0;\n  return {\n    bytes: Number.isFinite(bytes) ? bytes : 0,\n    lastModified: meta.updated ?? new Date().toISOString(),\n  };\n}\n", "/**\n * Thin GCS transport for the Cloud Run handler.\n *\n * The OSS distributed primitives are pure functions over local file paths;\n * the handler bridges GCS \u2194 the container's writable `/tmp` filesystem on\n * each request. Functions here are intentionally narrow: parse a URI,\n * download an object to a local path, upload a path, tar-pack a planDir,\n * tar-extract a planDir back out.\n *\n * Tar (not zip) for planDir transit:\n *   - planDirs contain symlinks (the extract stage materializes them but\n *     the compiled/ subtree may include linked assets); tar preserves them,\n *     zip does not.\n *   - We use the `tar` npm package (pure JS over `node:zlib`) so the\n *     archive format doesn't depend on a system `tar`/`unzip` being present\n *     in the container image.\n *\n * Apart from the `gs://` scheme and the `@google-cloud/storage` client this\n * is the same shape as `@hyperframes/aws-lambda`'s `s3Transport.ts`.\n */\n\nimport { createWriteStream, existsSync, mkdirSync, rmSync, statSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { pipeline } from \"node:stream/promises\";\nimport type { Storage } from \"@google-cloud/storage\";\nimport * as tar from \"tar\";\n\n/** Parsed `gs://bucket/key` URI. */\nexport interface GcsLocation {\n  bucket: string;\n  key: string;\n}\n\n/** Parse `gs://bucket/key/path` \u2192 `{ bucket, key }`. Throws on malformed input. */\n// fallow-ignore-next-line complexity\nexport function parseGcsUri(uri: string): GcsLocation {\n  if (!uri.startsWith(\"gs://\")) {\n    throw new Error(`[gcsTransport] expected gs:// URI, got: ${JSON.stringify(uri)}`);\n  }\n  const rest = uri.slice(\"gs://\".length);\n  const slash = rest.indexOf(\"/\");\n  if (slash === -1) {\n    throw new Error(`[gcsTransport] missing key in gs URI: ${JSON.stringify(uri)}`);\n  }\n  const bucket = rest.slice(0, slash);\n  const key = rest.slice(slash + 1);\n  if (!bucket || !key) {\n    throw new Error(`[gcsTransport] empty bucket or key in gs URI: ${JSON.stringify(uri)}`);\n  }\n  return { bucket, key };\n}\n\n/** Build `gs://bucket/key` from a location. */\nexport function formatGcsUri(loc: GcsLocation): string {\n  return `gs://${loc.bucket}/${loc.key}`;\n}\n\n/** Stream a GCS object to a local file path. */\nexport async function downloadGcsObjectToFile(\n  storage: Storage,\n  uri: string,\n  destPath: string,\n): Promise<void> {\n  const { bucket, key } = parseGcsUri(uri);\n  mkdirSync(dirname(destPath), { recursive: true });\n  const file = storage.bucket(bucket).file(key);\n  // `createReadStream` streams the object body; piping into a write stream\n  // keeps memory flat for large plan tarballs / chunk files rather than\n  // buffering the whole object the way `file.download()` would.\n  await pipeline(file.createReadStream(), createWriteStream(destPath));\n}\n\n/**\n * Upload a local file's contents to a GCS URI using a resumable upload.\n * GCS objects have no practical size ceiling for the artifacts this adapter\n * handles (plan tarballs \u2264 2 GB, chunks \u2264 a few hundred MB), so a single\n * upload call works for every case.\n */\nexport async function uploadFileToGcs(\n  storage: Storage,\n  localPath: string,\n  uri: string,\n  contentType?: string,\n): Promise<void> {\n  if (!existsSync(localPath)) {\n    throw new Error(`[gcsTransport] upload source missing: ${localPath}`);\n  }\n  const { bucket, key } = parseGcsUri(uri);\n  await storage.bucket(bucket).upload(localPath, {\n    destination: key,\n    // `resumable: false` (simple upload) is faster for the small-to-medium\n    // objects this adapter moves and avoids the extra round-trip a resumable\n    // session start costs; GCS recommends resumable only past ~8 MB but our\n    // chunks are reliably above that, so let the client pick by default.\n    contentType,\n  });\n}\n\n/**\n * Pack a directory into a `.tar.gz` at `destTarball`. Uses the `tar` npm\n * package (pure JS over `node:zlib`) rather than spawning a system tar\n * binary so the archive format is independent of the container's userland.\n */\nexport async function tarDirectory(sourceDir: string, destTarball: string): Promise<void> {\n  if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) {\n    throw new Error(`[gcsTransport] tar source must be an existing directory: ${sourceDir}`);\n  }\n  mkdirSync(dirname(destTarball), { recursive: true });\n  await tar.create({ gzip: true, file: destTarball, cwd: sourceDir }, [\".\"]);\n}\n\n/**\n * Extract a `.tar.gz` produced by {@link tarDirectory} into `destDir`.\n * The directory is created (or cleared) before extraction so a retried\n * request doesn't observe stale files from a prior run on the same warm\n * container instance.\n */\nexport async function untarDirectory(tarballPath: string, destDir: string): Promise<void> {\n  if (!existsSync(tarballPath)) {\n    throw new Error(`[gcsTransport] tarball missing: ${tarballPath}`);\n  }\n  // Wipe target so a warm container instance's prior planDir doesn't bleed\n  // into the new request. Cloud Run re-uses the instance filesystem across\n  // requests served by the same instance.\n  if (existsSync(destDir)) {\n    rmSync(destDir, { recursive: true, force: true });\n  }\n  mkdirSync(destDir, { recursive: true });\n  await tar.extract({ file: tarballPath, cwd: destDir });\n}\n", "/**\n * `renderToCloudRun` \u2014 start a distributed render against an already-deployed\n * Cloud Run service + Cloud Workflows definition and return a handle the\n * caller can poll with {@link getRenderProgress}.\n *\n * The function does *not* wait for the render to finish. Cloud Workflows\n * executions can run for hours; blocking the caller's process on the\n * execution is the wrong default. The returned `RenderHandle` carries\n * everything the progress / cost / download paths need.\n *\n * Wire order:\n *   1. Validate config (typed throw before any GCP call).\n *   2. `deploySite` if no `siteHandle` was provided.\n *   3. `CreateExecution` against the workflow with the argument shape the\n *      `packages/gcp-cloud-run/terraform/workflow.yaml` definition expects.\n *   4. Return handle. The GCS `outputKey` is deterministic from the\n *      client-generated `renderId` so the caller can predict the final\n *      object URL before the (server-assigned) execution id exists.\n *\n * Unlike Step Functions, Cloud Workflows assigns the execution id\n * server-side, so we cannot use it as the GCS prefix. We mint a `renderId`\n * (uuid) client-side, use it for every GCS path, and pass it into the\n * workflow argument; the server-assigned execution resource name is tracked\n * separately for polling.\n */\n\nimport { randomUUID } from \"node:crypto\";\nimport type { Storage } from \"@google-cloud/storage\";\nimport type { SerializableDistributedRenderConfig } from \"../events.js\";\nimport { formatExtension } from \"../formatExtension.js\";\nimport { formatGcsUri } from \"../gcsTransport.js\";\nimport { deploySite, type SiteHandle } from \"./deploySite.js\";\nimport { validateDistributedRenderConfig, validateWorkflowsInputSize } from \"./validateConfig.js\";\n\n/**\n * Minimal surface of `@google-cloud/workflows`' `ExecutionsClient` that\n * this module needs. The real client satisfies this; tests inject a double.\n */\nexport interface ExecutionsClientLike {\n  workflowPath(project: string, location: string, workflow: string): string;\n  createExecution(req: {\n    parent: string;\n    execution: { argument: string };\n  }): Promise<[{ name?: string | null; state?: string | null }, ...unknown[]]>;\n}\n\n/** Options for {@link renderToCloudRun}. */\nexport interface RenderToCloudRunOptions {\n  /** Local project directory. Required when `siteHandle` is not supplied. */\n  projectDir?: string;\n  /** Re-use an existing `deploySite` upload (skips tar+GCS upload). */\n  siteHandle?: SiteHandle;\n  /** Validated `SerializableDistributedRenderConfig` (no logger / abortSignal). */\n  config: SerializableDistributedRenderConfig;\n  /** GCS bucket from the Terraform output (`render_bucket_name`). */\n  bucketName: string;\n  /** GCP project id hosting the workflow. */\n  projectId: string;\n  /** Workflow location, e.g. `us-central1`. */\n  location: string;\n  /** Workflow id from the Terraform output (`workflow_name`). */\n  workflowId: string;\n  /**\n   * HTTPS URL of the deployed Cloud Run render service (Terraform output\n   * `service_url`). The workflow POSTs every step (plan / renderChunk /\n   * assemble) to this URL; passed as an execution argument so the workflow\n   * definition stays free of hard-coded URLs.\n   */\n  serviceUrl: string;\n  /**\n   * Final output GCS key. Defaults to `renders/<renderId>/output.<ext>`\n   * where `<ext>` is derived from `config.format`.\n   */\n  outputKey?: string;\n  /**\n   * Client-generated render id. Defaults to `hf-render-<uuid>`. Used as the\n   * GCS key prefix and echoed into the workflow argument; not the same as\n   * the server-assigned execution id.\n   */\n  renderId?: string;\n  /** Test injection seam \u2014 production callers leave unset. */\n  executions?: ExecutionsClientLike;\n  /** Test injection seam \u2014 propagated to `deploySite` when applicable. */\n  storage?: Storage;\n}\n\n/** Stable identifier + every URL/name the caller needs to follow the render. */\nexport interface RenderHandle {\n  /** Client-generated render id; the GCS prefix everything lands under. */\n  renderId: string;\n  /** Server-assigned execution resource name; pass to {@link getRenderProgress}. */\n  executionName: string;\n  bucketName: string;\n  workflowId: string;\n  outputGcsUri: string;\n  projectGcsUri: string;\n  startedAt: string;\n}\n\n// fallow-ignore-next-line complexity\nexport async function renderToCloudRun(opts: RenderToCloudRunOptions): Promise<RenderHandle> {\n  validateDistributedRenderConfig(opts.config);\n\n  if (!opts.bucketName) throw new Error(\"[renderToCloudRun] bucketName is required\");\n  if (!opts.projectId) throw new Error(\"[renderToCloudRun] projectId is required\");\n  if (!opts.location) throw new Error(\"[renderToCloudRun] location is required\");\n  if (!opts.workflowId) throw new Error(\"[renderToCloudRun] workflowId is required\");\n  if (!opts.serviceUrl) throw new Error(\"[renderToCloudRun] serviceUrl is required\");\n  if (!opts.siteHandle && !opts.projectDir) {\n    throw new Error(\"[renderToCloudRun] either siteHandle or projectDir must be supplied\");\n  }\n\n  const renderId = opts.renderId ?? `hf-render-${randomUUID()}`;\n  // `renderId` is interpolated directly into GCS object keys\n  // (`renders/<renderId>/\u2026`). Reject anything that could escape that prefix\n  // or build a malformed key \u2014 `..`, slashes, or other path metacharacters \u2014\n  // so a caller-supplied id can't collide with or overwrite another render's\n  // artifacts elsewhere in the bucket.\n  if (!/^[A-Za-z0-9._-]+$/.test(renderId) || renderId.includes(\"..\")) {\n    throw new Error(\n      `[renderToCloudRun] renderId must match [A-Za-z0-9._-]+ and not contain \"..\": ${JSON.stringify(renderId)}`,\n    );\n  }\n  const ext = formatExtension(opts.config.format);\n  const outputKey = opts.outputKey ?? `renders/${renderId}/output${ext}`;\n  const planOutputGcsPrefix = formatGcsUri({\n    bucket: opts.bucketName,\n    key: `renders/${renderId}/`,\n  });\n  const outputGcsUri = formatGcsUri({ bucket: opts.bucketName, key: outputKey });\n\n  const site =\n    opts.siteHandle ??\n    (await deploySite({\n      projectDir: opts.projectDir as string,\n      bucketName: opts.bucketName,\n      storage: opts.storage,\n    }));\n\n  const argument = {\n    RenderId: renderId,\n    ProjectGcsUri: site.projectGcsUri,\n    PlanOutputGcsPrefix: planOutputGcsPrefix,\n    OutputGcsUri: outputGcsUri,\n    ServiceUrl: opts.serviceUrl,\n    Config: opts.config,\n  };\n\n  // Reject oversize input client-side. Cloud Workflows caps the execution\n  // argument at 512 KiB; without this check, input bloat (typically from\n  // `config.variables` containing inlined media) surfaces as an opaque\n  // server-side error after the execution starts, far from the caller's\n  // stack frame.\n  validateWorkflowsInputSize(argument);\n\n  const executions = opts.executions ?? (await defaultExecutionsClient());\n  const parent = executions.workflowPath(opts.projectId, opts.location, opts.workflowId);\n  const startedAt = new Date().toISOString();\n  const [execution] = await executions.createExecution({\n    parent,\n    execution: { argument: JSON.stringify(argument) },\n  });\n\n  if (!execution.name) {\n    throw new Error(\"[renderToCloudRun] CreateExecution returned no execution name\");\n  }\n\n  return {\n    renderId,\n    executionName: execution.name,\n    bucketName: opts.bucketName,\n    workflowId: opts.workflowId,\n    outputGcsUri,\n    projectGcsUri: site.projectGcsUri,\n    startedAt,\n  };\n}\n\n/**\n * Lazily import the real `@google-cloud/workflows` ExecutionsClient. Dynamic\n * so SDK consumers that only call `validateDistributedRenderConfig` (or\n * inject their own client) don't pay the import cost.\n */\nasync function defaultExecutionsClient(): Promise<ExecutionsClientLike> {\n  const mod = await import(\"@google-cloud/workflows\");\n  const client = new mod.ExecutionsClient();\n  return client as unknown as ExecutionsClientLike;\n}\n", "/**\n * Map a distributed `format` to the file extension the assembled output\n * should carry on disk + in GCS. Shared by `src/server.ts` (chunk +\n * assemble output paths) and `src/sdk/renderToCloudRun.ts` (final\n * output key construction) so the two sides agree on what an mp4\n * looks like vs a png-sequence.\n */\n\nimport type { DistributedFormat } from \"@hyperframes/producer/distributed\";\n\nexport type { DistributedFormat } from \"@hyperframes/producer/distributed\";\n\n// Closed-enum lookup table. TS enforces exhaustiveness via the\n// `Record<DistributedFormat, string>` annotation \u2014 adding a format to\n// `DistributedFormat` without adding the matching key here fails to\n// typecheck, which is the same exhaustiveness guarantee a switch +\n// `_exhaustive: never` arm provides but at lower complexity.\nconst FORMAT_EXTENSIONS: Record<DistributedFormat, string> = {\n  mp4: \".mp4\",\n  mov: \".mov\",\n  webm: \".webm\",\n  \"png-sequence\": \"\",\n};\n\nexport function formatExtension(format: DistributedFormat): string {\n  return FORMAT_EXTENSIONS[format];\n}\n", "/**\n * Client-side validation for the Cloud Run adapter.\n *\n * The cloud-agnostic config-shape validation (`validateDistributedRenderConfig`,\n * `validateVariablesPayload`, `InvalidConfigError`) lives in\n * `@hyperframes/producer/distributed` and is shared with the other adapters.\n * This module re-exports those and adds the one piece that is specific to\n * Cloud Workflows: the 512 KiB execution-argument size cap.\n */\n\nimport { InvalidConfigError } from \"@hyperframes/producer/distributed\";\n\nexport {\n  InvalidConfigError,\n  validateDistributedRenderConfig,\n  validateVariablesPayload,\n} from \"@hyperframes/producer/distributed\";\n\n/**\n * Hard cap on Cloud Workflows execution arguments \u2014 512 KiB per the Workflows\n * quotas page (maximum size of arguments passed when an execution starts).\n * The cap is on the entire serialized argument, not just the variables,\n * because users hit it at the wire boundary regardless of which field caused\n * the bloat.\n *\n * Specific to Cloud Workflows. Other runtimes (Lambda + Step Functions,\n * Temporal) have different caps; don't reuse this constant for those without\n * confirming the limit.\n */\nexport const MAX_WORKFLOWS_INPUT_BYTES = 512 * 1024;\n\n/** Pointer to the docs section that explains the URL-your-assets convention. */\nconst LARGE_VARIABLES_DOCS_URL =\n  \"https://hyperframes.heygen.com/deploy/templates-on-lambda#working-with-large-variables\";\n\n/**\n * Validate that the serialized Cloud Workflows execution argument fits inside\n * the 512 KiB cap. Measured in UTF-8 bytes (the format the API uses on the\n * wire) \u2014 JS strings count UTF-16 code units, which under-reports for any\n * multi-byte character.\n *\n * Throws {@link InvalidConfigError} with a clear message naming the actual\n * byte count, the cap, and a pointer to the \"working with large variables\"\n * docs section, so users hit the limit at the SDK boundary with actionable\n * guidance instead of as an opaque argument-too-large error after the\n * execution starts.\n */\n// fallow-ignore-next-line complexity\nexport function validateWorkflowsInputSize(input: unknown): void {\n  let serialized: string | undefined;\n  try {\n    serialized = JSON.stringify(input);\n  } catch (err) {\n    throw new InvalidConfigError(\n      \"config\",\n      `Cloud Workflows execution argument is not JSON-serializable: ${err instanceof Error ? err.message : String(err)}`,\n    );\n  }\n  if (serialized === undefined) {\n    throw new InvalidConfigError(\n      \"config\",\n      \"Cloud Workflows execution argument is not JSON-serializable (JSON.stringify returned undefined). \" +\n        \"Check that all fields, including config.variables, are plain JSON values.\",\n    );\n  }\n  const byteLength = Buffer.byteLength(serialized, \"utf8\");\n  if (byteLength > MAX_WORKFLOWS_INPUT_BYTES) {\n    throw new InvalidConfigError(\n      \"config\",\n      `Cloud Workflows execution argument is ${byteLength} bytes, which exceeds the ` +\n        `${MAX_WORKFLOWS_INPUT_BYTES}-byte (512 KiB) limit. Variables are for typed data ` +\n        `(strings, numbers, structured records); media assets (images, audio, video) should ` +\n        `be passed as URL references the composition resolves at render time, not inlined as ` +\n        `base64. See ${LARGE_VARIABLES_DOCS_URL} for the URL-your-assets convention.`,\n    );\n  }\n}\n", "/**\n * Per-render cost accounting for {@link getRenderProgress}.\n *\n * Google bills the render service two ways:\n *\n *  - **Cloud Run** by **vCPU-seconds** and **GiB-seconds** of request\n *    processing time, plus a flat per-request charge. Each handler\n *    invocation returns its own `DurationMs` in the result body, so the\n *    progress reader can recover billed time per step without a separate\n *    Cloud Monitoring query \u2014 multiply by the service's configured vCPU /\n *    memory to get the resource-seconds.\n *  - **Cloud Workflows** by **steps executed**. The orchestration is a\n *    fixed shape (Plan + N\u00D7RenderChunk + Assemble + a handful of control\n *    steps), so the step count scales with chunk count.\n *\n * The math is documented inline so the constants stay close to the pricing\n * source they came from. Cost is **best-effort**: GCP pricing varies by\n * region + committed-use discounts; we use on-demand `us-central1` (Tier 1)\n * rates as of 2026-06 and label the result `displayCost` so callers see the\n * dollar value but downstream automation can also read the raw number.\n */\n\n/** Cloud Run request-based billing, us-central1 Tier 1: USD per vCPU-second. */\nconst CLOUD_RUN_USD_PER_VCPU_SECOND = 0.000024;\n/** Cloud Run request-based billing, us-central1 Tier 1: USD per GiB-second. */\nconst CLOUD_RUN_USD_PER_GIB_SECOND = 0.0000025;\n/** Cloud Run: USD per request ($0.40 per million). */\nconst CLOUD_RUN_USD_PER_REQUEST = 0.0000004;\n/** Cloud Workflows: USD per internal step ($0.01 per 1,000, after a free tier). */\nconst WORKFLOWS_USD_PER_STEP = 0.00001;\n\n/** Per-invocation billed slice the cost calc cares about. */\nexport interface BilledCloudRunInvocation {\n  /** Wall-clock the handler reported via `DurationMs` in its result body. */\n  durationMs: number;\n  /** vCPU the Cloud Run service was configured with at invocation time. */\n  vcpu: number;\n  /** Memory in GiB the Cloud Run service was configured with. */\n  memoryGib: number;\n  /** `true` if the duration was inferred (step result missing) rather than read from the handler payload. */\n  estimated: boolean;\n}\n\n/**\n * Result of {@link computeRenderCost}.\n *\n * NOTE: `displayCost` / `accruedSoFarUsd` cover Cloud Run compute + Cloud\n * Workflows steps only. They EXCLUDE GCS storage + network egress for the\n * plan tarball (which can be ~100 MB), chunk artifacts, and the final output\n * \u2014 see `breakdown.gcsEstimate`. Treat the figure as a compute-cost floor,\n * not the authoritative total bill.\n */\nexport interface RenderCost {\n  /** USD accrued to date (Cloud Run + Workflows only; excludes GCS \u2014 see note above). */\n  accruedSoFarUsd: number;\n  /** Human-readable USD string, e.g. `\"$0.0214\"`. Excludes GCS storage/egress. */\n  displayCost: string;\n  breakdown: {\n    cloudRunUsd: number;\n    workflowsUsd: number;\n    /** GCS transfer + storage cost varies by tier; we don't try to compute it here. */\n    gcsEstimate: \"not-included\";\n    /** `true` if any invocation fell back to estimated billing. */\n    estimated: boolean;\n  };\n}\n\n/**\n * Sum Cloud Run vCPU-seconds + GiB-seconds + per-request charges and Cloud\n * Workflows steps into an aggregate USD figure.\n *\n * `workflowSteps` is the count of Workflows steps executed so far \u2014 Plan\n * (1) + RenderChunk (chunkCount) + Assemble (1) + the control steps\n * (BuildChunkList, AssertChunkCount, \u2026). Pass the count the progress reader\n * derived from the execution; a rough constant overhead is fine since the\n * step charge is a rounding error next to Cloud Run compute.\n */\nexport function computeRenderCost(\n  invocations: BilledCloudRunInvocation[],\n  workflowSteps: number,\n): RenderCost {\n  let cloudRunUsd = 0;\n  let anyEstimated = false;\n  for (const inv of invocations) {\n    const seconds = inv.durationMs / 1000;\n    cloudRunUsd += seconds * inv.vcpu * CLOUD_RUN_USD_PER_VCPU_SECOND;\n    cloudRunUsd += seconds * inv.memoryGib * CLOUD_RUN_USD_PER_GIB_SECOND;\n    cloudRunUsd += CLOUD_RUN_USD_PER_REQUEST;\n    if (inv.estimated) anyEstimated = true;\n  }\n  const workflowsUsd = workflowSteps * WORKFLOWS_USD_PER_STEP;\n  const accruedSoFarUsd = roundUsd(cloudRunUsd + workflowsUsd);\n  return {\n    accruedSoFarUsd,\n    displayCost: formatUsd(accruedSoFarUsd),\n    breakdown: {\n      cloudRunUsd: roundUsd(cloudRunUsd),\n      workflowsUsd: roundUsd(workflowsUsd),\n      gcsEstimate: \"not-included\",\n      estimated: anyEstimated,\n    },\n  };\n}\n\nfunction roundUsd(usd: number): number {\n  // Four decimal places \u2014 enough resolution for per-chunk granularity.\n  // Anything finer is noise vs GCP's own rounding.\n  return Math.round(usd * 10_000) / 10_000;\n}\n\nfunction formatUsd(usd: number): string {\n  return `$${usd.toFixed(4)}`;\n}\n", "/**\n * `getRenderProgress` \u2014 read-only progress + cost snapshot for a single\n * render started by {@link renderToCloudRun}.\n *\n * Pulls one `GetExecution` per call. Cloud Workflows does not surface\n * per-step payloads through the basic Executions API the way Step Functions\n * exposes its history, so this reader takes a different tack than the AWS\n * adapter: the workflow definition **accumulates** each step's result body\n * (Plan + every RenderChunk + Assemble) and returns them as one structured\n * object. On success we parse that object for frame totals, the output\n * file, and per-step `DurationMs` (which the handler stamps into every\n * result), then compute cost against the service's configured vCPU/memory.\n *\n * Progress is therefore coarse while the execution is ACTIVE (we report\n * `running` with `overallProgress = 0`) and exact once it SUCCEEDS\n * (`overallProgress = 1`, real frame + cost numbers). Mid-flight per-chunk\n * progress would require the Workflows step-entries API; that's a tracked\n * follow-up, not part of the first version.\n */\n\nimport {\n  type BilledCloudRunInvocation,\n  computeRenderCost,\n  type RenderCost,\n} from \"./costAccounting.js\";\n\n/** Normalised render status. Maps from Cloud Workflows execution states. */\nexport type RenderStatus = \"running\" | \"succeeded\" | \"failed\" | \"cancelled\" | \"unknown\";\n\n/** One error surfaced by the execution. */\nexport interface RenderError {\n  /** Step the failure surfaced in, when recoverable from the error context; else `<execution>`. */\n  state: string;\n  /** Error class / type. */\n  error: string;\n  /** Cause string (often a stringified JSON payload from the handler). */\n  cause: string;\n}\n\n/** Snapshot of a single render's progress + cost + errors at one point in time. */\nexport interface RenderProgress {\n  status: RenderStatus;\n  /** `[0, 1]`; coarse while running, exact on success. */\n  overallProgress: number;\n  framesRendered: number;\n  /** `null` until the execution succeeds and the accumulated plan result is read. */\n  totalFrames: number | null;\n  /** Cloud Run invocations the workflow scheduled (Plan + chunks + Assemble), when known. */\n  invocationsObserved: number;\n  costs: RenderCost;\n  /** Final output object if Assemble succeeded; `null` otherwise. */\n  outputFile: { gcsUri: string; bytes: number | null } | null;\n  errors: RenderError[];\n  /** `true` once the execution has terminated in a non-success state. */\n  fatalErrorEncountered: boolean;\n  startedAt: string;\n  endedAt: string | null;\n}\n\n/** Protobuf Timestamp shape the gapic client returns for start/end times. */\ninterface ProtoTimestamp {\n  seconds?: number | string | null;\n  nanos?: number | null;\n}\n\n/** Subset of a Cloud Workflows Execution this reader consumes. */\nexport interface ExecutionRecord {\n  name?: string | null;\n  state?: string | null;\n  result?: string | null;\n  error?: { payload?: string | null; context?: string | null } | null;\n  startTime?: ProtoTimestamp | string | null;\n  endTime?: ProtoTimestamp | string | null;\n}\n\n/** Minimal surface of `@google-cloud/workflows`' `ExecutionsClient` for reads. */\nexport interface ExecutionsGetClientLike {\n  getExecution(req: { name: string }): Promise<[ExecutionRecord, ...unknown[]]>;\n}\n\n/** Options for {@link getRenderProgress}. */\nexport interface GetRenderProgressOptions {\n  /** Server-assigned execution resource name from a {@link renderToCloudRun} call. */\n  executionName: string;\n  /** vCPU the Cloud Run service is configured with (for cost). Default 4. */\n  vcpu?: number;\n  /** Memory in GiB the Cloud Run service is configured with (for cost). Default 16. */\n  memoryGib?: number;\n  /** Test injection seam \u2014 production callers leave unset. */\n  executions?: ExecutionsGetClientLike;\n}\n\nconst DEFAULT_VCPU = 4;\nconst DEFAULT_MEMORY_GIB = 16;\n\n/** Result body the handler returns for each action; the workflow accumulates these. */\ninterface AccumulatedResult {\n  Plan?: { TotalFrames?: number; DurationMs?: number } | null;\n  Chunks?: Array<{ FramesEncoded?: number; DurationMs?: number } | null> | null;\n  Assemble?: {\n    OutputGcsUri?: string;\n    FileSize?: number;\n    FramesEncoded?: number;\n    DurationMs?: number;\n  } | null;\n}\n\n/** Pull a current progress snapshot for one render. */\n// fallow-ignore-next-line complexity\nexport async function getRenderProgress(opts: GetRenderProgressOptions): Promise<RenderProgress> {\n  if (!opts.executionName) {\n    throw new Error(\"[getRenderProgress] executionName is required\");\n  }\n  const executions = opts.executions ?? (await defaultExecutionsClient());\n  const vcpu = opts.vcpu ?? DEFAULT_VCPU;\n  const memoryGib = opts.memoryGib ?? DEFAULT_MEMORY_GIB;\n\n  const [execution] = await executions.getExecution({ name: opts.executionName });\n  const status = mapState(execution.state);\n  const startedAt = toIso(execution.startTime) ?? new Date(0).toISOString();\n  const endedAt = toIso(execution.endTime);\n\n  const errors: RenderError[] = [];\n  if (execution.error) {\n    errors.push({\n      state: execution.error.context ?? \"<execution>\",\n      error: extractErrorName(execution.error.payload) ?? \"ExecutionError\",\n      cause: execution.error.payload ?? \"\",\n    });\n  }\n\n  // Default snapshot: running / unknown \u2014 no frame or cost data until the\n  // accumulated result is available on success.\n  if (status !== \"succeeded\") {\n    return {\n      status,\n      overallProgress: 0,\n      framesRendered: 0,\n      totalFrames: null,\n      invocationsObserved: 0,\n      costs: computeRenderCost([], 0),\n      outputFile: null,\n      errors,\n      fatalErrorEncountered: status === \"failed\" || status === \"cancelled\",\n      startedAt,\n      endedAt,\n    };\n  }\n\n  const acc = parseAccumulated(execution.result);\n  const chunks = acc.Chunks?.filter((c): c is NonNullable<typeof c> => c != null) ?? [];\n  const framesRendered = chunks.reduce((sum, c) => sum + (c.FramesEncoded ?? 0), 0);\n  const totalFrames = typeof acc.Plan?.TotalFrames === \"number\" ? acc.Plan.TotalFrames : null;\n\n  const invocations: BilledCloudRunInvocation[] = [];\n  const pushInv = (durationMs: number | undefined): void => {\n    invocations.push({\n      durationMs: typeof durationMs === \"number\" ? durationMs : 0,\n      vcpu,\n      memoryGib,\n      estimated: typeof durationMs !== \"number\",\n    });\n  };\n  if (acc.Plan) pushInv(acc.Plan.DurationMs);\n  for (const c of chunks) pushInv(c.DurationMs);\n  if (acc.Assemble) pushInv(acc.Assemble.DurationMs);\n\n  // Workflow step count: Plan + N chunks + Assemble + a small constant of\n  // control steps (BuildChunkList, AssertChunkCount, the map scaffold).\n  const workflowSteps = invocations.length + 4;\n  const costs = computeRenderCost(invocations, workflowSteps);\n\n  const outputGcsUri = acc.Assemble?.OutputGcsUri;\n  const outputFile = outputGcsUri\n    ? {\n        gcsUri: outputGcsUri,\n        bytes: typeof acc.Assemble?.FileSize === \"number\" ? acc.Assemble.FileSize : null,\n      }\n    : null;\n\n  return {\n    status,\n    overallProgress: 1,\n    framesRendered,\n    totalFrames,\n    invocationsObserved: invocations.length,\n    costs,\n    outputFile,\n    errors,\n    fatalErrorEncountered: false,\n    startedAt,\n    endedAt,\n  };\n}\n\n// fallow-ignore-next-line complexity\nfunction mapState(state: string | null | undefined): RenderStatus {\n  switch (state) {\n    case \"ACTIVE\":\n    case \"QUEUED\":\n      return \"running\";\n    case \"SUCCEEDED\":\n      return \"succeeded\";\n    case \"FAILED\":\n    case \"UNAVAILABLE\":\n      return \"failed\";\n    case \"CANCELLED\":\n      return \"cancelled\";\n    default:\n      return \"unknown\";\n  }\n}\n\n// fallow-ignore-next-line complexity\nfunction parseAccumulated(result: string | null | undefined): AccumulatedResult {\n  if (!result) return {};\n  try {\n    const parsed = JSON.parse(result) as unknown;\n    if (parsed && typeof parsed === \"object\") return parsed as AccumulatedResult;\n  } catch {\n    // Non-JSON result \u2014 treat as empty so cost/frames degrade to zero\n    // rather than throwing on a snapshot read.\n  }\n  return {};\n}\n\n/**\n * Best-effort pull of the handler's error name out of a Workflows failure\n * payload. On an http step failure, Workflows wraps the response as\n * `{ code, message, body, ... }` where `body` is the handler's JSON\n * `{ error, message }`. We dig out `error` (the typed name like\n * `PLAN_HASH_MISMATCH`) so triage sees the real cause, not a generic label.\n * Returns undefined for any shape we don't recognise \u2014 never throws.\n */\n// fallow-ignore-next-line complexity\nfunction extractErrorName(payload: string | null | undefined): string | undefined {\n  if (!payload) return undefined;\n  try {\n    const outer = JSON.parse(payload) as { error?: unknown; body?: unknown };\n    if (typeof outer.error === \"string\") return outer.error;\n    if (typeof outer.body === \"string\") {\n      const inner = JSON.parse(outer.body) as { error?: unknown };\n      if (typeof inner.error === \"string\") return inner.error;\n    } else if (outer.body && typeof outer.body === \"object\") {\n      const inner = outer.body as { error?: unknown };\n      if (typeof inner.error === \"string\") return inner.error;\n    }\n  } catch {\n    // Non-JSON / unexpected shape \u2014 fall through to the generic label.\n  }\n  return undefined;\n}\n\n// fallow-ignore-next-line complexity\nfunction toIso(ts: ProtoTimestamp | string | null | undefined): string | null {\n  if (ts == null) return null;\n  if (typeof ts === \"string\") return ts;\n  const seconds = ts.seconds == null ? null : Number(ts.seconds);\n  if (seconds == null || !Number.isFinite(seconds)) return null;\n  const ms = seconds * 1000 + (ts.nanos ?? 0) / 1e6;\n  return new Date(ms).toISOString();\n}\n\nasync function defaultExecutionsClient(): Promise<ExecutionsGetClientLike> {\n  const mod = await import(\"@google-cloud/workflows\");\n  const client = new mod.ExecutionsClient();\n  return client as unknown as ExecutionsGetClientLike;\n}\n"],
+  "mappings": "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",
+  "names": ["rmSync", "statSync", "statSync", "rmSync", "InvalidConfigError", "defaultExecutionsClient"]
+}

package/dist/sdk/renderToCloudRun.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `renderToCloudRun` — start a distributed render against an already-deployed
+ * Cloud Run service + Cloud Workflows definition and return a handle the
+ * caller can poll with {@link getRenderProgress}.
+ *
+ * The function does *not* wait for the render to finish. Cloud Workflows
+ * executions can run for hours; blocking the caller's process on the
+ * execution is the wrong default. The returned `RenderHandle` carries
+ * everything the progress / cost / download paths need.
+ *
+ * Wire order:
+ *   1. Validate config (typed throw before any GCP call).
+ *   2. `deploySite` if no `siteHandle` was provided.
+ *   3. `CreateExecution` against the workflow with the argument shape the
+ *      `packages/gcp-cloud-run/terraform/workflow.yaml` definition expects.
+ *   4. Return handle. The GCS `outputKey` is deterministic from the
+ *      client-generated `renderId` so the caller can predict the final
+ *      object URL before the (server-assigned) execution id exists.
+ *
+ * Unlike Step Functions, Cloud Workflows assigns the execution id
+ * server-side, so we cannot use it as the GCS prefix. We mint a `renderId`
+ * (uuid) client-side, use it for every GCS path, and pass it into the
+ * workflow argument; the server-assigned execution resource name is tracked
+ * separately for polling.
+ */
+import type { Storage } from "@google-cloud/storage";
+import type { SerializableDistributedRenderConfig } from "../events.js";
+import { type SiteHandle } from "./deploySite.js";
+/**
+ * Minimal surface of `@google-cloud/workflows`' `ExecutionsClient` that
+ * this module needs. The real client satisfies this; tests inject a double.
+ */
+export interface ExecutionsClientLike {
+    workflowPath(project: string, location: string, workflow: string): string;
+    createExecution(req: {
+        parent: string;
+        execution: {
+            argument: string;
+        };
+    }): Promise<[{
+        name?: string | null;
+        state?: string | null;
+    }, ...unknown[]]>;
+}
+/** Options for {@link renderToCloudRun}. */
+export interface RenderToCloudRunOptions {
+    /** Local project directory. Required when `siteHandle` is not supplied. */
+    projectDir?: string;
+    /** Re-use an existing `deploySite` upload (skips tar+GCS upload). */
+    siteHandle?: SiteHandle;
+    /** Validated `SerializableDistributedRenderConfig` (no logger / abortSignal). */
+    config: SerializableDistributedRenderConfig;
+    /** GCS bucket from the Terraform output (`render_bucket_name`). */
+    bucketName: string;
+    /** GCP project id hosting the workflow. */
+    projectId: string;
+    /** Workflow location, e.g. `us-central1`. */
+    location: string;
+    /** Workflow id from the Terraform output (`workflow_name`). */
+    workflowId: string;
+    /**
+     * HTTPS URL of the deployed Cloud Run render service (Terraform output
+     * `service_url`). The workflow POSTs every step (plan / renderChunk /
+     * assemble) to this URL; passed as an execution argument so the workflow
+     * definition stays free of hard-coded URLs.
+     */
+    serviceUrl: string;
+    /**
+     * Final output GCS key. Defaults to `renders/<renderId>/output.<ext>`
+     * where `<ext>` is derived from `config.format`.
+     */
+    outputKey?: string;
+    /**
+     * Client-generated render id. Defaults to `hf-render-<uuid>`. Used as the
+     * GCS key prefix and echoed into the workflow argument; not the same as
+     * the server-assigned execution id.
+     */
+    renderId?: string;
+    /** Test injection seam — production callers leave unset. */
+    executions?: ExecutionsClientLike;
+    /** Test injection seam — propagated to `deploySite` when applicable. */
+    storage?: Storage;
+}
+/** Stable identifier + every URL/name the caller needs to follow the render. */
+export interface RenderHandle {
+    /** Client-generated render id; the GCS prefix everything lands under. */
+    renderId: string;
+    /** Server-assigned execution resource name; pass to {@link getRenderProgress}. */
+    executionName: string;
+    bucketName: string;
+    workflowId: string;
+    outputGcsUri: string;
+    projectGcsUri: string;
+    startedAt: string;
+}
+export declare function renderToCloudRun(opts: RenderToCloudRunOptions): Promise<RenderHandle>;
+//# sourceMappingURL=renderToCloudRun.d.ts.map

package/dist/sdk/renderToCloudRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderToCloudRun.d.ts","sourceRoot":"","sources":["../../src/sdk/renderToCloudRun.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,cAAc,CAAC;AAGxE,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG9D;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1E,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC;KACjC,GAAG,OAAO,CAAC,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC;CAC9E;AAED,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,iFAAiF;IACjF,MAAM,EAAE,mCAAmC,CAAC;IAC5C,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC,CA4E3F"}

package/dist/sdk/validateConfig.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Client-side validation for the Cloud Run adapter.
+ *
+ * The cloud-agnostic config-shape validation (`validateDistributedRenderConfig`,
+ * `validateVariablesPayload`, `InvalidConfigError`) lives in
+ * `@hyperframes/producer/distributed` and is shared with the other adapters.
+ * This module re-exports those and adds the one piece that is specific to
+ * Cloud Workflows: the 512 KiB execution-argument size cap.
+ */
+export { InvalidConfigError, validateDistributedRenderConfig, validateVariablesPayload, } from "@hyperframes/producer/distributed";
+/**
+ * Hard cap on Cloud Workflows execution arguments — 512 KiB per the Workflows
+ * quotas page (maximum size of arguments passed when an execution starts).
+ * The cap is on the entire serialized argument, not just the variables,
+ * because users hit it at the wire boundary regardless of which field caused
+ * the bloat.
+ *
+ * Specific to Cloud Workflows. Other runtimes (Lambda + Step Functions,
+ * Temporal) have different caps; don't reuse this constant for those without
+ * confirming the limit.
+ */
+export declare const MAX_WORKFLOWS_INPUT_BYTES: number;
+/**
+ * Validate that the serialized Cloud Workflows execution argument fits inside
+ * the 512 KiB cap. Measured in UTF-8 bytes (the format the API uses on the
+ * wire) — JS strings count UTF-16 code units, which under-reports for any
+ * multi-byte character.
+ *
+ * Throws {@link InvalidConfigError} with a clear message naming the actual
+ * byte count, the cap, and a pointer to the "working with large variables"
+ * docs section, so users hit the limit at the SDK boundary with actionable
+ * guidance instead of as an opaque argument-too-large error after the
+ * execution starts.
+ */
+export declare function validateWorkflowsInputSize(input: unknown): void;
+//# sourceMappingURL=validateConfig.d.ts.map

package/dist/sdk/validateConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateConfig.d.ts","sourceRoot":"","sources":["../../src/sdk/validateConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EACL,kBAAkB,EAClB,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,mCAAmC,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,QAAa,CAAC;AAMpD;;;;;;;;;;;GAWG;AAEH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CA4B/D"}