@xemahq/dsl 0.1.1

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

@@ -0,0 +1,176 @@
+import {
+  WorkflowErrorCode,
+  isAgentRunRole,
+  type CompiledManifestSource,
+} from '@xemahq/kernel-contracts/workflow';
+import { compileManifest } from '../../../workspace-manifest';
+
+import { WorkflowDslError } from '../errors';
+import { ANY_INTERPOLATION_RE } from '../expression/interpolation';
+import type { ActionManifest } from '../types';
+import { isAgentShapedAction } from './action-shape';
+
+/**
+ * `metadata.version` on the synthesized envelope must satisfy the
+ * workspace-manifest-dsl semver regex. We use a static placeholder
+ * since the inline manifest never enters the manifests-api catalog —
+ * it lives in-process for the lifetime of the snapshot.
+ */
+const INLINE_MANIFEST_VERSION = '0.0.0';
+
+/**
+ * Compute the compile-time `manifestSource` discriminator for one job.
+ *
+ * Three terminal shapes:
+ *   • `null` — non-agent action (the action manifest doesn't expose
+ *     `compositionRef` + `mounts` on its `inputs:` schema).
+ *   • `{ kind: 'ref', ref }` — long-form ref is a literal string. The
+ *     activity resolves the Agent Composition it names at boot.
+ *   • `{ kind: 'inline', compiled }` — short-form mounts and every
+ *     value the inline manifest depends on (`agentSlug`, `phaseKey`
+ *     (YAML field — mapped onto kernel `groupKey`), `deliverableSpecRef`,
+ *     every entry of `mounts`) are YAML literals.
+ *     We synthesize a `WorkspaceManifest` envelope and feed it through
+ *     `compileManifest()` once at workflow compile so the worker skips
+ *     both the DB round-trip and the runtime synthesis.
+ *   • `{ kind: 'inline-deferred' }` — at least one of the inputs above
+ *     is a `${{ … }}` expression that must be evaluated per dispatch.
+ *     The worker keeps today's runtime-synthesis path for these.
+ *
+ * The `oneOf` invariant (exactly one of `compositionRef` / `mounts`) is
+ * enforced upstream by `enforceManifestSourceDiscriminator` in
+ * `mount-plan.ts`. By the time we get here that pair is already known
+ * to be well-formed, so this function only branches between
+ * literal-vs-expression.
+ */
+export function compileManifestSource(
+  jobKey: string,
+  withBlock: Readonly<Record<string, unknown>> | undefined,
+  actionManifest: ActionManifest | null,
+): CompiledManifestSource | null {
+  if (!isAgentShapedAction(actionManifest)) return null;
+  const block = withBlock ?? {};
+
+  const ref = block['compositionRef'];
+  if (typeof ref === 'string' && ref.length > 0) {
+    if (isLiteralString(ref)) {
+      return Object.freeze({ kind: 'ref' as const, ref });
+    }
+    return Object.freeze({ kind: 'inline-deferred' as const });
+  }
+  if (ref !== undefined) {
+    // ref is present but not a literal string → expression.
+    return Object.freeze({ kind: 'inline-deferred' as const });
+  }
+
+  // Mounts path. Caller has already asserted `mounts` is set.
+  const mounts = block['mounts'];
+  if (containsExpressions(mounts)) {
+    return Object.freeze({ kind: 'inline-deferred' as const });
+  }
+
+  const agentSlug = block['agentSlug'];
+  const phaseKey = block['phaseKey'];
+  const deliverableSpecRef = block['deliverableSpecRef'];
+  const roleRaw = block['role'];
+  if (
+    !isLiteralString(agentSlug) ||
+    !isLiteralStringOrUndefined(phaseKey) ||
+    !isLiteralStringOrNullOrUndefined(deliverableSpecRef) ||
+    !isLiteralStringOrUndefined(roleRaw)
+  ) {
+    return Object.freeze({ kind: 'inline-deferred' as const });
+  }
+
+  if (typeof roleRaw !== 'string' || !isAgentRunRole(roleRaw)) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Job '${jobKey}' uses inline 'mounts:' but its 'with.role' is missing or not a canonical AgentRunRole. ` +
+        `Declare 'role' explicitly (e.g. 'unit-worker', 'coordinator', 'gate-reviewer'); the action schema enforces this at compile time.`,
+      { jobKey, actionId: actionManifest.metadata.id },
+    );
+  }
+  const role = roleRaw;
+  const envelope = synthesizeInlineManifestEnvelope({
+    agentSlug,
+    phaseKey: typeof phaseKey === 'string' ? phaseKey : null,
+    role,
+    deliverableSpecRef:
+      typeof deliverableSpecRef === 'string' ? deliverableSpecRef : null,
+    mounts: mounts as Readonly<Record<string, unknown>>,
+  });
+  const result = compileManifest(envelope, {});
+  if (!result.ok) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Job '${jobKey}' inline workspace manifest failed to compile: ${result.errors
+        .map((e) => `${e.path}: ${e.message}`)
+        .join('; ')
+        .slice(0, 400)}`,
+      { jobKey, actionId: actionManifest.metadata.id },
+    );
+  }
+  return Object.freeze({ kind: 'inline' as const, compiled: result.compiled });
+}
+
+interface SynthesizeArgs {
+  readonly agentSlug: string;
+  readonly phaseKey: string | null;
+  readonly role: string;
+  readonly deliverableSpecRef: string | null;
+  readonly mounts: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Build the YAML-equivalent envelope object that `compileManifest()`
+ * accepts. We never round-trip through YAML — the kernel's compiler
+ * accepts a parsed object too.
+ */
+function synthesizeInlineManifestEnvelope(args: SynthesizeArgs): unknown {
+  return {
+    apiVersion: 'xema.dev/workspace/v1',
+    kind: 'WorkspaceManifest',
+    metadata: {
+      slug: 'inline',
+      version: INLINE_MANIFEST_VERSION,
+      // Inline-synthesized manifests only ever boot from a workflow
+      // step — interactive sessions reach the resolver through the
+      // long-form ref path. Pinning this here means
+      // `EnvironmentResolver` can fail fast if a workflow ever points
+      // an agent-session-only consumer at one of these.
+      surfaceCompat: ['workflow'],
+    },
+    spec: {
+      agent: {
+        slug: args.agentSlug,
+        phase: args.phaseKey ?? 'default',
+        role: args.role,
+        ...(args.deliverableSpecRef === null
+          ? {}
+          : { deliverableSpecRef: args.deliverableSpecRef }),
+      },
+      mounts: args.mounts,
+    },
+  };
+}
+
+function containsExpressions(node: unknown): boolean {
+  if (typeof node === 'string') return ANY_INTERPOLATION_RE.test(node);
+  if (Array.isArray(node)) return node.some(containsExpressions);
+  if (node !== null && typeof node === 'object') {
+    return Object.values(node as Record<string, unknown>).some(containsExpressions);
+  }
+  return false;
+}
+
+function isLiteralString(value: unknown): value is string {
+  return typeof value === 'string' && !ANY_INTERPOLATION_RE.test(value);
+}
+
+function isLiteralStringOrUndefined(value: unknown): boolean {
+  return value === undefined || isLiteralString(value);
+}
+
+function isLiteralStringOrNullOrUndefined(value: unknown): boolean {
+  return value === null || value === undefined || isLiteralString(value);
+}

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

@@ -0,0 +1,135 @@
+import { MatrixStrategyKind, WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+import type {
+  CompiledDynamicMatrixStrategy,
+  CompiledSingleStrategy,
+  CompiledStaticMatrixStrategy,
+  CompiledStrategy,
+} from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import type { WorkflowStrategyDeclaration } from '../types';
+import { compileExpression } from '../expression';
+import { stripInterpolation } from '../expression/interpolation';
+
+/** Hard cap on matrix cardinality — static and dynamic both enforce this. */
+const MATRIX_MAX_ENTRIES = 64;
+const MATRIX_DEFAULT_MAX_PARALLEL = 8;
+
+/**
+ * Compile an authored strategy declaration into a CompiledStrategy. Performs
+ * cartesian expansion for static matrices at compile time and pre-validates
+ * the dynamic `from:` expression.
+ *
+ * Static matrix cardinality is the product of each axis's length. The cap
+ * is applied to the product, not per-axis, so 8×8 (=64) is the ceiling.
+ */
+export function compileStrategy(
+  declaration: WorkflowStrategyDeclaration | undefined,
+  jobKey: string,
+): CompiledStrategy {
+  if (!declaration) {
+    const single: CompiledSingleStrategy = { kind: MatrixStrategyKind.SINGLE };
+    return single;
+  }
+
+  if ('matrix' in declaration) {
+    return expandStaticMatrix(declaration.matrix, declaration.maxParallel, jobKey);
+  }
+
+  return compileDynamicStrategy(declaration.dynamic, declaration.maxParallel, jobKey);
+}
+
+function expandStaticMatrix(
+  axes: Readonly<Record<string, readonly unknown[]>>,
+  maxParallelRaw: number | undefined,
+  jobKey: string,
+): CompiledStaticMatrixStrategy {
+  const axisKeys = Object.keys(axes).sort();
+  if (axisKeys.length === 0) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Job '${jobKey}' declares strategy.matrix with no axes.`,
+      { jobKey },
+    );
+  }
+
+  // Cartesian product in lexicographic order of axisKeys for determinism.
+  let entries: Record<string, unknown>[] = [{}];
+  for (const axis of axisKeys) {
+    const values = axes[axis]!;
+    const next: Record<string, unknown>[] = [];
+    for (const partial of entries) {
+      for (const value of values) {
+        next.push({ ...partial, [axis]: value });
+      }
+      if (next.length > MATRIX_MAX_ENTRIES) break;
+    }
+    entries = next;
+    if (entries.length > MATRIX_MAX_ENTRIES) break;
+  }
+
+  if (entries.length > MATRIX_MAX_ENTRIES) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_MATRIX_CARDINALITY_EXCEEDED,
+      `Job '${jobKey}' static matrix expansion produces ${entries.length} entries; cap is ${MATRIX_MAX_ENTRIES}.`,
+      { jobKey, cap: MATRIX_MAX_ENTRIES, cardinality: entries.length },
+    );
+  }
+
+  const maxParallel = resolveMaxParallel(maxParallelRaw, entries.length);
+
+  return {
+    kind: MatrixStrategyKind.STATIC,
+    entries: entries.map(Object.freeze) as readonly Readonly<Record<string, unknown>>[],
+    maxParallel,
+  };
+}
+
+function compileDynamicStrategy(
+  declaration: {
+    readonly from: string;
+    readonly as: string;
+    readonly maxEntries?: number;
+    readonly keyBy?: string;
+  },
+  maxParallelRaw: number | undefined,
+  jobKey: string,
+): CompiledDynamicMatrixStrategy {
+  const body = stripInterpolation(declaration.from);
+  // Compile expression at compile time — this rejects unknown roots and
+  // bad syntax now, so the runtime evaluator can only fail on an unknown
+  // property during real evaluation.
+  compileExpression(body);
+
+  const maxEntries = declaration.maxEntries ?? MATRIX_MAX_ENTRIES;
+  if (maxEntries < 1 || maxEntries > MATRIX_MAX_ENTRIES) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Job '${jobKey}' strategy.dynamic.maxEntries must be in [1, ${MATRIX_MAX_ENTRIES}]; got ${maxEntries}.`,
+      { jobKey, maxEntries, cap: MATRIX_MAX_ENTRIES },
+    );
+  }
+  const maxParallel = resolveMaxParallel(maxParallelRaw, maxEntries);
+
+  return {
+    kind: MatrixStrategyKind.DYNAMIC,
+    fromExpression: body,
+    bindingName: declaration.as,
+    maxEntries,
+    maxParallel,
+    keyBy: declaration.keyBy ?? null,
+  };
+}
+
+function resolveMaxParallel(raw: number | undefined, cardinality: number): number {
+  if (raw === undefined) {
+    return Math.min(MATRIX_DEFAULT_MAX_PARALLEL, Math.max(1, cardinality));
+  }
+  if (raw < 1) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `strategy.maxParallel must be >= 1 (got ${raw}).`,
+      { raw },
+    );
+  }
+  return Math.min(raw, MATRIX_MAX_ENTRIES);
+}

