@xemahq/dsl 0.6.1 → 0.8.0

package/src/workflow/lib/compiler/compile.ts

@@ -6,6 +6,7 @@ import {
   type ActionRef,
   type Briefcase,
   type CompiledJob,
+  type CompiledManifestSource,
   type CompiledRun,
   type PermissionResource,
   type PermissionScope,
@@ -75,7 +76,8 @@ import type {
  *   8. Emit CompiledRun with a deterministic sha256.
  */
 export function compileWorkflow(input: CompileInput): CompiledRun {
-  const { workflowRef, trigger, resolvedRefs, workflowDefinitionVersionSha256 } = input;
+  const { workflowRef, trigger, resolvedRefs, workflowDefinitionContentHash } =
+    input;
 
   // Fold `defaults.gate` into every decision-gate job's `with:` BEFORE any
   // other pass — expression validation, needs-shape validation, and the
@@ -83,7 +85,11 @@ export function compileWorkflow(input: CompileInput): CompiledRun {
   // like inline-authored values. Explicit per-gate keys always win.
   const workflow = applyGateDefaults(input.workflow, resolvedRefs);
 
-  const inputs = bindTriggerInputs(workflow, trigger, input.previewMode ?? false);
+  const inputs = bindTriggerInputs(
+    workflow,
+    trigger,
+    input.previewMode ?? false,
+  );
   const vars: Readonly<Record<string, unknown>> = workflow.vars ?? {};
 
   // W5 definition-vs-run boundary: the CompiledRun is the single
@@ -103,7 +109,12 @@ export function compileWorkflow(input: CompileInput): CompiledRun {
     ...(workflow.requires?.wallets ?? []),
   ]) as readonly string[];
   const permissions = normalizePermissions(workflow.permissions);
-  const concurrency = compileConcurrency(workflow.concurrency, trigger, inputs, vars);
+  const concurrency = compileConcurrency(
+    workflow.concurrency,
+    trigger,
+    inputs,
+    vars,
+  );
   const defaults = resolveWorkflowDefaults(workflow.defaults);
 
   // Validate every expression everywhere at compile time. We throw away the
@@ -161,7 +172,10 @@ export function compileWorkflow(input: CompileInput): CompiledRun {
   // job's declared deliverable spec. Skips when the engine couldn't
   // pre-fetch spec content (preview mode or specs without introspectable
   // shape).
-  validateDeliverableValueExpressions(workflow, input.resolvedDeliverableSpecs ?? {});
+  validateDeliverableValueExpressions(
+    workflow,
+    input.resolvedDeliverableSpecs ?? {},
+  );
 
   // Payload reach-in validation: `needs.<X>.outputs.<name>.<field>`
   // chains where `<field>` is not an ArtifactRef envelope field reach
@@ -189,128 +203,150 @@ export function compileWorkflow(input: CompileInput): CompiledRun {
     }),
   );
 
-  const compiledJobs: CompiledJob[] = orderedJobs.map(({ key, payload, needs }) => {
-    const resolved = lookupResolvedRef(payload.uses, resolvedRefs);
-    const actionRef: ActionRef = {
-      id: resolved.id,
-      version: resolved.version,
-      manifestSha256: resolved.manifestSha256,
-      executionKind: resolveJobExecutionKind(key, payload.with, resolved),
-      taskQueue: resolved.taskQueue,
-      actionKind: resolveActionKind(resolved),
-      isReusableWorkflow: resolved.isReusableWorkflow,
-      // Pin the manifest's `inputs:` schema into the compiled ref so the
-      // worker validates `with:` against the schema that was in effect at
-      // compile time — not whatever's currently published. Reusable
-      // workflows have their own `workflow_call.inputs`, validated by
-      // their own compile pass.
-      inputsSchema: resolved.isReusableWorkflow
-        ? null
-        : resolved.actionManifest?.spec.inputs ?? null,
-    };
-
-    const jobPermissions = normalizePermissions(payload.permissions);
-    assertJobPermissionsFit(jobPermissions, permissions, key);
-
-    const strategy = compileStrategy(payload.strategy, key);
-
-    // When the job uses a reusable workflow, mount planning is governed
-    // by the reusable workflow's own jobs, not by this job. So we emit an
-    // empty plan — the child workflow's compiler run will produce its own.
-    const mountPlan = resolved.isReusableWorkflow
-      ? { readOnly: {}, readWrite: {} }
-      : compileMountPlan(key, payload.with, resolved.actionManifest);
-
-    // For agent-shaped actions, pre-resolve the manifest source so the
-    // worker sees a single discriminated shape (`ref` / `inline` /
-    // `inline-deferred`) instead of branching on input fields at
-    // dispatch. Reusable-workflow jobs return null — their nested
-    // CompiledRun owns its own agent steps.
-    const manifestSource = resolved.isReusableWorkflow
+  const manifestSourcesByJob: Record<string, CompiledManifestSource | null> =
+    {};
+  for (const [jobKey, job] of Object.entries(workflow.jobs)) {
+    const resolved = lookupResolvedRef(job.uses, resolvedRefs);
+    manifestSourcesByJob[jobKey] = resolved.isReusableWorkflow
       ? null
-      : compileManifestSource(key, payload.with, resolved.actionManifest);
+      : compileManifestSource(
+          jobKey,
+          job.with,
+          resolved.actionManifest,
+          input.resolvedAgents ?? {},
+        );
+  }
 
-    const retry = resolveJobRetry(
-      defaults.retry,
-      resolved.actionManifest?.spec.retryDefaults ?? null,
-      payload.retry,
-    );
-    const timeoutMs = resolveJobTimeout(
-      defaults.timeoutMs,
-      resolved.actionManifest?.spec.timeoutDefaults ?? null,
-      payload.timeout,
-    );
+  const compiledJobs: CompiledJob[] = orderedJobs.map(
+    ({ key, payload, needs }) => {
+      const resolved = lookupResolvedRef(payload.uses, resolvedRefs);
+      const actionRef: ActionRef = {
+        id: resolved.id,
+        version: resolved.version,
+        manifestSha256: resolved.manifestSha256,
+        executionKind: resolveJobExecutionKind(key, payload.with, resolved),
+        taskQueue: resolved.taskQueue,
+        actionKind: resolveActionKind(resolved),
+        isReusableWorkflow: resolved.isReusableWorkflow,
+        // Pin the manifest's `inputs:` schema into the compiled ref so the
+        // worker validates `with:` against the schema that was in effect at
+        // compile time — not whatever's currently published. Reusable
+        // workflows have their own `workflow_call.inputs`, validated by
+        // their own compile pass.
+        inputsSchema: resolved.isReusableWorkflow
+          ? null
+          : (resolved.actionManifest?.spec.inputs ?? null),
+      };
 
-    // Validate `if` expression shape now — runtime evaluator only fails on
-    // unknown bindings after this point. Shorthand: rewrite a
-    // bare `needs.<X>` reference to `needs.<X>.outcome == 'ok'` so the
-    // evaluator sees the explicit success check (an envelope object is
-    // truthy even on failure — silent always-true is the trap this
-    // rewrite explicitly avoids).
-    const ifExpression = payload.if !== undefined
-      ? (() => {
-          const body = stripInterpolation(payload.if!);
-          const rewritten = rewriteBareNeedsInIf(body);
-          compileExpression(rewritten);
-          return rewritten;
-        })()
-      : null;
-
-    // For `xema/review@*` steps, rewrite `with:` from the author shape
-    // (`subject` + `redraft.step`) to the worker contract
-    // (`subjects` + embedded `redraft: { uses, with }`). Other steps
-    // pass through verbatim.
-    const compiledWith = rewriteReviewStepWith(key, payload, workflow);
-
-    // Compile-time installation-binding gate: when the engine threaded
-    // an installationScope through CompileInput, walk every literal
-    // `x-installation-resource` field in the `with:` block and confirm
-    // its value is bound to the calling installation. Rejects unbound
-    // walletIds (etc.) BEFORE the dispatch creates a run, instead of
-    // failing 3 activities later when connector-gateway-api refuses to
-    // mint credentials. Skips entirely for system / org-wide dispatches.
-    validateInstallationResourceBindings({
-      jobKey: key,
-      actionId: actionRef.id,
-      inputsSchema: actionRef.inputsSchema,
-      withValue: compiledWith,
-      scope: input.installationScope,
-    });
+      const jobPermissions = normalizePermissions(payload.permissions);
+      assertJobPermissionsFit(jobPermissions, permissions, key);
+
+      const strategy = compileStrategy(payload.strategy, key);
+
+      // When the job uses a reusable workflow, mount planning is governed
+      // by the reusable workflow's own jobs, not by this job. So we emit an
+      // empty plan — the child workflow's compiler run will produce its own.
+      const mountPlan = resolved.isReusableWorkflow
+        ? { readOnly: {}, readWrite: {} }
+        : compileMountPlan(key, payload.with, resolved.actionManifest);
+
+      // For agent-shaped actions, pre-resolve the manifest source so the
+      // worker sees one immutable revision pin or an explicitly deferred
+      // expression instead of branching on authoring selectors at dispatch.
+      // Reusable-workflow jobs return null — their nested CompiledRun owns its
+      // own agent steps.
+      const manifestSource = manifestSourcesByJob[key] ?? null;
+
+      const retry = resolveJobRetry(
+        defaults.retry,
+        resolved.actionManifest?.spec.retryDefaults ?? null,
+        payload.retry,
+      );
+      const timeoutMs = resolveJobTimeout(
+        defaults.timeoutMs,
+        resolved.actionManifest?.spec.timeoutDefaults ?? null,
+        payload.timeout,
+      );
 
-    return Object.freeze({
-      jobKey: key,
-      title: payload.title ?? null,
-      needs,
-      matrixGather: Object.freeze([...(payload.matrixGather ?? [])]) as readonly string[],
-      ifExpression,
-      strategy,
-      action: actionRef,
-      mountPlan,
-      manifestSource,
-      with: Object.freeze({ ...compiledWith }) as Readonly<Record<string, unknown>>,
-      // Strip the `${{ ... }}` wrapper at compile time so the runtime
-      // evaluator receives expression bodies directly — same convention
-      // as `ifExpression`. `validateAllAuthoredExpressions` already
-      // compiled each body to surface invalid expressions as DSL errors.
-      outputs: compileOutputsMap(payload.outputs, `jobs.${key}.outputs`),
-      retry,
-      timeoutMs,
-      permissions: jobPermissions,
-      // The DSL emits null; the engine (which owns the reusable-workflow
-      // registry) post-processes each CompiledRun and attaches the nested
-      // compiled body for jobs whose action is a reusable workflow.
-      reusableCompiledRun: null,
-      payloadReachIns: Object.freeze(
-        collectPayloadReachInsForJob(
-          workflow,
-          key,
-          payload,
-          input.resolvedDeliverableSpecs ?? {},
-          resolvedRefs,
+      // Validate `if` expression shape now — runtime evaluator only fails on
+      // unknown bindings after this point. Shorthand: rewrite a
+      // bare `needs.<X>` reference to `needs.<X>.outcome == 'ok'` so the
+      // evaluator sees the explicit success check (an envelope object is
+      // truthy even on failure — silent always-true is the trap this
+      // rewrite explicitly avoids).
+      const ifExpression =
+        payload.if !== undefined
+          ? (() => {
+              const body = stripInterpolation(payload.if!);
+              const rewritten = rewriteBareNeedsInIf(body);
+              compileExpression(rewritten);
+              return rewritten;
+            })()
+          : null;
+
+      // For `xema/review@*` steps, rewrite `with:` from the author shape
+      // (`subject` + `redraft.step`) to the worker contract
+      // (`subjects` + embedded `redraft: { uses, with }`). Other steps
+      // pass through verbatim.
+      const compiledWith = attachResolvedReviewerPins(
+        rewriteReviewStepWith(key, payload, workflow, manifestSourcesByJob),
+        input.resolvedAgents ?? {},
+      );
+
+      // Compile-time installation-binding gate: when the engine threaded
+      // an installationScope through CompileInput, walk every literal
+      // `x-installation-resource` field in the `with:` block and confirm
+      // its value is bound to the calling installation. Rejects unbound
+      // walletIds (etc.) BEFORE the dispatch creates a run, instead of
+      // failing 3 activities later when connector-gateway-api refuses to
+      // mint credentials. Skips entirely for system / org-wide dispatches.
+      validateInstallationResourceBindings({
+        jobKey: key,
+        actionId: actionRef.id,
+        inputsSchema: actionRef.inputsSchema,
+        withValue: compiledWith,
+        scope: input.installationScope,
+      });
+
+      return Object.freeze({
+        jobKey: key,
+        title: payload.title ?? null,
+        needs,
+        matrixGather: Object.freeze([
+          ...(payload.matrixGather ?? []),
+        ]) as readonly string[],
+        ifExpression,
+        strategy,
+        action: actionRef,
+        mountPlan,
+        manifestSource,
+        with: Object.freeze({ ...compiledWith }) as Readonly<
+          Record<string, unknown>
+        >,
+        // Strip the `${{ ... }}` wrapper at compile time so the runtime
+        // evaluator receives expression bodies directly — same convention
+        // as `ifExpression`. `validateAllAuthoredExpressions` already
+        // compiled each body to surface invalid expressions as DSL errors.
+        outputs: compileOutputsMap(payload.outputs, `jobs.${key}.outputs`),
+        retry,
+        timeoutMs,
+        permissions: jobPermissions,
+        // The DSL emits null; the engine (which owns the reusable-workflow
+        // registry) post-processes each CompiledRun and attaches the nested
+        // compiled body for jobs whose action is a reusable workflow.
+        reusableCompiledRun: null,
+        payloadReachIns: Object.freeze(
+          collectPayloadReachInsForJob(
+            workflow,
+            key,
+            payload,
+            input.resolvedDeliverableSpecs ?? {},
+            resolvedRefs,
+          ),
         ),
-      ),
-    }) as CompiledJob;
-  });
+      }) as CompiledJob;
+    },
+  );
 
   const snapshotCreatedAt = input.trigger.triggeredAt;
   const workflowCallOutputs = compileOutputsMap(
@@ -332,7 +368,7 @@ export function compileWorkflow(input: CompileInput): CompiledRun {
     defaults,
     jobs: Object.freeze(compiledJobs) as readonly CompiledJob[],
     snapshotCreatedAt,
-    workflowDefinitionVersionSha256,
+    workflowDefinitionContentHash,
     workflowCallOutputs,
     workflowOutputs,
     // Spread only when present so a run dispatched without a briefcase
@@ -593,6 +629,24 @@ function validateJobLiteralReferences(
         resolvedAgents,
       );
       validateReviewerAgents(jobKey, withMap['reviewers'], resolvedAgents);
+      validateReviewerAgents(jobKey, withMap['recipients'], resolvedAgents);
+      const escalationChain = withMap['escalationChain'];
+      if (Array.isArray(escalationChain)) {
+        for (let i = 0; i < escalationChain.length; i++) {
+          const step = escalationChain[i];
+          if (
+            step !== null &&
+            typeof step === 'object' &&
+            !Array.isArray(step)
+          ) {
+            validateReviewerAgents(
+              jobKey,
+              (step as Readonly<Record<string, unknown>>)['recipients'],
+              resolvedAgents,
+            );
+          }
+        }
+      }
     }
     if (resolvedSpecs) {
       assertLiteralDeliverableSpec(
@@ -626,12 +680,84 @@ function validateReviewerAgents(
     assertLiteralAgent(
       jobKey,
       `with.reviewers[${i}].agentRef`,
-      (reviewer as Record<string, unknown>)['agentRef'],
+      (
+        (reviewer as Record<string, unknown>)['target'] as
+          | Readonly<Record<string, unknown>>
+          | undefined
+      )?.['agentRef'] ?? (reviewer as Record<string, unknown>)['agentRef'],
       resolvedAgents,
     );
   }
 }
 
+/**
+ * Freeze literal Agent recipients at compile time. Reviewer/decision-gate
+ * targets are independent Agent invocations, so their authored `agentRef`
+ * selector must not survive as the runtime identity. The pin travels inside
+ * the target (whose action schema deliberately permits extension fields) and
+ * is copied into AgentDeciderActivity input by the deterministic workflow.
+ */
+function attachResolvedReviewerPins(
+  withBlock: Readonly<Record<string, unknown>>,
+  resolvedAgents: Readonly<Record<string, ResolvedAgentMeta>>,
+): Readonly<Record<string, unknown>> {
+  const pinRecipients = (value: unknown): unknown => {
+    if (!Array.isArray(value)) return value;
+    return value.map((recipient) => {
+      if (
+        recipient === null ||
+        typeof recipient !== 'object' ||
+        Array.isArray(recipient)
+      ) {
+        return recipient;
+      }
+      const record = recipient as Readonly<Record<string, unknown>>;
+      if (record['kind'] !== 'agent') return recipient;
+      const target = record['target'];
+      if (
+        target === null ||
+        typeof target !== 'object' ||
+        Array.isArray(target)
+      ) {
+        return recipient;
+      }
+      const targetRecord = target as Readonly<Record<string, unknown>>;
+      const agentRef = targetRecord['agentRef'];
+      if (!isLiteralStringValue(agentRef)) return recipient;
+      const resolved = resolvedAgents[agentRef];
+      if (resolved === undefined) return recipient;
+      return Object.freeze({
+        ...record,
+        target: Object.freeze({
+          ...targetRecord,
+          agentRevisionPin: Object.freeze({
+            agentRevisionId: resolved.agentRevisionId,
+            agentContentHash: resolved.agentContentHash,
+            agentSlug: resolved.slug,
+          }),
+        }),
+      });
+    });
+  };
+
+  const out: Record<string, unknown> = { ...withBlock };
+  if ('reviewers' in out) out['reviewers'] = pinRecipients(out['reviewers']);
+  if ('recipients' in out) out['recipients'] = pinRecipients(out['recipients']);
+  if (Array.isArray(out['escalationChain'])) {
+    out['escalationChain'] = out['escalationChain'].map((step) => {
+      if (step === null || typeof step !== 'object' || Array.isArray(step)) {
+        return step;
+      }
+      const record = step as Readonly<Record<string, unknown>>;
+      return Object.freeze({
+        ...record,
+        recipients: pinRecipients(record['recipients']),
+      });
+    });
+  }
+  return Object.freeze(out);
+}
+
 /**
  * Match the literal/expression policy used by `validateAllAuthoredExpressions`:
  * a value is "literal" when it is a string that does NOT contain `${{`. The
@@ -651,31 +777,22 @@ function assertLiteralAgent(
   if (!isLiteralStringValue(value)) {
     return;
   }
-  // `value` is an `agentRef`: a `<slug>` or `<slug>@<version>` reference.
-  // `resolvedAgents` is keyed by bare slug, so parse the slug segment off
-  // before the existence check. This is the single agent-naming path.
-  const slug = agentRefSlug(value);
-  if (resolvedAgents[slug] !== undefined) {
+  if (resolvedAgents[value] !== undefined) {
     return;
   }
   const knownPreview = formatKnownPreview(Object.keys(resolvedAgents));
   throw new WorkflowDslError(
     WorkflowErrorCode.DSL_UNKNOWN_AGENT,
     `Job '${jobKey}' ${fieldPath} = '${value}' is not a registered agent. Known: [${knownPreview}].`,
-    { jobKey, fieldPath, value, knownCount: Object.keys(resolvedAgents).length },
+    {
+      jobKey,
+      fieldPath,
+      value,
+      knownCount: Object.keys(resolvedAgents).length,
+    },
   );
 }
 
-/**
- * Parse the bare slug off an `agentRef`. An `agentRef` is either a
- * `<slug>` or a `<slug>@<version>` reference; `resolvedAgents` is keyed
- * by bare slug.
- */
-function agentRefSlug(ref: string): string {
-  const at = ref.indexOf('@');
-  return at === -1 ? ref : ref.slice(0, at);
-}
-
 function assertLiteralDeliverableSpec(
   jobKey: string,
   fieldPath: string,
@@ -816,11 +933,19 @@ function compileOutputsMap(
  */
 function compileWorkflowOutputs(
   workflow: WorkflowDocument,
-): Readonly<Record<string, import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor>> {
+): Readonly<
+  Record<
+    string,
+    import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor
+  >
+> {
   const raw = workflow.outputs;
   if (!raw || Object.keys(raw).length === 0) {
     return Object.freeze({}) as Readonly<
-      Record<string, import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor>
+      Record<
+        string,
+        import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor
+      >
     >;
   }
   const seenSlugs = new Set<string>();
@@ -841,7 +966,11 @@ function compileWorkflowOutputs(
       throw new WorkflowDslError(
         WorkflowErrorCode.DSL_SEMANTIC_INVALID,
         `outputs.${name}: job "${decl.fromJob}" does not declare an output named "${decl.fromOutput}"`,
-        { outputName: name, fromJob: decl.fromJob, fromOutput: decl.fromOutput },
+        {
+          outputName: name,
+          fromJob: decl.fromJob,
+          fromOutput: decl.fromOutput,
+        },
       );
     }
     if (seenSlugs.has(decl.slug)) {
@@ -881,7 +1010,10 @@ function compileWorkflowOutputs(
     }
   }
   return Object.freeze(compiled) as Readonly<
-    Record<string, import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor>
+    Record<
+      string,
+      import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor
+    >
   >;
 }
 
@@ -912,7 +1044,11 @@ function validateMatrixGather(doc: WorkflowDocument): void {
           { jobKey, target },
         );
       }
-      if (!targetDecl.strategy || (!('matrix' in targetDecl.strategy) && !('dynamic' in targetDecl.strategy))) {
+      if (
+        !targetDecl.strategy ||
+        (!('matrix' in targetDecl.strategy) &&
+          !('dynamic' in targetDecl.strategy))
+      ) {
         throw new WorkflowDslError(
           WorkflowErrorCode.DSL_SEMANTIC_INVALID,
           `Job '${jobKey}' matrixGather references '${target}' which has no matrix/dynamic strategy; gathering only makes sense across matrix entries.`,
@@ -1189,7 +1325,8 @@ function validateNeedsAccess(
   }
 
   const keyBy = isDynamicMatrix
-    ? (upstream.strategy as { dynamic: { keyBy?: string } }).dynamic.keyBy ?? null
+    ? ((upstream.strategy as { dynamic: { keyBy?: string } }).dynamic.keyBy ??
+      null)
     : null;
 
   // Bare `needs.X.outputs` is always OK — consumer chooses to receive
@@ -1199,7 +1336,13 @@ function validateNeedsAccess(
   const head = access.steps[0]!;
 
   if (head.kind === 'member' && head.name === 'byKey') {
-    validateByKeyChain(access, keyBy, consumerJobKey, consumerBinding, fieldPath);
+    validateByKeyChain(
+      access,
+      keyBy,
+      consumerJobKey,
+      consumerBinding,
+      fieldPath,
+    );
     return;
   }
 
@@ -1373,7 +1516,10 @@ function collectMatrixMemberPath(
 
 function assertStrategyInvariants(compiled: CompiledRun): void {
   for (const job of compiled.jobs) {
-    if (job.strategy.kind === MatrixStrategyKind.STATIC && job.strategy.entries.length === 0) {
+    if (
+      job.strategy.kind === MatrixStrategyKind.STATIC &&
+      job.strategy.entries.length === 0
+    ) {
       throw new WorkflowDslError(
         WorkflowErrorCode.DSL_SEMANTIC_INVALID,
         `Job '${job.jobKey}' static strategy expansion produced zero entries.`,
@@ -1384,7 +1530,8 @@ function assertStrategyInvariants(compiled: CompiledRun): void {
 
   // Permission escalation is already checked per-job. Cycle checked in DAG.
   // No-op placeholder kept explicit for the next author.
-  const _permissionRef: Readonly<Record<PermissionResource, PermissionScope>> = compiled.permissions;
+  const _permissionRef: Readonly<Record<PermissionResource, PermissionScope>> =
+    compiled.permissions;
   void _permissionRef;
 }
 
@@ -1408,7 +1555,13 @@ function validateDeliverableValueExpressions(
     for (const { source, fieldPath } of expressions) {
       const ast = compileExpression(source);
       walkDeliverableAccesses(ast, (access) => {
-        validateDeliverableAccess(doc, jobKey, fieldPath, access, resolvedSpecs);
+        validateDeliverableAccess(
+          doc,
+          jobKey,
+          fieldPath,
+          access,
+          resolvedSpecs,
+        );
       });
     }
   }

package/src/workflow/lib/compiler/concurrency.ts

@@ -147,7 +147,7 @@ function buildConcurrencyContext(
           kind: actorKindFromTrigger(trigger),
         },
       },
-      workflow: { key: '', version: '' },
+      workflow: { key: '', revisionNumber: 0 },
       job: { key: '', attempt: 0 },
     },
   };

package/src/workflow/lib/compiler/manifest-source.ts

@@ -6,6 +6,7 @@ import {
 import { WorkflowDslError } from '../errors';
 import { ANY_INTERPOLATION_RE } from '../expression/interpolation';
 import type { ActionManifest } from '../types';
+import type { ResolvedAgentMeta } from './types';
 import { isAgentShapedAction } from './action-shape';
 
 /**
@@ -14,11 +15,11 @@ import { isAgentShapedAction } from './action-shape';
  * `agentRef` is the SOLE way a workflow names its agent. Terminal shapes:
  *   • `null` — non-agent action (the action manifest doesn't expose
  *     `agentRef` on its `inputs:` schema).
- *   • `{ kind: 'ref', ref }` — `agentRef` is a literal string. The
- *     activity resolves the Agent it names at boot.
- *   • `{ kind: 'inline-deferred' }` — `agentRef` is a `${{ … }}`
- *     expression that must be evaluated per dispatch. The worker resolves
- *     the named Agent after expression evaluation.
+ *   • `{ kind: 'revision', ...pin }` — `agentRef` is a literal string
+ *     already resolved by the engine to an immutable Agent revision.
+ *   • `{ kind: 'deferred' }` — `agentRef` is a `${{ … }}` expression.
+ *     The worker records one immutable resolution in Temporal history after
+ *     expression evaluation and before scheduling the Agent activity.
  *
  * An agent-shaped action with no `agentRef` fails fast — there is no
  * inline `mounts` short-form anymore.
@@ -27,6 +28,7 @@ export function compileManifestSource(
   jobKey: string,
   withBlock: Readonly<Record<string, unknown>> | undefined,
   actionManifest: ActionManifest | null,
+  resolvedAgents: Readonly<Record<string, ResolvedAgentMeta>>,
 ): CompiledManifestSource | null {
   if (!isAgentShapedAction(actionManifest)) return null;
   const block = withBlock ?? {};
@@ -34,13 +36,26 @@ export function compileManifestSource(
   const ref = block['agentRef'];
   if (typeof ref === 'string' && ref.length > 0) {
     if (isLiteralString(ref)) {
-      return Object.freeze({ kind: 'ref' as const, ref });
+      const resolved = resolvedAgents[ref];
+      if (resolved === undefined) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_UNKNOWN_AGENT,
+          `Job '${jobKey}' with.agentRef = '${ref}' was not resolved to an immutable Agent revision.`,
+          { jobKey, fieldPath: 'with.agentRef', value: ref },
+        );
+      }
+      return Object.freeze({
+        kind: 'revision' as const,
+        agentRevisionId: resolved.agentRevisionId,
+        agentContentHash: resolved.agentContentHash,
+        agentSlug: resolved.slug,
+      });
     }
-    return Object.freeze({ kind: 'inline-deferred' as const });
+    return Object.freeze({ kind: 'deferred' as const });
   }
   if (ref !== undefined) {
     // ref is present but not a literal string → expression.
-    return Object.freeze({ kind: 'inline-deferred' as const });
+    return Object.freeze({ kind: 'deferred' as const });
   }
 
   throw new WorkflowDslError(