@xemahq/dsl 0.1.1

package/src/workflow/lib/types.ts

@@ -0,0 +1,361 @@
+import type { ConcurrencyMode, PermissionScope } from '@xemahq/kernel-contracts/workflow';
+
+/**
+ * Authored-shape TypeScript types for a Xema workflow document. These match
+ * the JSON Schema at schema/workflow.schema.json — validation is the source
+ * of truth, these types are ergonomics for callers that have already
+ * validated the input.
+ *
+ * Do NOT trust unvalidated user input typed as `WorkflowDocument` — always
+ * pass through `validateWorkflowDocument(raw)` first, which produces a
+ * narrowed value safely typed as this interface.
+ */
+export interface WorkflowDocument {
+  readonly apiVersion: 'xema.dev/workflow/v1alpha1';
+  readonly kind: 'Workflow';
+  readonly metadata: WorkflowMetadata;
+  readonly on: WorkflowTriggerDeclarations;
+  readonly concurrency?: WorkflowConcurrencyDeclaration;
+  readonly defaults?: WorkflowDefaults;
+  readonly permissions?: WorkflowPermissions;
+  readonly vars?: Readonly<Record<string, unknown>>;
+  /**
+   * Wallets (variable + secret bundles) the workflow needs at dispatch
+   * time. A wallet is a named group of project / org variables managed
+   * through `project-registry-api`. The engine resolves each declared
+   * wallet to its contents before starting the run; missing wallets or
+   * missing keys referenced by `${{ vars.X }}` / `${{ secrets.X }}`
+   * surface as
+   * `WorkflowErrorCode.WORKFLOW_WALLET_NOT_FOUND` /
+   * `WorkflowErrorCode.WORKFLOW_VARIABLES_MISSING` respectively, and
+   * the run is never started.
+   *
+   * Dispatch callers may pass additional wallet names on top of this
+   * list — additive only.
+   */
+  readonly requires?: WorkflowRequiresDeclaration;
+  readonly jobs: Readonly<Record<string, WorkflowJobDeclaration>>;
+  /**
+   * Workflow-level named outputs. Each entry references a single
+   * `(job, outputName)` pair and declares the kind of value it
+   * surfaces — deliverable artifact (the most common), structured
+   * JSON value, or plain text.
+   *
+   * Consumers:
+   *   - Biome `mcpWorkflowTools[].outputProjection.slug` (cross-
+   *     referenced at biome boot — the slug MUST match a key here).
+   *   - Future `workflow_call` reusable composition (consumes outputs
+   *     declared by the called workflow).
+   *   - Run-detail projections (`RunResponseDto.deliverables`) — built
+   *     by walking this map against the producing JobRun outputs.
+   *
+   * Validation at compile time:
+   *   - `fromJob` MUST exist in `jobs`.
+   *   - `fromOutput` MUST appear in that job's `outputs:` map.
+   *   - For `kind: 'deliverable'`, `deliverableSpecRef` MUST resolve
+   *     through the spec prefetch path.
+   */
+  readonly outputs?: Readonly<Record<string, WorkflowOutputDeclaration>>;
+}
+
+/**
+ * Per-output declaration shape. Discriminated by `kind`. Lives at the
+ * workflow document level (`workflow.outputs.<name>`), NOT on a job.
+ * Job-level `outputs:` remain the per-step expressions feeding into
+ * workflow outputs via `fromJob` / `fromOutput`.
+ */
+export type WorkflowOutputDeclaration =
+  | WorkflowDeliverableOutputDeclaration
+  | WorkflowStructuredOutputDeclaration
+  | WorkflowTextOutputDeclaration;
+
+interface WorkflowOutputDeclarationBase {
+  readonly slug: string;
+  readonly fromJob: string;
+  readonly fromOutput: string;
+  readonly description?: string;
+}
+
+export interface WorkflowDeliverableOutputDeclaration
+  extends WorkflowOutputDeclarationBase {
+  readonly kind: 'deliverable';
+  /** Reference to a published `DeliverableSpec` (slug or slug@version). */
+  readonly deliverableSpecRef: string;
+}
+
+export interface WorkflowStructuredOutputDeclaration
+  extends WorkflowOutputDeclarationBase {
+  readonly kind: 'structured';
+  /** Optional JSON Schema ref the platform validates the value against. */
+  readonly schemaRef?: string;
+}
+
+export interface WorkflowTextOutputDeclaration extends WorkflowOutputDeclarationBase {
+  readonly kind: 'text';
+}
+
+export interface WorkflowRequiresDeclaration {
+  /** Wallet names; must match `^[a-z][a-z0-9-]{0,62}$`. */
+  readonly wallets?: readonly string[];
+  /**
+   * Integration adapter kinds the workflow consumes. Biome-shipped
+   * workflows declare these so `biome-host-api` can cross-validate
+   * them against the biome's manifest `integrationRequirements` at
+   * boot. Stand-alone workflows (not biome-owned) may also declare
+   * them as documentation; dispatch-time enforcement only kicks in
+   * for biome-gated runs.
+   */
+  readonly integrations?: readonly WorkflowIntegrationRequirement[];
+}
+
+export interface WorkflowIntegrationRequirement {
+  /** Adapter kind slug (e.g. `scm`, `tracker`, `documentation`). */
+  readonly adapterKind: string;
+  /** Capability slugs the workflow exercises against the adapter. */
+  readonly capabilities: readonly string[];
+  /** Whether the workflow can degrade if the integration is unbound. */
+  readonly optional?: boolean;
+}
+
+export interface WorkflowMetadata {
+  readonly name: string;
+  readonly version: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly category?: string;
+  readonly tags?: readonly string[];
+}
+
+export interface WorkflowTriggerDeclarations {
+  readonly workflow_dispatch?: WorkflowDispatchDeclaration;
+  readonly schedule?: readonly ScheduleDeclaration[];
+  readonly webhook?: readonly WebhookDeclaration[];
+  readonly workflow_call?: WorkflowCallDeclaration;
+}
+
+export interface WorkflowDispatchDeclaration {
+  readonly inputs?: Readonly<Record<string, WorkflowInputDeclaration>>;
+}
+
+export interface ScheduleDeclaration {
+  readonly cron: string;
+  readonly timezone?: string;
+  readonly inputs?: Readonly<Record<string, unknown>>;
+}
+
+export interface WebhookDeclaration {
+  readonly event: string;
+  readonly secretRef?: string;
+  readonly filters?: Readonly<Record<string, string>>;
+}
+
+export interface WorkflowCallDeclaration {
+  readonly inputs?: Readonly<Record<string, WorkflowInputDeclaration>>;
+  readonly outputs?: Readonly<Record<string, string>>;
+}
+
+export interface WorkflowInputDeclaration {
+  readonly type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+  readonly required?: boolean;
+  readonly default?: unknown;
+  readonly description?: string;
+  readonly enum?: readonly unknown[];
+  readonly items?: Readonly<Record<string, unknown>>;
+}
+
+export interface WorkflowConcurrencyDeclaration {
+  readonly group: string;
+  readonly mode: ConcurrencyMode;
+}
+
+export interface WorkflowDefaults {
+  readonly retry?: WorkflowRetryDeclaration;
+  readonly timeout?: string;
+}
+
+export interface WorkflowRetryDeclaration {
+  readonly maxAttempts?: number;
+  readonly initialInterval?: string;
+  readonly backoffCoefficient?: number;
+  readonly maximumInterval?: string;
+  readonly nonRetryableErrorTypes?: readonly string[];
+}
+
+export type WorkflowPermissions = Partial<Record<'repos' | 'kb' | 'backlog' | 'integrations' | 'artifacts' | 'memory', PermissionScope>>;
+
+export interface WorkflowJobDeclaration {
+  readonly title?: string;
+  readonly needs?: readonly string[];
+  readonly if?: string;
+  readonly strategy?: WorkflowStrategyDeclaration;
+  readonly matrixGather?: readonly string[];
+  readonly uses: string;
+  readonly with?: Readonly<Record<string, unknown>>;
+  readonly outputs?: Readonly<Record<string, string>>;
+  readonly retry?: WorkflowRetryDeclaration;
+  readonly timeout?: string;
+  readonly permissions?: WorkflowPermissions;
+}
+
+export type WorkflowStrategyDeclaration =
+  | { readonly matrix: Readonly<Record<string, readonly unknown[]>>; readonly maxParallel?: number }
+  | { readonly dynamic: WorkflowDynamicStrategyDeclaration; readonly maxParallel?: number };
+
+export interface WorkflowDynamicStrategyDeclaration {
+  readonly from: string;
+  readonly as: string;
+  readonly maxEntries?: number;
+  /**
+   * Optional dotted path on each bound entry whose value becomes the
+   * entry's key in `needs.<thisJob>.outputs.byKey`. Enables per-CU
+   * downstream consumers to write
+   * `needs.X.outputs.byKey[matrix.<binding>.<keyBy>].field`. Validated
+   * lexically by the schema; resolved against actual entries at
+   * dispatch time.
+   */
+  readonly keyBy?: string;
+}
+
+// ── Action manifest ─────────────────────────────────────────────────────
+
+export interface ActionManifest {
+  readonly apiVersion: 'xema.dev/workflow/v1alpha1';
+  readonly kind: 'Action';
+  readonly metadata: ActionManifestMetadata;
+  readonly spec: ActionManifestSpec;
+}
+
+export interface ActionManifestMetadata {
+  readonly id: string;
+  readonly version: string;
+  readonly title?: string;
+  readonly description?: string;
+}
+
+export interface ActionManifestSpec {
+  readonly executionKind: 'activity' | 'child_workflow';
+  readonly taskQueue: 'xema_default' | 'xema_agent' | 'xema_human';
+  /**
+   * Semantic category — drives consumer presentation (FE canvas
+   * shape, badge icon). Optional; omitted manifests fall back to
+   * `generic`. Closed values mirror `ActionKind` in
+   * `@xemahq/kernel-contracts/workflow`; consumers MUST treat unknown
+   * strings as `generic` so newer manifests stay safe with older
+   * clients.
+   */
+  readonly actionKind?:
+    | 'agent'
+    | 'review'
+    | 'wait'
+    | 'timer'
+    | 'aggregate'
+    | 'dispatch'
+    | 'branch'
+    | 'loop'
+    | 'publish'
+    | 'notify'
+    | 'inquiry'
+    | 'fetch'
+    | 'transform'
+    | 'validate'
+    | 'terminate'
+    | 'generic';
+  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly outputs: Readonly<Record<string, unknown>>;
+  /**
+   * Per-output deliverable-spec bindings (plan §B per-output bindings).
+   * Each entry pins a named output to a deliverable-spec ref like
+   * `agent-summary@1.0.0`. The DSL compiler consults this first when
+   * resolving typed payload reach-in (`outputs.<name>.<field>`); it
+   * falls back to the job-level `with.deliverableSpecRef` only when no
+   * per-output binding is declared, preserving the current single-spec
+   * agent flow.
+   *
+   * Optional. Activities with no fixed per-output spec (e.g. the agent
+   * activity, whose deliverables spec is workflow-author-chosen) omit
+   * this. The compiler always proves at least one of (per-output spec,
+   * job-level spec) is set before letting a reach-in compile.
+   */
+  readonly outputBindings?: Readonly<Record<string, ActionOutputBinding>>;
+  readonly permissions?: WorkflowPermissions;
+  readonly allowedMounts?: readonly string[];
+  readonly retryDefaults: ActionManifestRetryDefaults;
+  readonly timeoutDefaults: ActionManifestTimeoutDefaults;
+  readonly auditEventMapping?: Partial<{ started: string; succeeded: string; failed: string }>;
+  /**
+   * Declarative contracts the action opts into. The DSL compiler reads
+   * this list to decide which validation lanes apply — e.g. the
+   * `workspace-manifest@v1` entry enables the manifest-source pair
+   * (`compositionRef` XOR inline short-form `mounts`) and the frontend
+   * canvas Inspector renders the manifest picker. Closed-set
+   * `kind`/`version` pair so biome-shipped agent actions inherit the
+   * same lanes without per-action-id branching.
+   *
+   * Today the only kind is `workspace-manifest`. New kinds extend the
+   * closed enum (deliverable-spec, knowledge-base-binding, …) with a
+   * single PR that fans out across the compiler, canvas, and runtime.
+   */
+  readonly consumes?: readonly ActionContract[];
+}
+
+/**
+ * Per-output binding declaration on an action manifest. Today the only
+ * binding field is `deliverableSpecRef`; future bindings (e.g. KB-page
+ * slug, custom contracts) extend the type.
+ */
+export interface ActionOutputBinding {
+  /**
+   * Deliverable spec ref governing this output's payload shape, in the
+   * canonical `<slug>@<version>` form (e.g. `metrics-snapshot@1.0.0`).
+   */
+  readonly deliverableSpecRef?: string;
+}
+
+/**
+ * Versioned consume-contract declaration on an action manifest.
+ *
+ * `workspace-manifest@v1` — enables the workspace-manifest triplet on
+ * `with:` (long-form ref, inline-anonymous envelope, or short-form
+ * mounts). Optional fields:
+ *  - `surfaces`: restricts the surfaces the action can be invoked on
+ *    (must intersect the manifest's `metadata.surfaceCompat`).
+ *  - `roleHint`: pins the manifest's `spec.agent.role` to a closed
+ *    `AgentRunRole`. Compile-time fail when a workflow points the
+ *    action at a manifest whose role doesn't match.
+ *
+ * `agent-composition@v1` — enables the `with.composition` field: a
+ * `slug@version` reference to an Agent Composition (llm-registry-api
+ * composition registry). The composition is the source of truth for the
+ * step's agent + sub-agents + skill/tool selection. Resolved at dispatch
+ * time by the runtime via the composition resolution endpoint. Optional
+ * and additive — existing workflows that point an agent step at a
+ * workspace manifest are unaffected.
+ */
+export type ActionContract =
+  | WorkspaceManifestActionContract
+  | AgentCompositionActionContract;
+
+export interface WorkspaceManifestActionContract {
+  readonly kind: 'workspace-manifest';
+  readonly version: 'v1';
+  readonly surfaces?: readonly ('workflow' | 'agent-session')[];
+  readonly roleHint?: string;
+}
+
+export interface AgentCompositionActionContract {
+  readonly kind: 'agent-composition';
+  readonly version: 'v1';
+}
+
+export interface ActionManifestRetryDefaults {
+  readonly maxAttempts: number;
+  readonly initialInterval: string;
+  readonly backoffCoefficient: number;
+  readonly maximumInterval: string;
+  readonly nonRetryableErrorTypes?: readonly string[];
+}
+
+export interface ActionManifestTimeoutDefaults {
+  readonly startToClose: string;
+  readonly heartbeat?: string;
+}

