feat(workflow-executor): serialize recordId as pipe string at front/orchestrator boundaries

packages/workflow-executor/src/adapters/agent-client-agent-port.ts

@@ -9,7 +9,7 @@ import type {
 } from '../ports/agent-port';
 import type SchemaCache from '../schema-cache';
 import type { StepUser } from '../types/execution-context';
-import type { CollectionSchema, RecordData } from '../types/validated/collection';
+import type { CollectionSchema, RecordData, RecordId } from '../types/validated/collection';
 import type { ActionEndpointsByCollection, SelectOptions } from '@forestadmin/agent-client';
 
 import { createRemoteAgentClient } from '@forestadmin/agent-client';
@@ -45,10 +45,7 @@ function restoreFieldNames(
   return Object.fromEntries(Object.entries(values).map(([k, v]) => [camelToOriginal[k] ?? k, v]));
 }
 
-function buildPkFilter(
-  primaryKeyFields: string[],
-  id: Array<string | number>,
-): SelectOptions['filters'] {
+function buildPkFilter(primaryKeyFields: string[], id: RecordId): SelectOptions['filters'] {
   if (primaryKeyFields.length === 1) {
     return { field: primaryKeyFields[0], operator: 'Equal', value: id[0] };
   }

packages/workflow-executor/src/adapters/forestadmin-client-activity-log-port.ts

@@ -10,6 +10,7 @@ import type {
   ActivityLogsServiceInterface,
 } from '@forestadmin/forestadmin-client';
 
+import { serializeRecordId } from './record-id-serializer';
 import withRetry from './with-retry';
 import { ActivityLogCreationError, extractErrorMessage } from '../errors';
 
@@ -34,7 +35,8 @@ export default class ForestadminClientActivityLogPort implements ActivityLogPort
             // The lib writes this value verbatim into relationships.collection.data.id
             // (JSON:API). The Forest server audit-trail API expects the numeric collectionId.
             collectionName: args.collectionId,
-            recordId: args.recordId,
+            // Record ids are serialized to the pipe wire format here, never in the executor.
+            recordId: args.recordId?.length ? serializeRecordId(args.recordId) : undefined,
             label: args.label,
           }),
         { logger: this.logger },

packages/workflow-executor/src/adapters/record-id-serializer.ts

@@ -0,0 +1,21 @@
+import type { RecordId } from '../types/validated/collection';
+
+import { RecordIdSerializationError } from '../errors';
+
+export function serializeRecordId(recordId: RecordId): string {
+  return recordId
+    .map(part => {
+      const serialized = String(part);
+
+      if (serialized.includes('|')) {
+        throw new RecordIdSerializationError(serialized);
+      }
+
+      return serialized;
+    })
+    .join('|');
+}
+
+export function deserializeRecordId(value: string): string[] {
+  return value.split('|');
+}

packages/workflow-executor/src/adapters/run-to-available-step-mapper.ts

