@xemahq/dsl 0.1.1

package/src/workflow/lib/compiler/payload-reach-in.ts

@@ -0,0 +1,497 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Payload reach-in validation (plan §C.1) ──
+//
+// Workflow YAML supports two flavours of `needs.<X>.outputs.<name>.<field>`:
+//
+//   1. Envelope-field access — `<field>` is one of
+//      {artifactId, versionId, version, hash, type, title}. Free; the
+//      runtime reads it off the ArtifactRef without fetching bytes.
+//      Already works structurally via `readProperty` on the ref object.
+//
+//   2. Payload reach-in — `<field>` is a property on the bound
+//      deliverable spec's JSON Schema. Requires the runtime to
+//      pre-fetch the artifact's parsed payload into the per-step
+//      `payloadCache`. The compiler validates the path against the
+//      bound spec at compile time so authors get a clean DSL error
+//      instead of a runtime "Unknown property" surfacing as
+//      `DSL_EXPRESSION_INVALID`.
+//
+// This module owns family #2's compile-time checks. The actual runtime
+// pre-fetch is the worker's responsibility — see the plan section on
+// "Compile-time resolution (chosen approach)" — and is gated by the
+// engine wiring spec metadata into `ResolvedDeliverableSpec`. Until
+// that wiring lands for every spec, this validator gracefully skips
+// when it cannot prove typing (the runtime then fails fast via
+// `DSL_PAYLOAD_PARSE_ERROR` if the author insisted on a payload field
+// without a typed binding).
+// ═══════════════════════════════════════════════════════════════════════════
+
+import {
+  isArtifactRefEnvelopeField,
+  WorkflowErrorCode,
+  type PayloadReachInPin,
+} from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import {
+  compileExpression,
+  ExpressionNodeKind,
+  stripInterpolation,
+  type ExpressionNode,
+  extractInterpolations,
+} from '../expression';
+import type { WorkflowDocument } from '../types';
+import type { ResolvedDeliverableSpec, ResolvedRef } from './types';
+
+/**
+ * Lookup helper: given an upstream job (by key) and an output name,
+ * return the deliverable-spec ref the upstream activity manifest pins
+ * for that output, or `null` when the manifest declares no per-output
+ * binding for it. The compiler prefers this over `with.deliverableSpecRef`
+ * — per-output bindings are activity-declared contracts; the job-level
+ * `with.deliverableSpecRef` is the workflow-author chosen runtime spec
+ * (dynamic, e.g. for the agent activity). They can coexist on the same
+ * job; the per-output binding wins for outputs it covers.
+ */
+function lookupOutputBindingSpecRef(
+  upstream: WorkflowDocument['jobs'][string],
+  outputName: string,
+  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
+): string | null {
+  const ref = resolvedRefs[upstream.uses];
+  const bindings = ref?.actionManifest?.spec.outputBindings;
+  if (!bindings) return null;
+  const binding = bindings[outputName];
+  if (!binding) return null;
+  const specRef = binding.deliverableSpecRef;
+  if (typeof specRef !== 'string' || specRef.length === 0) return null;
+  return specRef;
+}
+
+/**
+ * Walk every authored expression and field-check
+ * `needs.<X>.outputs.<name>.<field>` reach-ins.
+ *
+ * Decision table for each `<name>.<field>`:
+ *   • `<field>` is an ArtifactRef envelope field → OK (no payload fetch).
+ *   • Upstream activity manifest declares `outputBindings.<name>.deliverableSpecRef`
+ *     (plan §B per-output binding) → use that spec; otherwise fall back
+ *     to the upstream job's `with.deliverableSpecRef`. Then:
+ *       - resolved spec has `topLevelKeys` and `<field>` is one → OK.
+ *       - resolved spec has `topLevelKeys` and `<field>` is NOT one →
+ *         `DSL_FIELD_NOT_IN_SCHEMA`.
+ *   • Neither per-output binding NOR `with.deliverableSpecRef` is set,
+ *     upstream has no `outputs:` projection, and no expression-shaped
+ *     ref → `DSL_FIELD_NOT_TYPED`.
+ *   • Otherwise (custom `outputs:` projection, expression-shaped ref,
+ *     unknown spec, non-introspectable kind) → skip; the runtime
+ *     evaluator + `payloadCache` will fail fast via
+ *     `DSL_PAYLOAD_PARSE_ERROR` if the path is ultimately invalid.
+ *
+ * The validator runs only when `resolvedSpecs` is non-empty — same
+ * opt-out convention as the rest of the compiler (preview-raw passes
+ * an empty map).
+ */
+export function validatePayloadReachIns(
+  doc: WorkflowDocument,
+  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
+  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
+): void {
+  if (Object.keys(resolvedSpecs).length === 0) return;
+
+  for (const [jobKey, job] of Object.entries(doc.jobs)) {
+    const expressions = collectJobExpressions(jobKey, job);
+    for (const { source, fieldPath } of expressions) {
+      const ast = compileExpression(source);
+      walkPayloadReachIns(ast, (access) => {
+        validateReachIn(
+          doc,
+          jobKey,
+          fieldPath,
+          access,
+          resolvedSpecs,
+          resolvedRefs,
+        );
+      });
+    }
+  }
+
+  const callOutputs = doc.on.workflow_call?.outputs;
+  if (callOutputs) {
+    for (const [outputName, expr] of Object.entries(callOutputs)) {
+      const ast = compileExpression(stripInterpolation(expr));
+      walkPayloadReachIns(ast, (access) => {
+        validateReachIn(
+          doc,
+          '<workflow_call.outputs>',
+          `on.workflow_call.outputs.${outputName}`,
+          access,
+          resolvedSpecs,
+          resolvedRefs,
+        );
+      });
+    }
+  }
+}
+
+/**
+ * Walk every reach-in for a single job and emit one pin per
+ * `(upstreamJobKey, specRef)` pair. Pins drive the runtime spec-version
+ * assertion (plan §C.1 risks-and-mitigations) — the worker pre-fetches
+ * the artifact and refuses to proceed when its `schemaVersion` doesn't
+ * match the pin's `specVersion`.
+ *
+ * Returns `[]` when the job has no resolvable reach-ins (no upstream
+ * spec, expression-shaped ref, or projected upstream `outputs:`).
+ */
+export function collectPayloadReachInsForJob(
+  doc: WorkflowDocument,
+  jobKey: string,
+  job: WorkflowDocument['jobs'][string],
+  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
+  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
+): readonly PayloadReachInPin[] {
+  if (Object.keys(resolvedSpecs).length === 0) return [];
+
+  const pins: PayloadReachInPin[] = [];
+  const seen = new Set<string>();
+
+  const expressions = collectJobExpressions(jobKey, job);
+  for (const { source, fieldPath } of expressions) {
+    let ast;
+    try {
+      ast = compileExpression(source);
+    } catch {
+      continue;
+    }
+    walkPayloadReachIns(ast, (access) => {
+      const pin = resolveReachInPin(
+        doc,
+        fieldPath,
+        access,
+        resolvedSpecs,
+        resolvedRefs,
+      );
+      if (pin === null) return;
+      const dedupeKey = `${pin.upstreamJobKey}|${pin.outputName}|${pin.specRef}`;
+      if (seen.has(dedupeKey)) return;
+      seen.add(dedupeKey);
+      pins.push(pin);
+    });
+  }
+
+  return pins;
+}
+
+/**
+ * Resolve one reach-in to a pin entry, returning `null` when the pin
+ * cannot be statically materialized (e.g. expression-shaped specRef,
+ * upstream has a custom `outputs:` projection, spec not in the resolved
+ * map). The validator emits the user-facing error path; this collector
+ * is silent on un-resolvable reach-ins because the validator already
+ * surfaced them.
+ */
+function resolveReachInPin(
+  doc: WorkflowDocument,
+  fieldPath: string,
+  access: PayloadReachIn,
+  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
+  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
+): PayloadReachInPin | null {
+  const upstream = doc.jobs[access.upstreamJobKey];
+  if (!upstream) return null;
+  if (upstream.outputs && Object.keys(upstream.outputs).length > 0) {
+    return null;
+  }
+
+  // Prefer per-output binding from the upstream activity manifest
+  // (plan §B). Falls back to the job-level `with.deliverableSpecRef`
+  // when no per-output binding is declared OR when the reach-in's
+  // outputName is one of the indexed sentinels.
+  let specRef: string | null = null;
+  let outputName: string | null = null;
+  if (
+    access.outputName !== '<indexed>' &&
+    access.outputName !== '<byKey>'
+  ) {
+    const perOutputRef = lookupOutputBindingSpecRef(
+      upstream,
+      access.outputName,
+      resolvedRefs,
+    );
+    if (perOutputRef !== null) {
+      specRef = perOutputRef;
+      outputName = access.outputName;
+    }
+  }
+  if (specRef === null) {
+    const withMap = upstream.with as Record<string, unknown> | undefined;
+    const fromWith = withMap?.['deliverableSpecRef'];
+    if (typeof fromWith !== 'string' || fromWith.length === 0) return null;
+    if (fromWith.includes('${{')) return null;
+    specRef = fromWith;
+  }
+
+  const spec = resolvedSpecs[specRef];
+  if (!spec) return null;
+  const at = specRef.lastIndexOf('@');
+  const specVersion = at >= 0 ? specRef.slice(at + 1) : '';
+  if (specVersion.length === 0) return null;
+  return {
+    fieldPath,
+    upstreamJobKey: access.upstreamJobKey,
+    outputName,
+    specRef,
+    specVersion,
+  };
+}
+
+interface CollectedExpression {
+  readonly source: string;
+  readonly fieldPath: string;
+}
+
+function collectJobExpressions(
+  jobKey: string,
+  job: WorkflowDocument['jobs'][string],
+): readonly CollectedExpression[] {
+  const out: CollectedExpression[] = [];
+  if (job.if !== undefined) {
+    out.push({ source: stripInterpolation(job.if), fieldPath: `${jobKey}.if` });
+  }
+  if (job.with) {
+    for (const ext of extractInterpolations(job.with, [jobKey, 'with'])) {
+      out.push({ source: ext.source, fieldPath: ext.path.join('.') });
+    }
+  }
+  if (job.outputs) {
+    for (const [name, expr] of Object.entries(job.outputs)) {
+      out.push({
+        source: stripInterpolation(expr),
+        fieldPath: `${jobKey}.outputs.${name}`,
+      });
+    }
+  }
+  if (job.strategy && 'dynamic' in job.strategy) {
+    out.push({
+      source: stripInterpolation(job.strategy.dynamic.from),
+      fieldPath: `${jobKey}.strategy.dynamic.from`,
+    });
+  }
+  return out;
+}
+
+interface PayloadReachIn {
+  readonly upstreamJobKey: string;
+  readonly outputName: string;
+  readonly field: string;
+}
+
+export function walkPayloadReachIns(
+  node: ExpressionNode,
+  visit: (access: PayloadReachIn) => void,
+): void {
+  const match = matchPayloadReachIn(node);
+  if (match !== null) {
+    visit(match);
+    // Continue recursion so nested expressions inside index nodes are
+    // also walked — e.g. byKey[needs.Y.outputs.foo.bar] would carry
+    // its own reach-in.
+  }
+  switch (node.kind) {
+    case ExpressionNodeKind.MEMBER:
+      walkPayloadReachIns(node.target, visit);
+      return;
+    case ExpressionNodeKind.INDEX:
+      walkPayloadReachIns(node.target, visit);
+      walkPayloadReachIns(node.index, visit);
+      return;
+    case ExpressionNodeKind.CALL:
+      // Skip `fromJSON(...)` and `toJSON(...)` arguments — those are
+      // the documented escape hatch; the author opted out of typed
+      // reach-in validation by wrapping the ref.
+      for (const arg of node.args) walkPayloadReachIns(arg, visit);
+      return;
+    case ExpressionNodeKind.UNARY_NOT:
+      walkPayloadReachIns(node.operand, visit);
+      return;
+    case ExpressionNodeKind.BINARY_EQ:
+    case ExpressionNodeKind.BINARY_NEQ:
+    case ExpressionNodeKind.BINARY_AND:
+    case ExpressionNodeKind.BINARY_OR:
+      walkPayloadReachIns(node.left, visit);
+      walkPayloadReachIns(node.right, visit);
+      return;
+    case ExpressionNodeKind.LITERAL:
+    case ExpressionNodeKind.IDENTIFIER:
+      return;
+  }
+}
+
+/**
+ * Match the outermost `needs.<X>.outputs.<name>.<field>` shape. Returns
+ * null if the chain doesn't match, OR if `<field>` is an envelope
+ * field (the runtime reads those off the ArtifactRef without a fetch).
+ *
+ * Also matches:
+ *   needs.<X>.outputs[N].<field>
+ *   needs.<X>.outputs.byKey['k'].<field>
+ *
+ * For these, `<name>` is set to a sentinel so the validator still
+ * resolves the upstream job's spec but doesn't attempt per-output
+ * name resolution (today's data model declares the spec at the
+ * job level, not per-output — see the plan's "B." section).
+ */
+function matchPayloadReachIn(node: ExpressionNode): PayloadReachIn | null {
+  if (node.kind !== ExpressionNodeKind.MEMBER) return null;
+  const field = node.property;
+  if (isArtifactRefEnvelopeField(field)) return null;
+
+  // Walk one level up: `<base>.<field>` where `<base>` must resolve to
+  // `needs.<X>.outputs.<name>` (or an indexed/keyed variant).
+  const base = node.target;
+
+  // Form A: needs.<X>.outputs.<name>.<field>
+  if (base.kind === ExpressionNodeKind.MEMBER) {
+    const outputName = base.property;
+    if (outputName === 'byKey') return null; // handled below
+    const outputsNode = base.target;
+    const upstreamKey = matchNeedsOutputsRoot(outputsNode);
+    if (upstreamKey !== null) {
+      return { upstreamJobKey: upstreamKey, outputName, field };
+    }
+  }
+
+  // Form B: needs.<X>.outputs[N].<field>  OR  needs.<X>.outputs.byKey['k'].<field>
+  if (base.kind === ExpressionNodeKind.INDEX) {
+    const indexed = base.target;
+    // outputs[N]
+    const upstreamFromOutputs = matchNeedsOutputsRoot(indexed);
+    if (upstreamFromOutputs !== null) {
+      return {
+        upstreamJobKey: upstreamFromOutputs,
+        outputName: '<indexed>',
+        field,
+      };
+    }
+    // outputs.byKey['k']
+    if (
+      indexed.kind === ExpressionNodeKind.MEMBER &&
+      indexed.property === 'byKey'
+    ) {
+      const upstreamFromByKey = matchNeedsOutputsRoot(indexed.target);
+      if (upstreamFromByKey !== null) {
+        return {
+          upstreamJobKey: upstreamFromByKey,
+          outputName: '<byKey>',
+          field,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Match the chain `needs.<X>.outputs`. Returns the upstream job key, or
+ * null if the node isn't that shape.
+ */
+function matchNeedsOutputsRoot(node: ExpressionNode): string | null {
+  if (node.kind !== ExpressionNodeKind.MEMBER) return null;
+  if (node.property !== 'outputs') return null;
+  const needsRoot = node.target;
+  if (needsRoot.kind !== ExpressionNodeKind.MEMBER) return null;
+  const upstreamKey = needsRoot.property;
+  const ident = needsRoot.target;
+  if (ident.kind !== ExpressionNodeKind.IDENTIFIER) return null;
+  if (ident.name !== 'needs') return null;
+  return upstreamKey;
+}
+
+function validateReachIn(
+  doc: WorkflowDocument,
+  consumerJobKey: string,
+  fieldPath: string,
+  access: PayloadReachIn,
+  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
+  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
+): void {
+  const upstream = doc.jobs[access.upstreamJobKey];
+  if (!upstream) {
+    // Topological-sort step already raises a clearer error for unknown
+    // upstreams; don't double-report here.
+    return;
+  }
+
+  // If the upstream declares an `outputs:` projection, it re-shapes the
+  // exposed namespace. We can't statically introspect arbitrary author
+  // projections, so skip — the projection itself is expression-validated
+  // upstream.
+  if (upstream.outputs && Object.keys(upstream.outputs).length > 0) {
+    return;
+  }
+
+  // Per-output binding from the upstream activity manifest (plan §B)
+  // wins over the job-level `with.deliverableSpecRef` when present.
+  const perOutputBinding =
+    access.outputName === '<indexed>' || access.outputName === '<byKey>'
+      ? null
+      : lookupOutputBindingSpecRef(upstream, access.outputName, resolvedRefs);
+
+  const withMap = upstream.with as Record<string, unknown> | undefined;
+  const specRef = perOutputBinding ?? withMap?.['deliverableSpecRef'];
+
+  // Expression-shaped spec → unknowable at compile time. Runtime
+  // surfaces `DSL_PAYLOAD_PARSE_ERROR` if reach-in is ultimately wrong.
+  if (typeof specRef === 'string' && specRef.includes('${{')) {
+    return;
+  }
+
+  if (typeof specRef !== 'string' || specRef.length === 0) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_FIELD_NOT_TYPED,
+      `${fieldPath}: 'needs.${access.upstreamJobKey}.outputs.${access.outputName}.${access.field}' reaches into the payload of an output that has no schema-bearing deliverable spec. Either bind a typed 'with.deliverableSpecRef' on '${access.upstreamJobKey}' or use the 'fromJSON(...)' escape hatch.`,
+      {
+        consumerJobKey,
+        upstreamJobKey: access.upstreamJobKey,
+        outputName: access.outputName,
+        field: access.field,
+        fieldPath,
+      },
+    );
+  }
+
+  const spec = resolvedSpecs[specRef];
+  if (!spec) {
+    // Engine couldn't resolve the spec (e.g. registry unreachable) —
+    // the existing literal-reference validator already emits
+    // `DSL_UNKNOWN_DELIVERABLE_SPEC` for this case; don't double-report.
+    return;
+  }
+  if (!spec.topLevelKeys || spec.topLevelKeys.length === 0) {
+    // Spec kind doesn't support static field introspection
+    // (DOCUMENT_TEMPLATE, STRUCTURED_JSON, CUSTOM, …). Defer to runtime.
+    return;
+  }
+  if (spec.topLevelKeys.includes(access.field)) {
+    // Valid reach-in. The runtime is responsible for pre-fetching this
+    // artifact's payload into the per-step `payloadCache` before the
+    // expression evaluates — see the plan's runtime-resolver scaffold.
+    return;
+  }
+
+  const knownPreview = spec.topLevelKeys.slice(0, 12).join(', ');
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_FIELD_NOT_IN_SCHEMA,
+    `${fieldPath}: 'needs.${access.upstreamJobKey}.outputs.${access.outputName}.${access.field}' is not a top-level field on deliverable spec '${spec.ref}' (bound by '${access.upstreamJobKey}.with.deliverableSpecRef'). Known fields: [${knownPreview}].`,
+    {
+      consumerJobKey,
+      upstreamJobKey: access.upstreamJobKey,
+      outputName: access.outputName,
+      field: access.field,
+      fieldPath,
+      specRef: spec.ref,
+      knownFields: [...spec.topLevelKeys],
+    },
+  );
+}

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

@@ -0,0 +1,64 @@
+import {
+  PermissionResource,
+  PermissionScope,
+  WorkflowErrorCode,
+} from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import type { WorkflowPermissions } from '../types';
+
+/** Scope strength ordering: stronger scopes dominate weaker ones. */
+const SCOPE_RANK: Readonly<Record<PermissionScope, number>> = Object.freeze({
+  [PermissionScope.NONE]: 0,
+  [PermissionScope.READ]: 1,
+  [PermissionScope.LIMITED]: 2,
+  [PermissionScope.WRITE]: 3,
+});
+
+/** Zero permissions — the platform-safe default when nothing is authored. */
+export const ZERO_PERMISSIONS: Readonly<Record<PermissionResource, PermissionScope>> =
+  Object.freeze({
+    [PermissionResource.REPOS]: PermissionScope.NONE,
+    [PermissionResource.KB]: PermissionScope.NONE,
+    [PermissionResource.BACKLOG]: PermissionScope.NONE,
+    [PermissionResource.INTEGRATIONS]: PermissionScope.NONE,
+    [PermissionResource.ARTIFACTS]: PermissionScope.NONE,
+    [PermissionResource.MEMORY]: PermissionScope.NONE,
+  });
+
+/** Fill an authored permission map with explicit NONE values for unset resources. */
+export function normalizePermissions(
+  authored: WorkflowPermissions | undefined,
+): Readonly<Record<PermissionResource, PermissionScope>> {
+  const base: Record<PermissionResource, PermissionScope> = { ...ZERO_PERMISSIONS };
+  if (!authored) return base;
+  for (const resource of Object.values(PermissionResource)) {
+    const scope = authored[resource];
+    if (scope !== undefined) {
+      base[resource] = scope;
+    }
+  }
+  return base;
+}
+
+/**
+ * Verify that `job` does not request stronger permissions than `workflow`.
+ * Fails fast with DSL_PERMISSION_ESCALATION on any escalation — rule 9
+ * (clean architecture), rule 2 (fail-fast).
+ */
+export function assertJobPermissionsFit(
+  jobPermissions: Readonly<Record<PermissionResource, PermissionScope>>,
+  workflowPermissions: Readonly<Record<PermissionResource, PermissionScope>>,
+  jobKey: string,
+): void {
+  for (const resource of Object.values(PermissionResource)) {
+    const jobScope = jobPermissions[resource];
+    const workflowScope = workflowPermissions[resource];
+    if (SCOPE_RANK[jobScope] > SCOPE_RANK[workflowScope]) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_PERMISSION_ESCALATION,
+        `Job '${jobKey}' requests ${jobScope} on ${resource} but workflow grants only ${workflowScope}.`,
+        { jobKey, resource, jobScope, workflowScope },
+      );
+    }
+  }
+}

