feat(cloud): default distributed plans to v2

[jrusso1020]

What

• make omitted planProtocol select Plan v2 across the AWS Lambda and GCP Cloud Run handlers, orchestration, SDK helpers, examples, and smokes
• keep explicit planProtocol: "v1" as deprecated compatibility, with v1 handler branches and public event/result APIs intact
• stamp both v1 and v2 internal workflow tasks explicitly so new orchestration never relies on handler-side omission semantics
• document the infrastructure-first upgrade order and add omitted-v2 / explicit-v1 contract coverage

Why

Plan v2 is the content-addressed distributed transport and should be the normal path. The previous omission behavior still selected the monolithic v1 plan, leaving SDK, handler, and infrastructure defaults misaligned with the intended rollout.

How

The SDKs now serialize an explicit PlanProtocol: "v2" when callers omit the option. AWS CDK/SAM and the GCP workflow default top-level omission to v2, while every internal v1/v2 task carries an explicit selector. Runtime wire validation treats omission as v2 and continues to reject mixed locators.

Version skew and rollout

This is a behavioral default change and should ship in the next minor line (0.8.0), not as a 0.7.x patch. Existing installations must pause new work, drain active executions, and redeploy the Lambda+SAM/CDK or Cloud Run+workflow infrastructure from the same version before upgrading application SDKs. Until then, callers can remain on the prior version or pass planProtocol: "v1" explicitly.

No release or deployment is part of this PR.

Test plan

• Unit tests added/updated
• Manual cloud testing performed (not authorized in this task)
• Documentation updated

Validation performed on head 96a44dd4f:

• bun run --cwd packages/aws-lambda test — 143 passed
• bun run --cwd packages/gcp-cloud-run test — 101 passed
• AWS and GCP package typechecks — passed
• AWS and GCP package builds — passed
• bun run lint — passed, 0 warnings/errors
• bun run format:check — passed
• sample JSON validation and both smoke-script syntax checks — passed
• local AWS-handler plan-protocol parity (plan → 2 chunks → assemble) — v1/v2 produced identical 60-frame, 2-second MP4s with identical decoded frames, PCM audio, stream metadata, duration, chunk hashes, and encoded SHA
• mint validate and mint broken-links --check-redirects — passed

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Aug 17, 2026, 7:38 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[jrusso1020]

• feat(cloud): default distributed plans to v2 #3311 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miga-heygen]

LGTM with nits

Clean, well-structured default flip. The SSOT question was my main concern going in, and the answer is solid: each layer (SDK, orchestration, handler) owns exactly one decision point for "what does omitted mean," and they all agree on v2. The explicit PlanProtocol stamping in both the Step Functions template and Cloud Workflows definition is the real safety net — the handler never has to guess, because the orchestration layer resolves omission before the first Lambda/Cloud Run invocation. That is a good design.

Type system changes (swapping optionality between V1 and V2 event interfaces) are correct. !== "v1" as the dispatch check is the right polarity for a default-v2 world, and TypeScript's discriminated union narrowing handles it cleanly — PlanV1Event.PlanProtocol is required "v1", so !== "v1" eliminates it and narrows to PlanV2Event where PlanProtocol is "v2" | undefined.

---

Medium: AWS validatePlanProtocolShape has no direct tests

Files: packages/aws-lambda/src/handler.ts (new function, ~37 lines), packages/aws-lambda/src/handler.test.ts

The GCP side already had validatePlanProtocolShape with dedicated test coverage — including "rejects mixed v1/v2 locators at runtime" and the HTTP 400 mapping for PLAN_PROTOCOL_UNSUPPORTED. This PR copies the function into the AWS handler (adapted for S3 URIs), but the AWS test file has no equivalent coverage for:

• Unknown protocol values (e.g., "v3") — the function throws PLAN_PROTOCOL_UNSUPPORTED but nothing exercises that branch.
• Mixed locators (e.g., absent PlanProtocol with PlanS3Uri instead of v2 locators) — the cross-locator validation is the security-relevant part and goes untested.

The GCP test at roughly line 379 ("rejects mixed v1/v2 locators at runtime") is a good template. Porting the same two scenarios to the Lambda handler test would close the gap.

Nit: Orphaned *-v2.json sample events (6 files)

Files:

• examples/aws-lambda/sample-events/plan-v2.json, render-chunk-v2.json, assemble-v2.json
• examples/gcp-cloud-run/sample-events/plan-v2.json, render-chunk-v2.json, assemble-v2.json

These files still exist on the branch but are no longer referenced in any README or script. The PR correctly created new *-v1.json files for deprecated compatibility and updated the default *.json files to omit PlanProtocol (implicit v2). The old *-v2.json files — which carry explicit "PlanProtocol": "v2" — are now redundant with the updated defaults. They are not wrong (they would work), but they are dead weight that could confuse someone scanning the sample-events directory wondering which files are canonical.

Either delete them (my preference — the default files already demonstrate v2) or keep them with a note in the README explaining the three tiers (*.json = default/v2, *-v1.json = deprecated compat, *-v2.json = explicit v2).

