fix: check target run capabilities before encrypting hook payloads

When resumeHook()/resumeWebhook() is called on a newer deployment that
supports encryption, it would encode the payload with the 'encr' format.
If the target workflow run was created by an older deployment that
predates encryption support, the run would fail with:
  Error: Unknown serialization format: "encr". Known formats: devl

Add a capabilities table that maps @workflow/core versions to supported
serialization formats. Before encoding, resumeHook() now checks the
target run's workflowCoreVersion and suppresses encryption when the
run's deployment doesn't support it.

Author: TooTallNate

.changeset/fix-hook-resume-encryption-compat.md

@@ -0,0 +1,5 @@
+---
+"@workflow/core": patch
+---
+
+Fix `resumeHook()`/`resumeWebhook()` failing on workflow runs from pre-encryption deployments by checking the target run's `workflowCoreVersion` capabilities before encoding the payload

packages/core/package.json

@@ -93,12 +93,14 @@
     "ms": "2.1.3",
     "nanoid": "5.1.6",
     "seedrandom": "3.0.5",
+    "semver": "catalog:",
     "ulid": "catalog:",
     "zod": "catalog:"
   },
   "devDependencies": {
     "@opentelemetry/api": "1.9.0",
     "@types/debug": "4.1.12",
+    "@types/semver": "7.7.1",
     "@types/node": "catalog:",
     "@types/seedrandom": "3.0.8",
     "@workflow/tsconfig": "workspace:*",

packages/core/src/capabilities.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { getRunCapabilities } from './capabilities.js';
+import { SerializationFormat } from './serialization.js';
+
+describe('getRunCapabilities', () => {
+  describe('undefined version (very old runs)', () => {
+    it('only supports baseline formats', () => {
+      const { supportedFormats } = getRunCapabilities(undefined);
+      expect(supportedFormats.has(SerializationFormat.DEVALUE_V1)).toBe(true);
+      expect(supportedFormats.has(SerializationFormat.ENCRYPTED)).toBe(false);
+    });
+  });
+
+  describe('pre-encryption versions', () => {
+    it.each([
+      '4.1.0-beta.63',
+      '4.0.1-beta.27',
+      '3.0.0',
+    ])('%s does not support encryption', (version) => {
+      const { supportedFormats } = getRunCapabilities(version);
+      expect(supportedFormats.has(SerializationFormat.DEVALUE_V1)).toBe(true);
+      expect(supportedFormats.has(SerializationFormat.ENCRYPTED)).toBe(false);
+    });
+  });
+
+  describe('encryption-capable versions', () => {
+    it('supports encryption at the exact cutoff version', () => {
+      const { supportedFormats } = getRunCapabilities('4.2.0-beta.64');
+      expect(supportedFormats.has(SerializationFormat.DEVALUE_V1)).toBe(true);
+      expect(supportedFormats.has(SerializationFormat.ENCRYPTED)).toBe(true);
+    });
+
+    it.each([
+      '4.2.0-beta.74',
+      '4.2.0',
+      '5.0.0',
+    ])('%s supports encryption', (version) => {
+      const { supportedFormats } = getRunCapabilities(version);
+      expect(supportedFormats.has(SerializationFormat.ENCRYPTED)).toBe(true);
+    });
+  });
+});

packages/core/src/capabilities.ts

@@ -0,0 +1,84 @@
+/**
+ * Capabilities table for workflow runs based on their `@workflow/core` version.
+ *
+ * When resuming a hook or webhook, the payload must be encoded in a format
+ * that the *target* workflow run's deployment can decode. This module provides
+ * a way to look up what serialization formats a given `@workflow/core` version
+ * supports, so that newer deployments can avoid encoding payloads in formats
+ * that older deployments don't understand (e.g., the `encr` encryption format).
+ *
+ * ## Adding a new format
+ *
+ * When a new serialization format is introduced:
+ * 1. Add the format constant to `SerializationFormat` in `serialization.ts`
+ * 2. Add an entry to `FORMAT_VERSION_TABLE` below with the minimum
+ *    `@workflow/core` version that supports it
+ * 3. The `getRunCapabilities()` function will automatically include it
+ */
+
+import semver from 'semver';
+import {
+  SerializationFormat,
+  type SerializationFormatType,
+} from './serialization.js';
+
+/**
+ * Capabilities of a workflow run based on its `@workflow/core` version.
+ */
+export interface RunCapabilities {
+  /**
+   * The set of serialization format prefixes that the target run can decode.
+   * Use `supportedFormats.has(SerializationFormat.ENCRYPTED)` to check
+   * if encryption is supported, etc.
+   */
+  supportedFormats: ReadonlySet<SerializationFormatType>;
+}
+
+/**
+ * Maps serialization format identifiers to the minimum `@workflow/core`
+ * version that introduced support for them. Formats not listed here are
+ * assumed to be supported by all specVersion 2 runs (e.g., `devl`).
+ */
+const FORMAT_VERSION_TABLE: ReadonlyArray<{
+  format: SerializationFormatType;
+  minVersion: string;
+}> = [
+  { format: SerializationFormat.ENCRYPTED, minVersion: '4.2.0-beta.64' },
+  // Future entries:
+  // { format: SerializationFormat.CBOR, minVersion: '5.x.y' },
+  // { format: SerializationFormat.ENCRYPTED_V2, minVersion: '5.x.y' },
+];
+
+/**
+ * The set of formats supported by all specVersion 2 runs, regardless of
+ * `@workflow/core` version. These are the baseline formats that were present
+ * from the start of the specVersion 2 protocol.
+ */
+const BASELINE_FORMATS: ReadonlySet<SerializationFormatType> = new Set([
+  SerializationFormat.DEVALUE_V1,
+]);
+
+/**
+ * Look up what serialization capabilities a workflow run supports based on
+ * its `@workflow/core` version string (from `executionContext.workflowCoreVersion`).
+ *
+ * When the version is `undefined` (e.g. very old runs that predate the field),
+ * we assume the most conservative capabilities (baseline formats only).
+ */
+export function getRunCapabilities(
+  workflowCoreVersion: string | undefined
+): RunCapabilities {
+  if (!workflowCoreVersion) {
+    return { supportedFormats: BASELINE_FORMATS };
+  }
+
+  const formats = new Set<SerializationFormatType>(BASELINE_FORMATS);
+
+  for (const { format, minVersion } of FORMAT_VERSION_TABLE) {
+    if (semver.gte(workflowCoreVersion, minVersion)) {
+      formats.add(format);
+    }
+  }
+
+  return { supportedFormats: formats };
+}

packages/core/src/runtime/resume-hook.ts

@@ -11,10 +11,12 @@ import {
   type WorkflowInvokePayload,
   type WorkflowRun,
 } from '@workflow/world';
+import { getRunCapabilities } from '../capabilities.js';
 import { type CryptoKey, importKey } from '../encryption.js';
 import {
   dehydrateStepReturnValue,
   hydrateStepArguments,
+  SerializationFormat,
 } from '../serialization.js';
 import { WEBHOOK_RESPONSE_WRITABLE } from '../symbols.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
@@ -123,6 +125,17 @@ export async function resumeHook<T = any>(
           ...Attribute.WorkflowRunId(hook.runId),
         });
 
+        // Check the target run's capabilities to ensure we encode the
+        // payload in a format the run's deployment can decode. For example,
+        // runs created before encryption support was added cannot decode
+        // the 'encr' serialization format.
+        const { supportedFormats } = getRunCapabilities(
+          workflowRun.executionContext?.workflowCoreVersion
+        );
+        if (!supportedFormats.has(SerializationFormat.ENCRYPTED)) {
+          encryptionKey = undefined;
+        }
+
         // Dehydrate the payload for storage
         const ops: Promise<any>[] = [];
         const v1Compat = isLegacySpecVersion(hook.specVersion);

packages/next/package.json

@@ -37,7 +37,7 @@
     "@workflow/builders": "workspace:*",
     "@workflow/core": "workspace:*",
     "@workflow/swc-plugin": "workspace:*",
-    "semver": "7.7.4",
+    "semver": "catalog:",
     "watchpack": "2.5.1"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -16,6 +16,7 @@ catalog:
   ai: 6.0.116
   esbuild: ^0.27.3
   nitro: 3.0.1-alpha.1
+  semver: 7.7.4
   typescript: ^5.9.3
   ulid: ~3.0.1
   undici: 7.22.0