package/src/workflow/lib/compiler/retry-timeout.ts

@@ -0,0 +1,105 @@
+import type {
+  CompiledDefaults,
+  CompiledRetryPolicy,
+} from '@xemahq/kernel-contracts/workflow';
+import type {
+  ActionManifestRetryDefaults,
+  ActionManifestTimeoutDefaults,
+  WorkflowDefaults,
+  WorkflowRetryDeclaration,
+} from '../types';
+import { parseDurationMs } from '../duration';
+
+// Default retry applied when neither the workflow nor the action declares
+// one. Deliberately conservative — one attempt, no backoff — so authors
+// opt into retry explicitly.
+const PLATFORM_DEFAULT_RETRY: CompiledRetryPolicy = {
+  maxAttempts: 1,
+  initialIntervalMs: 1_000,
+  backoffCoefficient: 2.0,
+  maximumIntervalMs: 60_000,
+  nonRetryableErrorTypes: [],
+};
+
+// Default job timeout: 1 hour. Agent activities that need more declare it
+// explicitly in their action manifest or in the job's timeout field.
+const PLATFORM_DEFAULT_TIMEOUT_MS = 3_600_000;
+
+/** Merge workflow-level defaults against platform baseline. */
+export function resolveWorkflowDefaults(
+  authored: WorkflowDefaults | undefined,
+): CompiledDefaults {
+  return {
+    retry: resolveRetry(authored?.retry, PLATFORM_DEFAULT_RETRY),
+    timeoutMs: authored?.timeout !== undefined
+      ? parseDurationMs(authored.timeout)
+      : PLATFORM_DEFAULT_TIMEOUT_MS,
+  };
+}
+
+/**
+ * Merge job-level retry against workflow-level + action-manifest-level
+ * defaults. Merge order: action manifest → workflow → job (most specific
+ * wins). Explicit; no "if null, skip" silent fallbacks.
+ */
+export function resolveJobRetry(
+  workflowDefault: CompiledRetryPolicy,
+  actionDefault: ActionManifestRetryDefaults | null,
+  jobOverride: WorkflowRetryDeclaration | undefined,
+): CompiledRetryPolicy {
+  const actionBaseline = actionDefault
+    ? fromActionManifestRetry(actionDefault)
+    : workflowDefault;
+
+  return resolveRetry(jobOverride, actionBaseline);
+}
+
+/**
+ * Resolve job-level timeout. Merge order: action manifest → workflow → job.
+ */
+export function resolveJobTimeout(
+  workflowDefaultMs: number,
+  actionDefault: ActionManifestTimeoutDefaults | null,
+  jobOverride: string | undefined,
+): number {
+  if (jobOverride !== undefined) {
+    return parseDurationMs(jobOverride);
+  }
+  if (actionDefault) {
+    return parseDurationMs(actionDefault.startToClose);
+  }
+  return workflowDefaultMs;
+}
+
+function resolveRetry(
+  override: WorkflowRetryDeclaration | undefined,
+  baseline: CompiledRetryPolicy,
+): CompiledRetryPolicy {
+  if (!override) return baseline;
+  return {
+    maxAttempts: override.maxAttempts ?? baseline.maxAttempts,
+    initialIntervalMs:
+      override.initialInterval !== undefined
+        ? parseDurationMs(override.initialInterval)
+        : baseline.initialIntervalMs,
+    backoffCoefficient:
+      override.backoffCoefficient ?? baseline.backoffCoefficient,
+    maximumIntervalMs:
+      override.maximumInterval !== undefined
+        ? parseDurationMs(override.maximumInterval)
+        : baseline.maximumIntervalMs,
+    nonRetryableErrorTypes: override.nonRetryableErrorTypes !== undefined
+      ? [...override.nonRetryableErrorTypes]
+      : [...baseline.nonRetryableErrorTypes],
+  };
+}
+
+function fromActionManifestRetry(retry: ActionManifestRetryDefaults): CompiledRetryPolicy {
+  return {
+    maxAttempts: retry.maxAttempts,
+    initialIntervalMs: parseDurationMs(retry.initialInterval),
+    backoffCoefficient: retry.backoffCoefficient,
+    maximumIntervalMs: parseDurationMs(retry.maximumInterval),
+    nonRetryableErrorTypes: retry.nonRetryableErrorTypes !== undefined ? [...retry.nonRetryableErrorTypes] : [],
+  };
+}