package/src/workflow/lib/compiler/mount-plan.ts

@@ -0,0 +1,202 @@
+import {
+  AWP_V1_SPEC,
+  findSlot,
+  isKnownSlotKey,
+  SlotMode,
+  type WorkspaceSpec,
+} from '@xemahq/kernel-contracts/agent-workspace';
+import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+import type { MountPlan } from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import type { ActionManifest } from '../types';
+import { isAgentShapedAction } from './action-shape';
+
+/**
+ * Compile a job's `with:` block into a compile-time {@link MountPlan} —
+ * a declarative list of mount keys grouped by access, validated against
+ * (a) the workspace spec's closed slot set and (b) the action manifest's
+ * `allowedMounts`.
+ *
+ * Read/write classification is per-mount with a slot-default fallback:
+ *   - `with.mounts.<key>: true` uses the slot's `defaultMode` from the
+ *     {@link WorkspaceSpec}.
+ *   - `with.mounts.<key>: { mode: 'read-only' | 'read-write' }`
+ *     overrides the slot default. The value is the closed `SlotMode`
+ *     enum; any other string is rejected fail-fast.
+ *
+ * The legacy `with.mountKeys: []` / `with.writableMountKeys: []` array
+ * form is gone — the action manifest's input schema rejects it before
+ * this compiler runs, but we also explicitly reject those keys here so
+ * a misconfigured manifest can't sneak the legacy shape through.
+ *
+ * Concrete {@link MountSource} resolution is NOT the compiler's job: it
+ * requires access to the engine's org-scoped resource registry, which is
+ * only available at dispatch time.
+ *
+ * Rules:
+ *   - `with.mounts` absent → empty plan (no implicit mounts).
+ *   - Unknown slot keys (per the spec) fail fast.
+ *   - If the action manifest declares `allowedMounts`, keys outside it
+ *     also fail fast.
+ *   - Legacy `mountKeys` / `writableMountKeys` keys on `with:` → fail fast
+ *     with a migration hint.
+ */
+
+const SPEC: WorkspaceSpec = AWP_V1_SPEC;
+
+const LEGACY_MOUNT_KEYS = ['mountKeys', 'writableMountKeys'] as const;
+
+export function compileMountPlan(
+  jobKey: string,
+  withBlock: Readonly<Record<string, unknown>> | undefined,
+  actionManifest: ActionManifest | null,
+): MountPlan {
+  rejectLegacyShape(jobKey, withBlock);
+
+  enforceManifestSourceDiscriminator(jobKey, withBlock, actionManifest);
+
+  const mounts = extractMountsBlock(withBlock);
+  if (!mounts) {
+    return { readOnly: [], readWrite: [] };
+  }
+
+  const allowed =
+    actionManifest?.spec.allowedMounts !== undefined
+      ? new Set(actionManifest.spec.allowedMounts)
+      : null;
+
+  const readOnly: { key: string }[] = [];
+  const readWrite: { key: string }[] = [];
+
+  const sortedKeys = Object.keys(mounts).sort();
+  for (const key of sortedKeys) {
+    const mode = parseMountValue(jobKey, key, mounts[key]);
+    if (!isKnownSlotKey(SPEC, key)) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `Job '${jobKey}' requests mount '${key}' which is not a known slot in WorkspaceSpec '${SPEC.id}'.`,
+        { jobKey, mountKey: key, knownSlots: SPEC.slots.map((s) => s.key) },
+      );
+    }
+    if (allowed !== null && !allowed.has(key)) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `Job '${jobKey}' requests mount '${key}' but action manifest does not list it in allowedMounts.`,
+        { jobKey, mountKey: key, allowedMounts: [...allowed] },
+      );
+    }
+    const slot = findSlot(SPEC, key);
+    const slotDefault = slot?.defaultMode ?? SlotMode.ReadOnly;
+    const effective = mode ?? slotDefault;
+    if (slot && !slot.allowedModes.includes(effective)) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `Job '${jobKey}' requests mount '${key}' with mode '${effective}', which is not in slot allowedModes [${slot.allowedModes.join(', ')}].`,
+        { jobKey, mountKey: key, requestedMode: effective, allowedModes: [...slot.allowedModes] },
+      );
+    }
+    if (effective === SlotMode.ReadWrite) {
+      readWrite.push({ key });
+    } else {
+      readOnly.push({ key });
+    }
+  }
+
+  return { readOnly, readWrite };
+}
+
+function parseMountValue(
+  jobKey: string,
+  mountKey: string,
+  value: unknown,
+): SlotMode | null {
+  if (value === true) return null;
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+    const mode = obj['mode'];
+    if (mode === SlotMode.ReadOnly || mode === SlotMode.ReadWrite) {
+      return mode;
+    }
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Job '${jobKey}' mount '${mountKey}' has invalid 'mode': must be '${SlotMode.ReadOnly}' or '${SlotMode.ReadWrite}'.`,
+      { jobKey, mountKey, mode: typeof mode === 'string' ? mode : typeof mode },
+    );
+  }
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+    `Job '${jobKey}' mount '${mountKey}' value must be \`true\` or \`{ mode: 'read-only' | 'read-write' }\`.`,
+    { jobKey, mountKey, valueKind: Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value },
+  );
+}
+
+function extractMountsBlock(
+  withBlock: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, unknown>> | null {
+  if (!withBlock) return null;
+  const raw = withBlock['mounts'];
+  if (raw === undefined) return null;
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `\`with.mounts\` must be an object mapping slot keys to \`true\` or \`{ mode }\`.`,
+      { mountsKind: Array.isArray(raw) ? 'array' : raw === null ? 'null' : typeof raw },
+    );
+  }
+  return raw as Readonly<Record<string, unknown>>;
+}
+
+function rejectLegacyShape(
+  jobKey: string,
+  withBlock: Readonly<Record<string, unknown>> | undefined,
+): void {
+  if (!withBlock) return;
+  for (const legacyKey of LEGACY_MOUNT_KEYS) {
+    if (legacyKey in withBlock) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `Job '${jobKey}' uses legacy '${legacyKey}' on \`with:\`. Migrate to \`with.mounts\` (object form): \`mounts: { references: true, deliverables: { mode: 'read-write' } }\`.`,
+        { jobKey, legacyKey },
+      );
+    }
+  }
+}
+
+/**
+ * Manifest-source discriminator: when an action's `inputs:` schema
+ * declares both `compositionRef` and `mounts` as alternatives (via
+ * JSON-Schema `oneOf`), the workflow's `with:` block must specify
+ * exactly one of them. Detected generically so biome-shipped agent
+ * actions inherit the same compile-time check without a hardcoded
+ * action-id allowlist.
+ */
+function enforceManifestSourceDiscriminator(
+  jobKey: string,
+  withBlock: Readonly<Record<string, unknown>> | undefined,
+  actionManifest: ActionManifest | null,
+): void {
+  if (!isAgentShapedAction(actionManifest)) return;
+  const hasRef =
+    withBlock !== undefined &&
+    'compositionRef' in withBlock &&
+    typeof withBlock['compositionRef'] === 'string' &&
+    (withBlock['compositionRef'] as string).length > 0;
+  const hasMounts =
+    withBlock !== undefined &&
+    'mounts' in withBlock &&
+    withBlock['mounts'] !== undefined;
+  if (hasRef && hasMounts) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Job '${jobKey}' sets both \`compositionRef\` and \`mounts\` on \`with:\`. The action's manifest source is exactly one of the two.`,
+      { jobKey, actionId: actionManifest.metadata.id },
+    );
+  }
+  if (!hasRef && !hasMounts) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Job '${jobKey}' must set exactly one of \`compositionRef\` (long form) or \`mounts\` (short form) on \`with:\`.`,
+      { jobKey, actionId: actionManifest.metadata.id },
+    );
+  }
+}