@xemahq/dsl 0.8.1 → 0.8.2

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

@@ -1,172 +0,0 @@
-import type {
-  ActionExecutionKind,
-  Briefcase,
-  TaskQueueName,
-  TriggerPayload,
-  WalletContents,
-  WorkflowRef,
-} from '@xemahq/kernel-contracts/workflow';
-import type { ActionManifest, WorkflowDocument } from '../types';
-
-/**
- * Everything the compiler needs beyond the workflow document itself. The
- * engine gathers these inputs before calling `compileWorkflow(...)`:
- *
- *   - `workflow` — validated WorkflowDocument (pass through
- *     `validateWorkflowDocument` first).
- *   - `workflowRef` — slug/revision/content-contract identity, resolved from the DB.
- *   - `trigger` — the payload that fired this run.
- *   - `resolvedRefs` — map of `uses:` strings to resolved refs, populated
- *     by looking up each job's `uses:` in the action-manifest registry
- *     (for `xema/...`) or the reusable-workflow registry (for
- *     `xema://workflow/...`).
- *   - `workflowDefinitionContentHash` — content hash of the immutable source revision the
- *     compiler is consuming. Emitted into CompiledRun for audit.
- */
-export interface CompileInput {
-  readonly workflow: WorkflowDocument;
-  readonly workflowRef: WorkflowRef;
-  readonly trigger: TriggerPayload;
-  readonly resolvedRefs: Readonly<Record<string, ResolvedRef>>;
-  /**
-   * Map of authored literal agent ref → immutable Agent revision metadata.
-   * The engine resolves each exact ref through llm-registry-api before
-   * compilation. Literal refs are therefore compile-time selectors only:
-   * CompiledRun stores the immutable revision id + content hash.
-   * Expression-shaped refs (e.g. `${{ inputs.agentSlug }}`) are skipped
-   * — they resolve at dispatch and the activity's `AGENT_NOT_REGISTERED`
-   * preflight catches them at runtime.
-   *
-   * Pass an empty map (or omit) to opt out of agent validation (e.g.
-   * for the `preview-raw` endpoint when the engine cannot reach the
-   * registry, or for tests that don't exercise the registry).
-   */
-  readonly resolvedAgents?: Readonly<Record<string, ResolvedAgentMeta>>;
-  /**
-   * Map of literal deliverable-spec refs (used in `with.deliverableSpecRef`
-   * and the `produces:` array) to the spec metadata the compiler needs
-   * for validation. The engine pre-fetches this from
-   * deliverable-specs-api. Same literal-vs-expression rule as
-   * `resolvedAgents`. Same opt-out semantics: empty / omitted = skip.
-   */
-  readonly resolvedDeliverableSpecs?: Readonly<
-    Record<string, ResolvedDeliverableSpec>
-  >;
-  readonly workflowDefinitionContentHash: string;
-  /**
-   * Contents of every wallet referenced under `requires.wallets`, plus
-   * any additional wallets a dispatch caller asked for. The compiler
-   * unions the entries to derive `CompiledRun.requiredVariables` and to
-   * validate `${{ vars.X }}` / `${{ secrets.X }}` references. When
-   * omitted, wallet-derived validation is skipped — used by
-   * `preview-raw` during authoring where the engine can't reach the
-   * variable store.
-   */
-  readonly resolvedWallets?: Readonly<Record<string, WalletContents>>;
-  /**
-   * Installation scope of this dispatch — present when the workflow is
-   * dispatched from a biome installation (webhook trigger gated on
-   * the installation, manual dispatch from the installation's UX, a
-   * scheduled trigger tied to the installation). Absent for system /
-   * org-wide dispatches that don't belong to any installation.
-   *
-   * The compiler's installation-resource validator uses this scope to
-   * resolve `x-installation-resource: { kind: ... }` references in
-   * action input schemas against the installation's bound resources
-   * (wallets / repos / channels / …). When `installationScope` is
-   * undefined, the validator skips installation-bound fields — system
-   * workflows can still reference wallet ids, but compile-time
-   * binding-set validation only happens for biome-installed runs.
-   */
-  readonly installationScope?: InstallationCompileScope;
-  /**
-   * When true, the compiler substitutes type-appropriate sentinel values
-   * for missing required inputs instead of throwing. Intended only for
-   * the `preview-raw` endpoint (Monaco editor live feedback) where the
-   * caller deliberately omits real input values during YAML authoring.
-   * Never set this on real run compilation paths.
-   */
-  readonly previewMode?: boolean;
-  /**
-   * Run-scoped Briefcase the dispatch caller attached to this run.
-   * Synthesized server-side from the StartRun request body (uploads /
-   * references / vars / mcpTools) and threaded into the CompiledRun so
-   * the run's snapshot captures the dispatch payload alongside its
-   * inputs and trigger. Absent for runs without dispatch-attached
-   * context (compiler treats absent and `emptyBriefcase()` identically
-   * downstream).
-   */
-  readonly briefcase?: Briefcase;
-}
-
-/**
- * Installation context the engine pre-fetches at dispatch time. Each
- * `boundResources` entry lists the resource ids the installation is
- * bound to for a single `InstallationResourceKind` — the compiler
- * checks every literal value in a `x-installation-resource` field
- * against the matching kind's set and rejects unbound values.
- *
- * The engine populates this from biome-host-api right before calling
- * the compiler. Passing an empty array for a kind means "no resources
- * bound" — every literal value for that kind fails validation.
- */
-export interface InstallationCompileScope {
-  readonly installationId: string;
-  readonly orgId: string;
-  readonly projectId: string;
-  readonly biomeId: string;
-  readonly boundResources: Readonly<Record<string, readonly string[]>>;
-}
-
-/**
- * Minimal agent metadata the compiler keeps for each resolved agent,
- * keyed by bare slug (the slug segment of a `with.agentRef`). The engine
- * fetches the full row from llm-registry-api but the compiler only needs
- * the existence proof and the snapshot hash (so a future `CompiledRun`
- * can carry it for cache-invalidation matching). Extend with more fields
- * only when the compiler actually consumes them.
- */
-export interface ResolvedAgentMeta {
-  readonly slug: string;
-  readonly agentRevisionId: string;
-  readonly agentContentHash: string;
-}
-
-/**
- * Minimal deliverable-spec metadata the compiler keeps for each literal
- * `deliverableSpecRef`. Same minimality rule as `ResolvedAgentMeta`.
- *
- * Optional `topLevelKeys` enables compile-time field validation for
- * expressions of shape
- * `${{ job.outputs.deliverable.content.value.<field> }}` — when
- * populated, the DSL asserts `<field>` is one of these. The engine
- * extracts the keys from the spec's `zodSchemaSource` (Zod) or
- * `content`'s `properties` (JSON Schema) at registry-fetch time. Specs
- * whose kind has no known shape (e.g. CUSTOM, ENDPOINT_FETCH) leave it
- * undefined and the validator skips them.
- */
-export interface ResolvedDeliverableSpec {
-  readonly ref: string;
-  readonly slug: string;
-  readonly snapshotHash: string;
-  readonly topLevelKeys?: readonly string[];
-}
-
-/**
- * Resolved reference for a single `uses:` value. Emitted by the engine's
- * ref-resolution layer before compilation; the compiler trusts it blindly.
- *
- * For action refs, `actionManifest` is the full manifest (the compiler
- * needs retry/timeout/allowedMounts). For reusable-workflow refs,
- * `actionManifest` is null — reusable workflows have their own compilation
- * pass, so this outer compilation only records the pointer.
- */
-export interface ResolvedRef {
-  readonly id: string;
-  readonly version: string;
-  readonly manifestSha256: string;
-  readonly executionKind: ActionExecutionKind;
-  readonly taskQueue: TaskQueueName;
-  readonly isReusableWorkflow: boolean;
-  readonly actionManifest: ActionManifest | null;
-}