Nit: GCP smoke.sh comment line length

File: examples/gcp-cloud-run/scripts/smoke.sh, line ~5

The replacement comment runs to ~103 characters. Surrounding comment lines wrap at ~80. Not functional, just cosmetic.

---

What I verified

• Single source of truth: Default is set at exactly one point per layer — SDK (opts.planProtocol ?? "v2"), AWS template.yaml (Default: PlanV2), GCP workflow.yaml (default(..., "v2")), handler dispatch (event.PlanProtocol !== "v1"). No redundant fallback chains.
• Explicit stamping: Both orchestration layers (Step Functions template + Cloud Workflows YAML) now stamp PlanProtocol: "v1" on the v1 branch tasks and PlanProtocol: "v2" on the v2 branch tasks. The handler receives an unambiguous protocol field in all paths.
• Type narrowing: The optionality swap (V1Event.PlanProtocol required, V2Event.PlanProtocol optional) produces correct discriminated-union narrowing with !== "v1". The handlePlanV2 / handleRenderChunkV2 / handleAssembleV2 signatures were updated from Extract<...> to named event types — assignability is preserved.
• Wire validation: validatePlanProtocolShape rejects unknown protocols, mixed v1/v2 locators, and v2 assemble events with non-null AudioS3Uri. GCP version was updated in-place; AWS version is new. Both are structurally symmetric (S3 vs GCS URIs).
• Version skew documentation: Upgrade-order warnings are present in all four doc surfaces (both .mdx files, both README.md files) with the same instruction: drain active executions, redeploy infrastructure, then upgrade SDK.
• Stale concept scan: No remaining "defaults to v1" or "absence interpreted as v1" comments. All doc/comment updates are consistent with the new default.
• v1 compatibility preserved: Explicit planProtocol: "v1" paths are tested end-to-end in both platforms. Sample events, orchestration branches, and handler dispatch all retain functional v1 support.
• CDK snapshot test: The new assertion (selection.Default === "PlanV2", v1 branch presence, explicit PlanProtocol: "v1" in Plan task payload) cross-checks both the CDK-synthed definition and the SAM template.yaml, catching drift between the two infrastructure definitions.
• SDK tests: Both renderToLambda and renderToCloudRun tests verify the default wire payload carries PlanProtocol: "v2" and that explicit "v1" is forwarded correctly.
• Smoke scripts: Both AWS and GCP smoke defaults updated from v1 to v2. Smoke safety tests updated to assert the new default.

Review by Miga

[miga-heygen]

LGTM — all feedback addressed at 92250db12.

1. AWS validation tests added (lines ~805-853): "rejects unknown plan protocol values" and "rejects mixed v1/v2 plan locators at runtime" — both assert PLAN_PROTOCOL_UNSUPPORTED and verify zero S3 ops (side-effect-free rejection). Mirrors the GCP coverage exactly.
2. Orphaned *-v2.json files removed: assemble-v2.json deleted outright, plan-v2.json and render-chunk-v2.json renamed to *-v1.json (now the deprecated-compat samples). Clean two-tier scheme: *.json = default v2, *-v1.json = deprecated v1.
3. GCP smoke comment wrapped: fits the surrounding ~80-char convention.

Ready for stamp.

Review by Miga

[miga-heygen]

LGTM — delta at 96a44dd4f05 is clean.

The six *-v2.json sample files are restored unchanged (tracked-artifact policy), and both READMEs now document the three-tier scheme (*.json = default v2 with PlanProtocol omitted, *-v1.json = deprecated explicit v1, *-v2.json = explicit v2). GCP README adds a matching curl example for the explicit-v2 path. No code changes — AWS validator tests and smoke wrap from 92250db12 are intact.

Ready for stamp.

Review by Miga

[miguel-heygen]

Exact-head review at 96a44dd4f05abe2ca5824ad6d2789d8dbdf6e7d5.

No blocking findings.

• The AWS and GCP event unions now make v1 explicit and omission a typed v2 case; handler dispatch and locator collection use the same !== "v1" polarity.
• Both runtime boundaries reject unknown protocols and mixed/missing locator shapes before storage operations. The added AWS tests mirror GCP and assert zero S3 side effects.
• SDK helpers serialize explicit PlanProtocol: "v2" on omission, while explicit v1 compatibility remains covered.
• Step Functions/CDK and Cloud Workflows default top-level omission to v2, then stamp every internal v1/v2 task explicitly, avoiding version-skew dependence on handler omission.
• The final delta after 92250db12 is documentation/sample-only: all 18 sample JSON files parse, and both platforms now document the accepted three-tier scheme (omitted/default v2, explicit v1, explicit v2).

All eight required ruleset contexts are successful on this exact head: semantic title, runtime contract, typecheck, build, test, regression, and both Windows lanes.

Verdict: APPROVE
Reasoning: The default flip is consistent across types, runtime validation, orchestration, SDKs, examples, and rollout docs; compatibility is explicit and fail-closed, the final sample restoration is documented, and every required exact-head check is green.

— Magi