@@ -13,6 +13,7 @@ import type {
 
 import { z } from 'zod';
 
+import { deserializeRecordId } from './record-id-serializer';
 import toStepDefinition from './step-definition-mapper';
 import {
   DomainValidationError,
@@ -139,6 +140,12 @@ export default function toAvailableStepExecution(
     );
   }
 
+  if (!run.selectedRecordId) {
+    throw new InvalidStepDefinitionError(
+      `Run ${run.id} has no selectedRecordId — cannot build baseRecordRef`,
+    );
+  }
+
   const pending = run.workflowHistory.at(-1) ?? null;
   if (!pending || pending.done) return null;
 
@@ -149,7 +156,7 @@ export default function toAvailableStepExecution(
     collectionId: run.collectionId,
     baseRecordRef: {
       collectionName: run.collectionName,
-      recordId: [run.selectedRecordId],
+      recordId: deserializeRecordId(run.selectedRecordId),
       stepIndex: 0,
     },
     stepDefinition: toStepDefinition(pending.stepDefinition),

packages/workflow-executor/src/errors.ts

@@ -367,6 +367,15 @@ export class UnsupportedStepTypeError extends WorkflowExecutorError {
   }
 }
 
+export class RecordIdSerializationError extends WorkflowExecutorError {
+  constructor(part: string) {
+    super(
+      `Composite record id part "${part}" cannot contain the "|" separator`,
+      'A record identifier contains an unsupported character and cannot be processed.',
+    );
+  }
+}
+
 export class InvalidStepDefinitionError extends WorkflowExecutorError {
   constructor(detail: string) {
     super(

packages/workflow-executor/src/executors/load-related-record-step-executor.ts

@@ -62,7 +62,7 @@ export default class LoadRelatedRecordStepExecutor extends RecordStepExecutor<Lo
       action: 'listRelatedData',
       type: 'read',
       collectionId: this.context.collectionId,
-      recordId: this.context.baseRecordRef.recordId[0],
+      recordId: this.context.baseRecordRef.recordId,
     };
   }
 

packages/workflow-executor/src/executors/read-record-step-executor.ts

@@ -25,7 +25,7 @@ export default class ReadRecordStepExecutor extends RecordStepExecutor<ReadRecor
       action: 'index',
       type: 'read',
       collectionId: this.context.collectionId,
-      recordId: this.context.baseRecordRef.recordId[0],
+      recordId: this.context.baseRecordRef.recordId,
     };
   }
 

packages/workflow-executor/src/executors/trigger-record-action-step-executor.ts

@@ -41,7 +41,7 @@ export default class TriggerRecordActionStepExecutor extends RecordStepExecutor<
       action: 'action',
       type: 'write',
       collectionId: this.context.collectionId,
-      recordId: this.context.baseRecordRef.recordId[0],
+      recordId: this.context.baseRecordRef.recordId,
     };
   }
 

packages/workflow-executor/src/executors/update-record-step-executor.ts

@@ -133,7 +133,7 @@
       action: 'update',
       type: 'write',
       collectionId: this.context.collectionId,
-      recordId: this.context.baseRecordRef.recordId[0],
+      recordId: this.context.baseRecordRef.recordId,
     };
   }
 
