@xemahq/dsl 0.8.1 → 0.8.2

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

@@ -1,254 +0,0 @@
-import {
-  WorkflowErrorCode,
-  WorkflowTriggerKind,
-  type TriggerPayload,
-} from '@xemahq/kernel-contracts/workflow';
-import { WorkflowDslError } from '../errors';
-import type { WorkflowDocument, WorkflowInputDeclaration } from '../types';
-
-/**
- * Bind trigger inputs against the workflow's declared input schema(s),
- * applying declared defaults. Missing-required / type-mismatch is a
- * compile error — never a silent zero/null substitution (rule 2).
- *
- * We use the trigger kind to pick which declaration block governs:
- *   - workflow_dispatch → on.workflow_dispatch.inputs
- *   - schedule         → on.schedule[*].inputs (pre-bound on the schedule itself)
- *   - workflow_call    → on.workflow_call.inputs
- *   - webhook          → no input declaration; payload is the whole envelope
- *
- * Scheduled triggers carry their pre-bound inputs in `trigger.inputs`; we
- * validate against the workflow_dispatch declaration if present, or pass
- * through un-validated (schedule-authored inputs are trusted) — the engine
- * validates schedule-level inputs at schedule-creation time instead.
- */
-export function bindTriggerInputs(
-  workflow: WorkflowDocument,
-  trigger: TriggerPayload,
-  previewMode = false,
-): Readonly<Record<string, unknown>> {
-  switch (trigger.kind) {
-    case WorkflowTriggerKind.WORKFLOW_DISPATCH: {
-      if (workflow.on.workflow_dispatch === undefined) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-          `Workflow does not declare an 'on.workflow_dispatch' trigger and cannot be dispatched. Declared triggers: [${Object.keys(workflow.on).sort((a, b) => a.localeCompare(b)).join(', ') || '(none)'}].`,
-          { triggerKind: 'workflow_dispatch', declaredTriggers: Object.keys(workflow.on) },
-        );
-      }
-      const decl = workflow.on.workflow_dispatch.inputs ?? {};
-      return bindInputs(decl, trigger.inputs, 'workflow_dispatch', previewMode);
-    }
-    case WorkflowTriggerKind.WORKFLOW_CALL: {
-      if (workflow.on.workflow_call === undefined) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-          `Workflow does not declare an 'on.workflow_call' trigger and cannot be invoked from another workflow. Declared triggers: [${Object.keys(workflow.on).sort((a, b) => a.localeCompare(b)).join(', ') || '(none)'}].`,
-          { triggerKind: 'workflow_call', declaredTriggers: Object.keys(workflow.on) },
-        );
-      }
-      const decl = workflow.on.workflow_call.inputs ?? {};
-      return bindInputs(decl, trigger.inputs, 'workflow_call', previewMode);
-    }
-    case WorkflowTriggerKind.SCHEDULE: {
-      // Schedule inputs were validated against workflow_dispatch.inputs at
-      // schedule-create time by workflow-engine-api. Here we just validate
-      // the resulting bound payload against the same schema (defense in
-      // depth; cheap).
-      const decl = workflow.on.workflow_dispatch?.inputs ?? {};
-      return bindInputs(decl, trigger.inputs, 'schedule', previewMode);
-    }
-    case WorkflowTriggerKind.WEBHOOK: {
-      // Webhook does not declare typed inputs at the workflow level —
-      // validation of the canonical envelope happens at connector-gateway-api.
-      return trigger.payload;
-    }
-  }
-}
-
-/**
- * Engine-reserved trigger inputs. The workflow engine injects these onto a
- * CHILD run's trigger inputs at dispatch time — they carry dispatch lineage,
- * the inherited responder chain, and the triggering inquiry context. They are
- * NEVER author-declared, so they cannot appear in `on.<trigger>.inputs`, yet
- * they ride the same `inputs` map. Without an explicit allowlist the
- * unknown-input guard below rejects every child dispatch made by
- * `xema/dispatch-workflow` / `workflow-decider`.
- *
- * Closed set, mirrored by the producers (a bare `__` prefix is intentionally
- * NOT trusted — an unknown `__`-prefixed key is still a hard error, so a
- * caller cannot smuggle lineage/responder-chain values past the gate):
- *   - `dispatch-workflow.activity.ts`  → __dispatchReason,
- *       __concurrencyGroupOverride, __parentRunId, __parentJobRunId
- *   - `workflow-decider.activity.ts`   → __responderChain,
- *       __triggeredByInquiryId, __triggeredByRecipientId
- *
- * Reserved values pass through to the bound payload untouched (consumers read
- * them off the run's inputs) and are exempt from type/declaration validation.
- */
-export const RESERVED_TRIGGER_INPUT_KEYS: ReadonlySet<string> = new Set([
-  '__dispatchReason',
-  '__concurrencyGroupOverride',
-  '__parentRunId',
-  '__parentJobRunId',
-  '__responderChain',
-  '__triggeredByInquiryId',
-  '__triggeredByRecipientId',
-]);
-
-function bindInputs(
-  declarations: Readonly<Record<string, WorkflowInputDeclaration>>,
-  received: Readonly<Record<string, unknown>>,
-  label: string,
-  previewMode = false,
-): Readonly<Record<string, unknown>> {
-  const out: Record<string, unknown> = {};
-  const seen = new Set<string>();
-
-  for (const [name, decl] of Object.entries(declarations)) {
-    seen.add(name);
-    const hasValue = Object.hasOwn(received, name);
-    if (!hasValue) {
-      handleMissingInput(out, name, decl, label, previewMode);
-      continue;
-    }
-    const value = received[name];
-    assertInputType(value, decl, name, label);
-    out[name] = value;
-  }
-
-  // Reject unknown inputs — fail-fast beats silent pass-through. Engine-
-  // reserved keys are the sole exception: they are injected by the engine on
-  // child dispatches, never author-declared, so they pass through verbatim
-  // instead of tripping the guard.
-  for (const name of Object.keys(received)) {
-    if (seen.has(name)) {
-      continue;
-    }
-    if (RESERVED_TRIGGER_INPUT_KEYS.has(name)) {
-      out[name] = received[name];
-      continue;
-    }
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `${label} trigger received unknown input '${name}'. Declared inputs: [${Object.keys(declarations).sort((a, b) => a.localeCompare(b)).join(', ') || '(none)'}].`,
-      { label, inputName: name },
-    );
-  }
-
-  return out;
-}
-
-function handleMissingInput(
-  out: Record<string, unknown>,
-  name: string,
-  decl: WorkflowInputDeclaration,
-  label: string,
-  previewMode: boolean,
-): void {
-  if (decl.required !== true) {
-    // Optional inputs are always materialized in the bound payload so
-    // `${{ inputs.<name> }}` resolves deterministically — declared default
-    // when present, otherwise null. Without this, expressions referencing
-    // a not-provided optional input throw `Unknown property` at runtime.
-    out[name] = decl.default === undefined ? null : decl.default;
-    return;
-  }
-  if (previewMode) {
-    // In preview mode, substitute a type-appropriate sentinel so the
-    // compiler can validate structure (DAG, expressions, matrix)
-    // without requiring real input values. Never used on real runs.
-    out[name] = previewSentinel(decl.type);
-    return;
-  }
-  throw new WorkflowDslError(
-    WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-    `${label} trigger is missing required input '${name}'.`,
-    { label, inputName: name },
-  );
-}
-
-/**
- * Returns a type-appropriate sentinel value for use in preview mode when
- * a required input is missing. The sentinel must pass `assertInputType`
- * for its declared type — it is never used outside of preview compilation.
- */
-function previewSentinel(type: WorkflowInputDeclaration['type']): unknown {
-  switch (type) {
-    case 'string':
-      return '';
-    case 'number':
-      return 0;
-    case 'integer':
-      return 0;
-    case 'boolean':
-      return false;
-    case 'object':
-      return {};
-    case 'array':
-      return [];
-  }
-}
-
-function assertInputType(
-  value: unknown,
-  decl: WorkflowInputDeclaration,
-  name: string,
-  label: string,
-): void {
-  const received = classify(value);
-  if (!isAssignable(received, decl.type)) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `${label} trigger input '${name}' expected ${decl.type}, received ${received}.`,
-      { label, inputName: name, expected: decl.type, received },
-    );
-  }
-  if (decl.enum !== undefined) {
-    if (!decl.enum.includes(value)) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `${label} trigger input '${name}' value not in enum.`,
-        { label, inputName: name, enum: decl.enum },
-      );
-    }
-  }
-}
-
-/**
- * Whether a value classified as `received` satisfies a declared `expected`
- * type. Identity always holds. The one widening: an `integer` value is a
- * valid `number` (JSON Schema treats integer as a subtype of number), so a
- * whole-valued JS number like `5` — which `classify` reports as `'integer'`
- * — must bind to a `number`-typed input. The reverse never holds: a
- * `number`-declared field accepts integers, but an `integer`-declared field
- * still rejects fractional numbers. No other type pair is assignable.
- */
-function isAssignable(
-  received: WorkflowInputDeclaration['type'],
-  expected: WorkflowInputDeclaration['type'],
-): boolean {
-  if (received === expected) return true;
-  return expected === 'number' && received === 'integer';
-}
-
-function classify(value: unknown): WorkflowInputDeclaration['type'] {
-  if (Array.isArray(value)) return 'array';
-  if (value === null) return 'object'; // null treated as absence; Ajv doesn't emit null type for us
-  switch (typeof value) {
-    case 'string':
-      return 'string';
-    case 'boolean':
-      return 'boolean';
-    case 'number':
-      return Number.isInteger(value) ? 'integer' : 'number';
-    case 'object':
-      return 'object';
-    default:
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Unsupported input value kind: ${typeof value}`,
-        { valueKind: typeof value },
-      );
-  }
-}

package/src/workflow/lib/compiler/installation-resource-validator.ts

@@ -1,114 +0,0 @@
-import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
-
-import { WorkflowDslError } from '../errors';
-import {
-  collectInstallationResourceHints,
-  type InstallationResourceFieldHint,
-} from '../installation-resource-kind';
-
-import type { InstallationCompileScope } from './types';
-
-/**
- * Compile-time check that every `x-installation-resource` field on the
- * action manifest's `inputs:` schema points at a resource bound to the
- * calling biome installation.
- *
- * Cases handled:
- *   - Expression-shaped value (`${{ ... }}`): the literal isn't known
- *     yet, so we skip the binding check. Runtime auth lives at the
- *     activity layer (`AuthFailed` from credentials/resolve).
- *   - Literal string: must be in `boundResources[kind]`. Missing →
- *     DSL error with `inputs.<path>` pointer.
- *   - Array of strings (rare): every element must be bound.
- *   - Undefined + optional: no-op.
- *
- * Skipped entirely when `installationScope` is undefined (system /
- * org-wide dispatch) — only biome-installed runs get this gate.
- */
-export function validateInstallationResourceBindings(input: {
-  jobKey: string;
-  actionId: string;
-  inputsSchema: unknown;
-  withValue: Readonly<Record<string, unknown>>;
-  scope: InstallationCompileScope | undefined;
-}): void {
-  if (!input.scope) {return;}
-  if (!input.inputsSchema) {return;}
-  const hints = collectInstallationResourceHints(input.inputsSchema);
-  if (hints.length === 0) {return;}
-  for (const hint of hints) {
-    const value = readPath(input.withValue, hint.path);
-    if (value === undefined || value === null || value === '') {
-      if (hint.optional) {continue;}
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `jobs.${input.jobKey}.with.${hint.path} is required (action ${input.actionId} declares x-installation-resource kind="${hint.kind}") but the with-block omitted it`,
-      );
-    }
-    const ctx = {
-      jobKey: input.jobKey,
-      actionId: input.actionId,
-      scope: input.scope,
-    };
-    if (typeof value === 'string') {
-      assertBound(ctx, hint, value);
-      continue;
-    }
-    if (Array.isArray(value)) {
-      for (const item of value) {
-        if (typeof item === 'string') {
-          assertBound(ctx, hint, item);
-        }
-      }
-    }
-  }
-}
-
-function assertBound(
-  ctx: {
-    jobKey: string;
-    actionId: string;
-    scope: InstallationCompileScope;
-  },
-  hint: InstallationResourceFieldHint,
-  literal: string,
-): void {
-  // Expression-shaped values are deferred to runtime — the literal
-  // string the compiler sees here is the expression body itself
-  // (`${{ inputs.x }}`), not a resolvable id.
-  if (literal.startsWith('${{') || literal.includes('${{')) {return;}
-  const bound = ctx.scope.boundResources[hint.kind] ?? [];
-  if (bound.length === 0) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `jobs.${ctx.jobKey}.with.${hint.path} references ${hint.kind}="${literal}" but installation ${ctx.scope.installationId} has no ${hint.kind} resources bound — connect one before dispatching`,
-    );
-  }
-  if (!bound.includes(literal)) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `jobs.${ctx.jobKey}.with.${hint.path} references ${hint.kind}="${literal}" which is NOT bound to installation ${ctx.scope.installationId} (action ${ctx.actionId} declares x-installation-resource kind="${hint.kind}"). Bound: [${bound.join(', ')}]`,
-    );
-  }
-}
-
-function readPath(
-  obj: Readonly<Record<string, unknown>>,
-  path: string,
-): unknown {
-  if (path === '') {return obj;}
-  const segments = path.split('.');
-  let cursor: unknown = obj;
-  for (const seg of segments) {
-    if (!cursor || typeof cursor !== 'object') {return undefined;}
-    // Array-element path uses `[*]` — treat as "any element", returning
-    // the array itself so the caller iterates. The hint walker emits
-    // these for `items.x-installation-resource` shapes.
-    if (seg === '[*]') {
-      if (!Array.isArray(cursor)) {return undefined;}
-      return cursor;
-    }
-    cursor = (cursor as Record<string, unknown>)[seg];
-  }
-  return cursor;
-}

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

@@ -1,71 +0,0 @@
-import {
-  WorkflowErrorCode,
-  type CompiledManifestSource,
-} from '@xemahq/kernel-contracts/workflow';
-
-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';
-
-/**
- * Compute the compile-time `manifestSource` discriminator for one job.
- *
- * `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: '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.
- */
-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 ?? {};
-
-  const ref = block['agentRef'];
-  if (typeof ref === 'string' && ref.length > 0) {
-    if (isLiteralString(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: 'deferred' as const });
-  }
-  if (ref !== undefined) {
-    // ref is present but not a literal string → expression.
-    return Object.freeze({ kind: 'deferred' as const });
-  }
-
-  throw new WorkflowDslError(
-    WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-    `Job '${jobKey}' is an agent-shaped action but does not set \`with.agentRef\`. ` +
-      `\`agentRef\` (a \`<slug>\` or \`<slug>@<version>\` reference) is the only way a workflow names its agent.`,
-    { jobKey, actionId: actionManifest.metadata.id },
-  );
-}
-
-function isLiteralString(value: unknown): value is string {
-  return typeof value === 'string' && !ANY_INTERPOLATION_RE.test(value);
-}

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

@@ -1,135 +0,0 @@
-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);
-}