package/src/workflow/lib/compiler/variable-requirements.ts

@@ -1,208 +0,0 @@
-import {
-  WorkflowErrorCode,
-  type WalletContents,
-  type WorkflowVariableRequirement,
-} from '@xemahq/kernel-contracts/workflow';
-import { WorkflowDslError } from '../errors';
-import {
-  compileExpression,
-  ExpressionNodeKind,
-  extractInterpolations,
-  type ExpressionNode,
-} from '../expression';
-import { ExpressionRoot } from '../expression/ast';
-import { stripInterpolation } from '../expression/interpolation';
-import type { WorkflowDocument } from '../types';
-
-/**
- * Compile-time handling of `requires.wallets` and the `vars.*` /
- * `secrets.*` expression namespaces.
- *
- * The compiler trusts the engine to pre-fetch the contents of every
- * wallet listed in `workflow.requires.wallets` (plus any additional
- * wallets the dispatch caller asked for) and pass them as the
- * `resolvedWallets` map. Two responsibilities here, both fail-fast:
- *
- *   1. `WORKFLOW_WALLET_NOT_FOUND` — every wallet name declared under
- *      `requires.wallets` must have an entry in `resolvedWallets`.
- *      Missing entry = the engine couldn't find the wallet for the
- *      workflow's project/org scope.
- *
- *   2. `DSL_EXPRESSION_INVALID` — every `${{ vars.X }}` / `${{ secrets.X }}`
- *      member access must resolve to a key in the union of the resolved
- *      wallets' contents (modulo the YAML-static `vars:` block which can
- *      also satisfy a `vars.X` lookup). Catches typos / stale references
- *      at compile time instead of a runtime evaluator failure.
- *
- * The function returns the canonical flat list emitted into
- * `CompiledRun.requiredVariables` — the union of every wallet's
- * `(key, isSecret)` entries with duplicates collapsed (last writer wins
- * for `isSecret` if two wallets disagree; the engine surfaces the
- * conflict at fetch time with a different code).
- */
-export function resolveWalletRequirements(
-  doc: WorkflowDocument,
-  resolvedWallets: Readonly<Record<string, WalletContents>> | undefined,
-): readonly WorkflowVariableRequirement[] {
-  const declaredWallets = doc.requires?.wallets ?? [];
-
-  if (resolvedWallets === undefined) {
-    // Engine opted out (preview-raw / tests). Skip both checks and
-    // emit an empty requirements list — `${{ vars.X }}` / `${{ secrets.X }}`
-    // references that don't satisfy the YAML-static fallback will still
-    // surface at runtime, which is the documented contract for opt-out.
-    return Object.freeze([]);
-  }
-
-  const missingWallets: string[] = [];
-  for (const name of declaredWallets) {
-    if (!Object.hasOwn(resolvedWallets, name)) {
-      missingWallets.push(name);
-    }
-  }
-  if (missingWallets.length > 0) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.WORKFLOW_WALLET_NOT_FOUND,
-      `Wallet(s) declared in requires.wallets are not available for this project/org scope: ${missingWallets.join(', ')}`,
-      { missing: missingWallets },
-    );
-  }
-
-  const merged = new Map<string, WorkflowVariableRequirement>();
-  for (const name of declaredWallets) {
-    const wallet = resolvedWallets[name];
-    if (!wallet) {
-      // `declaredWallets` is derived from the same `resolvedWallets`
-      // map upstream, so a missing entry here would be an internal
-      // invariant violation — surface it instead of silently producing
-      // an empty merge.
-      throw new Error(
-        `Internal: declaredWallets references unresolved wallet '${name}'.`,
-      );
-    }
-    for (const entry of wallet.entries) {
-      merged.set(entry.key, {
-        name: entry.key,
-        secret: entry.isSecret,
-        optional: false,
-      });
-    }
-  }
-  return Object.freeze([...merged.values()]);
-}
-
-/**
- * Walk every `${{ ... }}` expression body in the workflow and, for each
- * `vars.<NAME>` / `secrets.<NAME>` member access, verify the referenced
- * name is satisfiable from the resolved wallets (or, for `vars.*` only,
- * from the YAML-static `vars:` block).
- */
-export function validateVariableReferences(
-  doc: WorkflowDocument,
-  requiredVariables: readonly WorkflowVariableRequirement[],
-  resolvedWallets: Readonly<Record<string, WalletContents>> | undefined,
-): void {
-  if (resolvedWallets === undefined) {
-    return;
-  }
-  const staticVarNames = new Set(Object.keys(doc.vars ?? {}));
-  const allowedVars = new Set<string>(staticVarNames);
-  const allowedSecrets = new Set<string>();
-  for (const r of requiredVariables) {
-    if (r.secret) {
-      allowedSecrets.add(r.name);
-    } else {
-      allowedVars.add(r.name);
-    }
-  }
-
-  for (const { source, pathLabel } of collectAllExpressions(doc)) {
-    const ast = compileExpression(source);
-    walkVariableAccesses(ast, (root, name) => {
-      if (root === ExpressionRoot.VARS && !allowedVars.has(name)) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_EXPRESSION_INVALID,
-          `Expression at ${pathLabel} reads vars.${name}, but '${name}' is not provided by workflow.vars or any wallet in requires.wallets.`,
-          { pathLabel, root, name, source },
-        );
-      }
-      if (root === ExpressionRoot.SECRETS && !allowedSecrets.has(name)) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_EXPRESSION_INVALID,
-          `Expression at ${pathLabel} reads secrets.${name}, but '${name}' is not provided by any wallet in requires.wallets (or the wallet entry is not marked secret).`,
-          { pathLabel, root, name, source },
-        );
-      }
-    });
-  }
-}
-
-interface CollectedExpression {
-  readonly source: string;
-  readonly pathLabel: string;
-}
-
-function collectAllExpressions(doc: WorkflowDocument): CollectedExpression[] {
-  const out: CollectedExpression[] = [];
-  for (const [jobKey, job] of Object.entries(doc.jobs)) {
-    for (const expr of extractInterpolations(job.with, ['jobs', jobKey, 'with'])) {
-      out.push({ source: expr.source, pathLabel: expr.path.join('.') });
-    }
-    for (const expr of extractInterpolations(job.outputs, ['jobs', jobKey, 'outputs'])) {
-      out.push({ source: expr.source, pathLabel: expr.path.join('.') });
-    }
-    if (typeof job.if === 'string' && job.if.length > 0) {
-      out.push({ source: stripInterpolation(job.if), pathLabel: `jobs.${jobKey}.if` });
-    }
-  }
-  return out;
-}
-
-/**
- * Visits every `<root>.<name>` member access in the AST and invokes
- * `onAccess(root, name)`. Other access shapes are ignored — the caller
- * validates only the first hop, which is sufficient because both
- * `vars.*` and `secrets.*` are string-keyed flat maps.
- */
-function walkVariableAccesses(
-  node: ExpressionNode,
-  onAccess: (root: ExpressionRoot, name: string) => void,
-): void {
-  switch (node.kind) {
-    case ExpressionNodeKind.MEMBER: {
-      const target = node.target;
-      if (
-        target.kind === ExpressionNodeKind.IDENTIFIER &&
-        (target.name === ExpressionRoot.VARS ||
-          target.name === ExpressionRoot.SECRETS)
-      ) {
-        onAccess(target.name as ExpressionRoot, node.property);
-        return;
-      }
-      walkVariableAccesses(target, onAccess);
-      return;
-    }
-    case ExpressionNodeKind.INDEX:
-      walkVariableAccesses(node.target, onAccess);
-      walkVariableAccesses(node.index, onAccess);
-      return;
-    case ExpressionNodeKind.CALL:
-      for (const arg of node.args) {
-        walkVariableAccesses(arg, onAccess);
-      }
-      return;
-    case ExpressionNodeKind.UNARY_NOT:
-      walkVariableAccesses(node.operand, onAccess);
-      return;
-    case ExpressionNodeKind.BINARY_EQ:
-    case ExpressionNodeKind.BINARY_NEQ:
-    case ExpressionNodeKind.BINARY_AND:
-    case ExpressionNodeKind.BINARY_OR:
-      walkVariableAccesses(node.left, onAccess);
-      walkVariableAccesses(node.right, onAccess);
-      return;
-    case ExpressionNodeKind.IDENTIFIER:
-    case ExpressionNodeKind.LITERAL:
-      return;
-  }
-}

