@xemahq/dsl 0.1.1

package/src/payload-codec/lib/http-blob-store.ts

@@ -0,0 +1,257 @@
+import type { Response as UndiciResponse } from 'undici-types';
+
+import { BlobStoreKind } from './enums';
+import { PayloadCodecError, PayloadCodecErrorCode } from './errors';
+import {
+  type BlobRef,
+  type BlobStore,
+  type StoredBlob,
+  sha256Hex,
+} from './blob-store';
+
+export interface HttpBlobStoreOptions {
+  /** Base URL of artifact-store-api (e.g. http://artifact-store-api.xema-prod:80). */
+  readonly baseUrl: string;
+  /**
+   * Async provider for the service identity JWT. The codec mints new
+   * requests on every put/get so the token can expire without a restart.
+   */
+  readonly tokenProvider: () => Promise<string>;
+  /** Optional correlation id; appended to `X-Correlation-Id`. */
+  readonly correlationIdProvider?: () => string | null;
+  /** Absolute timeout for an individual put/get request (ms). */
+  readonly requestTimeoutMs?: number;
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const PUT_PATH = '/blobs';
+const GET_PATH_PREFIX = '/blobs/';
+
+/**
+ * BlobStore backed by `artifact-store-api`. Contract the service exposes:
+ *
+ *   POST /blobs  Content-Type: any
+ *     headers: Authorization: Bearer <jwt>; X-Org-Id: <tenant>
+ *     body: raw bytes
+ *     response: { data: { sha256, sizeBytes, contentType, createdAt } }
+ *
+ *   GET /blobs/:sha256
+ *     headers: Authorization: Bearer <jwt>; X-Org-Id: <tenant>
+ *     response: raw bytes, Content-Type header from the upload
+ *
+ * `X-Org-Id` is required on every call — the artifact-store-api scopes
+ * blob rows by `(orgId, sha256)`, so reads/writes must declare a tenant.
+ * The codec passes the orgId at the call site (encode reads it from the
+ * configured orgIdProvider; decode reads it from the spill envelope).
+ *
+ * Authentication is service-to-service — the caller provides a bearer
+ * token (minted via `identity-api`). Idempotent: the server dedupes by
+ * `(orgId, sha256)`.
+ */
+export class HttpBlobStore implements BlobStore {
+  readonly kind = BlobStoreKind.ARTIFACT_STORE;
+
+  constructor(private readonly options: HttpBlobStoreOptions) {
+    if (!options.baseUrl) {
+      throw new Error('HttpBlobStore: baseUrl is required.');
+    }
+  }
+
+  async put(
+    bytes: Uint8Array,
+    contentType: string,
+    orgId: string,
+  ): Promise<StoredBlob> {
+    assertOrgId(orgId);
+    const token = await this.options.tokenProvider();
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+    );
+    try {
+      // Node's undici fetch accepts Uint8Array directly; Buffer is a
+      // Uint8Array subclass AND a documented BodyInit in @types/node's
+      // ambient fetch types, so wrap once to keep TS happy without `any`.
+      const response = (await fetch(this.resolveUrl(PUT_PATH), {
+        method: 'POST',
+        headers: this.buildHeaders(token, contentType, orgId),
+        body: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+        signal: controller.signal,
+      })) as unknown as UndiciResponse;
+      if (!response.ok) {
+        throw new PayloadCodecError(
+          PayloadCodecErrorCode.BLOB_PUT_FAILED,
+          `artifact-store-api POST /blobs failed: ${response.status} ${response.statusText}`,
+          { status: response.status, orgId },
+        );
+      }
+      const parsed = (await response.json()) as {
+        data?: {
+          sha256?: unknown;
+          sizeBytes?: unknown;
+          contentType?: unknown;
+          createdAt?: unknown;
+          uri?: unknown;
+        };
+      };
+      const data = parsed.data;
+      if (!data || typeof data.sha256 !== 'string') {
+        throw new PayloadCodecError(
+          PayloadCodecErrorCode.BLOB_PUT_FAILED,
+          'artifact-store-api POST /blobs: malformed response envelope.',
+          { received: parsed },
+        );
+      }
+      const expectedSha = sha256Hex(bytes);
+      if (data.sha256 !== expectedSha) {
+        throw new PayloadCodecError(
+          PayloadCodecErrorCode.SHA256_MISMATCH,
+          'artifact-store-api returned a different sha256 than the client computed.',
+          { expected: expectedSha, received: data.sha256 },
+        );
+      }
+      // The current artifact-store BlobResponseDto omits `uri`; the (orgId,
+      // sha256) pair is canonical for retrieval, so we synthesize a
+      // stable handle for diagnostics.
+      const uri =
+        typeof data.uri === 'string' && data.uri.length > 0
+          ? data.uri
+          : `artifact-store://${orgId}/${data.sha256}`;
+      const sizeBytes =
+        typeof data.sizeBytes === 'number' ? data.sizeBytes : bytes.byteLength;
+      const contentTypeOut =
+        typeof data.contentType === 'string' ? data.contentType : contentType;
+      const createdAt =
+        typeof data.createdAt === 'string'
+          ? data.createdAt
+          : new Date().toISOString();
+      return {
+        store: this.kind,
+        uri,
+        sha256: data.sha256,
+        orgId,
+        sizeBytes,
+        contentType: contentTypeOut,
+        createdAt,
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async get(ref: BlobRef): Promise<Uint8Array> {
+    if (ref.store !== this.kind) {
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.UNKNOWN_STORE_KIND,
+        `HttpBlobStore cannot read blobs from store '${ref.store}'.`,
+        { expected: this.kind, received: ref.store },
+      );
+    }
+    assertOrgId(ref.orgId);
+    const token = await this.options.tokenProvider();
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+    );
+    try {
+      const response = (await fetch(
+        this.resolveUrl(`${GET_PATH_PREFIX}${encodeURIComponent(ref.sha256)}`),
+        {
+          method: 'GET',
+          headers: this.buildHeaders(token, 'application/octet-stream', ref.orgId),
+          signal: controller.signal,
+        },
+      )) as unknown as UndiciResponse;
+      if (!response.ok) {
+        throw new PayloadCodecError(
+          PayloadCodecErrorCode.BLOB_GET_FAILED,
+          `artifact-store-api GET /blobs/${ref.sha256} failed: ${response.status} ${response.statusText}`,
+          { status: response.status, sha256: ref.sha256, orgId: ref.orgId },
+        );
+      }
+      const buffer = new Uint8Array(await response.arrayBuffer());
+      const actualSha = sha256Hex(buffer);
+      if (actualSha !== ref.sha256) {
+        throw new PayloadCodecError(
+          PayloadCodecErrorCode.SHA256_MISMATCH,
+          'Blob fetched from artifact-store-api does not match the requested sha256.',
+          { expected: ref.sha256, actual: actualSha },
+        );
+      }
+      return buffer;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async delete(
+    ref: Pick<BlobRef, 'sha256' | 'orgId'>,
+  ): Promise<{ deleted: boolean }> {
+    assertOrgId(ref.orgId);
+    const token = await this.options.tokenProvider();
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+    );
+    try {
+      const response = (await fetch(
+        this.resolveUrl(`${GET_PATH_PREFIX}${encodeURIComponent(ref.sha256)}`),
+        {
+          method: 'DELETE',
+          headers: this.buildHeaders(token, 'application/octet-stream', ref.orgId),
+          signal: controller.signal,
+        },
+      )) as unknown as UndiciResponse;
+      if (response.status === 204) {
+        // artifact-store-api returns 204 whether or not the row existed
+        // (idempotent). We log the call site's perspective ("requested
+        // delete completed") rather than the row-existed dimension —
+        // the sweeper persists the actual deletion count from its own
+        // Postgres delete in the SnapshotPointer table.
+        return { deleted: true };
+      }
+      if (response.status === 404) {
+        // Defensive: some auth proxies surface 404 for cross-tenant
+        // misses. Treat as "already gone" so retries don't loop.
+        return { deleted: false };
+      }
+      throw new PayloadCodecError(
+        PayloadCodecErrorCode.BLOB_GET_FAILED,
+        `artifact-store-api DELETE /blobs/${ref.sha256} failed: ${response.status} ${response.statusText}`,
+        { status: response.status, sha256: ref.sha256, orgId: ref.orgId },
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private resolveUrl(path: string): string {
+    const base = this.options.baseUrl.replace(/\/+$/, '');
+    return `${base}${path}`;
+  }
+
+  private buildHeaders(token: string, contentType: string, orgId: string): Headers {
+    const headers = new Headers({
+      Authorization: `Bearer ${token}`,
+      'Content-Type': contentType,
+      'X-Org-Id': orgId,
+    });
+    const correlationId = this.options.correlationIdProvider?.();
+    if (correlationId) {
+      headers.set('X-Correlation-Id', correlationId);
+    }
+    return headers;
+  }
+}
+
+function assertOrgId(orgId: string): void {
+  if (typeof orgId !== 'string' || orgId.length === 0) {
+    throw new PayloadCodecError(
+      PayloadCodecErrorCode.ORG_ID_REQUIRED,
+      'HttpBlobStore operations require a non-empty orgId for X-Org-Id.',
+    );
+  }
+}

package/src/payload-codec/lib/lru-cache.ts

@@ -0,0 +1,81 @@
+/**
+ * Tiny byte-capacity LRU cache keyed by string (sha256). Kept intentionally
+ * dependency-free — adding a full LRU lib for this alone would bloat the
+ * package. Map's insertion-order iteration gives us O(1) recency tracking:
+ * re-insert on access, evict from the front when over budget.
+ *
+ * Entries that exceed the cache's total capacity are refused outright
+ * (returned bytes bypass the cache). This avoids the anti-pattern where
+ * inserting a single huge value evicts everything else.
+ */
+export class BytesLruCache {
+  private readonly entries = new Map<string, Uint8Array>();
+  private totalBytes = 0;
+
+  constructor(private readonly capacityBytes: number) {
+    if (!Number.isFinite(capacityBytes) || capacityBytes < 0) {
+      throw new Error(`BytesLruCache: capacityBytes must be a non-negative finite number, got ${capacityBytes}.`);
+    }
+  }
+
+  /**
+   * Return cached bytes for `key`, or null if absent. Accessing an entry
+   * marks it most-recently-used (moves to the back of the Map).
+   */
+  get(key: string): Uint8Array | null {
+    const found = this.entries.get(key);
+    if (found === undefined) {
+      return null;
+    }
+    // Refresh LRU position.
+    this.entries.delete(key);
+    this.entries.set(key, found);
+    return found;
+  }
+
+  /**
+   * Insert `value` under `key`. If `value` is larger than the total
+   * capacity, the cache skips insertion and the caller receives the
+   * untouched bytes. Evicts oldest entries until under capacity.
+   */
+  put(key: string, value: Uint8Array): void {
+    if (value.byteLength > this.capacityBytes) {
+      return; // Too big; don't thrash the cache.
+    }
+    if (this.entries.has(key)) {
+      const prev = this.entries.get(key)!;
+      this.totalBytes -= prev.byteLength;
+      this.entries.delete(key);
+    }
+    this.entries.set(key, value);
+    this.totalBytes += value.byteLength;
+    while (this.totalBytes > this.capacityBytes) {
+      const oldest = this.entries.keys().next();
+      if (oldest.done === true) {
+        break;
+      }
+      const evicted = this.entries.get(oldest.value);
+      if (evicted === undefined) {
+        break;
+      }
+      this.totalBytes -= evicted.byteLength;
+      this.entries.delete(oldest.value);
+    }
+  }
+
+  /** Clears the cache. Used by tests. */
+  clear(): void {
+    this.entries.clear();
+    this.totalBytes = 0;
+  }
+
+  /** Current occupancy in bytes. Used by tests + instrumentation. */
+  get size(): number {
+    return this.totalBytes;
+  }
+
+  /** Current number of entries. Used by tests. */
+  get count(): number {
+    return this.entries.size;
+  }
+}

package/src/workflow/index.ts

@@ -0,0 +1,98 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Xema Workflow DSL — Barrel Export ──
+//
+// Pure TypeScript package (no NestJS, no Temporal, no DB access). Exposes:
+//   - JSON Schema Draft 2020-12 validation for workflow / reusable-workflow
+//     / action documents.
+//   - A deterministic expression engine (no `eval`, closed grammar).
+//   - A semantic compiler that produces CompiledRun structures consumed by
+//     workflow-engine-api and workflow-runtime-worker.
+//
+// Consumers: `workflow-engine-api` (compile + seed), `workflow-runtime-worker`
+// (evaluate `if`/outputs/matrix-from/mount-plan at dispatch), and CI scripts
+// that validate authored YAML in `biomes/software-dev/workflow-config/`.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export { WorkflowDslError, isWorkflowDslError } from './lib/errors';
+export {
+  validateActionInputs,
+  type ActionInputValidationFailure,
+  type ActionInputValidationResult,
+} from './lib/action-input-validator';
+export {
+  InstallationResourceKind,
+  collectInstallationResourceHints,
+  type InstallationResourceFieldHint,
+} from './lib/installation-resource-kind';
+export type { InstallationCompileScope } from './lib/compiler/types';
+export {
+  parseAndValidateActionYaml,
+  parseAndValidateReusableWorkflowYaml,
+  parseAndValidateWorkflowYaml,
+  validateActionManifest,
+  validateReusableWorkflowDocument,
+  validateWorkflowDocument,
+} from './lib/validate';
+export {
+  EMPTY_CONTEXT_SEEDS,
+  ExpressionFunction,
+  ExpressionNodeKind,
+  ExpressionRoot,
+  compileExpression,
+  evaluateExpression,
+  extractInterpolations,
+  isInterpolationWrapped,
+  stripInterpolation,
+  type ExpressionContext,
+  type ExpressionNode,
+  type NeedsEntry,
+} from './lib/expression';
+export { parseDurationMs } from './lib/duration';
+export {
+  DispatchInputFieldType,
+  DispatchInputStringFormat,
+  extractDispatchInputDescriptors,
+  type DispatchInputDescriptor,
+} from './lib/dispatch-inputs';
+export { dispatchInputsToJsonSchema } from './lib/dispatch-inputs/to-json-schema';
+export { serializeWorkflowDocument } from './lib/serializer';
+export {
+  canonicalJsonSha256,
+  canonicalJsonStringify,
+  compileManifestSource,
+  compileWorkflow,
+  getWorkspaceManifestContract,
+  isAgentShapedAction,
+  type CompileInput,
+  type ResolvedAgent,
+  type ResolvedDeliverableSpec,
+  type ResolvedRef,
+} from './lib/compiler';
+export {
+  extractZodTopLevelObjectKeys,
+  extractJsonSchemaTopLevelKeys,
+} from './lib/deliverable-spec-keys';
+export type {
+  ActionContract,
+  ActionManifest,
+  ActionManifestMetadata,
+  ActionManifestRetryDefaults,
+  ActionManifestSpec,
+  ActionManifestTimeoutDefaults,
+  WorkspaceManifestActionContract,
+  ScheduleDeclaration,
+  WebhookDeclaration,
+  WorkflowCallDeclaration,
+  WorkflowConcurrencyDeclaration,
+  WorkflowDefaults,
+  WorkflowDispatchDeclaration,
+  WorkflowDocument,
+  WorkflowDynamicStrategyDeclaration,
+  WorkflowInputDeclaration,
+  WorkflowJobDeclaration,
+  WorkflowMetadata,
+  WorkflowPermissions,
+  WorkflowRetryDeclaration,
+  WorkflowStrategyDeclaration,
+  WorkflowTriggerDeclarations,
+} from './lib/types';

package/src/workflow/lib/action-input-validator.ts

@@ -0,0 +1,160 @@
+/**
+ * Runtime validator for an action's `with:` payload against the JSON Schema
+ * declared in its manifest's `spec.inputs`.
+ *
+ * The DSL compiler pins `spec.inputs` into `ActionRef.inputsSchema` so the
+ * worker validates against the schema that was in effect when the run was
+ * compiled — not whatever's currently published. The worker calls
+ * {@link validateActionInputs} from the activity-registry wrapper just before
+ * dispatching the underlying activity; failures throw fast with a precise
+ * `inputs.<path>: <message>` pointer instead of letting bad payloads ride
+ * through to the downstream service.
+ *
+ * Implementation choices:
+ * - A dedicated Ajv instance (separate from the strict one used to validate
+ *   manifests themselves) so user-authored schemas with looser conventions
+ *   still compile. We turn off `strict` because action authors aren't
+ *   schema-spec lawyers — `additionalProperties: false` plus `required`
+ *   already catches typos.
+ * - Validators are memoized by schema reference identity. CompiledRun
+ *   schemas are frozen objects whose identity is stable for the lifetime of
+ *   the worker process, so a `WeakMap` cache means each schema compiles at
+ *   most once per worker — even across concurrent dispatches.
+ * - We refuse to compile an empty / non-object schema. If a manifest didn't
+ *   declare `inputs:`, the compiler emits `inputsSchema: null` and the
+ *   caller skips validation entirely.
+ */
+import Ajv2020, { type ErrorObject, type ValidateFunction } from 'ajv/dist/2020';
+import addFormats from 'ajv-formats';
+
+const ajv = new Ajv2020({
+  // Author-friendly: action manifests use plain JSON Schema, not Ajv-strict
+  // dialect. We still get type-safety from `additionalProperties: false`
+  // (every action schema declares it) plus `required:`.
+  strict: false,
+  allErrors: true,
+  useDefaults: false,
+  validateFormats: true,
+});
+addFormats(ajv);
+
+/**
+ * Custom JSON Schema keyword `x-installation-resource` — marks a string
+ * field as referencing a resource bound to the calling biome
+ * installation. The compiler's installation-resource validator
+ * (workflow-engine `CompilerService`) reads the keyword + queries the
+ * installation's bound resources of the declared `kind`; if the value
+ * isn't in the bound set, the dispatch fails BEFORE the workflow
+ * starts.
+ *
+ * At the worker layer (here, AJV runtime) the keyword is a no-op
+ * accepted metadata — the compiler is the authoritative gate and runs
+ * with installation scope; by the time the worker validates `with:`
+ * the compile-time check has already confirmed the reference is bound.
+ *
+ * Declaration shape on an action manifest field:
+ *   walletId:
+ *     type: string
+ *     x-installation-resource: { kind: 'wallet' }
+ *
+ * Closed `kind` set lives in `installation-resource-kind.ts` to keep
+ * the wire stable across the SDK, the engine, and biome-host-api.
+ */
+ajv.addKeyword({
+  keyword: 'x-installation-resource',
+  metaSchema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['kind'],
+    properties: {
+      kind: { type: 'string', enum: ['wallet', 'repo', 'project', 'channel', 'space'] },
+    },
+  },
+});
+
+const validatorCache = new WeakMap<
+  Readonly<Record<string, unknown>>,
+  ValidateFunction
+>();
+
+export interface ActionInputValidationFailure {
+  readonly path: string;
+  readonly message: string;
+}
+
+export interface ActionInputValidationResult {
+  readonly valid: boolean;
+  readonly failures: readonly ActionInputValidationFailure[];
+}
+
+/**
+ * Validate `value` against the JSON Schema attached to a compiled
+ * ActionRef. Returns `{ valid: true, failures: [] }` on success.
+ *
+ * On failure, returns up to N failures (Ajv `allErrors: true`) each with a
+ * dotted `inputs.<path>` pointer so callers can compose
+ * `<actionId>: inputs.slug must match pattern …`-style messages.
+ *
+ * Throws synchronously only if the schema itself is unparseable (a bug in
+ * the compiler or a malformed manifest that slipped past `ACTION_SCHEMA`).
+ */
+export function validateActionInputs(
+  schema: Readonly<Record<string, unknown>>,
+  value: unknown,
+): ActionInputValidationResult {
+  const validate = compileOrGet(schema);
+  if (validate(value)) {
+    return { valid: true, failures: [] };
+  }
+  const errors = validate.errors ?? [];
+  return {
+    valid: false,
+    failures: errors.map(formatError),
+  };
+}
+
+function compileOrGet(
+  schema: Readonly<Record<string, unknown>>,
+): ValidateFunction {
+  const cached = validatorCache.get(schema);
+  if (cached) return cached;
+  const compiled = ajv.compile(schema);
+  validatorCache.set(schema, compiled);
+  return compiled;
+}
+
+/**
+ * Translate an Ajv error object into a deterministic
+ * `inputs.<path>: <message>` shape.
+ *
+ * `instancePath` is JSON-pointer syntax (`/slug`, `/labels/foo`); we
+ * convert to dotted form and prepend `inputs.` so the pointer matches the
+ * call-site phrase the workflow author authored (`with.slug`, `with.labels.foo`).
+ */
+function formatError(err: ErrorObject): ActionInputValidationFailure {
+  const dotted = err.instancePath
+    .replace(/^\//, '')
+    .split('/')
+    .filter((seg) => seg.length > 0)
+    .join('.');
+  const path = dotted.length > 0 ? `inputs.${dotted}` : 'inputs';
+  // For `required` violations Ajv puts the missing key in `params.missingProperty`
+  // and emits `instancePath: ''` — splice the key into the path so the message
+  // points at the offending field, not at the parent.
+  if (err.keyword === 'required' && typeof err.params?.['missingProperty'] === 'string') {
+    const missing = err.params['missingProperty'] as string;
+    const subPath = path === 'inputs' ? `inputs.${missing}` : `${path}.${missing}`;
+    return { path: subPath, message: 'is required but missing' };
+  }
+  // additionalProperties: name the unexpected key in the path so the
+  // workflow author can see exactly which `with:` field the schema refused.
+  if (err.keyword === 'additionalProperties' && typeof err.params?.['additionalProperty'] === 'string') {
+    const extra = err.params['additionalProperty'] as string;
+    const subPath = path === 'inputs' ? `inputs.${extra}` : `${path}.${extra}`;
+    return { path: subPath, message: 'is not declared on this action — remove it from the with-block' };
+  }
+  return {
+    path,
+    message: err.message ?? `failed ${err.keyword} check`,
+  };
+}

package/src/workflow/lib/compiler/action-shape.ts

@@ -0,0 +1,71 @@
+import type {
+  ActionManifest,
+  AgentCompositionActionContract,
+  WorkspaceManifestActionContract,
+} from '../types';
+
+/**
+ * Returns the action's `workspace-manifest@v1` contract entry when the
+ * manifest declares one explicitly. This is the source of truth for the
+ * manifest-source triplet check in `manifest-source.ts` — biomes ship
+ * an action by adding `consumes: [{ kind: workspace-manifest, version: v1, ... }]`
+ * to its manifest and inherit the manifest picker, the canvas
+ * Inspector, and the runtime resolver lane for free.
+ */
+export function getWorkspaceManifestContract(
+  actionManifest: ActionManifest | null,
+): WorkspaceManifestActionContract | null {
+  if (!actionManifest) return null;
+  const contracts = actionManifest.spec.consumes;
+  if (!contracts || contracts.length === 0) return null;
+  for (const c of contracts) {
+    if (c.kind === 'workspace-manifest' && c.version === 'v1') {
+      return c;
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns true when an action manifest opts into the workspace-manifest
+ * contract (preferred, declarative) OR matches the legacy `inputs:`
+ * shape heuristic (both `compositionRef` and `mounts` as properties).
+ * The heuristic remains a fallback so action manifests authored before
+ * the explicit contract still compile — Phase 9 sweeps the first-party
+ * actions and adds the explicit `consumes` entry, after which the
+ * heuristic can be removed in a follow-up PR.
+ */
+export function isAgentShapedAction(
+  actionManifest: ActionManifest | null,
+): actionManifest is ActionManifest {
+  if (!actionManifest) return false;
+  if (getWorkspaceManifestContract(actionManifest) !== null) return true;
+  const inputs = actionManifest.spec.inputs as
+    | { properties?: Readonly<Record<string, unknown>> }
+    | undefined;
+  const properties = inputs?.properties;
+  if (!properties) return false;
+  return 'compositionRef' in properties && 'mounts' in properties;
+}
+
+/**
+ * Returns the action's `agent-composition@v1` contract entry when the
+ * manifest declares one. An action that opts into this contract accepts
+ * `with.composition` — a `slug@version` reference to an Agent Composition
+ * in the llm-registry-api composition registry. The runtime resolves the
+ * composition at dispatch time; the composition is the source of truth
+ * for the step's agent + sub-agents + skill/tool selection.
+ */
+export function getAgentCompositionContract(
+  actionManifest: ActionManifest | null,
+): AgentCompositionActionContract | null {
+  if (!actionManifest) return null;
+  const contracts = actionManifest.spec.consumes;
+  if (!contracts || contracts.length === 0) return null;
+  for (const c of contracts) {
+    if (c.kind === 'agent-composition' && c.version === 'v1') {
+      return c;
+    }
+  }
+  return null;
+}