package/src/workflow/lib/validate.ts

@@ -0,0 +1,199 @@
+import Ajv2020, { type ErrorObject, type ValidateFunction } from 'ajv/dist/2020';
+import addFormats from 'ajv-formats';
+import { load as parseYaml } from 'js-yaml';
+import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from './errors';
+import {
+  ACTION_SCHEMA,
+  REUSABLE_WORKFLOW_SCHEMA,
+  WORKFLOW_SCHEMA,
+} from './schemas-loader';
+import type { ActionManifest, WorkflowDocument } from './types';
+
+/**
+ * Ajv is constructed exactly once per process (module scope). `strict:true`
+ * keeps us honest — we catch schema authoring bugs at module-load time
+ * instead of silently coercing them at runtime.
+ *
+ * Per-request validation is a hot path; re-compiling schemas would burn CPU
+ * for no correctness gain. Rule 7 (horizontal scalability): this validator
+ * is stateless and safe to share across concurrent requests in a NestJS
+ * process.
+ *
+ * `strictRequired` is explicitly disabled: it conflicts with the standard
+ * JSON-Schema-2020-12 `oneOf` discrimination idiom (`oneOf: [{required:[a]},
+ * {required:[b]}]`) where the referenced properties are declared in the
+ * parent subschema's `properties`. The remaining strict flags
+ * (`strictSchema`, `strictTypes`, `strictTuples`) plus
+ * `additionalProperties:false` in every object schema already catch the
+ * typos `strictRequired` would catch, so the safety tradeoff is zero.
+ */
+const ajv = new Ajv2020({
+  strict: true,
+  strictSchema: true,
+  strictTypes: true,
+  strictRequired: false,
+  strictTuples: true,
+  allErrors: true,
+  allowUnionTypes: false,
+  useDefaults: false,
+  validateFormats: true,
+});
+addFormats(ajv);
+
+// Register referenced schemas so `$ref` across files resolves. Order
+// matters: reusable-workflow references workflow.schema.json by $id.
+ajv.addSchema(WORKFLOW_SCHEMA);
+ajv.addSchema(REUSABLE_WORKFLOW_SCHEMA);
+ajv.addSchema(ACTION_SCHEMA);
+
+const validateWorkflow = compile<WorkflowDocument>(
+  'https://xema.dev/schemas/workflow/v1alpha1/Workflow.json',
+);
+const validateReusableWorkflow = compile<WorkflowDocument>(
+  'https://xema.dev/schemas/workflow/v1alpha1/ReusableWorkflow.json',
+);
+const validateAction = compile<ActionManifest>(
+  'https://xema.dev/schemas/workflow/v1alpha1/Action.json',
+);
+
+function compile<T>(schemaId: string): ValidateFunction<T> {
+  const fn = ajv.getSchema<T>(schemaId);
+  if (!fn) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.COMPILE_INTERNAL,
+      `Ajv failed to compile schema ${schemaId}. Schema registration order is wrong.`,
+      { schemaId },
+    );
+  }
+  return fn;
+}
+
+/**
+ * Parse a YAML workflow document and validate it against the workflow
+ * schema. Returns the narrowed document on success; throws
+ * {@link WorkflowDslError} with code DSL_SCHEMA_INVALID on any validation
+ * failure (never silent pass-through, never partial validation).
+ */
+export function parseAndValidateWorkflowYaml(yaml: string): WorkflowDocument {
+  return parseAndValidate(yaml, validateWorkflow, 'workflow');
+}
+
+/**
+ * Parse a YAML reusable-workflow document and validate it against the
+ * reusable-workflow schema.
+ */
+export function parseAndValidateReusableWorkflowYaml(yaml: string): WorkflowDocument {
+  return parseAndValidate(yaml, validateReusableWorkflow, 'reusable-workflow');
+}
+
+/** Parse a YAML action manifest and validate it against the action schema. */
+export function parseAndValidateActionYaml(yaml: string): ActionManifest {
+  return parseAndValidate(yaml, validateAction, 'action');
+}
+
+/**
+ * Validate an already-parsed document object. Useful for programmatic
+ * construction (e.g. tests) and for the engine seeding path that reads
+ * JSON directly from the DB.
+ */
+export function validateWorkflowDocument(doc: unknown): WorkflowDocument {
+  if (doc !== null && typeof doc === 'object' && !Array.isArray(doc)) {
+    normalizeJobNeedsShorthand(doc);
+  }
+  return runValidator(doc, validateWorkflow, 'workflow');
+}
+
+export function validateReusableWorkflowDocument(doc: unknown): WorkflowDocument {
+  if (doc !== null && typeof doc === 'object' && !Array.isArray(doc)) {
+    normalizeJobNeedsShorthand(doc);
+  }
+  return runValidator(doc, validateReusableWorkflow, 'reusable-workflow');
+}
+
+export function validateActionManifest(doc: unknown): ActionManifest {
+  return runValidator(doc, validateAction, 'action');
+}
+
+function parseAndValidate<T>(
+  yaml: string,
+  validator: ValidateFunction<T>,
+  kind: 'workflow' | 'reusable-workflow' | 'action',
+): T {
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(yaml, { schema: undefined, json: false });
+  } catch (err) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SCHEMA_INVALID,
+      `YAML parse failure in ${kind} document: ${(err as Error).message}`,
+      { kind },
+    );
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SCHEMA_INVALID,
+      `Top-level YAML value in ${kind} document must be a mapping.`,
+      { kind },
+    );
+  }
+  // Plan §G shorthand: `needs: <string>` → `[<string>]`. Normalize
+  // BEFORE validation so the schema stays strict (one canonical shape)
+  // and the rest of the compiler never branches on shorthand. Workflow +
+  // reusable-workflow documents both have `jobs: { <key>: { needs?... } }`;
+  // action manifests have no `needs`, so this is a no-op there.
+  if (kind !== 'action') {
+    normalizeJobNeedsShorthand(parsed);
+  }
+  return runValidator(parsed, validator, kind);
+}
+
+/**
+ * Mutates `doc.jobs.<key>.needs` from `<string>` to `[<string>]` in
+ * place. Authors can write either form; the canonical form is the
+ * array. Documented in plan §G under "Simplified DSL".
+ */
+function normalizeJobNeedsShorthand(doc: object): void {
+  const jobs = (doc as { jobs?: unknown }).jobs;
+  if (!jobs || typeof jobs !== 'object' || Array.isArray(jobs)) return;
+  for (const job of Object.values(jobs as Record<string, unknown>)) {
+    if (!job || typeof job !== 'object' || Array.isArray(job)) continue;
+    const rec = job as Record<string, unknown>;
+    if (typeof rec.needs === 'string') {
+      rec.needs = [rec.needs];
+    }
+  }
+}
+
+function runValidator<T>(
+  doc: unknown,
+  validator: ValidateFunction<T>,
+  kind: 'workflow' | 'reusable-workflow' | 'action',
+): T {
+  if (validator(doc)) {
+    return doc;
+  }
+  const errors = validator.errors ?? [];
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_SCHEMA_INVALID,
+    `Schema validation failed for ${kind} document: ${formatErrors(errors)}`,
+    { kind, issues: errors.map(formatIssue) },
+  );
+}
+
+function formatIssue(err: ErrorObject): Readonly<Record<string, unknown>> {
+  return {
+    instancePath: err.instancePath,
+    schemaPath: err.schemaPath,
+    keyword: err.keyword,
+    message: err.message ?? '',
+    params: err.params,
+  };
+}
+
+function formatErrors(errors: readonly ErrorObject[]): string {
+  if (errors.length === 0) return '(no detail)';
+  return errors
+    .map((e) => `${e.instancePath || '/'} ${e.message ?? ''} [${e.keyword}]`.trim())
+    .join('; ');
+}

package/src/workspace-manifest/index.ts

@@ -0,0 +1,27 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── @xemahq/workspace-manifest-dsl ──
+//
+// Schema, compiler, and interpolation engine for `WorkspaceManifest`
+// YAMLs. A manifest declares the SHAPE of `/workspace/` for an agent
+// invocation — which user-data slots are populated, which agent runs,
+// which seed files are dropped in.
+//
+// Consumers:
+//   - `biomes/agent-runtime/api/llm-registry-api` (composition seeder): compiles each
+//     biome-shipped manifest and projects it into a published
+//     `Composition` row.
+//   - `packages/agent-session-runtime` (composer): turns a compiled
+//     manifest + bind inputs into a `WorkspaceMountPlan` that gets
+//     applied via workspace-proxy `/workspace/mounts/apply`.
+//   - `packages/workflow-dsl`: validates inline `mounts:` blocks on
+//     `xema/agent` jobs at workflow compile time.
+//
+// Sibling to `@xemahq/workflow-dsl`. Workflow DSL describes the
+// process; workspace manifest describes the environment shape.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/types';
+export * from './lib/schema';
+export * from './lib/interpolate';
+export * from './lib/compile';
+export * from './lib/resolve-extends';