@xemahq/dsl 0.8.1 → 0.8.2

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

@@ -1,160 +0,0 @@
-/**
- * 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

@@ -1,71 +0,0 @@
-import type {
-  ActionManifest,
-  AgentActionContract,
-  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 `inputs:` shape
- * heuristic (declares an `agentRef` property). `agentRef` is the sole
- * way a workflow names its agent, so its presence on the action's input
- * schema is the heuristic. The heuristic remains a fallback so action
- * manifests authored before the explicit `consumes` contract still
- * compile.
- */
-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 'agentRef' 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
- * 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 getAgentContract(
-  actionManifest: ActionManifest | null,
-): AgentActionContract | 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' && c.version === 'v1') {
-      return c;
-    }
-  }
-  return null;
-}

package/src/workflow/lib/compiler/canonical-json.ts

@@ -1,66 +0,0 @@
-import { createHash } from 'node:crypto';
-
-/**
- * Canonical JSON serialization used to compute the CompiledRun's sha256.
- * Determinism is the whole point: two compilations of the same workflow +
- * trigger MUST produce byte-identical output, so every replica derives the
- * same hash.
- *
- * Rules:
- *   - Object keys are emitted in lexicographic (UTF-16) order.
- *   - No whitespace.
- *   - Numbers use JSON.stringify's representation.
- *   - undefined is forbidden (throws); callers must use explicit null.
- *   - Symbols / functions are forbidden (throws).
- */
-export function canonicalJsonStringify(value: unknown): string {
-  return stringify(value, new Set());
-}
-
-/** Convenience: canonical stringify + sha256 hex. */
-export function canonicalJsonSha256(value: unknown): string {
-  return createHash('sha256').update(canonicalJsonStringify(value), 'utf8').digest('hex');
-}
-
-function stringify(value: unknown, seen: Set<object>): string {
-  if (value === null) return 'null';
-  if (value === undefined) {
-    throw new Error('canonicalJsonStringify: undefined is not serializable');
-  }
-  if (typeof value === 'string') return JSON.stringify(value);
-  if (typeof value === 'number') {
-    if (!Number.isFinite(value)) {
-      throw new Error(`canonicalJsonStringify: non-finite number ${value}`);
-    }
-    return JSON.stringify(value);
-  }
-  if (typeof value === 'boolean') return value ? 'true' : 'false';
-  if (Array.isArray(value)) {
-    // Guard against circular references (e.g. cyclic YAML anchors) so a
-    // self-referential input yields a clear error instead of a stack overflow.
-    if (seen.has(value)) {
-      throw new Error('canonicalJsonStringify: circular reference is not serializable');
-    }
-    seen.add(value);
-    const out = `[${value.map((child) => stringify(child, seen)).join(',')}]`;
-    seen.delete(value);
-    return out;
-  }
-  if (typeof value === 'object') {
-    if (seen.has(value)) {
-      throw new Error('canonicalJsonStringify: circular reference is not serializable');
-    }
-    seen.add(value);
-    const record = value as Record<string, unknown>;
-    const keys = Object.keys(record).sort();
-    const entries: string[] = [];
-    for (const key of keys) {
-      const child = record[key];
-      if (child === undefined) continue; // drop undefined; do not emit
-      entries.push(`${JSON.stringify(key)}:${stringify(child, seen)}`);
-    }
-    seen.delete(value);
-    return `{${entries.join(',')}}`;
-  }
-  throw new Error(`canonicalJsonStringify: unsupported type ${typeof value}`);
-}