@@ -165,11 +165,11 @@
         // A user override of `null` (clearing the field) must win over the AI suggestion, so
         // distinguish "no override" (undefined) from "override to null".
         const rawValue =
           userConfirmation?.value !== undefined ? userConfirmation.value : pendingData!.value;
 
         const target: UpdateTarget = {
           selectedRecordRef,
           ...pendingData!,
           // The value comes from an `unknown` HTTP value (may be a boolean or array), so coerce
           // it to the field's native type before updating. Idempotent on already-typed values.
           value: await this.coerceOverride(selectedRecordRef, pendingData, rawValue),

packages/workflow-executor/src/http/executor-http-server.ts

@@ -10,6 +10,7 @@ import http from 'http';
 import Koa from 'koa';
 import koaJwt from 'koa-jwt';
 
+import serializeStepForWire from './step-serializer';
 import ConsoleLogger from '../adapters/console-logger';
 import {
   RunNotFoundError,
@@ -160,7 +161,7 @@ export default class ExecutorHttpServer {
 
   private async handleGetRun(ctx: Koa.Context): Promise<void> {
     const steps = await this.options.runner.getRunStepExecutions(ctx.params.runId);
-    ctx.body = { steps };
+    ctx.body = { steps: steps.map(serializeStepForWire) };
   }
 
   private async handleTrigger(ctx: Koa.Context): Promise<void> {

packages/workflow-executor/src/http/pending-data-validators.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 
+import { deserializeRecordId } from '../adapters/record-id-serializer';
+
 // Per-step-type schemas for the userConfirmation payload sent by the front via
 // POST /runs/:runId/trigger. Validated into `execution.userConfirmation`; schemas
 // use .strict() to reject unknown fields.
@@ -39,12 +41,15 @@ const loadRelatedRecordPatchSchema = z
     // orchestrator); the executor re-derives displayName + relatedCollectionName from
     // the live schema when processing the confirmation.
     fieldName: z.string().min(1).optional(),
-    // User may override the AI-selected record; must be non-empty when provided.
-    // Required when confirming with a relation override — the original record ID
-    // belongs to a different collection and cannot be reused for the new relation.
+    // User may override the AI-selected record; pipe-separated string (e.g. 'id1|id2'),
+    // deserialized to an id array. Required when confirming with a relation override —
+    // the original record ID belongs to a different collection and cannot be reused.
+    // The .pipe(...) rejects empty segments that would build a bogus PK.
     selectedRecordId: z
-      .array(z.union([z.string(), z.number()]))
+      .string()
       .min(1)
+      .transform(deserializeRecordId)
+      .pipe(z.array(z.string().min(1)))
       .optional(),
   })
   .strict()

packages/workflow-executor/src/http/step-serializer.ts

@@ -0,0 +1,54 @@
+import type { StepExecutionData } from '../types/step-execution-data';
+import type { RecordRef } from '../types/validated/collection';
+
+import { serializeRecordId } from '../adapters/record-id-serializer';
+
+function serializeRecordRef(ref: RecordRef): unknown {
+  return { ...ref, recordId: serializeRecordId(ref.recordId) };
+}
+
+export default function serializeStepForWire(step: StepExecutionData): unknown {
+  switch (step.type) {
+    case 'read-record':
+    case 'update-record':
+    case 'trigger-action':
+      return { ...step, selectedRecordRef: serializeRecordRef(step.selectedRecordRef) };
+
+    case 'load-related-record': {
+      const result: Record<string, unknown> = {
+        ...step,
+        selectedRecordRef: serializeRecordRef(step.selectedRecordRef),
+      };
+
+      if (step.pendingData) {
+        const { availableRecordIds, suggestedRecord } = step.pendingData;
+
+        result.pendingData = {
+          ...step.pendingData,
+          availableRecordIds: availableRecordIds.map(c => ({
+            ...c,
+            recordId: serializeRecordId(c.recordId),
+          })),
+          ...(suggestedRecord && {
+            suggestedRecord: {
+              ...suggestedRecord,
+              recordId: serializeRecordId(suggestedRecord.recordId),
+            },
+          }),
+        };
+      }
+
+      if (step.executionResult && 'record' in step.executionResult) {
+        result.executionResult = {
+          ...step.executionResult,
+          record: serializeRecordRef(step.executionResult.record),
+        };
+      }
+
+      return result;
+    }
+
+    default:
+      return step;
+  }
+}

packages/workflow-executor/src/ports/activity-log-port.ts

@@ -1,9 +1,11 @@
+import type { RecordId } from '../types/validated/collection';
+
 export interface CreateActivityLogArgs {
   renderingId: number;
   action: string;
   type: 'read' | 'write';
   collectionId?: string;
-  recordId?: string | number;
+  recordId?: RecordId;
   label?: string;
 }
 

packages/workflow-executor/src/types/step-execution-data.ts

@@ -1,6 +1,6 @@
 /** @draft Types derived from the workflow-executor spec -- subject to change. */
 
-import type { RecordRef } from './validated/collection';
+import type { RecordId, RecordRef } from './validated/collection';
 import type {
   LoadRelatedRecordConfirmation,
   McpConfirmation,
@@ -133,7 +133,7 @@ export interface RecordStepExecutionData extends BaseStepExecutionData {
 
 // -- Load Related Record --
 export interface LoadRelatedRecordCandidate {
-  recordId: Array<string | number>;
+  recordId: RecordId;
   referenceFieldValue: string | null;
 }
 

packages/workflow-executor/src/types/validated/collection.ts

@@ -94,12 +94,15 @@ export type CollectionSchema = z.infer<typeof CollectionSchemaSchema>;
 export const RecordRefSchema = z
   .object({
     collectionName: z.string().min(1),
-    recordId: z.array(z.union([z.string(), z.number()])).min(1),
+    recordId: z.array(z.union([z.string().min(1), z.number()])).min(1),
     // Index of the workflow step that loaded this record.
     stepIndex: z.number().int().nonnegative(),
   })
   .strict();
 export type RecordRef = z.infer<typeof RecordRefSchema>;
 
+// A record's primary key: one segment for a simple key, several for a composite key.
+export type RecordId = RecordRef['recordId'];
+
 // No stepIndex — the agent doesn't know about steps.
 export type RecordData = Omit<RecordRef, 'stepIndex'> & { values: Record<string, unknown> };

packages/workflow-executor/test/adapters/forestadmin-client-activity-log-port.test.ts

@@ -63,6 +63,24 @@ describe('ForestadminClientActivityLogPort', () => {
       expect(service.createActivityLog).toHaveBeenCalledTimes(1);
     });
 
+    it('serializes a composite recordId to the pipe wire format', async () => {
+      const service = makeService();
+      service.createActivityLog.mockResolvedValue({ id: 'log-1', attributes: { index: '0' } });
+      const port = makePort(service);
+
+      await port.createPending({
+        renderingId: 5,
+        action: 'update',
+        type: 'write',
+        collectionId: 'col-1',
+        recordId: ['tenant', 7],
+      });
+
+      expect(service.createActivityLog).toHaveBeenCalledWith(
+        expect.objectContaining({ recordId: 'tenant|7' }),
+      );
+    });
+
     it('retries on 503 and succeeds on the second attempt', async () => {
       const service = makeService();
       service.createActivityLog

packages/workflow-executor/test/adapters/record-id-serializer.test.ts

@@ -0,0 +1,47 @@
+import { deserializeRecordId, serializeRecordId } from '../../src/adapters/record-id-serializer';
+import { RecordIdSerializationError } from '../../src/errors';
+
+describe('serializeRecordId', () => {
+  it('single id → no pipe', () => {
+    expect(serializeRecordId(['42'])).toBe('42');
+  });
+
+  it('composite ids → pipe-joined', () => {
+    expect(serializeRecordId(['id1', 'id2'])).toBe('id1|id2');
+  });
+
+  it('numbers are stringified', () => {
+    expect(serializeRecordId([42, 99])).toBe('42|99');
+  });
+
+  it('mixed string and number ids', () => {
+    expect(serializeRecordId(['org', 42])).toBe('org|42');
+  });
+
+  // '|' is the reserved segment delimiter, so a part that contains it would over-split on the way
+  // back and match the wrong record. Fail loudly instead of silently corrupting the key.
+  it('throws when a part contains the reserved pipe separator', () => {
+    expect(() => serializeRecordId(['a|b'])).toThrow(RecordIdSerializationError);
+  });
+});
+
+describe('deserializeRecordId', () => {
+  it('single id → single-element array', () => {
+    expect(deserializeRecordId('42')).toEqual(['42']);
+  });
+
+  it('pipe string → multi-element array', () => {
+    expect(deserializeRecordId('id1|id2')).toEqual(['id1', 'id2']);
+  });
+
+  it('three segments', () => {
+    expect(deserializeRecordId('a|b|c')).toEqual(['a', 'b', 'c']);
+  });
+
+  // deserialize stays permissive (bare split). Empty segments from a malformed wire value are
+  // rejected at the validation boundaries that consume the result, not here.
+  it('over-splits a raw value containing the reserved pipe (rejected at the boundary, not here)', () => {
+    expect(deserializeRecordId('a|b|c')).toEqual(['a', 'b', 'c']);
+    expect(deserializeRecordId('a|')).toEqual(['a', '']);
+  });
+});