feat(producer): version distributed plan protocol

Author: jrusso1020

packages/producer/src/distributed.ts

@@ -82,6 +82,24 @@ export {
 } from "./services/distributed/renderConfigValidation.js";
 export { hashProjectDir } from "./services/distributed/projectHash.js";
 
+// ── Plan protocol compatibility ────────────────────────────────────────────
+// Workers validate this descriptor before consuming layout-specific
+// artifacts. Missing descriptors remain compatible with legacy v1 plans.
+export {
+  CURRENT_PLAN_PROTOCOL,
+  DISTRIBUTED_RENDER_CAPABILITIES,
+  getDistributedRenderCapabilities,
+  PLAN_ARTIFACT_LAYOUT,
+  PLAN_HASH_SCHEMA,
+  PLAN_PROTOCOL_UNSUPPORTED,
+  PLAN_SCHEMA_VERSION,
+  PlanProtocolUnsupportedError,
+  readPlanProtocol,
+  type DistributedRenderCapabilities,
+  type PlanProtocolDescriptor,
+  type PlanProtocolV1Descriptor,
+} from "./services/distributed/planProtocol.js";
+
 // ── Format union ────────────────────────────────────────────────────────────
 // Canonical output-format type. The aws-lambda package re-exports it so
 // CLI / adopter SDKs can derive runtime allowlists from one source.

packages/producer/src/index.ts

@@ -133,10 +133,22 @@ export {
 // separate subpath import.
 export {
   assemble,
+  CURRENT_PLAN_PROTOCOL,
+  DISTRIBUTED_RENDER_CAPABILITIES,
+  getDistributedRenderCapabilities,
+  PLAN_ARTIFACT_LAYOUT,
+  PLAN_HASH_SCHEMA,
+  PLAN_PROTOCOL_UNSUPPORTED,
+  PLAN_SCHEMA_VERSION,
   plan,
+  PlanProtocolUnsupportedError,
+  readPlanProtocol,
   renderChunk,
   type AssembleResult,
   type ChunkResult,
+  type DistributedRenderCapabilities,
   type DistributedRenderConfig,
+  type PlanProtocolDescriptor,
+  type PlanProtocolV1Descriptor,
   type PlanResult,
 } from "./distributed.js";

packages/producer/src/services/distributed/assemble.ts

@@ -40,6 +40,7 @@ import { defaultLogger, type ProducerLogger } from "../../logger.js";
 import { formatExportFrameName } from "../../utils/paths.js";
 import { padOrTrimAudioToVideoFrameCount } from "../render/audioPadTrim.js";
 import type { ChunkSliceJson } from "../render/stages/freezePlan.js";
+import { readPlanProtocol } from "./planProtocol.js";
 import type { DistributedFormat } from "./shared.js";
 
 /**
@@ -56,6 +57,7 @@ export interface AssembleResult {
 
 /** Shape of the planDir's top-level `plan.json` — only the fields `assemble` needs. */
 interface PlanJsonForAssemble {
+  protocol?: unknown;
   planHash: string;
   totalFrames: number;
   hasAudio: boolean;
@@ -118,10 +120,11 @@ export async function assemble(
   if (!existsSync(planJsonPath)) {
     throw new Error(`[assemble] planDir missing plan.json: ${planJsonPath}`);
   }
+  const plan = JSON.parse(readFileSync(planJsonPath, "utf-8")) as PlanJsonForAssemble;
+  readPlanProtocol(plan);
   if (!existsSync(chunksJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/chunks.json: ${chunksJsonPath}`);
   }
-  const plan = JSON.parse(readFileSync(planJsonPath, "utf-8")) as PlanJsonForAssemble;
   const chunks = JSON.parse(readFileSync(chunksJsonPath, "utf-8")) as ChunkSliceJson[];
   if (chunkPaths.length !== chunks.length) {
     throw new Error(

packages/producer/src/services/distributed/plan.test.ts

@@ -20,6 +20,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { recomputePlanHashFromPlanDir } from "../render/stages/freezePlan.js";
 import { RenderQualityError } from "../renderOrchestrator.js";
+import { CURRENT_PLAN_PROTOCOL } from "./planProtocol.js";
 import {
   applyDistributedAudioWarningPolicy,
   buildChunkSlices,
@@ -345,6 +346,7 @@ describe("plan() — golden planDir + planHash determinism", () => {
 
       // ── PlanResult contract ─────────────────────────────────────────────
       expect(result.planDir).toBe(planDir);
+      expect(result.planProtocol).toEqual(CURRENT_PLAN_PROTOCOL);
       expect(result.planHash).toMatch(/^[0-9a-f]{64}$/);
       expect(result.chunkCount).toBe(1);
       expect(result.totalFrames).toBe(30); // 1s @ 30fps
@@ -373,6 +375,7 @@ describe("plan() — golden planDir + planHash determinism", () => {
         unknown
       >;
       expect(planJson.planHash).toBe(result.planHash);
+      expect(planJson.protocol).toEqual(CURRENT_PLAN_PROTOCOL);
       expect(planJson.hasAudio).toBe(false);
       expect(planJson.totalFrames).toBe(result.totalFrames);
     },
@@ -460,8 +463,18 @@ describe("plan() — golden planDir + planHash determinism", () => {
       expect(recomputed).toBe(result.planHash);
       const planJson = JSON.parse(readFileSync(join(planDir, "plan.json"), "utf-8")) as {
         planHash: string;
+        protocol?: unknown;
       };
       expect(planJson.planHash).toBe(result.planHash);
+      expect(planJson.protocol).toEqual(CURRENT_PLAN_PROTOCOL);
+
+      delete planJson.protocol;
+      writeFileSync(join(planDir, "plan.json"), `${JSON.stringify(planJson, null, 2)}\n`, "utf-8");
+      expect(recomputePlanHashFromPlanDir(planDir)).toBe(result.planHash);
+
+      planJson.protocol = CURRENT_PLAN_PROTOCOL;
+      writeFileSync(join(planDir, "plan.json"), `${JSON.stringify(planJson, null, 2)}\n`, "utf-8");
+      expect(recomputePlanHashFromPlanDir(planDir)).toBe(result.planHash);
     },
     TIMEOUT_MS,
   );

packages/producer/src/services/distributed/plan.ts

@@ -79,6 +79,7 @@ import {
   readFfmpegVersion,
   readProducerVersion,
 } from "./shared.js";
+import { CURRENT_PLAN_PROTOCOL, type PlanProtocolV1Descriptor } from "./planProtocol.js";
 
 /**
  * Caller-supplied configuration for a distributed render. `fps`, `width`,
@@ -254,6 +255,7 @@ export interface DistributedRenderConfig {
  */
 export interface PlanResult {
   planDir: string;
+  planProtocol: Readonly<PlanProtocolV1Descriptor>;
   planHash: string;
   chunkCount: number;
   totalFrames: number;
@@ -1084,6 +1086,7 @@ export async function plan(
 
   return {
     planDir,
+    planProtocol: CURRENT_PLAN_PROTOCOL,
     planHash,
     chunkCount,
     totalFrames,