package/src/workflow/lib/deliverable-spec-introspection-error.ts

@@ -1,63 +0,0 @@
-/**
- * Typed failure raised when a deliverable spec's Zod source cannot be
- * introspected UNAMBIGUOUSLY. Distinct from the `null` return of the
- * extractors, which means "this source has no introspectable shape at
- * all" — a spec kind or body we simply cannot read. This error means the
- * opposite: the source DOES declare a shape, but the spec has not said
- * WHICH one is the contract, so any answer would be a guess.
- *
- * Callers MUST branch on `.reason` — free-form message matching is
- * forbidden so handling stays exhaustive (same convention as
- * `WorkflowDslError.code`).
- */
-
-/** Closed set of introspection failure reasons. */
-export enum DeliverableSpecIntrospectionFailure {
-  /**
-   * The source declares two or more top-level `z.object({ … })` schemas
-   * and the spec did not name which one is the contract. Resolving this
-   * by position ("the first one") is guesswork: a schema hoisted above
-   * the contract purely so the contract can reference it would silently
-   * become the contract.
-   */
-  AmbiguousSchema = 'AMBIGUOUS_SCHEMA',
-  /**
-   * The spec named a contract export (`zodSchemaExport`) that the source
-   * does not declare as a top-level `z.object({ … })` — a typo, a rename,
-   * or an unbalanced literal the scanner could not close.
-   */
-  ExportNotFound = 'EXPORT_NOT_FOUND',
-}
-
-export class DeliverableSpecIntrospectionError extends Error {
-  readonly reason: DeliverableSpecIntrospectionFailure;
-  readonly details: Readonly<Record<string, unknown>>;
-
-  constructor(
-    reason: DeliverableSpecIntrospectionFailure,
-    message: string,
-    details: Readonly<Record<string, unknown>> = {},
-  ) {
-    super(message);
-    this.name = 'DeliverableSpecIntrospectionError';
-    this.reason = reason;
-    this.details = details;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-
-  toJSON(): Readonly<Record<string, unknown>> {
-    return {
-      name: this.name,
-      reason: this.reason,
-      message: this.message,
-      details: this.details,
-    };
-  }
-}
-
-/** Narrowing helper. */
-export function isDeliverableSpecIntrospectionError(
-  err: unknown,
-): err is DeliverableSpecIntrospectionError {
-  return err instanceof DeliverableSpecIntrospectionError;
-}

package/src/workflow/lib/deliverable-spec-keys.ts

@@ -1,147 +0,0 @@
-/**
- * Static introspection of deliverable-spec content to recover the
- * top-level keys an agent's output object MUST expose. The compiler uses
- * these keys to validate workflow expressions of shape
- * `${{ job.outputs.deliverable.content.value.<field> }}` against the
- * spec the producing job declared via `with.deliverableSpecRef` —
- * catching "the YAML reads `.changeUnits` but the spec has
- * `.handoffPackage`" at compile time, not at runtime when projection
- * blows up. The same keys are the ONLY content gate the harvester has
- * for a `ZOD_SCHEMA` spec (nothing anywhere evaluates the Zod schema),
- * so a wrong key set silently rejects correct agent output.
- *
- * Two extractors:
- *   - `extractZodTopLevelObjectKeys`: reads the field names of the
- *     `z.object({ … })` literal a spec designates as its contract, out of
- *     TypeScript Zod source. Same scanner the deliverable-specs-api
- *     ZodSchemaHandler uses for harvest-time validation; single source of
- *     truth lives here so the DSL compiler and the harvester agree.
- *   - `extractJsonSchemaTopLevelKeys`: pulls keys from the `properties`
- *     object of a JSON Schema document.
- *
- * Both return `null` when a source has NO introspectable shape, so
- * callers can skip the field check (preview / specs without introspectable
- * shape). `null` never means "we guessed" — an unresolvable-but-present
- * shape raises `DeliverableSpecIntrospectionError` instead.
- */
-
-import {
-  DeliverableSpecIntrospectionError,
-  DeliverableSpecIntrospectionFailure,
-} from './deliverable-spec-introspection-error';
-import { scanTopLevelZodObjectDeclarations } from './deliverable-spec-source-scan';
-
-import type { TopLevelZodObjectDeclaration } from './deliverable-spec-source-scan';
-
-/**
- * Return the top-level field identifiers of the `z.object({ … })` literal
- * that IS this spec's contract.
- *
- * Which literal that is comes from the spec, not from source order:
- *
- *   - `exportName` given → the literal bound to that name. Absent from
- *     the source ⇒ `EXPORT_NOT_FOUND`, never a fallback to another
- *     schema. A spec that names a contract it does not have is broken,
- *     and guessing would reintroduce exactly the bug this parameter
- *     exists to remove.
- *   - `exportName` omitted, source declares exactly ONE top-level
- *     literal → that one. There is nothing to choose between, so the
- *     spec is not asked to restate it.
- *   - `exportName` omitted, source declares TWO OR MORE →
- *     `AMBIGUOUS_SCHEMA`. This is the case the predecessor resolved by
- *     taking the first literal in the file, which silently picked an
- *     element/helper schema hoisted above the contract that references
- *     it. There is no correct positional answer; the spec must say.
- *   - source declares NONE → `null` (no introspectable shape).
- *
- * Deliberately a scanner, not a Zod evaluation: this runs in the DSL
- * compiler, a CI gate, and a request-scoped API handler, none of which
- * may transpile or execute spec-authored TypeScript.
- *
- * @throws {DeliverableSpecIntrospectionError} on a named export that is
- *   absent, or on an unnamed contract in a multi-schema source.
- */
-export function extractZodTopLevelObjectKeys(
-  source: string,
-  exportName?: string | null,
-): readonly string[] | null {
-  if (!source || source.trim().length === 0) return null;
-  const declarations = scanTopLevelZodObjectDeclarations(source);
-  const named = exportName?.trim() ?? '';
-
-  if (named.length > 0) {
-    const match = declarations.find((d) => d.exportName === named);
-    if (!match) {
-      throw new DeliverableSpecIntrospectionError(
-        DeliverableSpecIntrospectionFailure.ExportNotFound,
-        `deliverable spec names '${named}' as its Zod contract, but the source declares no top-level \`z.object({ … })\` bound to that name. ` +
-          `${describeDeclarations(declarations)} Fix the spec's \`zodSchemaExport\`, or check the literal's braces are balanced.`,
-        { exportName: named, available: availableNames(declarations) },
-      );
-    }
-    return match.keys;
-  }
-
-  if (declarations.length === 0) return null;
-  if (declarations.length === 1) return declarations[0]!.keys;
-
-  throw new DeliverableSpecIntrospectionError(
-    DeliverableSpecIntrospectionFailure.AmbiguousSchema,
-    `deliverable spec source declares ${declarations.length} top-level \`z.object({ … })\` schemas and the spec does not say which one is the contract. ` +
-      `${describeDeclarations(declarations)} Set \`zodSchemaExport\` on the spec to the contract's export name.`,
-    { available: availableNames(declarations) },
-  );
-}
-
-/**
- * Pull the top-level field names from a JSON Schema document. Accepts
- * either a parsed object or a raw JSON string. Honors `properties` —
- * the conventional shape — and ignores `patternProperties` /
- * `additionalProperties` / Draft 2020 `unevaluatedProperties` because
- * those don't enumerate concrete keys an author can reference by name.
- *
- * Returns `null` when the schema is unparseable or has no `properties`
- * map.
- */
-export function extractJsonSchemaTopLevelKeys(
-  source: string | object,
-): readonly string[] | null {
-  let parsed: unknown;
-  if (typeof source === 'string') {
-    if (source.trim().length === 0) return null;
-    try {
-      parsed = JSON.parse(source);
-    } catch {
-      return null;
-    }
-  } else {
-    parsed = source;
-  }
-  if (!isPlainObject(parsed)) return null;
-  const properties = (parsed as Record<string, unknown>)['properties'];
-  if (!isPlainObject(properties)) return null;
-  const keys = Object.keys(properties);
-  return Object.freeze(keys);
-}
-
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return v !== null && typeof v === 'object' && !Array.isArray(v);
-}
-
-function availableNames(
-  declarations: readonly TopLevelZodObjectDeclaration[],
-): readonly string[] {
-  return declarations
-    .map((d) => d.exportName)
-    .filter((n): n is string => n !== null);
-}
-
-function describeDeclarations(
-  declarations: readonly TopLevelZodObjectDeclaration[],
-): string {
-  const names = availableNames(declarations);
-  if (names.length === 0) {
-    return 'The source declares no NAMED top-level schema.';
-  }
-  return `Top-level schemas in this source: ${names.join(', ')}.`;
-}